Prompt Contract Versioning: The Missing Discipline for Multi-Agent Systems

The most dangerous prompt change in a production multi-agent system is the one labeled "minor cleanup." Not a model swap. Not a new tool integration. A platform team added a sentence to a customer support agent's system prompt to clarify escalation tone. They ran five manual tests. It looked better. They shipped it.

Three days later, a routing orchestrator upstream began misclassifying 12% of escalated tickets — because that orchestrator was extracting a priority signal from a specific clause the "cleanup" had reworded. Nobody had documented the dependency. It surfaced in ticket quality data two business cycles later, not in monitoring.

That failure pattern has a name: an implicit output format dependency in a downstream consumer, broken by an undocumented prompt change. It is the core problem that prompt contract versioning exists to solve.

Prompt contract versioning is the practice of treating every production system prompt as a versioned interface with defined downstream consumers, documented output contracts, and explicit breaking change classification. The discipline is borrowed directly from API versioning. The mechanics need adaptation for the probabilistic, prose-heavy outputs of LLMs — but the governance logic is identical.

Prompt registries — the standard tooling recommendation for this problem — manage versions and enable rollback. What they do not do: tell you which downstream systems depend on specific output fields, or block a change that removes those fields before it reaches production. That gap is where silent failures live.

Software engineering has a well-developed vocabulary for interface contracts. When a REST API removes a field, the provider bumps a major version, communicates the deprecation, and gives consumers a migration window. The contract between provider and consumer is explicit, versioned, and observable.

Production AI agents have a contract too. Almost nobody treats it like one.

An agent that produces structured output — a JSON response, a formatted report, a decision with specific field names — is an interface. Anything consuming that output has a dependency on its format and behavior. The dependency is real whether it is documented or not. Teams discover this the hard way when a routing orchestrator breaks because the research agent it calls changed its citation structure, or a summarization pipeline starts injecting wrong data because an upstream classifier's output schema quietly shifted.

The gap compounds in multi-agent systems. A routing orchestrator is written to parse what the upstream classifier "happens to produce." A summarization pipeline is built against whatever the research agent currently outputs. These implicit dependencies accumulate as teams iterate on prompts independently, often without knowing who else is consuming the output. The result: a web of undocumented interface assumptions that nobody owns and nobody tests.

Prompt registries tell you what version is running and let you roll back. They do not enforce contracts between producers and consumers. They cannot tell you which downstream systems will break if you restructure the output format or remove a field. That gap — between version tracking and contract enforcement — is where the failure class described above lives. ^[2]

Semantic versioning adapted for system prompts gives teams a shared vocabulary for what counts as a breaking change. Without this vocabulary, every prompt change becomes a judgment call. Judgment calls at scale become inconsistent — which means some breaking changes ship unannounced and some patch changes get escalated unnecessarily.

The counter-intuitive rule: a "typo fix" is a patch only if no downstream consumer depends on the exact phrasing you fixed. If a downstream parser was extracting a value by matching on a specific string that happened to contain the typo, fixing it is a major version bump — regardless of your intent. Classification is determined by the consumer's dependency, not the author's perception of the change. ^[3]

This matters because most prompt authors underestimate how many downstream systems parse around specific output phrasing. The practical approach: before classifying any change as patch, ask whether any registered consumer test touches the modified clause. If you do not have consumer contracts registered yet, ask who consumes this agent's output and contact them before shipping.

The failures that matter are two or three hops deep.

A common structure: an orchestrating agent calls a research agent, extracts structured data from the response, and passes it to a summarization agent. The research agent's team updates their system prompt — "minor clarification of citation format." The orchestrating agent was parsing a priority field that reliably appeared in position three of the citation block. After the update, the citation structure shifted enough that position three now contains a different value. The orchestrator injects wrong data into the summarization agent's context. The summarization agent produces plausible but incorrect summaries. No exception is thrown. No alert fires. The divergence surfaces in a quality audit three weeks later.

Three properties make this failure class dangerous: it is silent (no exceptions, no degraded health indicators), it is delayed (surfaced through output quality rather than system metrics), and it is deep (three hops from the change to the visible symptom). Standard observability — error rates, latency, uptime — would not catch this. Only a registered consumer contract, running as an automated check on every prompt change, would have blocked the update before it shipped.

This is not hypothetical. Teams that have instrumented their multi-agent stacks commonly find undocumented format dependencies that only become visible during incident postmortems or structured dependency audits. A practical rule that has emerged from teams who have been through this: if Agent B's behavior depends on Agent A's output format in any way, changing Agent A's prompt is a major version bump — regardless of how the change feels to Agent A's team. The version bump decision belongs to the consumer's dependency, not the author's intent. ^[3]

The agent manifest is a document that maps each production agent to the contracts it publishes and the contracts it depends on. Its purpose is not documentation — it is searchability. When a prompt change is proposed, the manifest answers immediately: which downstream systems depend on this agent's output format? Without a manifest, answering that question requires a codebase audit, trace log parsing, and conversations with teams who may not remember what they built. ^[3]

The manifest has two halves. The provider half records which version of the prompt is active, what output schema and fields the current version produces, and when each field was introduced. The consumer half records which upstream agents' outputs this agent depends on, which fields it extracts, and which version of the upstream contract it was last tested against.

Consumer contracts — the test fixtures that block breaking changes in CI — are registered within the manifest. Each registered consumer specifies: given this input, the upstream agent's output must contain these fields with these types. The platform team runs these fixtures against every candidate prompt version before promotion. One failing fixture blocks the deployment.

This pattern is well-established for REST APIs under the Consumer-Driven Contract (CDC) model, popularized by tools like Pact. Applying it to prompts requires adapting to probabilistic outputs — you test structural contracts (field presence, type, schema conformance), not exact value matches. ^[1]