Transfer bounded evidence with explicit ownership

Learning objective

Transfer bounded, provenance-preserving context between agents through explicit handoff contracts

Core idea

An agent receiving a handoff needs enough context to continue the authorized task, but it does not need every message or permission the sender has. Define the handoff as an explicit contract: what work moves, what evidence supports it, what remains uncertain, and what the receiver must return or complete.

For an architect, the important distinction is between routing control and transferring trustworthy state. Microsoft Agent Framework supplies handoff routing and context synchronization. A bounded, provenance-preserving business payload is still an application design. Do not assume a routing feature proves that every source, commitment, or authorization survives the transition.

See 2.1.5 for role-specific context selection and executor context modes. This lesson owns the evidence contract carried across the transfer, rather than the specialist’s prompt or workflow topology.

How it works

Separate routing from the payload

Agent Framework configures handoff routing with Python’s HandoffBuilder(...).with_start_agent(...).add_handoff(...), or .NET’s AgentWorkflowBuilder.CreateHandoffBuilderWith(...) and WithHandoffs(...). Its HandoffAgentExecutor routes the resulting handoff tool calls; participating Agent instances must support local tool execution.

Handoff participants have separate AgentSession instances. Synchronization broadcasts user and agent messages but excludes tool calls, tool results, and approval payloads; see 2.1.5 for the content rules.

Those rules matter when a specialist needs proof from a preceding tool. A visible assistant sentence about a database result is not equivalent to the database’s source record. The handoff contract must preserve the permitted evidence separately, or give the receiver an authorized reference from which to retrieve it.

A full-history broadcast can also exceed your intended transfer budget. If the requirement is that the receiver must never receive unrelated history, verify the chosen orchestration’s synchronization behavior. Use a controlled application transfer or an agent-as-tool call with selected inputs where its ownership model fits; do not label automatic broadcast as a selective payload mechanism.

Define an application envelope

An envelope should make the receiving agent’s next decision possible without requiring it to infer identities or commitments from prose. The following fields are illustrative application fields, not a Foundry or Agent Framework schema:

Use stable order or case identifiers rather than pronouns such as “it” or names that can refer to several objects. A statement about order A must not become a claim about order B when the summary replaces both with “the shipment.” If evidence is an inference rather than a source observation, label that distinction in the envelope.

For each evidence item, preserve the source record or document identifier, its relevant version, and the precise passage or result being relied on. A URL alone might point to content that changes. A summary without an origin cannot be checked. Preserve the linkage between the claim and its evidence after shortening the payload.

Validate before transferring ownership

The sender can produce a typed envelope through Agent Framework structured outputs. In Python, define an application-owned Pydantic model named HandoffEnvelope, call agent.run(..., options={"response_format": HandoffEnvelope}), and read the model instance from response.value. This requires an underlying chat client that supports structured outputs. In .NET, use RunAsync<HandoffEnvelope>() for a typed result. Check that a structured value was returned before proceeding.

Pass that value to a receiving workflow validation step: Python uses an executor @handler whose input annotation is HandoffEnvelope; .NET uses Executor<HandoffEnvelope> and overrides HandleAsync. These documented mechanisms carry the typed contract. They do not establish that its claims are true or that its recipient is authorized. The handler implements the application checks for recipient, entity references, evidence completeness, and rendered token budget before invoking the receiving agent. The envelope fields remain your business schema; built-in handoff routing does not automatically apply this custom validation step.

Apply the budget to the actual rendered payload, including labels, identifiers, and references. If it is too large, remove irrelevant evidence first, replace bulky artifacts with authorized references, or split the work into smaller transfers. Do not satisfy the cap by deleting the unresolved commitment that explains why the receiver is being called.

The receiver validates the same contract and records acceptance or rejection against handoff_id. Make the ownership change explicit in the workflow’s authoritative task record. This application record prevents two participants from independently treating themselves as the owner after duplicate delivery or an interrupted transfer.

Authorization remains separate. A source reference is useful only if the receiver can legitimately read it. The envelope identifies what evidence is needed; downstream credentials and access controls determine what the receiver can retrieve. See 1.1.7 for tool permissions and 2.2.6 for memory access.

Key distinctions and trade-offs

Choose the control and ownership pattern separately from the evidence envelope; see 1.1.3 for delegation ownership.

Inline evidence makes the receiving decision reproducible without another retrieval, but consumes context and duplicates sensitive data. References reduce payload size, but require available, authorized sources and stable versions. A useful contract combines short decisive excerpts with source identifiers for verification.

A concise summary is a navigation aid, not a substitute for facts and commitments. Keep conclusions separate from observations and unresolved questions. This lets the receiver disagree with the sender’s interpretation without losing the original evidence.

Architecture / decision scenario

A delivery agent transfers a disputed replacement to a billing specialist. The history contains two orders, a promise to waive shipping only if a replacement is approved, and a carrier scan that contradicts the customer’s account.

The sender returns HandoffEnvelope through structured output, and a typed executor validates it before the application delivers the billing context. The application creates this envelope for the billing decision only. It names the disputed order by ID, carries the carrier scan’s record ID and timestamp, preserves the conditional waiver as an unfinished commitment, and lists the contradictory customer statement as a separate source. It includes no unrelated purchase history.

The receiver’s budget is 1,500 tokens, an application choice rather than a Microsoft limit. The validator counts the rendered envelope. It replaces a long carrier report with a short excerpt and an authorized record reference, retaining the evidence linkage and condition. A repeated delivery uses the same handoff_id and does not create another ownership transfer.

If the specialist must take over the case, use a handoff and verify how synchronized history reaches it. If the specialist only calculates eligibility, invoke it as a tool with the bounded contract and keep ownership with the delivery agent. In either path, reject an envelope that confuses the two orders or removes the waiver condition.

Common exam traps

• Equating synchronized messages with shared session instances.
• Assuming tool results or approval payloads are broadcast to every participant.
• Calling an unrestricted history transfer a bounded contract.
• Replacing stable entity IDs with ambiguous names or pronouns.
• Treating a sender’s conclusion as primary evidence.
• Transferring authority merely by copying a source reference.

What to remember

Routing chooses the next participant; the contract preserves what that participant needs to decide. Bound the rendered payload, retain claim-to-source links and unfinished commitments, and validate ownership explicitly. Framework handoff synchronization is useful, but its content rules must match your transfer requirement.

Knowledge check

References

• Microsoft, Handoff orchestration
• Microsoft, Structured outputs
• Microsoft, Executors