Handoff operation

handoff moves the conversation to another agent from inside an operation tree. Use it when the tree decides where the conversation goes — after a lookup, inside an if. When the model should pick a destination from what the caller asks for, use the agent’s handoffs field instead. To reach a person, use transfer.

[
  {
    "kind": "http",
    "config": {
      "method": "GET",
      "url": "https://api.example.com/accounts/{{args.account_id}}",
      "headers": { "Authorization": "Bearer {{secrets.CRM_API_KEY}}" },
      "timeout": 8
    },
    "silent": true,
    "publish_fields": [{ "path": "tier", "store": "tooldata" }]
  },
  {
    "kind": "if",
    "config": { "left": "{{tooldata.tier}}", "op": "eq", "right": "enterprise" },
    "then": [
      {
        "kind": "handoff",
        "config": {
          "target_agent_id": "9c1e6f42-7b30-4a55-9d18-2f0a6c4b8e31",
          "context": "summary",
          "summary": "{{args.summary}}",
          "recent_turns": 3,
          "message": "You're on our enterprise plan, so let me bring in your account team."
        }
      }
    ],
    "else": [
      {
        "kind": "generate_reply",
        "config": { "instructions": "Tell the caller you can help with this yourself and ask for the first detail you need." }
      }
    ]
  }
]

Config

Field	Type	Default	Meaning
`target_agent_id`	string	—	A published agent in this workspace
`agent_name`	string	—	A member of the agent team this call runs, by name
`context`	`transcript` \| `summary` \| `none`	`transcript`	What the target inherits from the handing-over agent. See context policies
`summary`	string	—	Required under `summary`, refused under any other context. The text that crosses, templated
`recent_turns`	integer, 1–10	`2`	`summary` only: turns of this session that cross verbatim beside the summary. Refused under other contexts
`message`	string	—	Spoken while the target loads. Templated
`instructions`	string	—	What the target is told as it opens, when it has no greeting. Templated

Set exactly one of target_agent_id and agent_name; neither or both is refused at save.

`summary` is text, not a request

The tree runs after the model’s tool call, so there is no second model call to write a summary. summary resolves like any template, and what it resolves to is what the target receives:

{{args.summary}} — declare a summary property on this tool’s json_schema and describe what to put in it; the model writes it when it calls the tool.
{{tooldata.brief}} — something an earlier operation published.
Fixed prose, optionally with tokens.

If it resolves to empty on a call, the handoff still happens and the target gets only the recent turns.

What is checked when

Check	When
Exactly one target; `summary` and `recent_turns` match `context`	Save
`target_agent_id` exists and is published	Tool validate and publish
`agent_name` exists	Only when the call starts. Tool publish warns that it resolves only in a team that defines it
Same channel, pipeline and avatar on both sides	Publish of an agent carrying the tool. See handoffs
No `handoff` in a `long_running_task` tool	Tool publish
No `handoff` in a tool attached to an agent task	Agent and task publish

At run time

message is queued before the target is built and always plays to the end before the target speaks. The target then runs its on_enter hook, then speaks its greeting, or opens from instructions and its prompt if it has none.
handoff is terminal: nothing may follow it in its chain.
A call allows 25 handoffs in total, counting both handoffs and this operation. Past that, the agent tells the caller it cannot pass them on again.
In a test run the handoff is simulated: the step reports the resolved target, context, summary and message, the run returns handed_off: true, and the target is never loaded.

Handoffs

Routing by tree, from the team’s side.

Context policies

What transcript, summary and none carry.

Get started

Build

Guides

Handoff operation

Config

`summary` is text, not a request

What is checked when

At run time

Next

Handoffs

Context policies

​Config

​summary is text, not a request

​What is checked when

​At run time

​Next

Handoffs

Context policies

Config

`summary` is text, not a request

What is checked when

At run time

Next