Skip to main content
A distributed agent runs in its own process, possibly on another machine, and takes over a call when another agent hands it over. The caller stays on the same call: the agent taking over brings its own instructions, tools, hooks, pipeline, and workflow. Use distributed agents when roles are built, deployed, or scaled separately, such as a front desk owned by one team and a booking agent owned by another. For roles that live in one codebase, use subagents.
Distributed agents are available in the Python SDK, in releases after zeroruntime 0.2.1.

Serve Each Agent

Each agent is a normal agent served with zeroruntime.serve(). Give each one its own id with ZERORUNTIME_AGENT_ID: other agents hand the call over by that id.
Run alone, the agent takes the calls dispatched to it. It also waits for calls handed to its id, over connections it opens to the runtime, so its machine needs no public address. Each call it takes over gets a new instance of the class you serve, as a dispatched call does.

Hand Over the Call

Return transfer_to(RemoteAgent(...)) from a tool, with the other agent’s id:
transfer_to waits for the other agent to join the call before it returns. If no process serving that id can join, or the runtime doesn’t answer within 15 seconds, it raises RemoteAgentError and the call stays with your agent, so your tool can tell the caller. A line said with say covers the wait. The agent taking over reads reason in on_enter. The conversation carries over unless you pass inherit_context=False.
A move only works if you return it.

Hand the Call Back

Any served agent can be handed the call by its id, including the one that started it. To send the caller back to the front desk:
The front desk needs no extra code for this. on_enter runs again with the new reason, so it can greet the caller as someone returning:
Subagents and distributed agents mix. An agent can hand the call to a subagent in its own process with transfer_to(PolicyDesk()), and to another process with transfer_to(RemoteAgent(...)).

Subagents or Distributed Agents

Both hand the call to another agent with transfer_to. Pick by where the agent lives: Start with subagents. Move a role out to its own process when another team owns it, or when it needs to scale or deploy on its own.

Run Them Together

Start each agent in its own terminal or on its own machine:
Every agent must:
  • use the same ZERORUNTIME_AUTH_TOKEN. The runtime refuses an agent on another token.
  • reach the same runtime pod through ZERORUNTIME_TARGET. With several pods behind one address, point the agents at the call’s pod.
  • have its own provider keys. The front desk doesn’t need the booking agent’s keys.
To have an agent take only its own calls, serve it with zeroruntime.serve(MyAgent, accept_transfers=False).

Limits

  • If the process holding the call stops, the call goes back to the agent that had it before. A workflow there resumes only when the call is handed to that agent again.
  • All agents on a call must use be deployed on same account.

What’s Next

Subagents

Split a call into roles within one process.

Distributed Example

A front desk, booking, and travel support, each in its own process.