Agent handoff design is the discipline of turning “send this to the specialist” into a typed, authorized and testable boundary. A reliable handoff names the task, relevant state, supporting evidence, permitted actions, acceptance criteria, return conditions and provenance. It does not dump an entire conversation into another prompt and hope the receiving agent infers what matters. The handoff contract should be inspectable before transfer and reconstructable after completion.
Frameworks make a handoff easy to invoke, but production correctness sits around that invocation. The OpenAI Agents SDK handoff guide models handoffs as tools that transfer execution to another agent and supports typed input, callbacks and input filters. This article adds an operating contract around those mechanics. For the surrounding loop and controls, see Edilec's AI agents workflow guide and agent control plan.
Make agent handoff design a real boundary
Use a handoff when the receiving specialist should become responsible for advancing the task, not merely return a fact. Responsibility includes deciding which permitted steps to take and determining when its part is complete. If the coordinator wants to retain all planning and call a narrow capability, expose the specialist as a tool instead. This distinction prevents nominal handoffs that still depend on hidden coordinator state.
Name both roles: transferor and transferee. The transferor validates that the handoff is appropriate and packages the contract. The transferee validates that it has the skill, capacity and authority to accept. Acceptance should create a stable handoff or task identifier and a status. A rejected handoff returns a structured reason and recovery option; it should not disappear into conversational prose.
Transfer a minimal state envelope
The envelope should include task objective, current status, constraints, relevant entities, completed steps, unresolved questions, deadline, locale and output schema. Reference large records by immutable identifier and authorized retrieval path rather than copying them. Separate user statements from verified system facts and agent inferences. This allows the receiver to decide what evidence is trustworthy and prevents a summary from silently upgrading a guess into a fact.
Use schema versions and reject unknown critical fields. Every field needs an owner and retention rule. Conversation turns are useful only when they alter intent, constraints or evidence; routine pleasantries and unrelated history should be filtered. The SDK results documentation distinguishes run outputs, new items and input suitable for subsequent runs, illustrating why an application should deliberately select what becomes the next agent's input.
| Handoff field | Required content | Do not transfer |
|---|---|---|
| Objective | Specific outcome and completion test | Broad persona prompt |
| State | Completed steps and current authoritative status | Unverified chain-of-thought |
| Evidence | Source IDs, timestamps and verification class | Copied secrets or unrelated records |
| Authority | Allowed actions, limits and expiry | Transferor's entire credential set |
| Return contract | Output schema, terminal states and escalation route | An assumption that prose means success |
Preserve evidence and provenance
For each consequential claim, record its source: user assertion, system record, policy decision, tool result or agent inference. Include retrieval time and immutable record version where available. The receiving agent can then refresh stale facts and treat user-provided content as untrusted. Evidence references also reduce prompt size and let access control remain with the source system instead of propagating sensitive content across agents.
Do not transfer hidden reasoning. Transfer decisions and their externally reviewable basis: selected option, policy version, evidence IDs, confidence where meaningful and unresolved alternatives. This is enough for audit and continuation without encouraging systems to depend on private model deliberation. The A2A specification provides messages, task state and artifacts as separate concepts; a local handoff contract benefits from the same separation even when A2A is not used on the wire.
Delegate authority explicitly and narrowly
A handoff can transfer responsibility without transferring every permission. List allowed capability identifiers, resource scopes, value limits, destinations, expiry and whether further delegation is permitted. The receiver obtains its own audience-bound credentials through the platform. Never embed bearer tokens in the handoff payload. A human approval transfers evidence that a defined action is approved, not an open-ended permission to change similar actions.
Define non-delegable decisions, such as accepting legal terms, releasing a payment above a threshold or changing the identity policy. If the specialist reaches one, it returns an approval request containing a digest of the proposed effect and supporting evidence. Server-side policy checks the final request again after approval. Edilec's tool permissions guide explains how action tiers and transaction limits support this boundary.
Specify acceptance, return, and escalation
Acceptance confirms that the receiver understands the schema version, recognizes the objective, can access required evidence and has a compatible authority profile. It may accept, reject or request missing input. Once accepted, define heartbeat or status expectations for long work. The transferor should not continue the same side effect in parallel unless the workflow deliberately supports competing execution and has a reconciliation rule.
Return states should include completed, failed, canceled, input required, approval required and timed out. A completed return carries structured outputs, artifact references and authoritative confirmation of effects. Failure identifies whether retry is safe and which work may already have occurred. Escalation names a human or agent role, not merely “manual review.” Terminal state belongs to the contract; natural-language confidence is not a terminal state.
State who owns the user relationship during the transfer. The receiver may speak directly, while the original coordinator still owns notification, deadline and complaint handling. If that split is not explicit, each party can assume the other communicated a delay or failure. Include user-visible status responsibility and privacy notice requirements in the handoff policy, even when they are not sent inside every payload.
Validate contracts at both sides
Before sending, validate schema, required evidence, data classification, authority bounds and destination eligibility. On receipt, repeat validation under the receiver's current policy. A transferor may be compromised or simply stale. Check tenant and entity consistency, reject references the receiver should not access and refresh material facts before effects. Sign or integrity-protect cross-trust-domain envelopes where the transport does not already provide sufficient protection.
Create contract tests for missing fields, conflicting identifiers, stale evidence, expired authority, unsupported schema and duplicate delivery. Fuzz free-text fields for instructions that try to override receiver policy. Test cyclic handoffs and cap transfer depth. A handoff chain should not bounce indefinitely among specialists because none owns a terminal decision. Every rejection and escalation needs a bounded next state.
| Failure scenario | Receiver behavior | Coordinator recovery |
|---|---|---|
| Schema version unsupported | Reject before execution | Transform through approved adapter or route elsewhere |
| Evidence expired | Request refresh | Retrieve from source and resubmit |
| Authority insufficient | Return approval or scope request | Obtain bounded authorization |
| Duplicate handoff ID | Return existing status | Resume observation, do not start again |
| Ambiguous side effect | Enter reconciliation state | Query authoritative system before retry |
Trace handoffs as linked responsibility spans
Record transferor, receiver, handoff ID, parent task, schema version, acceptance state, authority profile, evidence references, timestamps and terminal outcome. Connect agent and tool spans without logging sensitive prompt bodies. The OpenTelemetry generative AI conventions offer shared semantic fields for agent operations; add business task and policy identifiers through a governed extension.
Measure acceptance latency, rejection reason, re-handoff rate, stale-evidence refresh, approval wait, duplicate suppression, completion rate and reconciliation time. High handoff volume is not inherently good. Repeated transfers may reveal overlapping specialties or missing ownership. Sample completed handoffs for output correctness and user outcome, not only technically successful status transitions. Feed recurring contract defects into schema and routing changes.
Roll out one typed handoff at a time
Choose a frequent transition where specialist ownership is already clear. Capture the current informal transfer, identify lost information and define the smallest typed envelope. Run the receiver in advisory mode, comparing its result with the existing process. Then enable acceptance and return states before granting write authority. This sequence isolates contract quality from action risk.
Add consequential tools only after duplicate delivery, timeout, cancellation and escalation tests pass. Review what context is actually used and remove fields that create exposure without improving outcomes. Extend the pattern to a second specialist only after the first has stable measures and an owner. A reusable contract framework should standardize envelopes and evidence, while domain teams own the meaning of objectives and completion.
Key takeaways
- Use a handoff only when the receiver assumes responsibility for advancing the task.
- Transfer a versioned minimal state envelope with facts separated from inference.
- Reference authoritative evidence and delegate bounded capabilities instead of credentials.
- Define acceptance, rejection, input, approval, failure and completion as structured states.
- Trace responsibility and measure contract defects, duplicate suppression and reconciliation.
Frequently asked questions
Should a handoff include the whole conversation?
Usually not. Include only turns that establish objective, constraints, decisions or evidence. Provide a concise structured summary and authorized references. Whole-history transfer increases cost, privacy exposure and prompt-injection surface while making the receiver rediscover state.
Can the receiving agent change the objective?
It may clarify or reject an infeasible objective, but material changes should return to the owner or coordinator for acceptance. Otherwise the receiver can complete a different task while reporting success. Record approved amendments as new contract versions or task events.
How do handoffs differ from agents as tools?
With a handoff, the specialist becomes the active owner of the conversation or task. With an agent as a tool, the manager retains control and consumes the specialist's result. The distinction determines where state, guardrails and final accountability live.
Conclusion
Agent handoff design makes delegated work legible. The receiving specialist gets enough state and evidence to act, only the authority it needs, and an explicit definition of return. The transferor gets acceptance, status and outcomes it can reconcile. Both sides share identifiers without sharing hidden reasoning or unrestricted credentials.
Begin by replacing one informal prompt dump with a typed envelope and structured terminal states. The immediate benefit is fewer missing facts; the larger benefit is an auditable boundary where teams can test responsibility, access and recovery before multi-agent behavior expands.