Handoffs & orchestration

Two ways to put agents together, for two different shapes of problem. A handoff transfers the conversation — right when one specialist should take over and answer the user directly. An orchestrator keeps control — right when one agent should delegate subtasks, collect the results, and combine them.

Handoffs

A handoff passes the conversation to another agent. It's the seed of the Crew API and is how you build triage, specialists and escalation paths today.

from nobelagentic import Agent

billing = Agent("Handle billing questions. Be precise.", name="billing", tools=["data"])
support = Agent("Handle technical support.", name="support", tools=["web"])

triage = Agent(
    "Route each request to billing or support. Hand off immediately; don't answer yourself.",
    handoffs=[billing, support],
)

result = triage.run("I was charged twice this month")
print(result.agent)    # "billing"
print(result.output)

Each handoff target shows up to the model as a tool named handoff_to_<name>. When it's called, the target's instructions replace the system prompt, the full conversation carries over, and the loop continues as that agent — with its own tools and model.

Events

Listen for Handoff events to show the user who's answering:

async for ev in triage.stream("..."):
    if isinstance(ev, Handoff):
        print(f"→ now talking to {ev.to_agent}")

Orchestration: agents as tools

as_tool() turns any agent into a tool another agent can call. The orchestrator never gives up the conversation — it fires off tasks, gets answers back, and synthesizes:

from nobelagentic import Agent

researcher = Agent("You find facts and cite sources.", name="researcher", tools=["web"])
writer     = Agent("You turn notes into crisp prose.", name="writer")

orchestrator = Agent(
    "You produce short reports. Use the researcher for facts, "
    "the writer for the final text. Combine their work yourself.",
    tools=[researcher.as_tool(), writer.as_tool()],
)

print(orchestrator.run("One paragraph on the state of African fintech"))

Same in TypeScript:

const orchestrator = new Agent("You produce short reports...", {
  tools: [researcher.asTool(), writer.asTool()],
});

The sub-agent shows up to the model as a tool named ask_<name> (override with as_tool(name=..., description=...)). Because sub-agents are ordinary tools, the kernel's parallel tool calls apply: when the orchestrator asks the researcher and the writer for independent things in one step, they run concurrently.

Choosing between them: handoff when the user should end up talking to the specialist (triage, escalation). Orchestrate when the agent needs the specialist's output as an ingredient (research → write → combine).

Limits

Handoffs are one-way, and an orchestrator sees only a sub-agent's final answer, not its intermediate events. For round-trips, review loops, shared state and resumable multi-step pipelines, use the Graph API (v0.2) or the Crew API (v0.3).