Recommended Free Tools
A router-plus-specialists workflow is one triage agent that reads each request and sends it to a narrowly scoped specialist. The design decision that matters most is ownership: does the chosen specialist answer the user directly, or does a manager agent call the specialist for a bounded subtask and keep responsibility for the final reply? The OpenAI Agents SDK for Python implements these as handoffs and agents-as-tools, and choosing between them should come before you write any routing code.
Start with one agent that runs end to end
The official Python quickstart recommends getting a single agent working before adding routing, tools, or state. Its own guidance is to add capabilities incrementally once the first loop works. OpenAI’s Python quickstart documents the steps below.
- Create a virtual environment and install the package with
pip install openai-agents. - Configure your OpenAI credentials as the quickstart describes before running anything.
- Import
AgentandRunnerfrom theagentsmodule. - Run the agent asynchronously with
Runner.run(...)and read the answer fromresult.final_output.
A minimal run looks like this:
import asyncio
from agents import Agent, Runner
async def main():
agent = Agent(name="Assistant", instructions="You are a helpful assistant.")
result = await Runner.run(agent, "Name two differences between handoffs and agents-as-tools.")
print(result.final_output)
asyncio.run(main())Confirm this prints a sensible answer before you add a second agent. Most routing bugs are easier to diagnose when the single-agent loop is already known to work.
Choose the control flow before writing the router
The SDK’s orchestration guide frames multi-agent work around one question: who should own the next response? It describes two patterns, and the router design follows from the answer.
#1 Best Overall
| Decision axis | Handoffs | Agents-as-tools |
|---|---|---|
| Who owns the next response? | The selected specialist takes over that branch. | The manager remains in control. |
| Best fit | Routing is part of the workflow and the specialist should respond directly. | Specialist work is bounded, and a manager should combine outputs or own the final response. |
| Specialist context | A handoff receives conversation history by default; filters and configuration can narrow it. | The specialist runs as a tool for a task while the manager keeps ownership of the answer. |
Sources: the OpenAI Agents SDK agent orchestration guide and the Python handoffs guide.
As a rule of thumb, use handoffs for a support-style triage where a billing or refund specialist should speak to the customer directly. Use agents-as-tools when a manager needs several specialist outputs and must write one coherent reply.
Build the router and specialists
Define one router or triage role
The router’s only job is selection. Its instructions should say which specialists exist and when each one applies. The quickstart’s routing material uses a triage agent with separate handoff destinations, which is the pattern to copy. The specific sample on that page is JavaScript; the Python equivalent should be written from the Python handoff documentation, not translated from that snippet.
Keep specialists small and non-overlapping
Give each specialist distinct instructions and a narrow scope. Overlap is the most common cause of misrouting: if two specialists could plausibly answer a request, the router has no reliable basis for choosing. The Python handoff guide notes that a specialist’s handoff description can guide the model’s choice of destination, so write each description as a short statement of what that specialist handles and what it does not.
Register each handoff destination explicitly
Each specialist that the router may reach should be registered as its own handoff destination. The SDK exposes those destinations for selection. The Python handoff guide also documents optional customization: descriptions, callbacks, input schemas, and input filters. Use only the options you need for the first version.
Limit the context each specialist receives
Handoffs normally carry conversation history to the receiving agent. That is useful when the specialist needs the whole exchange, but it can leak irrelevant detail to a narrow specialist. Use input filters or history configuration when a specialist should see less. For agents-as-tools, pass the manager’s bounded task rather than the full transcript unless the specialist truly needs it.
Handle later turns deliberately
A single Runner.run call continues through tool calls and handoffs until the runtime reaches a stopping point. That loop is the within-run boundary. Conversation state across separate runs is a different problem, and the OpenAI running-agents guide distinguishes the two. For the second turn onward, pick one strategy and apply it consistently:
- Application-held history: your code stores the messages and passes them back on each run.
- A session: the SDK’s session support maintains continuity across runs.
- A conversation ID: the platform keeps the conversation under an identifier you pass back.
- A previous response ID: each new turn references the response that came before it.
Mixing strategies is a common source of duplicated or missing context, so decide before the second turn ships.
Add guardrails and tracing only when the example needs them
The SDK overview lists guardrails, sessions, and tracing as built-in capabilities. Guardrails help with validation, sessions with continuity, and tracing with seeing what each agent did during a run. Add them when a specific problem calls for them: misrouted requests, lost context, or unclear failures. Their presence in the SDK does not by itself make the workflow correct, so test routing decisions with your own representative requests.
What the official sources do and do not establish
The official documentation establishes the install command, the basic async run, the two orchestration patterns, the handoff configuration options, and the state distinction described above. It does not establish performance, reliability, or cost figures for router designs, and it does not offer a cross-framework comparison. Treat any claim that one orchestration style is faster or cheaper as unverified unless you measure it in your own application.
The orchestration guide contains this sentence, which is a good summary of the ownership rule: “Use handoffs when routing itself is part of the workflow and you want the chosen specialist to own the remainder of the current turn.” It is documentation wording rather than a quotation from a named person.
Quick Recap
“
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errors
