While LLMs excel at generating text, compound-beta
takes the next step.
It's an advanced AI system that is designed to solve problems by taking action and intelligently uses external tools - starting with web search and code execution - alongside the powerful Llama 4 models and Llama 3.3 70b model.
This allows it access to real-time information and interaction with external environments, providing more accurate, up-to-date, and capable responses than an LLM alone.
There are two agentic tool systems available:
compound-beta
: supports multiple tool calls per request. This system is great for use cases that require multiple web searches or code executions per request.compound-beta-mini
: supports a single tool call per request. This system is great for use cases that require a single web search or code execution per request. compound-beta-mini
has an average of 3x lower latency than compound-beta
.Both systems support the following tools:
Custom user-provided tools are not supported at this time.
To use agentic tools, change the model
parameter to either compound-beta
or compound-beta-mini
:
1from groq import Groq
2
3client = Groq()
4
5completion = client.chat.completions.create(
6 messages=[
7 {
8 "role": "user",
9 "content": "What is the current weather in Tokyo?",
10 }
11 ],
12 # Change model to compound-beta to use agentic tooling
13 # model: "llama-3.3-70b-versatile",
14 model="compound-beta",
15)
16
17print(completion.choices[0].message.content)
18# Print all tool calls
19# print(completion.choices[0].message.executed_tools)
And that's it!
When the API is called, it will intelligently decide when to use search or code execution to best answer the user's query. These tool calls are performed on the server side, so no additional setup is required on your part to use agentic tooling.
In the above example, the API will use its build in web search tool to find the current weather in Tokyo. If you didn't use agentic tooling, you might have needed to add your own custom tools to make API requests to a weather service, then perform multiple API calls to Groq to get a final result. Instead, with agentic tooling, you can get a final result with a single API call.
To view the tools (search or code execution) used automatically by the compound system, check the executed_tools
field in the response:
1import os
2from groq import Groq
3
4client = Groq(api_key=os.environ.get("GROQ_API_KEY"))
5
6response = client.chat.completions.create(
7 model="compound-beta",
8 messages=[
9 {"role": "user", "content": "What did Groq release last week?"}
10 ]
11)
12# Log the tools that were used to generate the response
13print(response.choices[0].message.executed_tools)
Customize web search behavior by either excluding specific domains from search results or restricting searches to only include specific domains. These parameters are supported for both compound-beta
and compound-beta-mini
.
Parameter | Type | Description |
---|---|---|
exclude_domains | string[] | List of domains to exclude when performing web searches. Supports wildcards (e.g., "*.com") |
include_domains | string[] | Restrict web searches to only search within these specified domains. Supports wildcards (e.g., "*.edu") |
Both include_domains
and exclude_domains
support wildcard patterns using the *
character. This allows for flexible domain filtering:
*.com
to include/exclude all .com domains*.edu
to include/exclude all educational institutionsexample.com
to include/exclude exact matchesYou can combine both parameters to create precise search scopes. For example:
curl "https://api.groq.com/openai/v1/chat/completions" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GROQ_API_KEY}" \
-d '{
"messages": [
{
"role": "user",
"content": "Tell me about the history of Bonsai trees in America"
}
],
"model": "compound-beta-mini",
"exclude_domains": ["wikipedia.org"]
}'
Compound-beta excels at a wide range of use cases, particularly when real-time information is required.
Your application needs to answer questions or provide information that requires up-to-the-minute knowledge, such as:
Building and maintaining your own web scraping or search API integration is complex and time-consuming.
Simply send the user's query to compound-beta
. If the query requires current information beyond its training data, it will automatically trigger its built-in web search tool (powered by Tavily) to fetch relevant, live data before formulating the answer.
1import os
2from groq import Groq
3
4# Ensure your GROQ_API_KEY is set as an environment variable
5client = Groq(api_key=os.environ.get("GROQ_API_KEY"))
6
7user_query = "What were the main highlights from the latest Apple keynote event?"
8# Or: "What's the current weather in San Francisco?"
9# Or: "Summarize the latest developments in fusion energy research this week."
10
11chat_completion = client.chat.completions.create(
12 messages=[
13 {
14 "role": "user",
15 "content": user_query,
16 }
17 ],
18 # The *only* change needed: Specify the compound model!
19 model="compound-beta",
20)
21
22print(f"Query: {user_query}")
23print(f"Compound Beta Response:\n{chat_completion.choices[0].message.content}")
24
25# You might also inspect chat_completion.choices[0].message.executed_tools
26# if you want to see if/which tool was used, though it's not necessary.
You want users to perform calculations, run simple data manipulations, or execute small code snippets using natural language commands within your application, without building a dedicated parser or execution environment.
Frame the user's request as a task involving computation or code. compound-beta-mini
can recognize these requests and use its secure code execution tool to compute the result.
1import os
2from groq import Groq
3
4client = Groq(api_key=os.environ.get("GROQ_API_KEY"))
5
6# Example 1: Calculation
7computation_query = "Calculate the monthly payment for a $30,000 loan over 5 years at 6% annual interest."
8
9# Example 2: Simple code execution
10code_query = "What is the output of this Python code snippet: `data = {'a': 1, 'b': 2}; print(data.keys())`"
11
12# Choose one query to run
13selected_query = computation_query
14
15chat_completion = client.chat.completions.create(
16 messages=[
17 {
18 "role": "system",
19 "content": "You are a helpful assistant capable of performing calculations and executing simple code when asked.",
20 },
21 {
22 "role": "user",
23 "content": selected_query,
24 }
25 ],
26 # Use the compound model
27 model="compound-beta-mini",
28)
29
30print(f"Query: {selected_query}")
31print(f"Compound Beta Response:\n{chat_completion.choices[0].message.content}")
Developers often need quick help understanding error messages or testing small code fixes. Searching documentation or running snippets requires switching contexts.
Users can paste an error message and ask for explanations or potential causes. Compound Beta Mini might use web search to find recent discussions or documentation about that specific error. Alternatively, users can provide a code snippet and ask "What's wrong with this code?" or "Will this Python code run: ...?". It can use code execution to test simple, self-contained snippets.
Note: compound-beta-mini
uses one tool per turn, so it might search OR execute, not both simultaneously in one response.
1import os
2from groq import Groq
3
4client = Groq(api_key=os.environ.get("GROQ_API_KEY"))
5
6# Example 1: Error Explanation (might trigger search)
7debug_query_search = "I'm getting a 'Kubernetes CrashLoopBackOff' error on my pod. What are the common causes based on recent discussions?"
8
9# Example 2: Code Check (might trigger code execution)
10debug_query_exec = "Will this Python code raise an error? `import numpy as np; a = np.array([1,2]); b = np.array([3,4,5]); print(a+b)`"
11
12# Choose one query to run
13selected_query = debug_query_exec
14
15chat_completion = client.chat.completions.create(
16 messages=[
17 {
18 "role": "system",
19 "content": "You are a helpful coding assistant. You can explain errors, potentially searching for recent information, or check simple code snippets by executing them.",
20 },
21 {
22 "role": "user",
23 "content": selected_query,
24 }
25 ],
26 # Use the compound model
27 model="compound-beta-mini",
28)
29
30print(f"Query: {selected_query}")
31print(f"Compound Beta Response:\n{chat_completion.choices[0].message.content}")