Multi-agent lets a model spin up and coordinate subagents in parallel, synthesizing their work to provide a final response. This is especially effective for applications with complex tasks that benefit from parallel work delegation, such as codebase exploration, documentation, and implementation.
Multi-agent is available in beta with GPT-6.2 Astra, GPT-6.2 Sol, GPT-6.1 Sol, and all GPT-5.6 models. Check the model page before enabling Multi-agent in your application.
Tasks can often be divided into independent sections of work that a single agent would complete sequentially, but multiple agents are able to tackle in parallel. Multi-agent enables a root agent to delegate to multiple subagents that complete work concurrently. This can provide multiple benefits:
- Parallel execution. Independent research, analysis, or implementation tasks can proceed at the same time, which can lead to faster execution.
- Focused context. Each subagent receives a bounded task and maintains its own context, which reduces interference in context between unrelated lines of work and improves performance.
- Model-directed coordination. The root agent can create subagents, send them additional information, wait for results, and synthesize a final answer without requiring your application to implement orchestration.
Multi-agent orchestration is most useful when a task can be divided into concrete, independent workstreams, such as:
- Exploring separate parts of a large codebase
- Comparing multiple proposals, documents, or hypotheses
- Researching several sources in parallel
- Implementing independent components or writing independent test suites
- Investigating different possible causes of a failure in parallel
- Exploring separate approaches to a problem concurrently
Note that adding subagents can increase token usage, and may not be as beneficial for tasks that depend on a single ordered chain of reasoning, require frequent writes to shared mutable state, or are already dominated by one slow external operation.
| Use Multi-agent when |
Prefer one agent when |
| Work can be split into independent, bounded tasks |
Each step depends directly on the previous step |
| Separate context improves focus |
The task is small enough to complete in one short run |
| Parallel exploration can reduce wall-clock time |
Agents would contend over the same mutable resource |
| Comparing independent findings improves coverage |
You require a fixed, deterministic execution graph |
The Python and TypeScript examples use the beta Responses SDK. For HTTP
requests, use client.beta.responses and pass responses_multi_agent=v1 in
the betas argument. For raw HTTP requests and WebSocket connections, pass
OpenAI-Beta: responses_multi_agent=v1 in the request or connection headers.
Item schemas may change while Multi-agent is in beta.
Enable Multi-agent in your Responses API request with multi_agent.enabled. When multi_agent.enabled is true, the root agent becomes eligible to spawn a tree of subagents. The subagents share the request’s model and available tools, while agents coordinate through collaboration primitives such as spawning, messaging, and waiting (see How Multi-agent works). The root agent is responsible for synthesizing subagent responses and providing the final response.
The Go examples use github.com/openai/openai-go/v3 at v3.99.0 and its
typed client.Beta.Responses API. HTTP requests set Betas to []string {"responses_multi_agent=v1"}. The WebSocket example uses
client.Beta.Responses.Connect and passes the beta header when opening the
connection. Its complete program reads the comparison prompt from standard
input.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import OpenAI from "openai";
const client = new OpenAI();
async function reviewPullRequest(diff: string) {
const response = await client.beta.responses.create({
model: "gpt-6.2-sol",
input:
"Review the pull-request diff below with three agents: one for " +
"correctness, one for security, and one for missing tests. " +
"Reconcile duplicate or conflicting findings, then return a " +
"prioritized review with file and line references.\n\n" +
`<diff>\n${diff}\n</diff>`,
multi_agent: {
enabled: true,
max_concurrent_subagents: 3,
},
betas: ["responses_multi_agent=v1"],
});
return response.output
.flatMap((item) =>
item.type === "message" &&
item.agent?.agent_name === "/root" &&
item.phase === "final_answer"
? item.content
: []
)
.filter((part) => part.type === "output_text")
.map((part) => part.text)
.join("");
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34from openai import OpenAI
client = OpenAI()
def review_pull_request(diff: str) -> str:
response = client.beta.responses.create(
model="gpt-6.2-sol",
input=(
"Review the pull-request diff below with three agents: one for "
"correctness, one for security, and one for missing tests. "
"Reconcile duplicate or conflicting findings, then return a "
"prioritized review with file and line references.\n\n"
f"<diff>\n{diff}\n</diff>"
),
multi_agent={
"enabled": True,
"max_concurrent_subagents": 3,
},
betas=["responses_multi_agent=v1"],
)
return "".join(
part.text
for item in response.output
if (
item.type == "message"
and item.agent is not None
and item.agent.agent_name == "/root"
and item.phase == "final_answer"
)
for part in item.content
if part.type == "output_text"
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26func reviewPullRequest(ctx context.Context, client openai.Client, diff string) (string, error) {
response, err := client.Beta.Responses.New(ctx, openai.BetaResponseNewParams{
Model: "gpt-6.2-sol",
Input: openai.BetaResponseNewParamsInputUnion{OfString: openai.String("Review the pull-request diff below with three agents: one for correctness, one for security, and one for missing tests. Reconcile duplicate or conflicting findings, then return a prioritized review with file and line references.\n\n<diff>\n" + diff + "\n</diff>")},
MultiAgent: openai.BetaResponseNewParamsMultiAgent{Enabled: true, MaxConcurrentSubagents: openai.Int(3)},
Betas: []string{"responses_multi_agent=v1"},
})
if err != nil {
return "", err
}
if response.Status != "completed" {
return "", fmt.Errorf("review did not complete: %s", response.Status)
}
var text strings.Builder
for _, item := range response.Output {
if item.Type != "message" || item.Agent.AgentName != "/root" || item.Phase != "final_answer" {
continue
}
for _, part := range item.AsMessage().Content {
if part.Type == "output_text" {
text.WriteString(part.Text)
}
}
}
return text.String(), nil
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20def review_pull_request(client, diff)
response = client.beta.responses.create(
model: "gpt-6.2-sol",
input: "Review the pull-request diff below with three agents: one for " \
"correctness, one for security, and one for missing tests. " \
"Reconcile duplicate or conflicting findings, then return a " \
"prioritized review with file and line references.\n\n<diff>\n#{diff}\n</diff>",
multi_agent: {
enabled: true,
max_concurrent_subagents: 3
},
betas: ["responses_multi_agent=v1"]
)
response.output.filter_map do |item|
next unless item.type == :message && item.agent&.agent_name == "/root" && item.phase == :final_answer
item.content.filter_map { |part| part.text if part.type == :output_text }.join
end.join
end
max_concurrent_subagents sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent.
The API does not impose a fixed upper bound on this setting. The default is 3, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run.
Add a developer message to tune when the root model should spawn subagents. This developer message is additive to the instructions injected for the root agent and subagents.
Examples of developer messages include:
- “Do not spawn subagents unless the user explicitly asks for subagents, delegation, or parallel agent work.”
- “Proactive Multi-agent delegation is active. Use subagents when parallel work would materially improve speed or quality.”
The Responses API provides the root and subagent models with hosted orchestration actions and instructions for using them. The root agent is named /root. Spawned subagents use hierarchical paths such as:
/root
├── /root/researcher
├── /root/reviewer
└── /root/reviewer/tester
Multi-agent imposes no fixed limit on the total number of subagents or tree depth. For most tasks, use the default max_concurrent_subagents value of 3. This setting limits the number of active subagent turns across the entire tree, including children and deeper descendants.
When Multi-agent mode is enabled, the Responses API provides six hosted collaboration actions. You may see these as multi_agent_call items. Your application should not execute these or submit outputs for them.
| Action |
Purpose |
spawn_agent |
Create a subagent and assign its initial task. |
send_message |
Queue a message for an existing agent without starting a new turn. |
followup_task |
Assign more work to an existing non-root agent and start or resume its turn. |
wait_agent |
Wait for an update in the calling agent’s mailbox. |
interrupt_agent |
Interrupt another agent’s active turn without deleting its context. |
list_agents |
Return the current agent tree, statuses, and each agent’s last_task_message. |
Handling developer-defined tool calls works in the same way as without Multi-agent enabled. Any agent in the tree may emit a function_call. Your application must execute the call and submit a matching function_call_output.
Note that all agents in the tree have access to the tools configured in the API request’s model call.
HTTP and WebSocket support the same Multi-agent capabilities, but WebSocket is recommended for tool-heavy or long-running workflows. Its persistent connection lets your application return function outputs as they become available, reducing continuation overhead and allowing agents to spend less time waiting.
With HTTP, the response completes once every active agent has either finished or paused to wait for a client-executed function call. Your application then executes all outstanding function calls and submits their outputs in a new Responses API request, allowing the paused agents to resume.
With WebSocket, your application can inject each function output into the response as soon as it becomes available, without waiting for the active response to complete. The waiting agent can resume immediately while other agents continue working. This reduces coordination delays and avoids extra request round trips when agents finish or request tools at different times.
HTTP may be sufficient for workflows that require calling multiple hosted tools, such as parallel web searches, or one-request workflows with few function calls. For most Multi-agent workflows, WebSocket is likely to provide lower latency and better end-to-end performance.


These examples require beta SDK builds that expose the beta Responses API. For HTTP streaming, call client.beta.responses.create and pass responses_multi_agent=v1 with the betas argument; this enables beta types and autocomplete. In Python, import beta response item types from openai.types.beta when adding type annotations.
Example client-side code:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121import OpenAI from "openai";
const client = new OpenAI();
const ROOT = "/root";
const proposals = {
alpha: { estimated_weeks: 6, risk: "medium" },
beta: { estimated_weeks: 8, risk: "low" },
};
const tools: OpenAI.Beta.Responses.BetaTool[] = [
{
type: "function",
name: "get_proposal",
description:
"Return details for a proposal that the agents should compare.",
parameters: {
type: "object",
properties: {
proposal: {
type: "string",
enum: ["alpha", "beta"],
},
},
required: ["proposal"],
additionalProperties: false,
},
strict: true,
},
];
const history: (
| OpenAI.Beta.Responses.BetaResponseInputItem
| OpenAI.Beta.Responses.BetaResponseOutputItem
)[] = [
{
role: "user",
content: "Compare proposal alpha and proposal beta.",
},
];
function agentName(item: OpenAI.Beta.Responses.BetaResponseOutputItem) {
return item.agent?.agent_name ?? ROOT;
}
function processToolCall(name: string, argumentsJson: string) {
if (name !== "get_proposal") {
throw new Error(`Unknown tool: ${name}`);
}
const { proposal }: { proposal: unknown } = JSON.parse(argumentsJson);
if (proposal !== "alpha" && proposal !== "beta")
throw new Error(`Unknown proposal: ${proposal}`);
return JSON.stringify(proposals[proposal]);
}
while (true) {
let outputItems: OpenAI.Beta.Responses.BetaResponseOutputItem[] = [];
let completed = false;
const itemAgents = new Map();
const stream = await client.beta.responses.create({
model: "gpt-6.2-sol",
// HTTP tool results arrive in the next request. Waiting for an agent that
// needs those results would prevent this response from ending.
instructions:
"Use separate subagents to look up each proposal. After spawning them, " +
"finish your own turn without calling wait_agent so the HTTP caller can " +
"supply their get_proposal results. When those results are present in " +
"the conversation, compare the subagents' findings and give the final answer.",
// Replay Beta output unchanged, including agent metadata. The SDK input
// union is narrower than the agent_message content returned by the API.
input: history as OpenAI.Beta.Responses.BetaResponseInput,
tools,
store: false,
multi_agent: {
enabled: true,
max_concurrent_subagents: 3,
},
stream: true,
betas: ["responses_multi_agent=v1"],
});
for await (const event of stream) {
if (event.type === "response.output_item.added") {
itemAgents.set(event.output_index, agentName(event.item));
} else if (event.type === "response.output_text.delta") {
const agent = itemAgents.get(event.output_index) ?? ROOT;
const destination = agent === ROOT ? process.stdout : process.stderr;
destination.write(
agent === ROOT ? event.delta : `[${agent}] ${event.delta}`
);
} else if (event.type === "response.completed") {
// The completed response includes hosted-agent replay items that may not
// appear as individual output_item.done events.
outputItems = event.response.output;
completed = true;
console.error("\nUsage:", event.response.usage);
} else if (
event.type === "error" ||
event.type === "response.failed" ||
event.type === "response.incomplete"
) {
throw new Error(JSON.stringify(event));
}
}
if (!completed) throw new Error("Stream ended before the response completed");
const pendingCalls = outputItems.filter(
(item) => item.type === "function_call"
);
history.push(...outputItems);
for (const call of pendingCalls) {
history.push({
type: "function_call_output",
call_id: call.call_id,
output: processToolCall(call.name, call.arguments),
});
}
if (pendingCalls.length === 0) break;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125from __future__ import annotations
import json
import sys
from openai import OpenAI
from openai.types.beta import BetaResponseOutputItem
client = OpenAI()
ROOT = "/root"
PROPOSALS = {
"alpha": {"estimated_weeks": 6, "risk": "medium"},
"beta": {"estimated_weeks": 8, "risk": "low"},
}
tools = [
{
"type": "function",
"name": "get_proposal",
"description": "Return details for a proposal that the agents should compare.",
"parameters": {
"type": "object",
"properties": {
"proposal": {
"type": "string",
"enum": ["alpha", "beta"],
}
},
"required": ["proposal"],
"additionalProperties": False,
},
"strict": True,
}
]
history = [
{
"role": "user",
"content": (
"Use two subagents, one for proposal alpha and one for proposal beta. "
"Have each call get_proposal, then compare their findings."
),
}
]
def agent_name(item: BetaResponseOutputItem) -> str:
return item.agent.agent_name if item.agent else ROOT
def render_to_user(delta: str) -> None:
print(delta, end="", flush=True)
def log_subagent_text(agent: str, delta: str) -> None:
print(f"[{agent}] {delta}", end="", file=sys.stderr, flush=True)
def process_tool_call(name: str, arguments: str) -> str:
if name != "get_proposal":
raise ValueError(f"Unknown tool: {name}")
parsed_arguments = json.loads(arguments)
return json.dumps(PROPOSALS[parsed_arguments["proposal"]])
while True:
output_items = []
pending_calls = []
item_agents: dict[int, str] = {}
completed = False
with client.beta.responses.create(
model="gpt-6.2-sol",
instructions=(
"After launching both subagents, call get_proposal for alpha yourself "
"before waiting for their findings. Use that direct result to check the final comparison."
),
input=history,
tools=tools,
store=False,
multi_agent={
"enabled": True,
"max_concurrent_subagents": 3,
},
stream=True,
betas=["responses_multi_agent=v1"],
) as stream:
for event in stream:
if event.type == "response.output_item.added":
item_agents[event.output_index] = agent_name(event.item)
elif event.type == "response.output_text.delta":
agent = item_agents.get(event.output_index, ROOT)
if agent == ROOT:
render_to_user(event.delta)
else:
log_subagent_text(agent, event.delta)
elif event.type == "response.output_item.done":
output_items.append(event.item)
if event.item.type == "function_call":
# Handle function calls from both the root agent and subagents.
pending_calls.append(event.item)
elif event.type == "response.completed":
print(f"\nUsage: {event.response.usage}", file=sys.stderr)
completed = True
elif event.type in {
"error",
"response.failed",
"response.incomplete",
}:
raise RuntimeError(event)
if not completed:
raise RuntimeError("Stream ended without a completed response")
history.extend(output_items)
for call in pending_calls:
history.append(
{
"type": "function_call_output",
"call_id": call.call_id,
"output": process_tool_call(call.name, call.arguments),
}
)
if not pending_calls:
break
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120package main
import (
"context"
"encoding/json"
"fmt"
"log"
"os"
"time"
"github.com/openai/openai-go/v3"
)
func run(ctx context.Context) error {
client := openai.NewClient()
proposals := map[string]any{"alpha": map[string]any{"estimated_weeks": 6, "risk": "medium"}, "beta": map[string]any{"estimated_weeks": 8, "risk": "low"}}
tools := []openai.BetaToolUnionParam{{OfFunction: &openai.BetaFunctionToolParam{
Name: "get_proposal", Description: openai.String("Return details for a proposal that the agents should compare."), Strict: openai.Bool(true),
Parameters: map[string]any{"type": "object", "properties": map[string]any{"proposal": map[string]any{"type": "string", "enum": []string{"alpha", "beta"}}}, "required": []string{"proposal"}, "additionalProperties": false},
}}}
history := []openai.BetaResponseInputItemUnionParam{{OfMessage: &openai.BetaEasyInputMessageParam{Role: "user", Content: openai.BetaEasyInputMessageContentUnionParam{OfString: openai.String("Use two subagents, one for proposal alpha and one for proposal beta. Have each call get_proposal, then compare their findings.")}}}}
for {
stream := client.Beta.Responses.NewStreaming(ctx, openai.BetaResponseNewParams{
Model: "gpt-6.2-sol", Input: openai.BetaResponseNewParamsInputUnion{OfInputItemList: history}, Tools: tools, Store: openai.Bool(false),
Instructions: openai.String("After launching both subagents, call get_proposal for alpha yourself before waiting for their findings. Use that direct result to check the final comparison."),
MultiAgent: openai.BetaResponseNewParamsMultiAgent{Enabled: true, MaxConcurrentSubagents: openai.Int(3)}, Betas: []string{"responses_multi_agent=v1"},
})
completed := false
agents := map[int64]string{}
var outputs []openai.BetaResponseOutputItemUnion
var calls []openai.BetaResponseFunctionToolCall
for stream.Next() {
event := stream.Current()
switch event.Type {
case "response.output_item.added":
agent := event.Item.Agent.AgentName
if agent == "" {
agent = "/root"
}
agents[event.OutputIndex] = agent
case "response.output_text.delta":
agent := agents[event.OutputIndex]
if agent == "" {
agent = "/root"
}
if agent == "/root" {
fmt.Print(event.Delta)
} else {
fmt.Fprintf(os.Stderr, "[%s] %s", agent, event.Delta)
}
case "response.output_item.done":
outputs = append(outputs, event.Item)
if event.Item.Type == "function_call" {
calls = append(calls, event.Item.AsFunctionCall())
}
case "response.completed":
completed = true
usage, err := json.Marshal(event.Response.Usage)
if err != nil {
stream.Close()
return err
}
fmt.Fprintf(os.Stderr, "\nUsage: %s\n", usage)
case "error", "response.failed", "response.incomplete":
stream.Close()
return fmt.Errorf("multi-agent response failed: %s", event.RawJSON())
}
}
err := stream.Err()
stream.Close()
if err != nil {
return err
}
if !completed {
return fmt.Errorf("stream ended without a completed response")
}
// Keep every agent's output, including attribution and encrypted reasoning.
for _, item := range outputs {
var input openai.BetaResponseInputItemUnionParam
if item.Type == "message" {
// Select the output-message variant to retain agent attribution.
message := item.AsMessage().ToParam()
input.OfOutputMessage = &message
} else if err := json.Unmarshal([]byte(item.RawJSON()), &input); err != nil {
return err
}
history = append(history, input)
}
for _, call := range calls {
if call.Name != "get_proposal" {
return fmt.Errorf("unknown tool: %s", call.Name)
}
var args struct {
Proposal string `json:"proposal"`
}
if err := json.Unmarshal([]byte(call.Arguments), &args); err != nil {
return err
}
proposal, ok := proposals[args.Proposal]
if !ok {
return fmt.Errorf("unknown proposal: %s", args.Proposal)
}
output, err := json.Marshal(proposal)
if err != nil {
return err
}
history = append(history, openai.BetaResponseInputItemUnionParam{OfFunctionCallOutput: &openai.BetaResponseInputItemFunctionCallOutputParam{CallID: openai.String(call.CallID), Output: openai.BetaResponseInputItemFunctionCallOutputOutputUnionParam{OfString: openai.String(string(output))}}})
}
if len(calls) == 0 {
return nil
}
}
}
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 4*time.Minute)
defer cancel()
if err := run(ctx); err != nil {
log.Fatal(err)
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106require "openai"
require "json"
client = OpenAI::Client.new
proposals = {
"alpha" => {
estimated_weeks: 6,
risk: "medium"
},
"beta" => {
estimated_weeks: 8,
risk: "low"
}
}
tools = [
{
type: :function,
name: "get_proposal",
description: "Return details for a proposal that the agents should compare.",
parameters: {
type: "object",
properties: {
proposal: {
type: "string",
enum: ["alpha", "beta"]
}
},
required: ["proposal"],
additionalProperties: false
},
strict: true
}
]
history = [
{
role: :user,
content: "Use two subagents, one for proposal alpha and one for proposal beta. " \
"Have each call get_proposal, then compare their findings."
}
]
loop do
output_items = []
pending_calls = []
item_agents = {}
state = { completed: false }
stream = client.beta.responses.stream_raw(
model: "gpt-6.2-sol", input: history, tools: tools, store: false,
instructions: "After launching both subagents, call get_proposal for alpha yourself " \
"before waiting for their findings. Use that direct result to check the final comparison.",
multi_agent: {
enabled: true,
max_concurrent_subagents: 3
},
betas: ["responses_multi_agent=v1"]
)
begin
stream.each do |event|
case event
when OpenAI::Models::Beta::BetaResponseOutputItemAddedEvent
item_agents[event.output_index] = event.item.agent&.agent_name || "/root"
when OpenAI::Models::Beta::BetaResponseTextDeltaEvent
agent = item_agents.fetch(event.output_index, "/root")
if agent == "/root"
$stdout.print(event.delta)
$stdout.flush
else
$stderr.print("[#{agent}] #{event.delta}")
$stderr.flush
end
when OpenAI::Models::Beta::BetaResponseOutputItemDoneEvent
output_items << event.item
pending_calls << event.item if event.item.is_a?(OpenAI::Models::Beta::BetaResponseFunctionToolCall)
when OpenAI::Models::Beta::BetaResponseCompletedEvent
state[:completed] = true
warn("\nUsage: #{event.response.usage.to_json}")
when OpenAI::Models::Beta::BetaResponseErrorEvent,
OpenAI::Models::Beta::BetaResponseFailedEvent,
OpenAI::Models::Beta::BetaResponseIncompleteEvent
raise "Multi-agent response failed: #{event.type}"
end
end
ensure
stream.close
end
raise "Stream ended without a completed response" unless state[:completed]
# Preserve every output item, including subagent calls, for the next turn.
history.concat(output_items)
pending_calls.each do |call|
raise "Unknown tool: #{call.name}" unless call.name == "get_proposal"
proposal = JSON.parse(call.arguments).fetch("proposal")
history << {
type: :function_call_output,
call_id: call.call_id,
output: JSON.generate(proposals.fetch(proposal))
}
end
break if pending_calls.empty?
end
If one or more agents call developer-defined functions, execute every pending call and create a continuation request containing their outputs.
In WebSocket mode, when an agent calls a developer-defined function, execute the function in your application and send its result to the active response with a response.inject event. The waiting agent can then resume without waiting for the entire Multi-agent response to complete.
1234567891011{
"type": "response.inject",
"response_id": "resp_123",
"input": [
{
"type": "function_call_output",
"call_id": "call_123",
"output": "{\"temperature\":72}"
}
]
}
For a valid response.inject request, the server replies with one of two events:
response.inject.created: the input was validated and accepted for injection
response.inject.failed: the input was not injected; inspect error.code
12345{
"type": "response.inject.created",
"sequence_number": 42,
"response_id": "resp_123"
}
12345678910111213141516{
"type": "response.inject.failed",
"sequence_number": 43,
"response_id": "resp_123",
"input": [
{
"type": "function_call_output",
"call_id": "call_123",
"output": "{\"temperature\":72}"
}
],
"error": {
"code": "response_already_completed",
"message": "Response 'resp_123' has already completed."
}
}
If a request doesn’t conform to the response.inject schema, the server sends a generic error with status 400 and closes the WebSocket connection. Fix the request and open a new WebSocket connection before sending another event.
The Python beta SDK exposes WebSocket mode through client.beta.responses.connect. The TypeScript beta SDK exposes it through ResponsesWS. Pass OpenAI-Beta: responses_multi_agent=v1 in the connection headers; unlike HTTP streaming, the WebSocket connectors do not yet accept the betas argument.
Save the response ID from the response.created event and include it in every response.inject event you send for that response. After sending an injection item, continue reading from the WebSocket until the response has completed and every injection has produced either a response.inject.created or response.inject.failed event.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148import OpenAI from "openai";
import { ResponsesWS } from "openai/resources/beta/responses/ws";
const client = new OpenAI();
const proposals = {
alpha: { estimated_weeks: 6, risk: "medium" },
beta: { estimated_weeks: 8, risk: "low" },
};
const tools: OpenAI.Beta.Responses.BetaTool[] = [
{
type: "function",
name: "get_proposal",
description:
"Return details for a proposal that the agents should compare.",
parameters: {
type: "object",
properties: {
proposal: {
type: "string",
enum: ["alpha", "beta"],
},
},
required: ["proposal"],
additionalProperties: false,
},
strict: true,
},
];
function processToolCall(name: string, argumentsJson: string) {
if (name !== "get_proposal") {
throw new Error(`Unknown tool: ${name}`);
}
const { proposal }: { proposal: unknown } = JSON.parse(argumentsJson);
if (proposal !== "alpha" && proposal !== "beta")
throw new Error(`Unknown proposal: ${proposal}`);
return JSON.stringify(proposals[proposal]);
}
async function runMultiAgent(ws: ResponsesWS) {
let previousResponseId;
let pendingInput: OpenAI.Beta.Responses.BetaResponseInput = [
{ role: "user", content: process.argv.slice(2).join(" ") },
];
while (pendingInput.length > 0) {
ws.send({
type: "response.create",
model: "gpt-6.2-sol",
store: true,
multi_agent: {
enabled: true,
max_concurrent_subagents: 3,
},
tools,
input: pendingInput,
previous_response_id: previousResponseId,
});
const nextInput = [];
let completedResponse;
let responseId;
let pendingInjections = 0;
for await (const message of ws) {
if (message.type === "error") throw message.error;
if (message.type !== "message") continue;
const event = message.message;
if (event.type === "response.created") {
responseId = event.response.id;
} else if (
event.type === "response.output_item.done" &&
event.item.type === "function_call"
) {
if (!responseId) {
throw new Error("Received a function call before response.created");
}
pendingInjections += 1;
ws.send({
type: "response.inject",
response_id: responseId,
input: [
{
type: "function_call_output",
call_id: event.item.call_id,
output: processToolCall(event.item.name, event.item.arguments),
},
],
});
} else if (event.type === "response.inject.created") {
pendingInjections -= 1;
} else if (event.type === "response.inject.failed") {
pendingInjections -= 1;
if (event.error.code !== "response_already_completed") {
throw new Error(JSON.stringify(event.error));
}
nextInput.push(...event.input);
} else if (event.type === "response.completed") {
completedResponse = event.response;
} else if (
event.type === "error" ||
event.type === "response.failed" ||
event.type === "response.incomplete"
) {
throw new Error(JSON.stringify(event));
}
if (completedResponse && pendingInjections === 0) break;
}
if (!completedResponse) {
throw new Error("Connection ended before response.completed");
}
if (pendingInjections !== 0) {
throw new Error("Connection ended with unacknowledged tool results");
}
if (nextInput.length === 0) return completedResponse;
previousResponseId = completedResponse.id;
pendingInput = nextInput;
}
throw new Error("The response ended without a result.");
}
const ws = new ResponsesWS(client, {
headers: { "OpenAI-Beta": "responses_multi_agent=v1" },
});
try {
const response = await runMultiAgent(ws);
const text = response.output
.flatMap((item) =>
item.type === "message" &&
item.agent?.agent_name === "/root" &&
item.phase === "final_answer"
? item.content
: []
)
.filter((part) => part.type === "output_text")
.map((part) => part.text)
.join("");
console.log(text);
} finally {
ws.close();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146from __future__ import annotations
import json
from openai import OpenAI
client = OpenAI()
PROPOSALS = {
"alpha": {"estimated_weeks": 6, "risk": "medium"},
"beta": {"estimated_weeks": 8, "risk": "low"},
}
tools = [
{
"type": "function",
"name": "get_proposal",
"description": "Return details for a proposal that the agents should compare.",
"parameters": {
"type": "object",
"properties": {
"proposal": {
"type": "string",
"enum": ["alpha", "beta"],
}
},
"required": ["proposal"],
"additionalProperties": False,
},
"strict": True,
}
]
def process_tool_call(name: str, arguments: str) -> str:
if name != "get_proposal":
raise ValueError(f"Unknown tool: {name}")
parsed_arguments = json.loads(arguments)
return json.dumps(PROPOSALS[parsed_arguments["proposal"]])
def run_multi_agent(connection):
previous_response_id: str | None = None
pending_input: list[dict[str, object]] = [{"role": "user", "content": input()}]
while pending_input:
request = {
"type": "response.create",
"model": "gpt-6.2-sol",
"store": True,
"multi_agent": {"enabled": True},
"tools": tools,
"input": pending_input,
}
if previous_response_id is not None:
request["previous_response_id"] = previous_response_id
connection.send(request)
next_input: list[dict[str, object]] = []
completed_response = None
response_id: str | None = None
pending_injections = 0
for event in connection:
event_type = event.type
if event_type == "response.created":
response_id = event.response.id
elif event_type == "response.output_item.done":
item = event.item
if item.type == "function_call":
if response_id is None:
raise RuntimeError(
"Received a function call before response.created"
)
output = {
"type": "function_call_output",
"call_id": item.call_id,
"output": process_tool_call(item.name, item.arguments),
}
pending_injections += 1
connection.send(
{
"type": "response.inject",
"response_id": response_id,
"input": [output],
}
)
elif event_type == "response.inject.created":
pending_injections -= 1
elif event_type == "response.inject.failed":
pending_injections -= 1
if event.error.code != "response_already_completed":
raise RuntimeError(event.error)
next_input.extend(item.model_dump(mode="json") for item in event.input)
elif event_type == "response.completed":
completed_response = event.response
elif event_type in {
"error",
"response.failed",
"response.incomplete",
}:
raise RuntimeError(event)
if completed_response is not None and pending_injections == 0:
break
if completed_response is None:
raise RuntimeError("Connection ended before response.completed")
if pending_injections:
raise RuntimeError("Connection ended with unacknowledged tool results")
if not next_input:
return completed_response
previous_response_id = completed_response.id
pending_input = next_input
with client.beta.responses.connect(
extra_headers={"OpenAI-Beta": "responses_multi_agent=v1"},
) as connection:
response = run_multi_agent(connection)
print(
"".join(
part.text
for item in response.output
if (
item.type == "message"
and item.agent is not None
and item.agent.agent_name == "/root"
and item.phase == "final_answer"
)
for part in item.content
if part.type == "output_text"
)
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159package main
import (
"bufio"
"context"
"encoding/json"
"fmt"
"log"
"os"
"strings"
"time"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/option"
)
func toolOutput(call openai.BetaResponseFunctionToolCall) (openai.BetaResponseInputItemUnionParam, error) {
var zero openai.BetaResponseInputItemUnionParam
if call.Name != "get_proposal" {
return zero, fmt.Errorf("unknown tool: %s", call.Name)
}
var args struct {
Proposal string `json:"proposal"`
}
if err := json.Unmarshal([]byte(call.Arguments), &args); err != nil {
return zero, err
}
proposals := map[string]any{"alpha": map[string]any{"estimated_weeks": 6, "risk": "medium"}, "beta": map[string]any{"estimated_weeks": 8, "risk": "low"}}
value, ok := proposals[args.Proposal]
if !ok {
return zero, fmt.Errorf("unknown proposal: %s", args.Proposal)
}
output, err := json.Marshal(value)
if err != nil {
return zero, err
}
return openai.BetaResponseInputItemUnionParam{OfFunctionCallOutput: &openai.BetaResponseInputItemFunctionCallOutputParam{CallID: openai.String(call.CallID), Output: openai.BetaResponseInputItemFunctionCallOutputOutputUnionParam{OfString: openai.String(string(output))}}}, nil
}
func runMultiAgent(ctx context.Context, connection *openai.BetaResponseConnection, prompt string) (*openai.BetaResponse, error) {
tools := []openai.BetaToolUnionParam{{OfFunction: &openai.BetaFunctionToolParam{Name: "get_proposal", Description: openai.String("Return details for a proposal that the agents should compare."), Strict: openai.Bool(true), Parameters: map[string]any{"type": "object", "properties": map[string]any{"proposal": map[string]any{"type": "string", "enum": []string{"alpha", "beta"}}}, "required": []string{"proposal"}, "additionalProperties": false}}}}
input := openai.BetaResponseInputParam{{OfMessage: &openai.BetaEasyInputMessageParam{Role: "user", Content: openai.BetaEasyInputMessageContentUnionParam{OfString: openai.String(prompt)}}}}
previous := ""
for len(input) > 0 {
request := openai.BetaResponsesClientEventResponseCreateParam{Model: "gpt-6.2-sol", Store: openai.Bool(true), MultiAgent: openai.BetaResponsesClientEventResponseCreateMultiAgentParam{Enabled: true}, Tools: tools, Input: openai.BetaResponsesClientEventResponseCreateInputUnionParam{OfResponse: &input}}
if previous != "" {
request.PreviousResponseID = openai.String(previous)
}
if err := connection.Send(ctx, openai.BetaResponsesClientEventUnionParam{OfResponseCreate: &request}); err != nil {
return nil, err
}
responseID := ""
pending := 0
var completed *openai.BetaResponse
var retry []openai.BetaResponseInputItemUnionParam
for completed == nil || pending != 0 {
event, err := connection.Recv(ctx)
if err != nil {
return nil, fmt.Errorf("connection ended before completion and injection acknowledgements: %w", err)
}
switch event.Type {
case "response.created":
responseID = event.AsResponseCreated().Response.ID
case "response.output_item.done":
item := event.AsResponseOutputItemDone().Item
if item.Type != "function_call" {
continue
}
if responseID == "" {
return nil, fmt.Errorf("function call arrived before response creation")
}
output, err := toolOutput(item.AsFunctionCall())
if err != nil {
return nil, err
}
pending++
if err := connection.Send(ctx, openai.BetaResponsesClientEventUnionParam{OfResponseInject: &openai.BetaResponseInjectEventParam{ResponseID: responseID, Input: []openai.BetaResponseInputItemUnionParam{output}}}); err != nil {
return nil, err
}
case "response.inject.created":
ack := event.AsBetaResponseInjectCreatedEvent()
if responseID == "" || ack.ResponseID != responseID || pending == 0 {
return nil, fmt.Errorf("unexpected injection acknowledgement")
}
pending--
case "response.inject.failed":
ack := event.AsBetaResponseInjectFailedEvent()
if responseID == "" || ack.ResponseID != responseID || pending == 0 {
return nil, fmt.Errorf("unexpected injection acknowledgement")
}
pending--
if ack.Error.Code != "response_already_completed" {
return nil, fmt.Errorf("injection failed: %s", ack.Error.Code)
}
for _, item := range ack.Input {
var value openai.BetaResponseInputItemUnionParam
if err := json.Unmarshal([]byte(item.RawJSON()), &value); err != nil {
return nil, err
}
retry = append(retry, value)
}
case "response.completed":
response := event.AsResponseCompleted().Response
if responseID == "" || response.ID != responseID {
return nil, fmt.Errorf("unexpected response completion")
}
completed = &response
case "error", "response.failed", "response.incomplete":
return nil, fmt.Errorf("multi-agent response failed: %s", event.RawJSON())
}
}
if len(retry) == 0 {
return completed, nil
}
previous = completed.ID
input = retry
}
return nil, fmt.Errorf("no response was created")
}
func run(ctx context.Context) error {
scanner := bufio.NewScanner(os.Stdin)
if !scanner.Scan() {
if err := scanner.Err(); err != nil {
return err
}
return fmt.Errorf("expected a prompt on stdin")
}
client := openai.NewClient()
connection, err := client.Beta.Responses.Connect(ctx, openai.BetaResponseConnectionOptions{}, option.WithQuery("beta", "true"), option.WithHeader("OpenAI-Beta", "responses_multi_agent=v1"))
if err != nil {
return err
}
defer connection.Close()
response, err := runMultiAgent(ctx, connection, scanner.Text())
if err != nil {
return err
}
var text strings.Builder
for _, item := range response.Output {
if item.Type != "message" || item.Agent.AgentName != "/root" || item.Phase != "final_answer" {
continue
}
for _, part := range item.AsMessage().Content {
if part.Type == "output_text" {
text.WriteString(part.Text)
}
}
}
fmt.Println(text.String())
return nil
}
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 4*time.Minute)
defer cancel()
if err := run(ctx); err != nil {
log.Fatal(err)
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141require "async"
require "async/http/endpoint"
require "async/websocket/client"
require "json"
PROPOSALS = {
"alpha" => {
estimated_weeks: 6,
risk: "medium"
},
"beta" => {
estimated_weeks: 8,
risk: "low"
}
}.freeze
def process_tool_call(name, arguments)
raise "Unknown tool: #{name}" unless name == "get_proposal"
JSON.generate(PROPOSALS.fetch(JSON.parse(arguments).fetch("proposal")))
end
def run_multi_agent(connection, tools)
state = {
previous: nil,
input: [
{
role: "user",
content: $stdin.readline.chomp
}
]
}
until state[:input].empty?
request = {
type: "response.create",
model: "gpt-6.2-sol",
store: true,
multi_agent: { enabled: true },
tools: tools,
input: state[:input]
}
request[:previous_response_id] = state[:previous] if state[:previous]
connection.write(JSON.generate(request))
connection.flush
round = {
response_id: nil,
completed: nil,
pending: 0,
retry: []
}
while (message = connection.read)
event = JSON.parse(message.to_str)
case event.fetch("type")
when "response.created"
round[:response_id] = event.fetch("response").fetch("id")
when "response.output_item.done"
item = event.fetch("item")
if item["type"] == "function_call"
raise "Function call arrived before response creation" unless round[:response_id]
output = {
type: "function_call_output",
call_id: item.fetch("call_id"),
output: process_tool_call(item.fetch("name"), item.fetch("arguments"))
}
round[:pending] += 1
connection.write(JSON.generate(type: "response.inject", response_id: round[:response_id], input: [output]))
connection.flush
end
when "response.inject.created", "response.inject.failed"
unless event.fetch("response_id") == round[:response_id] && round[:pending].positive?
raise "Unexpected injection acknowledgement"
end
round[:pending] -= 1
if event["type"] == "response.inject.failed"
raise "Injection failed: #{event.fetch("error")}" unless event.fetch("error").fetch("code") == "response_already_completed"
round[:retry].concat(event.fetch("input"))
end
when "response.completed"
round[:completed] = event.fetch("response")
when "error", "response.failed", "response.incomplete"
raise "Multi-agent response failed: #{event}"
end
break if round[:completed] && round[:pending].zero?
end
raise "Connection closed before response completion" unless round[:completed]
raise "Connection closed with unacknowledged results" unless round[:pending].zero?
return round[:completed] if round[:retry].empty?
state[:previous] = round[:completed].fetch("id")
state[:input] = round[:retry]
end
raise "No response was created"
end
tools = [
{
type: "function",
name: "get_proposal",
description: "Return details for a proposal that the agents should compare.",
parameters: {
type: "object",
properties: {
proposal: {
type: "string",
enum: ["alpha", "beta"]
}
},
required: ["proposal"],
additionalProperties: false
},
strict: true
}
]
base = ENV.fetch("OPENAI_BASE_URL", "https://api.openai.com/v1").sub(%r{/+\z}, "")
endpoint = Async::HTTP::Endpoint.parse("#{base.sub(/\Ahttp/, "ws")}/responses?beta=true", timeout: 30, alpn_protocols: ["http/1.1"])
headers = {
"Authorization" => "Bearer #{ENV.fetch("OPENAI_API_KEY")}",
"OpenAI-Beta" => "responses_multi_agent=v1"
}
Sync do |task|
task.with_timeout(240) do
Async::WebSocket::Client.connect(endpoint, headers: headers) do |connection|
response = run_multi_agent(connection, tools)
text = response.fetch("output").select do |item|
item["type"] == "message" && item.dig("agent", "agent_name") == "/root" && item["phase"] == "final_answer"
end.flat_map { |item| item.fetch("content") }.select { |part| part["type"] == "output_text" }.map { |part| part.fetch("text") }.join
puts text
end
end
end
After sending a response.inject event, keep reading from the WebSocket and handle the acknowledgement:
response.inject.created: The function output was added to the active response. Continue reading events for that response.
response.inject.failed with response_already_completed: The response completed before the function output could be added. Take the input returned in the failure event and send it in a new response.create request that continues from the completed response.
response.inject.failed with response_not_found: The server could not find the response identified by response_id. Verify that you are using the ID received from response.created.
A single Multi-agent run may span multiple Responses API requests. Over HTTP, when an agent calls a developer-defined function, your application executes the function and submits its output in a new response.create call. Over WebSocket, your application instead injects the function output into the active response.
Multi-agent responses can include three additional output item types:
multi_agent_call: records a hosted Multi-agent action, such as spawn_agent.
multi_agent_call_output: contains the result from execution of a hosted action.
agent_message: carries an encrypted message from one agent to another.
The call_id field links each multi_agent_call to its corresponding multi_agent_call_output.
Each item also includes an agent attribute. For an agent_message, agent.agent_name identifies the recipient agent. Use author and recipient to trace the message direction.
When your application receives a multi_agent_call, do not execute it as a function call or send back a result. The Responses API executes the hosted action and returns the corresponding multi_agent_call_output. Preserve both items if your application needs them for replay or tracing.
1234567891011121314151617181920212223242526272829303132333435363738[
{
"type": "multi_agent_call",
"id": "mac_123",
"call_id": "call_spawn_a",
"action": "spawn_agent",
"arguments": "{\"task_name\":\"agent_a\",\"fork_turns\":\"all\",\"message\":\"enc_...\"}",
"agent": { "agent_name": "/root" }
},
{
"type": "multi_agent_call_output",
"id": "maco_123",
"call_id": "call_spawn_a",
"action": "spawn_agent",
"output": [
{
"type": "output_text",
"text": "{\"task_name\":\"/root/agent_a\"}",
"annotations": [],
"logprobs": []
}
],
"agent": { "agent_name": "/root" }
},
{
"type": "agent_message",
"id": "amsg_123",
"author": "/root/agent_a",
"recipient": "/root",
"content": [
{
"type": "encrypted_content",
"encrypted_content": "enc_..."
}
],
"agent": { "agent_name": "/root" }
}
]
Agent-attributed SSE events include a top-level agent attribute. For an agent_message event, agent.agent_name identifies the recipient agent. Response lifecycle events such as response.created and response.completed describe the overall response rather than an individual agent, so they do not include an agent attribute.
1234567891011121314151617{
"type": "response.output_item.done",
"agent": { "agent_name": "/root" },
"item": {
"type": "agent_message",
"id": "amsg_123",
"author": "/root/agent_a",
"recipient": "/root",
"content": [
{
"type": "encrypted_content",
"encrypted_content": "enc_..."
}
],
"agent": { "agent_name": "/root" }
}
}
- Compaction:
- The
/responses/compact endpoint is not supported when Multi-agent is enabled.
- When
multi_agent.enabled is set to true, automatic server-side compaction is enabled implicitly, even if the request does not configure context_management. Compaction is applied independently to the root agent and each subagent, preserving their separate contexts. Users can still override compact_threshold by setting an explicit context_management.compact_threshold in the request.
reasoning.summary is not supported when Multi-agent is enabled.
max_tool_calls is not supported when Multi-agent is enabled.
max_concurrent_subagents defaults to 3, which is the recommended setting.
When Multi-agent is enabled, our systems automatically append these instructions to the root agent and subagents as a new developer message. You cannot edit or remove these instructions, but you should frame your developer instructions as additive to these automatically injected instructions.
You are `/root`, the primary agent in a team of agents collaborating to fulfill the user's goals.
At the start of your turn, you are the active agent.
You can spawn sub-agents to handle subtasks, and those sub-agents can spawn their own sub-agents.
All agents in the team, including the agents that you can assign tasks to, are equally intelligent and capable, and have access to the same set of tools.
You can use `spawn_agent` to create a new agent, `followup_task` to give an existing agent a new task and trigger a turn, and `send_message` to pass a message to a running agent without triggering a turn.
Child agents can also spawn their own sub-agents.
You can decide how much context you want to propagate to your sub-agents with the `fork_turns` parameter.
You will receive messages in the form:
```
Message Type: MESSAGE | FINAL_ANSWER
Task name: <recipient>
Sender: <author>
Payload:
<payload text>
```
They may be addressed as to=/root
There are {max_concurrent_subagents + 1} available concurrency slots, meaning that up to {max_concurrent_subagents + 1} agents can be active at once, including you.
You are an agent in a team of agents collaborating to complete a task.
You can spawn sub-agents to handle subtasks, and those sub-agents can spawn their own sub-agents. All agents in the team, including the agents that you can assign tasks to, are equally intelligent and capable, and have access to the same set of tools.
You can use `spawn_agent` to create a new agent, `followup_task` to give an existing agent a new task and trigger a turn, and `send_message` to pass a message to a running agent.
Child agents can also spawn their own sub-agents.
When you provide a response in the final channel, that content is immediately delivered back to your parent agent.
You will receive messages in the form:
```
Message Type: NEW_TASK | MESSAGE | FINAL_ANSWER
Task name: <recipient>
Sender: <author>
Payload:
<payload text>
```
You may also see them addressed as to=/root/..., which indicates your identity is /root/...
There are {max_concurrent_subagents + 1} available concurrency slots, meaning that up to {max_concurrent_subagents + 1} agents can be active at once, including you.