> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Distributed Agents

> Hand one call between agents that run in separate processes or on separate machines.

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](https://docs.zeroruntime.ai/runtime-sdk/build/subagents.md).

> [!NOTE]
>
> 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.

```python theme={null}
import os

import zeroruntime
from zeroruntime import Agent, Pipeline


class BookingAgent(Agent):
    def __init__(self) -> None:
        super().__init__(
            name="booking",
            instructions="You book trips. Ask where and when they'd like to go.",
            pipeline=Pipeline(...),
        )


if __name__ == "__main__":
    os.environ.setdefault("ZERORUNTIME_AGENT_ID", "booking")
    zeroruntime.serve(BookingAgent)
```

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:

```python theme={null}
from zeroruntime import RemoteAgent, RemoteAgentError, function_tool


class FrontDesk(Agent):
    ...

    @function_tool
    async def transfer_to_booking(self, summary: str):
        """Hand the caller to our booking team.

        Args:
            summary: What they'd like to book, in a few words.
        """
        await self.session.say("Sure, let me get you over to our booking team.", add_to_chat_context=False)
        try:
            return await self.transfer_to(RemoteAgent("booking"), reason=summary)
        except RemoteAgentError:
            await self.session.say("Sorry, our booking team isn't available right now.", add_to_chat_context=False)
            return {"transferred": False, "note": "Booking is unavailable. Offer to help another way."}
```

`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`.

> [!WARNING]
>
> 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:

```python theme={null}
@function_tool
async def transfer_to_front_desk(self):
    """The booking is done."""
    return await self.transfer_to(RemoteAgent("front_desk"), reason="booking finished")
```

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:

```python theme={null}
async def on_enter(self, reason: str):
    if reason == "call started":
        await self.session.reply("Greet the caller and ask what brings them in.")
    else:
        await self.session.reply("Welcome them back and ask if there's anything else.")
```

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:

| | Subagents | Distributed agents |
| :- | :- | :- |
| Hand over with | `transfer_to(Billing())` | `transfer_to(RemoteAgent("booking"))` |
| Runs in | The same process as the call | Its own process, on any machine |
| Code lives in | One codebase | Separate codebases |
| Deploy and scale | Together | Each agent on its own |
| Provider keys | Shared by the process | Each process brings its own |
| If the agent isn't there | Can't happen | `RemoteAgentError`, and the call stays put |
| SDKs | Python and Node JS | Python |

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:

```bash theme={null}
python booking.py
python travel_support.py
python front_desk.py
```

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

> [card] [Subagents](https://docs.zeroruntime.ai/runtime-sdk/build/subagents.md)
>
> Split a call into roles within one process.

> [card] [Distributed Example](https://github.com/ZeroRuntimeAI/zeroruntime-python-examples/tree/main/distributed-agents)
>
> A front desk, booking, and travel support, each in its own process.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.