Repository Public
1# Orchestration and handoffs23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45Multi-agent workflows are useful when specialists should own different parts of the job. The first design choice is deciding who owns the final user-facing answer at each branch of the workflow.67## Choose the orchestration pattern89| Pattern | Use it when | What happens |10| --------------- | ----------------------------------------------------------------------------- | ---------------------------------------- |11| Handoffs | A specialist should take over the conversation for that branch of the work | Control moves to the specialist agent |12| Agents as tools | A manager should stay in control and call specialists as bounded capabilities | The manager keeps ownership of the reply |1314## Use handoffs for delegated ownership1516Handoffs are the clearest fit when a specialist should own the next response rather than merely helping behind the scenes.1718Delegate with handoffs1920```javascript21import { Agent, handoff } from "@openai/agents";2223const billingAgent = new Agent({ name: "Billing agent" });24const refundAgent = new Agent({ name: "Refund agent" });2526const triageAgent = Agent.create({27 name: "Triage agent",28 handoffs: [billingAgent, handoff(refundAgent)],29});30```3132```python33from agents import Agent, handoff3435billing_agent = Agent(name="Billing agent")36refund_agent = Agent(name="Refund agent")3738triage_agent = Agent(39 name="Triage agent",40 handoffs=[billing_agent, handoff(refund_agent)],41)42```434445Keep the routing surface legible:4647- Give each specialist a narrow job.48- Keep `handoffDescription` in TypeScript or `handoff_description` in Python short and concrete.49- Split only when the next branch truly needs different instructions, tools, or policy.5051At the advanced end, handoffs can also carry structured metadata or filtered history. Those exact APIs stay in the SDK docs because the wiring differs by language.5253## Use agents as tools for manager-style workflows5455Use `agent.asTool()` in TypeScript or `agent.as_tool()` in Python when the main agent should stay responsible for the final answer and call specialists as helpers.5657Call a specialist as a tool5859```javascript60import { Agent } from "@openai/agents";6162const summarizer = new Agent({63 name: "Summarizer",64 instructions: "Generate a concise summary of the supplied text.",65});6667const mainAgent = new Agent({68 name: "Research assistant",69 tools: [70 summarizer.asTool({71 toolName: "summarize_text",72 toolDescription: "Generate a concise summary of the supplied text.",73 }),74 ],75});76```7778```python79from agents import Agent8081summarizer = Agent(82 name="Summarizer",83 instructions="Generate a concise summary of the supplied text.",84)8586main_agent = Agent(87 name="Research assistant",88 tools=[89 summarizer.as_tool(90 tool_name="summarize_text",91 tool_description="Generate a concise summary of the supplied text.",92 )93 ],94)95```969798This is usually the better fit when:99100- the manager should synthesize the final answer101- the specialist is doing a bounded task like summarization or classification102- you want one stable outer workflow with nested specialist calls instead of ownership transfer103104## Add specialists only when the contract changes105106Start with one agent whenever you can. Add specialists only when they materially improve capability isolation, policy isolation, prompt clarity, or trace legibility.107108Splitting too early creates more prompts, more traces, and more approval surfaces without necessarily making the workflow better.109110## Next steps111112Once the ownership pattern is clear, continue with the guide that covers the adjacent runtime or state question.113114115116 [Agent definitions117118119120 Refine each specialist's instructions, tools, and output contract.](https://developers.openai.com/api/docs/guides/agents/define-agents)121 [Running agents122123124125 Understand how handoffs and tools behave inside a run.](https://developers.openai.com/api/docs/guides/agents/running-agents)126 [Results and state127128129130 See how 131 `lastAgent` in TypeScript or `last_agent` in Python 132 and resumable state affect the next turn.](https://developers.openai.com/api/docs/guides/agents/results)