Agents API multi-agent orchestration

Multi-agent lets an agent delegate tasks to subagents. Each subagent has its own context and can work in parallel with the others. The main agent coordinates their work and combines their results.

When to use subagents #

Use subagents for independent tasks, such as reviewing separate documents or investigating different causes of a failure. Give each task a clear question and expected result.

Keep short tasks and dependent steps in the main agent. Agents that edit the same files must coordinate their changes.

Enable multi-agent orchestration #

Set agent.multi_agent.enabled to true when you create a session. The harness supplies tools to create, message, wait for, and interrupt subagents. You do not declare these tools yourself.

This example asks two subagents to review separate release notes, then combines their findings. It needs no environment or configured tools:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16from openai import OpenAI

client = OpenAI()

with client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Delegate each release to a separate subagent. Ask each to extract customer-visible changes and required migration steps using only its release notes. Wait for both results, then combine them into one release summary with release labels. Do not invent missing details.",
        "multi_agent": {"enabled": True, "max_concurrent_subagents": 2},
    },
    environment={"type": "none"},
    input="Release A: Search now supports filtering by date. Existing queries continue to work. Release B: The export endpoint now returns a download URL instead of file bytes. Update clients to fetch that URL.",
    stream=True,
) as events:
    for event in events:
        print(event.model_dump_json())

With environment.type: "none", include the initial input in the create request. Setting stream: true also streams the first turn. See Session events and items for stream handling and recovery.

Concurrency settings

max_concurrent_subagents limits how many subagents can run at once. The default is 6, excluding the coordinator. Set a positive integer when delegation is enabled.

To disable delegation, omit multi_agent, or set enabled to false and omit the limit. These settings apply at session creation. Changes to a stored agent apply to new sessions.

Use an environment #

When agents need files or command execution, add an environment. The coordinator and subagents share its filesystem. Creating a subagent does not create another environment.

This example creates a session for work in your own environment:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15const result = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "Prepare release notes from the repository. Have one subagent identify customer-visible changes and another check migration guides and examples, then combine their findings.",
    multi_agent: {
      enabled: true,
      max_concurrent_subagents: 3,
    },
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
  },
});

Store the returned session and environment IDs in your application. Connect the environment, then send input to start work.

Tools available to subagents

Subagents inherit configured MCP tools, their credentials and allowed tools, and web search settings. They can also use the environment’s files and command-line tools. Subagents do not support function tools.

Observe delegation #

The session event stream reports subagent activity:

• agent.session.subagent.created provides the new subagent’s ID.
• agent.session.turn.item.added andagent.session.turn.item.done report coordination actions. Their item types includecreate_subagent_call ,send_subagent_input_call ,wait_for_subagents_call , andinterrupt_subagent_call .

The harness executes these actions. A completed create or wait action does not mean the subagent finished its task. On a create item, agent_id identifies the agent that requested the subagent.

Coordination items can omit message content. An agent_message item contains inter-agent text when available, but the stream does not provide a full conversation transcript.

Read the main agent’s response for the combined result. Use saved items and turns to inspect prior work, including each subagent’s history.

Attribute commands

Given a command item and its session ID, retrieve the command’s turn to identify the agent that ran it. The turn’s subagent_id is null for the main agent.

1
2
3
4
5
6// Use the saved session ID and command execution item from your application.
const turn = await client.beta.agents.sessions.turns.retrieve(
  command.turn_id,
  { session_id: sessionId }
);
console.log(turn.subagent_id);