Unit 09.01: Handoff, and what travels with it

Passing the whole state to the next agent is the default, the easiest thing to write, and wrong in three separate ways.

An allowlist, not the whole state

A handoff is a contract: these fields, and only these, cross the boundary. Writing it as an explicit allowlist makes the contract readable and testable.

The code filters a realistic state down to three fields.

full_state = {
    "question": "why was I charged twice?",
    "customer_id": "ACC-1187",
    "internal_notes": "flagged as a repeat complainer",
    "raw_transcript": "..." * 200,
    "api_key": "sk-secret",
    "findings": ["duplicate charge on 2026-06-14"],
}

HANDOFF_ALLOWED = {"question", "customer_id", "findings"}
handoff = {k: v for k, v in full_state.items() if k in HANDOFF_ALLOWED}

print("full state fields   :", sorted(full_state))
print("handed to next agent:", sorted(handoff))
print("withheld            :", sorted(set(full_state) - HANDOFF_ALLOWED))

# Passing the whole state is the default and it is wrong three times over: the
# secret travels, the internal note reaches an agent that may quote it, and the
# transcript makes every downstream prompt more expensive.
# An allowlist makes the contract between agents explicit.

Three things are withheld and each for a different reason. The API key is a secret that had no business travelling. The internal note - "flagged as a repeat complainer" - is the kind of text an agent may quote back to the person it describes. The raw transcript is simply large, and it makes every downstream prompt more expensive for the rest of the run.

Only the last of those is about cost. The first two are about what a downstream agent can do with information it was never meant to have.

The mistake this prevents

The mistake is filtering the handoff in the prompt - telling the next agent not to mention the internal note. The note is in its context, so whether it appears in the output is a matter of probability. Fields that must not travel must not be passed.

Takeaway

Define the handoff as an explicit allowlist of fields. Passing the whole state carries secrets, carries text that should not be quoted, and inflates every prompt downstream.

Mark complete