Handoff is a contract.

Why the interface matters more than the agent CORE

Imagine you have two agents, each of which does a fine job on its own. The research agent produces a clean, well-cited set of notes when you hand it a topic. The drafter agent produces a clean, readable brief when you hand it a set of notes. Separately, both are good. Connected, their combined pipeline produces a brief that reads like it was written from half the research — citations drop, the angle is off, the draft misses one of the source documents entirely.

A Module 7 student’s instinct is to blame the drafter — “the drafter isn’t picking up on the sources correctly.” A Module 8 student reads the trace and asks a different question: what did the researcher hand to the drafter, and did the drafter know what to do with it?

Almost always, the answer is the same. The researcher produced notes in one shape — a pile of bullet points, some with source URLs, some without, some with two-sentence summaries, some with one-sentence summaries. The drafter was given those notes and told “write a brief.” The drafter did what it was trained to do — it produced a readable brief — but it had no way to know that the one-sentence bullet points were the important ones and the two-sentence ones were peripheral, or that a bullet without a URL was supposed to be flagged and excluded. The drafter guessed, sensibly, and guessed wrong.

Nothing in the drafter’s prompt was wrong. Nothing in the researcher’s prompt was wrong. The thing that was wrong was the interface — the handoff. Neither agent had a shared understanding of what the output of the research step was supposed to look like and what the input to the drafting step was supposed to be.

This is the most common failure mode of multi-agent systems. It is not “the model is bad.” It is not “the prompt is bad.” It is that the student built two agents and then drew an arrow between them and assumed the arrow would carry meaning. Arrows do not carry meaning. Contracts carry meaning. A handoff contract is the written specification of what flows down the arrow, and it is the most important artifact in the pipeline.

The headline claim of this module, in one sentence: the quality of an orchestrated system is set by the quality of its handoff contracts, not by the quality of its agents. A pipeline of three mediocre agents with tight contracts will outperform a pipeline of three brilliant agents with vague ones. This is not a marketing slogan; it is what you will see the moment you start building.

The four-field handoff contract CORE

A handoff contract has four fields. You write them down before you write the agents. The contract is short — rarely more than half a page per handoff — because its purpose is to be readable at a glance by the student, by a future self, and by the agent on either side of the handoff.

1. Input shape. What the receiving agent expects to get. The name of the file (or files) it will read. The format — markdown, JSON, prose, a list. Any required structure (headings, bullets, numbered steps, fields). Any required content (must include citations, must not include speculative claims, must be under a length limit). If the input is a set of files, the contract names how many files, how they are named, and what each one contains.

2. Output shape. What the sending agent promises to produce. Same structural specificity as input shape, but from the sender’s point of view. If the receiver’s input shape and the sender’s output shape do not match, the contract is broken by definition. In practice the two fields often look identical — that is fine, and is the sign the contract is tight.

3. Success criteria. How the receiving agent decides that the handoff is usable. “The file exists at the expected path.” “The file has at least three bulleted items.” “Every claim has a URL in parentheses.” “The summary is between 200 and 400 words.” Success criteria are checks the receiver can perform without reading the sender’s mind — they are objective, and ideally testable.

4. Failure mode. What happens if the handoff fails — if the file is missing, if the structure is wrong, if the success criteria are not met. Failure modes come in a small menu: stop the pipeline and alert the student, retry once with a tighter prompt, fall back to a degraded output, skip this stage and pass empty to the next. Naming the failure mode in advance prevents the retry-runaway problem — an agent that “retries until it works” is an agent that can spend your month’s budget in an afternoon.

All four fields must be present. A contract with three of the four is not a contract; it is a wish. The most common omission is field 4 — students name success criteria but do not say what happens when those criteria are not met. That omission is exactly the opening through which retry runaway enters.

How many contracts, in which pattern CORE

A pipeline has exactly as many contracts as it has handoffs. Count the handoffs, write that many contracts. The count varies by pattern:

Sequential pipeline. N agents, N–1 handoffs. A two-agent pipeline (research → draft) has one contract. A three-agent pipeline (research → draft → review) has two: research → draft, and draft → review. A four-agent pipeline has three. Each contract stands alone; the fact that research → draft exists does not tell the draft → review contract anything.

Parallel workers. Two contracts per fan-out/fan-in unit, regardless of the worker count. The fan-out contract specifies what each worker receives as input and what each worker is expected to produce as output (the workers all share this contract). The fan-in contract specifies how the combiner reads the N worker outputs and what the combined output looks like. A pipeline with three parallel workers has one fan-out contract and one fan-in contract — two contracts total, not four. The combiner is an agent, but its input is governed by the fan-in contract, which already says “reads N outputs produced per the fan-out contract.”

Hierarchical supervisor. One contract per supervisor-worker edge. A supervisor with four worker types (even if it chooses to spawn multiple instances of a worker type) has four contracts — one per worker type. The supervisor itself needs a contract if it is receiving input from an upstream agent or producing output for a downstream one; that is a separate contract.

Counting contracts before you start writing agents is a useful sanity check. A pipeline with too many contracts — six, eight, ten — is almost always a pipeline that wants to be flatter than its author has let it be. A pipeline with too few contracts for its agent count is almost always a pipeline where handoffs have been left as arrows without specification, and the student has not noticed yet.

When the contract needs a schema CORE

A handoff contract is always written as prose in the blueprint. The question this block answers is whether the output shape the sender produces should be a structured format the receiver can parse by pattern (JSON, YAML, a table) or a prose format the receiver reads as natural language (markdown with headings, a plain paragraph). Both are legitimate. The wrong choice either adds ceremony that slows the pipeline (schemas where prose would do) or leaves the receiver guessing (prose where a schema would have been clearer).

The three-part test:

1. Is the output consumed by logic or by language? If the next stage is an agent that will read the output and reason about it, prose is usually fine — the agent can parse meaning from text. If the next stage is a script or tool that will act on specific fields (write to a calendar, file an email, populate a template), you need a schema. Every field the script will read needs to be in a machine-parseable format.

2. Is the output’s structure stable enough to write down? If the output has a fixed set of fields that appear every time — title, URL, summary, three-word tag — that is a schema-shaped output. If the output is variable-length, variable-section, variable-emphasis — “however many sources the topic needs, with whatever commentary makes sense for each” — forcing it into a schema is ceremony and will probably lose information.

3. Is the pipeline running often enough to reward the ceremony? A pipeline you will run once a week is not worth a schema you will also have to maintain; prose is fine. A pipeline that runs every day at 6 a.m. and whose output feeds a downstream script benefits from a schema because you will save minutes of debug time every time it runs.

Applied to the research → draft handoff from Content Block 2: consumed by language (the drafter reads, reasons, writes), variable structure (summaries vary in length and emphasis), runs several times a week. Prose with a markdown structure is the right call — which is what the example contract used.

Applied to a scheduled-tasks handoff where the first stage writes calendar events and the second stage populates a calendar via an MCP connector: consumed by logic (a tool will read specific fields), stable structure (every event has start, end, title, attendees), daily. JSON schema is the right call.

The practical consequence: most Module 8 pipelines end up with prose contracts for their language-to-language handoffs and one or two structured-schema contracts where a tool takes over at the end. That asymmetry is normal. It is not a sign the pipeline is inconsistent; it is a sign the pipeline is honest about where language ends and structure begins.

Six signs of a vague contract CORE

A key Module 8 skill is the ability to look at a handoff contract and recognize when it is vague. Here are the signs. Every one of them has bitten a student into a runaway or a silent-failure hour.

• “The output should be good.” Or “high-quality,” or “well-organized,” or “clear.” These are not success criteria; they are hopes. Replace with testable statements: word counts, required sections, required fields, “every claim has a URL.”
• “The receiver reads the output and uses it.” Not specified what shape, not specified what happens if the shape is unexpected. Replace with file path, format, structure, and the failure mode on malformed input.
• “Retry if something goes wrong.” Unbounded retries are the fastest path to token runaway. Specify how many retries, under what conditions, and what triggers “give up and stop.”
• “The output is a JSON object.” Not specified which keys, which types, which are required vs. optional. A JSON contract that does not name its keys is a prose contract in disguise, with an extra step.
• “The input is whatever the upstream agent produces.” This is the absence of a contract. If you find yourself writing it, stop and write the actual input shape — you have not thought about the handoff yet.
• Contract longer than a page. Usually a sign the student is trying to do the agent’s job inside the contract. A contract describes the interface; the agent’s prompt does the work. If the contract is doing work, pull it back out.

When you write contracts for your pipeline, read each one with this list in hand. A contract that passes all six is rare on the first draft and common on the third. The iteration is the point.