context on a handoff entry or handoff operation decides what the target agent inherits from the agent handing over. It sets what the target can answer without asking again, and what you pay in tokens on every turn the target takes.
The same three words appear on an agent’s own conversation.context, which answers a different question: what a new session starts with from earlier sessions with this person.
Choosing a policy
A good default for a support line:
summary out to a specialist, and summary with recent_turns: 1 on the way back to the front desk.
The target inherits from the handing-over agent’s own context, not from everything said on the session. With Front desk → Billing on none and Billing → Refunds on transcript, Refunds sees Billing’s turns and nothing Front desk heard. Whatever the target is given, it keeps for the rest of the session, including when a text chat’s agent is reloaded after a quiet period.
transcript
The target inherits the source agent’s context exactly, minus the source’s system prompt — earlier-session summaries, tool calls and results, and any summary the source itself inherited. If the source started from a summary or none edge, the target gets that narrower context too.
The cost is that the target re-reads all of it on every reply, on your provider key. On a long call this is usually the largest LLM cost.
summary
The generated handoff_to_* tool takes one argument, the summary, which the source agent writes in the same model turn as its decision to hand over. No second LLM call is made, so realtime agents can use it. The caller hears a pause while the summary is generated.
The target receives one system message, then the verbatim tail:
agent.handoff event records summary_fallback: true.
On a handoff operation, the summary is the operation’s summary template instead (required under this policy), since no model is writing one at that moment.
recent_turns
integer | null
default:"null"
Turns of the current session that cross verbatim beside the summary. 1 to 10; null means 2. Refused under
transcript and none.- A turn starts at a user message and runs until the next one, so a turn is never cut in half.
- Tool calls and their results never cross in the tail; facts from them belong in the summary.
- The tail never reaches back before the current session.
- The minimum is 1. A summary with no tail leaves the target not knowing the current question. Past 10 turns, use
transcript.
summary_prompt
string | null
default:"null"
The description of the summary argument, so it is literally what the source agent is asked to write. Refused outside
summary.name filled in:
{{userdata.…}}, {{system_vars.…}} and {{vars.…}}. Keep it to a line or two: it sits in the source agent’s tool schema on every request, and a longer summary is a longer pause.
none
The target starts with its system prompt and tools and no history at all. Tell it how to open in its prompt or in the edge’s instructions. Use it for a survey after a support call, a payment step, or a desk that starts over in another language.
summary is not a privacy boundary
It narrows what the target model is shown and guarantees nothing:
- At least one turn of the tail always crosses verbatim.
userdatais shared by every agent on the session regardless of policy.- The full transcript is still recorded and shown in the dashboard.
- The summary is written by the model and can include anything it saw.
summary or none. If a fact must not reach the next agent, do not let the first agent hold it: put it behind a tool only the second agent has.
What actually crossed
GET /v1/calls/{session_id} returns the call’s events; each handoff is an agent.handoff event:
The payload also carries
from_agent_id and to_agent_id.
Next
Handoffs
The rest of the handoff entry and the rules across a team.
Conversation memory
The other
context field: what a new session knows about earlier ones.