Agents API multi-agent orchestration

OpenAI's Agents API now supports multi-agent orchestration, letting a coordinator agent delegate tasks to subagents that each run in their own context and in parallel, enabled by setting agent.multi_agent.enabled to true at session creation. The feature defaults to max_concurrent_subagents of 6 excluding the coordinator, and subagents inherit configured MCP tools, credentials, allowed tools and web search settings but do not support function tools. Subagents share the coordinator's environment filesystem, and the session event stream reports delegation activity through events such as agent.session.subagent.created.

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: python 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 https://developers.openai.com/api/docs/guides/agents-api/sessions/events 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 https://developers.openai.com/api/docs/guides/agents-api/architecture . 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 https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted , then send input https://developers.openai.com/api/docs/guides/agents-api/sessions 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 https://developers.openai.com/api/docs/guides/agents-api/tools/functions . Observe delegation The session event stream https://developers.openai.com/api/docs/guides/agents-api/sessions/events reports subagent activity: - agent.session.subagent.created provides the new subagent’s ID. - agent.session.turn.item.added and agent.session.turn.item.done report coordination actions. Their item types include create subagent call , send subagent input call , wait for subagents call , and interrupt 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 https://developers.openai.com/api/docs/guides/agents-api/sessions/events fetch-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 ;