Agents That Delegate to Each Other
View as MarkdownAn agent can hand a subtask to another agent it's allowed to work with and get the result back, the same way a person delegates to a teammate.
Finding a teammate
An agent can look up which other agents it's been granted access to work with, optionally filtered by what it's looking for help doing, before deciding who to hand a subtask to.
Handing off the work
Delegating a subtask to that teammate and getting its result back happens in a single step from the delegating agent's point of view: no manually assembled request, no writing a poll loop to check whether the teammate is done.
Access is exactly the access you've already granted. A teammate is reachable only if you've connected and bound that specific agent-to-agent relationship. Delegation can't reach an agent it wasn't explicitly given, and a request to an unbound teammate fails immediately with a clear reason rather than partially working.
Long delegations don't block anything
If a teammate takes a while, the delegating agent doesn't sit there holding a slot that other work is waiting behind. It parks, durably, and picks back up automatically the moment the teammate actually finishes, rather than occupying a worker the whole time it's waiting.
Built on the same connection as linking two installs
delegate and find_agents aren't a separate mechanism: they're the ergonomic front door over the same heartbeat_agents integration used to connect one HeartBeatAgents instance to another (see Integrations Guide). A "teammate" is a connected heartbeat_agents account bound to your agent, the same way any other integration gets bound to an agent. What delegate adds on top is the ergonomics: no hand-assembled request, and no writing your own poll loop to check whether the teammate is done.
Setting it up
A teammate has to be connected and bound before an agent can find or delegate to it:
- From Settings → Integrations, connect a
heartbeat_agentsaccount, pointing it at the teammate agent's own invoke endpoint. - Give that connection an account label; this is the name
find_agentsanddelegateboth use to refer to it. - Bind the connection to the agent that should be able to delegate to it, the same way you'd bind any other integration.
An agent only ever sees teammates connected and bound to it specifically; there's no directory of every agent on the instance to browse.