Agent handoff contracts need versions when field meaning or required structure changes. An older specialist can produce plausible output that the new coordinator interprets incorrectly unless the boundary is explicit.
Agent contracts include semantics and scope
A data contract defines accepted fields, result categories, evidence references, uncertainty representation, and permitted task scope. A JSON shape alone does not establish whether “complete” means analysis finished or a business action executed.
For a proposed contract registry, record version, producer and consumer compatibility, required fields, defaults, authority assumptions, and representative fixtures. Include the version in every handoff and preserve it in diagnostic records.
Do not silently reinterpret old packets through the newest contract. Use a tested adapter or return a safe unsupported-version result. Long-running tasks and delayed messages may outlive a rolling deployment.
Rehearse a fictional status change
Version one returns “ready” to mean that a recommendation is available. Version two uses the same word to mean the action is approved for execution. Keeping the field type unchanged would not make this compatible; it changes the authority boundary.
The migration should introduce distinct semantics and test old-producer/new-consumer combinations. An adapter must preserve the original recommendation status rather than upgrade it into permission.
| Contract change | Test requirement |
|---|---|
| Optional evidence field added | Omission preserves safe behaviour |
| Required operation reference added | Older packets handled explicitly |
| Status meaning changed | New semantic version or equivalent explicit boundary |
| Uncertainty representation narrowed | No silent certainty upgrade |
| Access scope changed | Trusted permission checks remain authoritative |
Replay stored fictional packets from each supported version. Verify the final business behaviour, not merely that parsing succeeds.
Retire versions with observable evidence
Track which active tasks and consumers depend on older contracts. Define a retirement condition and owner. A deployment finishing does not prove every delayed response or recovery job has migrated.
Adapters add maintenance and can hide divergent assumptions if kept indefinitely. Keep their purpose narrow and test domain meaning. A small stable contract is often easier to operate than a packet carrying every previous message and optional interpretation.
This versioning design is proposed. The voice integration case study provides related integration context. Pair it with structured agent handoffs.
During migration, include a fixture where an older agent returns late after its replacement has already completed the task. The stale response must not revive execution.
Agent contract FAQ
Is adding a field always safe?
No. Defaults, consumer validation, and behavioural meaning determine compatibility.
Can a prompt version identify the contract implicitly?
Record the relationship explicitly, especially when producers and consumers deploy independently.
What should happen to an unsupported packet?
Reject or adapt it through a documented tested path without guessing consequential meaning or authority.