Multi-agent systems need integration contracts

Contract the boundary, not the persona

Calling components researcher, implementer, and reviewer does not specify how they cooperate. For every handoff, define the input schema, output artifact, owner, allowed tools, data classification, deadline or expiry, and terminal states. Include unsupported and needs-clarification outcomes; otherwise an agent is pressured to manufacture a normal-looking result. MCP tool definitions illustrate typed input and optional output schemas, while A2A distinguishes stateful tasks, messages, and artifacts. Those protocols provide useful vocabulary, not an architecture guarantee. A production contract still needs domain rules such as whether an empty result means no findings, an incomplete search, or a failed dependency. Natural-language explanation may accompany an artifact, but downstream automation should not have to infer status from prose.

Make ownership and versioning explicit

One component should own each state transition and durable artifact. If both coordinator and worker may mark a task complete, cancellation and retry will eventually disagree. Give every task and attempted side effect stable identifiers. Version schemas independently from agent prompts, and state compatibility rules: reject unknown major versions, tolerate additive optional fields only when safe, and retain the producer version in the artifact. A2A's model separates messages used for interaction from artifacts used as task outputs and warns that transient messages are not necessarily reliable delivery. The engineering implication is broader: do not treat chat history as a queue, database, or completion ledger. Persist critical handoffs in a store with explicit delivery and deduplication behavior.

Worked example: a hypothetical migration team

A hypothetical dependency-migration workflow has three agents. The scout emits a MigrationInventory artifact containing repository revision, affected files, API patterns, unknown cases, and evidence links. The planner accepts exactly one inventory version and emits ordered ChangeBatches with protected paths and checks. Implementers claim batch IDs and return PatchResult artifacts with commit, commands, outcomes, and unresolved items. No agent merges. A human integrator reviews results and records Accepted, Rework, or Superseded. If two implementers touch the same file, the coordinator does not ask another model to blend their prose; it marks a contract conflict and replans from the current revision. This example is hypothetical, but the failure is ordinary distributed ownership, not a special property of language models.

Test integration failure before model quality

Use stub agents to exercise duplicate delivery, stale revisions, malformed artifacts, timeouts, cancellation races, partial results, incompatible versions, and a worker that reports success without its required evidence. Verify that the coordinator reaches a visible terminal or intervention state rather than looping. Then add real models and test semantic quality. This sequence separates integration defects from reasoning variance. Put limits on fan-out, retries, and context propagation so one ambiguous task cannot multiply into many expensive runs. Record lineage from final artifact back to inputs and agent versions. Multi-agent architecture earns its complexity only when specialization or parallelism produces a measurable benefit after coordination and review costs; otherwise one bounded agent with tools is easier to evaluate and govern.

A2A core concepts ↗

MCP tools specification ↗

Count coordination as work

Measure queue delay, duplicate research, merge conflicts, abandoned branches, and human arbitration alongside model usage. These costs often sit outside each agent's runtime and disappear from vendor dashboards. If coordination consumes the time that specialization was meant to save, collapse roles or redesign the artifact boundaries before adding another agent.