Repository Public
1<!-- source: https://docs.x.ai/developers/model-capabilities/text/multi-agent (from https://docs.x.ai/llms-full.txt, retrieved 2026-09-19T05:28:55Z) -->2#### Model Capabilities34# Multi Agent56> [!WARNING]7>8> This feature is currently in **beta**. The API interface and behavior may change as we iterate. Please bear in mind that the API interface is not final and may include breaking changes down the line.910Realtime Multi-agent Research enables Grok to orchestrate multiple AI agents that work together in real time to perform deep, multi-step research tasks. Agents specialize in particular aspects of the research (searching the web, analyzing data, synthesizing findings) and collaborate to deliver comprehensive, well-sourced answers.1112## Overview1314Multi-agent research goes beyond single-turn tool use by coordinating a team of specialized agents that can:1516* **Search and gather** information from multiple sources simultaneously17* **Analyze and cross-reference** findings across different domains18* **Synthesize** comprehensive answers with citations and supporting evidence19* **Iterate** on research in real time, refining results based on intermediate findings2021## Getting Started2223To use Realtime Multi-agent Research, specify `grok-4.20-multi-agent` as the model name in your API requests. This model is optimized for orchestrating multiple agents that collaborate on research tasks.2425```python customLanguage="pythonXAI" highlightedLines="9"26import os2728from xai_sdk import Client29from xai_sdk.chat import user30from xai_sdk.tools import web_search, x_search3132client = Client(api_key=os.getenv("XAI_API_KEY"))33chat = client.chat.create(34 model="grok-4.20-multi-agent",35 tools=[web_search(), x_search()],36 include=["verbose_streaming"],37)3839chat.append(user("Research the latest breakthroughs in quantum computing and summarize the key findings."))4041is_thinking = True42for response, chunk in chat.stream():43 if response.usage.reasoning_tokens and is_thinking:44 print(f"\rThinking... ({response.usage.reasoning_tokens} tokens)", end="", flush=True)45 if chunk.content and is_thinking:46 print("\n\nFinal Response:")47 is_thinking = False48 if chunk.content and not is_thinking:49 print(chunk.content, end="", flush=True)5051print("\n\nUsage:")52print(response.usage)53```5455```python customLanguage="pythonOpenAISDK" highlightedLines="10"56import os57from openai import OpenAI5859client = OpenAI(60 api_key=os.getenv("XAI_API_KEY"),61 base_url="https://api.x.ai/v1",62)6364response = client.responses.create(65 model="grok-4.20-multi-agent",66 input=[67 {68 "role": "user",69 "content": "Research the latest breakthroughs in quantum computing and summarize the key findings.",70 },71 ],72 tools=[73 {"type": "web_search"},74 {"type": "x_search"},75 ],76)7778print(response)79```8081```python customLanguage="pythonRequests" highlightedLines="10"82import os83import requests8485url = "https://api.x.ai/v1/responses"86headers = {87 "Content-Type": "application/json",88 "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}"89}90payload = {91 "model": "grok-4.20-multi-agent",92 "input": [93 {94 "role": "user",95 "content": "Research the latest breakthroughs in quantum computing and summarize the key findings."96 }97 ],98 "tools": [99 {"type": "web_search"},100 {"type": "x_search"}101 ]102}103response = requests.post(url, headers=headers, json=payload)104print(response.json())105```106107```bash customLanguage="bash" highlightedLines="5"108curl https://api.x.ai/v1/responses \109 -H "Content-Type: application/json" \110 -H "Authorization: Bearer $XAI_API_KEY" \111 -d '{112 "model": "grok-4.20-multi-agent",113 "input": [114 {115 "role": "user",116 "content": "Research the latest breakthroughs in quantum computing and summarize the key findings."117 }118 ],119 "tools": [120 {"type": "web_search"},121 {"type": "x_search"}122 ]123}'124```125126```typescript customLanguage="javascriptAISDK" highlightedLines="5"127import { xai } from "@ai-sdk/xai";128import { generateText } from "ai";129130const { text } = await generateText({131 model: xai.responses("grok-4.20-multi-agent"),132 prompt:133 "Research the latest breakthroughs in quantum computing and summarize the key findings.",134 tools: {135 web_search: xai.tools.webSearch(),136 x_search: xai.tools.xSearch(),137 },138});139140console.log(text);141```142143## How Multi-agent Works144145When you send a request to the multi-agent model, multiple agents are launched to discuss and collaborate on your query. Each agent contributes its own perspective, reasoning, and findings. A designated **leader agent** is responsible for synthesizing the discussion and presenting the final answer back to you.146147### Supported Models148149* `grok-4.20-multi-agent`150151### Built-in Tools Support152153xAI provides a set of built-in tools you can enable in the request to help with the most common use cases, e.g., `web_search`, `x_search`, `code_execution`, `collections_search`. Check out [this doc](/developers/tools/overview) for more information.154155Once you enable those tools in the request, the server will perform the agent loop to invoke those tools on the server side based on your query until the final answer is generated.156157> [!NOTE]158>159> Using built-in tools will incur an additional cost. Please review the [pricing details for built-in tools](/developers/pricing#tools-pricing).160161### Output Behavior162163Only the **tool calls** and the **final response** from the leader agent are sent back to the user. All sub-agent state — including their intermediate reasoning, tool calls, and outputs — is encrypted and included in the response only when `use_encrypted_content` is set to `True` in the xAI SDK. This keeps the default response clean and focused while still allowing you to preserve the full multi-agent context for multi-turn conversations.164165## Configuration166167You can configure how many agents collaborate on a request. The two available setups are **4 agents** and **16 agents**. More agents means deeper, more thorough research at the cost of higher token usage and latency.168169| SDK / API | Parameter | 4 Agents | 16 Agents |170|---|---|---|---|171| xAI SDK | `agent_count` | `4` | `16` |172| OpenAI SDK | `reasoning.effort` | `"low"` or `"medium"` | `"high"` or `"xhigh"` |173| Vercel AI SDK | `reasoningEffort` | `"low"` or `"medium"` | `"high"` or `"xhigh"` |174| REST API | `reasoning.effort` | `"low"` or `"medium"` | `"high"` or `"xhigh"` |175176**Best For:** Use 4 agents for quick research and focused queries. Use 16 agents for deep research and complex multi-faceted topics.177178### 4-Agent Setup179180```python customLanguage="pythonXAI" highlightedLines="8,9"181import os182183from xai_sdk import Client184from xai_sdk.chat import user185186client = Client(api_key=os.getenv("XAI_API_KEY"))187chat = client.chat.create(188 model="grok-4.20-multi-agent",189 agent_count=4,190)191192chat.append(user("What are the key differences between TCP and UDP?"))193for response, chunk in chat.stream():194 if chunk.content:195 print(chunk.content, end="", flush=True)196```197198```python customLanguage="pythonOpenAISDK" highlightedLines="10,11"199import os200from openai import OpenAI201202client = OpenAI(203 api_key=os.getenv("XAI_API_KEY"),204 base_url="https://api.x.ai/v1",205)206207response = client.responses.create(208 model="grok-4.20-multi-agent",209 reasoning={"effort": "low"},210 input=[211 {212 "role": "user",213 "content": "What are the key differences between TCP and UDP?",214 },215 ],216)217218print(response.output_text)219```220221```python customLanguage="pythonRequests" highlightedLines="10,11"222import os223import requests224225url = "https://api.x.ai/v1/responses"226headers = {227 "Content-Type": "application/json",228 "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}"229}230payload = {231 "model": "grok-4.20-multi-agent",232 "reasoning": {"effort": "low"},233 "input": [234 {235 "role": "user",236 "content": "What are the key differences between TCP and UDP?"237 }238 ]239}240response = requests.post(url, headers=headers, json=payload)241print(response.json())242```243244```bash customLanguage="bash" highlightedLines="5,6"245curl https://api.x.ai/v1/responses \246 -H "Content-Type: application/json" \247 -H "Authorization: Bearer $XAI_API_KEY" \248 -d '{249 "model": "grok-4.20-multi-agent",250 "reasoning": {"effort": "low"},251 "input": [252 {253 "role": "user",254 "content": "What are the key differences between TCP and UDP?"255 }256 ]257}'258```259260```typescript customLanguage="javascriptAISDK" highlightedLines="5,8"261import { xai } from "@ai-sdk/xai";262import { generateText } from "ai";263264const { text } = await generateText({265 model: xai.responses("grok-4.20-multi-agent"),266 prompt: "What are the key differences between TCP and UDP?",267 providerOptions: {268 xai: { reasoningEffort: "low" },269 },270});271272console.log(text);273```274275### 16-Agent Setup276277```python customLanguage="pythonXAI" highlightedLines="8,9"278import os279280from xai_sdk import Client281from xai_sdk.chat import user282283client = Client(api_key=os.getenv("XAI_API_KEY"))284chat = client.chat.create(285 model="grok-4.20-multi-agent",286 agent_count=16,287)288289chat.append(user("Analyze the design trade-offs in modern programming languages: compare Rust's ownership model, Go's simplicity philosophy, and Haskell's pure functional approach. Cover memory safety, concurrency, developer productivity, and ecosystem maturity."))290for response, chunk in chat.stream():291 if chunk.content:292 print(chunk.content, end="", flush=True)293```294295```python customLanguage="pythonOpenAISDK" highlightedLines="10,11"296import os297from openai import OpenAI298299client = OpenAI(300 api_key=os.getenv("XAI_API_KEY"),301 base_url="https://api.x.ai/v1",302)303304response = client.responses.create(305 model="grok-4.20-multi-agent",306 reasoning={"effort": "high"},307 input=[308 {309 "role": "user",310 "content": "Analyze the design trade-offs in modern programming languages: compare Rust's ownership model, Go's simplicity philosophy, and Haskell's pure functional approach. Cover memory safety, concurrency, developer productivity, and ecosystem maturity.",311 },312 ],313)314315print(response.output_text)316```317318```python customLanguage="pythonRequests" highlightedLines="10,11"319import os320import requests321322url = "https://api.x.ai/v1/responses"323headers = {324 "Content-Type": "application/json",325 "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}"326}327payload = {328 "model": "grok-4.20-multi-agent",329 "reasoning": {"effort": "high"},330 "input": [331 {332 "role": "user",333 "content": "Analyze the design trade-offs in modern programming languages: compare Rust's ownership model, Go's simplicity philosophy, and Haskell's pure functional approach. Cover memory safety, concurrency, developer productivity, and ecosystem maturity."334 }335 ]336}337response = requests.post(url, headers=headers, json=payload)338print(response.json())339```340341```bash customLanguage="bash" highlightedLines="5,6"342curl https://api.x.ai/v1/responses \343 -H "Content-Type: application/json" \344 -H "Authorization: Bearer $XAI_API_KEY" \345 -d '{346 "model": "grok-4.20-multi-agent",347 "reasoning": {"effort": "high"},348 "input": [349 {350 "role": "user",351 "content": "Analyze the design trade-offs in modern programming languages: compare Rust'\''s ownership model, Go'\''s simplicity philosophy, and Haskell'\''s pure functional approach. Cover memory safety, concurrency, developer productivity, and ecosystem maturity."352 }353 ]354}'355```356357```typescript customLanguage="javascriptAISDK" highlightedLines="5,9"358import { xai } from "@ai-sdk/xai";359import { generateText } from "ai";360361const { text } = await generateText({362 model: xai.responses("grok-4.20-multi-agent"),363 prompt:364 "Analyze the design trade-offs in modern programming languages: compare Rust's ownership model, Go's simplicity philosophy, and Haskell's pure functional approach. Cover memory safety, concurrency, developer productivity, and ecosystem maturity.",365 providerOptions: {366 xai: { reasoningEffort: "high" },367 },368});369370console.log(text);371```372373> [!NOTE]374>375> The 16-agent setup uses significantly more tokens than the 4-agent setup. Choose the agent count based on the complexity of your research task — use 4 agents for focused queries and 16 agents when you need comprehensive, multi-perspective analysis.376377## Common Patterns378379### Without Built-in Tools380381Multi-agent works without any built-in tools — the agents rely purely on their collective knowledge and reasoning to collaborate on a response.382383```python customLanguage="pythonXAI"384import os385386from xai_sdk import Client387from xai_sdk.chat import user388389client = Client(api_key=os.getenv("XAI_API_KEY"))390chat = client.chat.create(391 model="grok-4.20-multi-agent",392 include=["verbose_streaming"],393)394395chat.append(user("Compare the major approaches to distributed consensus in computer science: Paxos, Raft, and Byzantine fault tolerance. Analyze the trade-offs in safety guarantees, performance, and implementation complexity."))396397is_thinking = True398for response, chunk in chat.stream():399 if response.usage.reasoning_tokens and is_thinking:400 print(f"\rThinking... ({response.usage.reasoning_tokens} tokens)", end="", flush=True)401 if chunk.content and is_thinking:402 print("\n\nFinal Response:")403 is_thinking = False404 if chunk.content and not is_thinking:405 print(chunk.content, end="", flush=True)406407print("\n\nUsage:")408print(response.usage)409```410411```python customLanguage="pythonOpenAISDK"412import os413from openai import OpenAI414415client = OpenAI(416 api_key=os.getenv("XAI_API_KEY"),417 base_url="https://api.x.ai/v1",418)419420response = client.responses.create(421 model="grok-4.20-multi-agent",422 input=[423 {424 "role": "user",425 "content": "Compare the major approaches to distributed consensus in computer science: Paxos, Raft, and Byzantine fault tolerance. Analyze the trade-offs in safety guarantees, performance, and implementation complexity.",426 },427 ],428)429430print(response)431```432433```python customLanguage="pythonRequests"434import os435import requests436437url = "https://api.x.ai/v1/responses"438headers = {439 "Content-Type": "application/json",440 "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}"441}442payload = {443 "model": "grok-4.20-multi-agent",444 "input": [445 {446 "role": "user",447 "content": "Compare the major approaches to distributed consensus in computer science: Paxos, Raft, and Byzantine fault tolerance. Analyze the trade-offs in safety guarantees, performance, and implementation complexity."448 }449 ]450}451response = requests.post(url, headers=headers, json=payload)452print(response.json())453```454455```bash customLanguage="bash"456curl https://api.x.ai/v1/responses \457 -H "Content-Type: application/json" \458 -H "Authorization: Bearer $XAI_API_KEY" \459 -d '{460 "model": "grok-4.20-multi-agent",461 "input": [462 {463 "role": "user",464 "content": "Compare the major approaches to distributed consensus in computer science: Paxos, Raft, and Byzantine fault tolerance. Analyze the trade-offs in safety guarantees, performance, and implementation complexity."465 }466 ]467}'468```469470```typescript customLanguage="javascriptAISDK"471import { xai } from "@ai-sdk/xai";472import { generateText } from "ai";473474const { text } = await generateText({475 model: xai.responses("grok-4.20-multi-agent"),476 prompt:477 "Compare the major approaches to distributed consensus in computer science: Paxos, Raft, and Byzantine fault tolerance. Analyze the trade-offs in safety guarantees, performance, and implementation complexity.",478});479480console.log(text);481```482483### Multi-turn Conversation484485Multi-agent research supports multi-turn conversations using `previous_response_id`, just like any other model. You can ask follow-up questions to refine or expand on previous research results, and the agents will use the prior context to deliver more targeted answers.486487For the full multi-turn conversation pattern with reusable functions and code examples, see [Chaining the conversation](/developers/model-capabilities/text/generate-text#chaining-the-conversation).488489## Pricing490491All tokens consumed by both the **leader agent** and **sub-agents** are billed, including input tokens, output tokens, and reasoning tokens. Similarly, all **server-side tool calls** made by any agent — whether the leader or a sub-agent — count toward your tool usage and are billed accordingly.492493Because multiple agents may run in parallel and each can independently invoke tools, a single multi-agent request may use significantly more tokens and tool calls than a standard single-agent request. You can monitor your usage via the `usage` and `server_side_tool_usage` fields in the response.494495For detailed pricing information, see the [Pricing](/developers/pricing) page and the [Tool Pricing](/developers/pricing#tools-pricing) page.496497## Prompting Guide498499Getting the most out of multi-agent research starts with how you frame your request. Here are patterns that work well:500501**Set the scope and depth explicitly**502503Rather than asking a broad question, tell the agents exactly what dimensions to cover:504505```text506❌ "Tell me about electric vehicles."507✅ "Compare the top 3 EV manufacturers by battery technology, range, charging infrastructure, and 2025 sales projections."508```509510**Ask for structured output**511512Multi-agent research excels when you request organized, structured responses:513514```text515✅ "Research the pros and cons of microservices vs monolithic architecture. Present your findings as a comparison table with categories: scalability, complexity, deployment, and team size requirements."516```517518**Specify sources or perspectives**519520Guide the agents toward the types of evidence you value:521522```text523✅ "Analyze the environmental impact of large language model training, citing recent academic papers and industry reports from 2024-2025."524```525526**Break complex research into a conversation**527528For deep topics, start broad and narrow down with follow-ups rather than packing everything into one prompt:529530```text531Turn 1: "What are the leading approaches to carbon capture technology?"532Turn 2: "Which of those has the best cost-per-ton economics today?"533Turn 3: "What are the main engineering challenges preventing that approach from scaling?"534```535536**Provide context when relevant**537538If your research builds on prior knowledge or specific constraints, include that context in the prompt:539540```text541✅ "I'm building a fintech app targeting Southeast Asian markets. Research the regulatory requirements for digital payments in Singapore, Indonesia, and the Philippines."542```543544## Limitations545546* **Only leader agent output is exposed:** Only the leader agent's output is returned, including its tool calls and response content. Sub-agent state is encrypted and only included when `use_encrypted_content` is enabled — see [Output Behavior](#output-behavior) for details.547* **No client-side or custom tools:** Client-side tools (function calling) and custom tools are not currently supported by the multi-agent model variant. We do support a set of built-in tools (e.g., `web_search`, `x_search`) and remote MCP tools. See our [built-in tool docs](/developers/tools/overview) for more details.548* **Chat Completions API not supported:** The multi-agent model does **not** work with the OpenAI Chat Completions API. Use the [xAI SDK](https://github.com/xai-org/xai-sdk-python) or the [Responses API](/developers/model-capabilities/text/generate-text) instead.549* **`max_tokens` is not supported:** The `max_tokens` parameter is not currently supported by the multi-agent model variant.550