Input/Output Contract Design

Every agent in a team makes two promises. It promises to accept a specific input format. It promises to return a specific output format. These two promises — the input/output contract — are what make agent composition possible. Without contracts, connecting Agent A to Agent B is guesswork. With contracts, it is plumbing.

The input contract specifies: what data the agent expects, in what format, with what fields required versus optional. The research agent expects a company name (string, required), an industry vertical (string, optional), and a list of specific data points to find (array of strings, required). If the input does not match the contract, the agent should fail clearly — "Missing required field: company_name" — rather than hallucinate a response from incomplete data.

The output contract specifies: what the agent returns, in what format, with what guarantees. The research agent returns a JSON object with company_name, funding_stage, team_size, product_description, recent_news (array of 3 items), and data_sources (array of URLs). Every field is present in every response. If the agent could not find a data point, the field contains null with a reason — not an omitted key.

Why does this level of specification matter? Because the next agent in the pipeline depends on it. If the draft writer expects a research JSON with a recent_news array and the research agent sometimes returns recent_news as a string instead of an array, the pipeline breaks intermittently. Intermittent failures are the worst kind — they work in testing and fail in production. Strict output contracts prevent intermittent failures by making the format predictable.

Contract design also enables substitution. If your research agent is underperforming, you can swap it with a better one — as long as the replacement honors the same input/output contract. The rest of the pipeline does not care which agent produced the research. It cares about the format of the output. This is the same principle that makes APIs composable in software engineering: the interface is stable, the implementation is replaceable.

In practice, I document contracts in the CLAUDE.md file or a dedicated contracts.md file in the project. Every agent's prompt includes its contract. The parent coordinator knows what to feed each agent and what to expect back. When something breaks, the first diagnostic step is checking whether the contract was honored. Nine times out of ten, the problem is a contract violation — an agent returned something unexpected, and the downstream agent could not parse it.