{"slug": "agents-api-multi-agent-orchestration", "title": "Agents API multi-agent orchestration", "summary": "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.", "body_md": "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.\n\n## When to use subagents\n\nUse 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.\n\nKeep short tasks and dependent steps in the main agent. Agents that edit the same files must coordinate their changes.\n\n## Enable multi-agent orchestration\n\nSet `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.\n\nThis example asks two subagents to review separate release notes, then combines their findings. It needs no environment or configured tools:\n\n``` python\n1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n11\n12\n13\n14\n15\n16from openai import OpenAI\n\nclient = OpenAI()\n\nwith client.beta.agents.sessions.create(\n    agent={\n        \"model\": \"gpt-6-astra\",\n        \"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.\",\n        \"multi_agent\": {\"enabled\": True, \"max_concurrent_subagents\": 2},\n    },\n    environment={\"type\": \"none\"},\n    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.\",\n    stream=True,\n) as events:\n    for event in events:\n        print(event.model_dump_json())\n```\n\nWith `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.\n\n### Concurrency settings\n\n`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.\n\nTo 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.\n\n## Use an environment\n\nWhen 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.\n\nThis example creates a session for work in your own environment:\n\n```\n1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n11\n12\n13\n14\n15const result = await client.beta.agents.sessions.create({\n  agent: {\n    model: \"gpt-6-astra\",\n    instructions:\n      \"Prepare release notes from the repository. Have one subagent identify customer-visible changes and another check migration guides and examples, then combine their findings.\",\n    multi_agent: {\n      enabled: true,\n      max_concurrent_subagents: 3,\n    },\n  },\n  environment: {\n    type: \"self_hosted\",\n    workspace_directory: \"/workspace\",\n  },\n});\n```\n\nStore 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.\n\n### Tools available to subagents\n\nSubagents 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).\n\n## Observe delegation\n\nThe [session event stream](https://developers.openai.com/api/docs/guides/agents-api/sessions/events) reports subagent activity:\n\n- `agent.session.subagent.created` provides the new subagent’s ID.\n- `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` .\n\nThe 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.\n\nCoordination 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.\n\nRead 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.\n\n### Attribute commands\n\nGiven 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.\n\n```\n1\n2\n3\n4\n5\n6// Use the saved session ID and command execution item from your application.\nconst turn = await client.beta.agents.sessions.turns.retrieve(\n  command.turn_id,\n  { session_id: sessionId }\n);\nconsole.log(turn.subagent_id);\n```\n\n", "url": "https://wpnews.pro/news/agents-api-multi-agent-orchestration", "canonical_source": "https://developers.openai.com/api/docs/guides/agents-api/multi-agent", "published_at": "2026-09-23 00:00:00+00:00", "updated_at": "2026-09-24 21:30:06.343358+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols", "artificial-intelligence"], "entities": ["OpenAI", "Agents API", "gpt-6-astra", "MCP"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/agents-api-multi-agent-orchestration", "markdown": "https://wpnews.pro/news/agents-api-multi-agent-orchestration.md", "text": "https://wpnews.pro/news/agents-api-multi-agent-orchestration.txt", "jsonld": "https://wpnews.pro/news/agents-api-multi-agent-orchestration.jsonld"}}