Designing agent handoffs: the contract between two agents
AI-assisted research. This note was prepared with the assistance of AI tools. It may contain errors and is not professional advice. See our Legal Disclosures.
Agentic marketing programs rarely run on one agent for long. Research feeds outreach, planning feeds writing, and writing feeds review, so the quality of the whole system depends on what survives each pass from one agent to the next.
When one agent passes work to another, something is always lost. The research agent knew why it chose these accounts, and the outreach agent only sees the list. The planner knew the campaign's constraints, and the writer only sees the brief.
In human teams, people fill these gaps with a quick conversation. In agent systems, the gap stays a gap unless you design for it.
We treat every handoff as a contract: an explicit agreement about what is passed, in what form, and what the receiver can rely on.
Why the gap is invisible
A handoff failure rarely looks like a failure. The sending agent finishes its task and reports success. The receiving agent gets a payload, does its job, and also reports success. Each step passes its own checks, and the problem only shows up downstream, in a weak email or a misdirected offer.
That is why handoffs deserve their own design. An agent's instructions describe what it should do with its inputs. They rarely describe what it should refuse, or what it should expect to be missing. Without a contract, the receiver fills the gaps with plausible guesses, and plausible guesses are the hardest errors to catch.
The four parts of a handoff contract
A complete contract has four parts. The first is the work itself, and the other three are what usually goes missing.
- Payload: the actual work product, such as a list of accounts, a draft, or a summary, in a defined structure.
- Context: what the receiver needs to use the payload well, including the goal, the audience, the constraints, and any decisions already made.
- Assumptions and confidence: what the sender was unsure about. A note such as "these three accounts had limited public information" is useful downstream.
- Acceptance criteria: what makes the payload valid. If the receiver gets something that does not meet them, it should reject it rather than improvise.
These four parts match the handoff contract shown at the delegate step of our orchestration run diagram. The hub's router attaches them when it sends a task to a specialist.
Structure beats prose
Handoffs written as free text are hard to check. Handoffs written as structured data, with named fields, can be validated automatically before the receiver starts work. We suggest a small schema for each handoff type, with fields like these.
goal: the outcome this work serves.items: the payload, each item with its required fields.notes: assumptions, caveats, and open questions.source: which agent or person produced it, and when.count: how many items the sender meant to pass.
When a handoff fails validation, the system can route it back to the sender or to a person instead of letting a downstream agent guess. The same discipline applies to the data agents read from your systems, which we cover in the marketing data contract.
Prose still has a place. A short free-text note inside the notes field often carries the nuance a schema cannot. The point is that the fields a receiver depends on should never live only in prose.
Common handoff failures
Four failures are worth designing against from the start. Each has a simple countermeasure once you know to look for it.
- Lost constraints: the planner knew the budget cap and the executor did not. Constraints must travel with the work.
- Silent truncation: a long list gets cut short somewhere in the chain and nobody notices. Include counts and check them on arrival.
- Format drift: one agent changes its output format slightly and breaks the next. Version your schemas and reject unknown versions.
- Confidence laundering: a guess made early becomes a fact later because nothing marked it as a guess. Carry confidence forward with each item.
Confidence laundering deserves extra attention. It is the failure most likely to reach a customer, because by the time the guess appears in a draft it reads as settled. A field that marks each item as verified, inferred, or unknown makes the guess visible at every later step.
A worked example
Consider a hypothetical account-based campaign. A research agent profiles 30 target accounts and hands them to an outreach agent that drafts first-touch emails. Under a loose handoff, the payload is a list of company names with a paragraph of notes on each.
Now add a contract. Each account carries a named contact, a reason for selection, a source for every fact, and a confidence flag. The context field states that the campaign excludes current customers and caps outreach at two contacts per account. The acceptance criteria require all 30 accounts, a source on every fact, and no contact without a verified role.
On arrival, the outreach agent counts 28 accounts and finds two contacts with roles marked as inferred. Instead of drafting 28 emails and guessing at the roles, it sends the handoff back with the two specific gaps listed.
A person resolves them in a few minutes. Without the contract, the same gaps would surface later as a misaddressed email, or never surface at all. Our post on agentic ABM covers the wider workflow this example sits inside.
Testing handoffs
Handoffs are among the easiest parts of an agent system to test, and among the most neglected. For each contract, we suggest a short test routine you can rerun whenever either agent changes.
- Collect real payloads: save recent examples, including messy ones, as a test set.
- Probe the edges: check that the receiver handles missing fields, empty lists, and low-confidence notes correctly.
- Confirm rejection: send invalid payloads and make sure they are rejected rather than quietly accepted.
- Check round trips: confirm that a rejected handoff reaches the sender or a person with a clear reason.
These tests catch problems before they reach production, and they are cheap to run. They also double as documentation: a new team member can read the test set and understand what each agent expects.
What to measure
A handoff contract gives you something concrete to count. We recommend tracking a few measures for each busy handoff, reviewed weekly while the workflow is new.
- Rejection rate: share of handoffs the receiver sends back, and the reasons given.
- Downstream defects: errors found in review that trace back to a handoff rather than to either agent.
- Resolution time: how long a rejected handoff waits before it is fixed and resent.
- Schema changes: how often a contract changes, and whether every change was versioned.
A rejection rate near zero is not always good news. It can mean the contract is too loose to catch anything. Pair it with downstream defects, and look at the run log in your observability tooling to see where errors actually start.
Open questions
We are still studying how much context a handoff should carry. Too little and the receiver guesses. Too much and the receiver spends its context window on material it does not need, which raises cost and can lower quality. The right amount likely varies by task, and we are testing whether the receiver itself can request more context on demand instead of the sender passing everything up front.
How to apply this: pick the busiest handoff in your current workflow, whether between agents or between an agent and a person. Write its contract in four parts (payload, context, assumptions, and acceptance criteria), then check how many recent handoffs actually met it.
Related research
Orchestration, not individual agents, is the real unit of work
A single agent can draft an email. A campaign needs research, drafting, review, routing, and measurement to work together, and coordination is the hard part.
The planner-executor pattern: separating what to do from doing it
Separating the agent that decides what to do from the agents that do it makes campaign automation easier to review, test, and trust.
Multi-agent content pipelines: researcher, writer, editor, checker
Splitting content creation across specialized agents mirrors how editorial teams already work, and makes each step easier to test, measure, and improve.
Put this research to work
Marketix turns these patterns into software: agents, automated workflows, and a hub that keeps people in control. Sign up for early access.
