← Back to Guides
3

Series

Federated AI Agents· Part 3

Companion to the book Federated AI Agents · this part maps to Chapter 4

GuideFor: AI Engineers, ML Engineers, Platform Engineers, AI Systems Architects

A2A Agent Card Versioning: a Version Bump Is Not a Contract

A version bump tells callers that something changed, and a dated notice tells every caller the same thing. From the caller's side, only dated terms checked against what each caller depends on warn the right caller early.

#a2a-protocol#agent-card#api-versioning#contract-testing#multi-agent-systems#agent-interoperability

This series grew into a book: Federated AI Agents. Chapter 4 covers this part. Where the chapter goes further is at the end of this article.

A repair network called Northgate bumped its A2A agent card from v7 to v8, added "needs the vehicle's VIN" to a skill description, and from the next motor claim on, every estimate task an insurer sent it came back rejected. Northgate had done what the guides advise, and every motor claim at the insurer stopped at the same seam and waited in a queue for a person. The claims team learned about v8 from its error rate.

A2A agent card versioning has no rule in the protocol. Changing the version on an agent card tells a caller's code that something changed, never what changed or whether it matters to that caller, because the protocol does not say what a version change means. The usual upgrade is a dated notice, such as a Sunset header, and it fails in a quieter way. A date with no terms gives notice without relevance: it says when something changes and not whether the change touches you. A caller then has to choose between missing breaks and alarms that someone must read. This guide shows how to publish dated terms on the card and check them at connect, so a breaking change reaches only the callers it affects.

I worked that choice through on nine constructed revisions of one partner, and then on two callers of the same partner. From the caller's side, only dated terms on the card, checked by each caller against its own expectations at every connect, get out of it.

Release v8 priced parts per vehicle model, so estimate_repair needed the VIN. The claims graph raised a typed error on every rejection, as Part 2 built it to, so no claim was paid on a missing estimate. Meridian Mutual, its claims graph and Northgate are the fictional running example from my book, but the behaviour is real. A test in the companion repository deploys v8 behind a card that changed only its version and description, and a clean claim's estimate is rejected after Northgate has already received the task.

A2A agent card versioning: what the card promises a caller's code

An A2A agent card describes an agent, and most of it is written for a person. Look at one skill. In the v1.0.1 protocol buffer, AgentSkill has exactly eight fields: id, name, description, tags, examples, input_modes, output_modes and security_requirements. None of them is an input schema or an output schema, and none of them is a version. Both "modes" fields list media types, such as application/json, not fields.

The card itself does have a version. Here is everything the proto says about it: "The version of the agent." Its comment gives "1.0.0" as an example, and says nothing about what a change in that string means, which changes need one, or what a client should do when it sees one.

Community guides have filled that gap with a habit: bump the version when behaviour changes. A field-by-field agent card guide on frankx.ai, titled "the portability contract", says "If you need to change behavior, bump the version of the agent and consider keeping the old skill ID as a deprecation alias for a release cycle." It also promises that "Agents consuming your Card can pin to a known version." Its production checklist ends with "Version bumped if behavior changed since last publish". (That page returned 404 on 2026-11-18; I quote the Internet Archive's copy from 2026-09-11.) Nothing in the spec gives that advice anything to stand on, which is why following it did not help Northgate.

I call these brochure fields: card fields written for a person, or a model, to read, which no deterministic check can act on correctly. They include the name, the description, the version string, a skill's examples and its tags. Changing a brochure field announces a change to a person who happens to be looking. Meridian's claims client builds its connection from the interface URL, picks the skill by its id and copies the version into a log, so its code never sees the announcement. A planner model that reads skill descriptions to choose a call would see the words "needs the vehicle's VIN", but nothing checks what it does with them, and nobody is told when it gets them wrong.

Part 1 summed up the contract property of a seam as "a versioned card you test against". This part makes that precise: what you test against is the versioned terms on the card, and the version string labels them.

Now list what a caller needs to know before it sends a task to an agent somebody else owns, and set each question against the card fields that could answer it.

d2
grid-columns: 2
grid-gap: 30
classes: {
  code: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  person: {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
  yes: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  no: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
}
card: "What a v1.0.1 card carries" {
  label.near: top-center
  grid-columns: 1
  grid-gap: 10
  c1: "Read by code: interface URL,\nskill id, security schemes,\ncapabilities" {class: code}
  c2: "Brochure fields: name, description,\nversion, skill tags, examples" {class: person}
}
needs: "What a seam needs before its first task" {
  label.near: top-center
  grid-columns: 2
  grid-gap: 8
  q1: "Where to send" {class: yes}
  q2: "How to authenticate" {class: yes}
  q3: "Required input fields" {class: no}
  q4: "Output meaning and unit" {class: no}
  q5: "Which data it may receive" {class: no}
  q6: "Questions it may ask" {class: no}
  q7: "How long it takes" {class: no}
  q8: "When any of this changes" {class: no}
}

Two of the eight questions have a field. For the other six there is, at best, a sentence in a description, and for the last one, when anything changes, there is only the version string. That string tells you that something changed and leaves out what and when.

What makes an A2A agent card a contract: dated terms the caller checks

The usual advice is that the card is a contract and the version is how you signal breaking it. The careful version of that advice adds a date, so callers get warning. My claim is that both fail for the same reason. A version and a date tell every caller the same thing, and whether a change breaks a seam depends on what one caller depends on. A signal with a date and no terms is notice without relevance, and no rule a caller writes over it can be both early and quiet. A card escapes that only under three conditions:

  1. Each partner publishes its terms as data on the card, in revisions that each carry the date they take effect.
  2. Each time it connects, and on a schedule such as daily, the caller checks its own, narrower expectations against every revision on the card. A breaking change is then found at the caller's first connect after the partner announces it, as far ahead of its effective date as the partner announced it.
  3. A breach refuses the one seam it breaks, and the rest of the caller keeps running.

The check has one limit, and I will show it in code rather than hide it. It reads declarations, so a partner that changes behaviour under terms it did not change passes every check.

For a team adopting this, the useful view is who owns each condition and when it runs:

d2
grid-rows: 4
grid-columns: 3
grid-gap: 10
classes: {
  head: {style: {fill: "#95A5A6"; stroke: "#6E7B7C"; font-color: "#2C2C2A"; bold: true}}
  theirs: {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
  ours: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  run: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
}
h1: "Condition" {class: head}
h2: "Owned by" {class: head}
h3: "Runs" {class: head}
c1: "1. dated terms on the card" {class: theirs}
o1: "the partner, under the\npartner agreement" {class: theirs}
w1: "once per release,\nat announcement" {class: theirs}
c2: "2. expectations checked" {class: ours}
o2: "the caller, one file\nper seam it calls" {class: ours}
w2: "at every connect\nand in CI" {class: ours}
c3: "3. per-seam refusal" {class: run}
o3: "the caller's runtime" {class: run}
w3: "on every send,\nbefore a byte crosses" {class: run}

Only the first row needs the partner: it publishes each revision, and withdraws, postpones or reorders revisions when plans change. The other two rows are code in the caller's repository that runs without anybody reading a changelog.

This failure has already happened to a real, widely used API. On 8 August 2025, GitHub's changelog announced changes to the payloads of its Events API, with a brownout test on 8 September and the change itself on 7 October. One line read "Push events: Removing commit summaries and counts that require slow external calls." The announcement was correct, dated and public. It was also prose. In GitHub Discussion #177111, one user called it "a silent breaking change to the Events API" and wrote that "existing, production-critical jobs and integrations broke overnight." GitHub has a dated API version header, X-GitHub-Api-Version, and the same post notes the change "rolled out under the same 2022-11-28 version header." A caller pinned to a version would have been broken as well.

That is the Northgate pattern in a public API: an announcement in prose for people to read, which the code that depended on it never saw, and which a version label would not have caught either.

Why gating on the version string fails

If the version is the signal, the obvious fix is to act on it, so I tested that. I built eleven Northgate revisions and ran each through four gates a caller could put in front of the estimate seam. Each revision is labelled with the truth: does it actually break what Claims depends on?

  • ignore: what the claims graph did on the day of the incident. It records the version and acts on nothing.
  • exact pin: refuse any version other than v7.
  • major pin: semantic-versioning discipline, refuse any change of major version.
  • check: the contract check this article builds, run against Claims' expectations file.

Both version gates are the code a careful team writes after the first incident:

python
def exact_pin_refuses(card: AgentCard) -> bool:  # anything but the tested release    return card.version != "v7"def major_pin_refuses(card: AgentCard) -> bool:  # trust semver: a new major only    return card.version.lstrip("v").split(".")[0].split("-")[0] != "7"

I built the eleven revisions myself to cover the kinds of change a partner makes. Nobody released them, so the counts show failure modes, and they are not rates. My script imports the companion's chapter-4 code and changes one thing per revision; it is not part of the companion repository. The scripts are not published, so every revision is below for anyone who wants to rebuild the experiment:

RevisionWhat changedBreaks Claims?
v7.1new optional input paint_codeno
v7.2estimate_history returns one more fieldno
v7.3p95 promise drops from 4.0 s to 2.5 sno
v7-hotfixlabel only, terms unchangedno
v9estimate_history skill removedno
v8new required input vinyes
v8.1estimate declared in EUR, not claim currencyyes
v8.2may ask for vin in input-requiredyes
v8.3accepts no vehicle datayes
v7.4may ask for adjuster_notesyes
v7card unchanged, agent now returns EURyes

Here is how each gate scored:

GateHarmless revisions refused (of 5)Breaking revisions missed (of 6)
ignore06
exact pin51
major pin12
check01

Two revisions decide the major-pin row. In v7.4, Northgate's skill may now stop and ask for adjuster_notes. Northgate calls that additive and labels it a minor release. For Claims it is a new question that nobody has decided whether to answer, and a claim would stop on it. In v9, Northgate drops its estimate_history skill and labels it, correctly, a major release. Claims never calls estimate_history, so v9 is harmless to Claims. The major pin passes the first and refuses the second, as these three rows from the script's own output show:

text
revision                                     breaks?  ignore  pin     major   checkv7 relabelled v7-hotfix, nothing changed     False    pass    REFUSE  pass    passv7.4 may ask for adjuster_notes (minor)      True     pass    REFUSE  pass    REFUSEv9 drops estimate_history (major)            False    pass    REFUSE  REFUSE  pass

One caution about the set. A first run had eight revisions, and on those the major pin scored as well as the check. I then added v7.4, v9 and the unchanged card, because those are the cases where the partner's label and the caller's impact disagree. So the table shows that such cases exist and what each gate does with them, but it does not show how often they happen.

The "Breaks Claims?" column does not come from the expectations file the check reads. I took it from behaviour. A small subclass of the companion's Northgate executor behaves as each revision says: it rejects a missing required input or data it no longer accepts, stops to ask any question in asks (the photo only for frame damage, as in the companion), and returns euros where the terms say EUR. The stub turns every "may ask" into an actual question, which is the worst case the terms allow. Claims' real federated graph then runs the clean claim CLM-1001 with the contract check switched off, as the companion's incident test does. On v7 the claim is paid 3,000. Every revision the column marks harmless is also paid 3,000. Every revision it marks breaking either raises a typed error (PartnerRejected for v8 and v8.3, PartnerNeedsInput for v8.2 and v7.4) or, worse, is paid 2,760, which is the two euro rows: the field map accepted a number in the wrong currency. The stub is mine, and v7.3's faster promise is not simulated as time, but no row of the column rests on the file alone.

Read the version gates as one trade. The exact pin refuses every release, including a hotfix that changed only the label, while the major pin trusts the partner's judgement of what is breaking. Neither can do better, because whether a release breaks anything depends on the release and on one caller together. Ian Robinson made this argument in 2006, in his article on consumer-driven contracts: "provider contracts emerge to meet consumer expectations and demands." A version is one label the partner chooses for every caller at once, and Northgate cannot know that v7.4 breaks Claims unless it knows what Claims depends on.

The one break the check missed is the last revision: the v7 card, unchanged, while the agent behind it now returns estimates in euros. Every gate missed it, and the limits section comes back to it.

The counts hide a second difference, which matters more: when each gate sees a break. A fair test has to show every gate the same announcement, so I added two date-only controls that read the announcement and nothing about its terms. The any notice gate fires on every announcement. It is an upper bound that no real header reaches: those headers mark the deprecation of a resource, carry a date and no description of the change, and nobody sends one for an added optional input. The realistic date-only gate is the next one, so I treat it as the main comparison. The dated label gate is more generous than any real header: it also reads the announced revision's label, and fires when that label is a new major version, so it trusts the partner's semver.

Then I ran a calendar. Each of the nine revisions that change anything is announced on 2026-10-05 and deployed on 2026-11-02. Every day, the script builds a real AgentCard the way Northgate would publish it. Before deploy, the card has version v7 and both revisions' terms. From deploy day, it has the new version and only the new terms. Each gate reads that card and nothing else, and the script records the first day each gate fires. Here is its output, with the labels shortened and the columns narrowed to fit:

text
revision                  breaks  exact   major   label   any     checkv7.1 optional paint_code  False   deploy  never   never   -28 d   neverv7.2 history returns more False   deploy  never   never   -28 d   neverv7.3 faster p95           False   deploy  never   never   -28 d   neverv8 requires vin           True    deploy  deploy  -28 d   -28 d   -28 dv8.1 estimate in EUR      True    deploy  deploy  -28 d   -28 d   -28 dv8.2 asks for vin         True    deploy  deploy  -28 d   -28 d   -28 dv8.3 no vehicle data      True    deploy  deploy  -28 d   -28 d   -28 dv7.4 asks adjuster_notes  True    deploy  never   never   -28 d   -28 dv9 drops estimate_history False   deploy  deploy  -28 d   -28 d   never

"deploy" means the gate first fires on deploy day, and "-28 d" means 28 days before it. I chose the 28-day gap myself, so the pattern carries the result. Both version gates read card.version, which changes on deploy day, so they cannot fire before deploy day. By then a breaking release is already failing claims, and the exact pin also refuses four harmless ones; the major pin never refuses v7.4 at all. Each date-only gate gets the same 28 days as the check and then has to guess. Among the nine announced revisions, the dated label makes the major pin's two mistakes a month earlier: it warns on v9 and stays silent on v7.4. The any-notice gate catches all five breaks, and it also raises an alarm on all four harmless revisions, so somebody at Claims has to read every one of Northgate's changelogs to find out which alarm matters. That reading is what the GitHub Events API change showed integrators do not reliably do.

The two controls are the two ends of one dial. Any rule over a date and a label has to decide which announcements to trust, and a rule loose enough to catch v7.4 also fires on v7.1, v7.2 and v7.3, because those carry the same kind of label. Turning the dial moves errors from one column to the other, and no setting removes them, because the information that separates v7.4 from v7.1 is not in the signal. It is in the terms, compared with what one caller sends and reads. Only the check is right on all nine, and it fires 28 days before deploy. On the calendar, from announcement to effective date:

d2
grid-rows: 5
grid-columns: 3
grid-gap: 12
classes: {
  head: {style: {fill: "#95A5A6"; stroke: "#6E7B7C"; font-color: "#2C2C2A"; bold: true}}
  gate: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  zero: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
  lead: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  some: {style: {fill: "#FFD93D"; stroke: "#C9A400"; font-color: "#2C2C2A"}}
}
h1: "Gate" {class: head}
h2: "2026-10-05\nrevision announced" {class: head}
h3: "2026-11-02\nrevision in force" {class: head}
g1: "exact or major pin" {class: gate}
a1: "silent: card.version\nis still v7" {class: zero}
b1: "deploy day: too late for\nbreaks, false refusals\nof harmless releases" {class: some}
g3: "dated label (control)" {class: gate}
a3: "warns on v9 (harmless),\nsilent on v7.4 (breaks)" {class: some}
b3: "no new signal: v7.4 now\nbreaks with no warning" {class: zero}
g4: "any notice (control)" {class: gate}
a4: "warns on all 9:\n5 breaks, 4 false alarms" {class: some}
b4: "no new signal: a person\nhad to read all 9" {class: some}
g2: "check() via held_to()" {class: gate}
a2: "dated breach for every announced\nbreaking revision, none for v9" {class: lead}
b2: "refuses the one\nbreached seam" {class: lead}

Why a Sunset header cannot tell two A2A callers apart

The dial argument has a sharper form. If relevance lives in the terms read against one caller, two callers reading the same card on the same day should get different answers, and no date or label carries what separates them. I tested that with a second insurer. Harbor is hypothetical, and it calls the same Northgate skill under a different expectations file. Its adjusters answer adjuster_notes, its intake answers photo requests, and it waits five seconds for an estimate where Claims waits ten. Both files pass against v7 today. Then each revision is announced on the v7 card, and each caller runs held_to() against its own file:

text
revision announced on the v7 card        Claims    Harborv7.1 optional paint_code input           -         -v7.2 estimate_history returns more       -         -v7.3 faster p95 (4.0 -> 2.5 s)           -         -v8 requires vin                          breach    breachv8.1 estimate in EUR only                breach    breachv8.2 may ask for vin as a question       breach    breachv8.3 accepts no vehicle data             breach    breachv7.4 may ask for adjuster_notes (minor)  breach    -v9 drops estimate_history (major)        -         -v7.5 p95 promise 4.0 -> 8.0 s            -         breach

Two rows split the callers, and they split in opposite directions. v7.4 breaks Claims and not Harbor, because Harbor's people answer that question. v7.5, a slower promise added for this run, breaches Harbor's declared five-second timeout and not Claims' ten. A p95 of 8 seconds does not mean every call is slow, so this row is an honest slower promise that no longer fits Harbor's timeout, and I did not simulate it as latency. Harbor runs under Meridian's data-class policy. Both callers saw the same card, the same label and the same date, and each could write its own rule over that signal. It would not help. Claims' rule cannot tell v7.4 from v7.1, v7.2 and v7.3 by label or date, and Harbor's rule cannot tell v7.5, a slower promise, from v7.3, a faster one. Both are minor releases announced the same way. Northgate cannot fix this from its side either, because no single label for v7.4 is right for both callers:

d2
direction: right
classes: {
  card: {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
  file: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  hdr: {style: {fill: "#FFD93D"; stroke: "#C9A400"; font-color: "#2C2C2A"}}
  brk: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
  ok: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
}
card: "One Northgate card\nv7 in force, v7.4 announced" {class: card}
sig: "Date-only signal:\nthe same for both" {class: hdr}
cf: "Claims' file:\nrefuses unplanned questions" {class: file}
hf: "Harbor's file:\nanswers adjuster_notes" {class: file}
cv: "dated breach" {class: brk}
hv: "no breach" {class: ok}
sv: "one label for both:\nNorthgate cannot make\nit right for each" {class: hdr}
card -> cf: "terms"
card -> hf: "terms"
card -> sig: "date only"
cf -> cv: "held_to()"
hf -> hv: "held_to()"
sig -> sv

This is the measured difference from the scanners and headers in the prior-art section below. Headers and labels send the same signal to every consumer. Deprecation scanners do compute relevance per consumer, but against one vendor's public, version-keyed schedule, with no partner-specific terms to fetch at connect. Harbor is my construction, as the revisions are, and I ran its column through held_to() only, since the companion has no Harbor graph to run.

Consumer-driven contracts for A2A agents

So the contract needs two halves, with two owners. Inside one team, a contract between agents is a design choice in the topology you pick; across a company line, it has to be written down on both sides. My book calls the pair a seam contract, after Part 1's owner seam: the boundary where a call crosses from one owner to another.

The partner's half is its terms. For each skill, they list its input and output fields with type, required flag, scale and unit, the questions it may stop to ask, and its promised response time. For the partner as a whole, they give the auth schemes and the classes of data it agrees to hold. They are published in revisions, and each revision has an effective date.

Against them the caller holds its consumer expectations: what this one seam sends, what it reads and on what scale, which partner questions it answers or refuses, and the auth and response time it needs. Both the term and the idea are Robinson's. This article changes who holds them. In Robinson's pattern, and in tools like Pact, the provider runs its consumers' contracts. Across a company line, Northgate is not obliged to run anything Meridian wrote, so the consumer keeps its expectations and checks them itself.

The strongest objection is that Northgate could simply run every insurer's contract before each release, through Pact's can-i-deploy. Some partners will, and that is better than nothing. It needs a broker that competing insurers all publish to, so each one hands its dependencies to a service its competitors also use. It also depends on Northgate wanting to know, release after release, and on Northgate agreeing at all. When it works, it is stronger than a notice, because it can block Northgate's deploy. Pact's verification results are machine-readable, and a broker can expose them to each consumer, but the result exists only if Northgate runs the verification and gives you access to the broker. The caller-side check needs none of that, and it still works when the partner does run Pact, because the two checks answer different people.

d2
direction: right
classes: {
  theirs: {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
  ours: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  chk: {style: {fill: "#FFD93D"; stroke: "#C9A400"; font-color: "#2C2C2A"; bold: true}}
  out: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
}
ng: "Northgate owns: terms on its card" {
  label.near: top-center
  grid-columns: 1
  grid-gap: 10
  v7: "v7, effective 2026-06-01\nin force" {class: theirs}
  v8: "v8, effective 2026-11-02\nadds required input: vin" {class: theirs}
}
check: "check()\nruns on the caller's side,\nat every connect" {class: chk}
cl: "Claims owns: one file per seam" {
  label.near: top-center
  grid-columns: 1
  grid-gap: 10
  e1: "repair_estimate.toml\nsends: claim_id, damaged_parts" {class: ours}
  e2: "reads: estimate, a number\nin claim currency" {class: ours}
}
b: "v8 (from 2026-11-02):\nestimate_repair requires vin,\nwhich this seam does not send" {class: out}
ng -> check
cl -> check
check -> b

Each owner has its own box in the diagram, and neither edits the other's. Only the check reads both files, and it runs in the caller's process, because the caller is the one a mismatch would hurt. Most of a partner's terms do not concern you. A new optional input, a skill you never call, or a change to an output you never read does not break you, unless your own parser is stricter than your expectations file says. What can break you is a change to something your expectations name, or a new requirement, such as v8's vin, that what you send does not meet.

Where the terms go: a data-only extension on the card

A2A 1.0 has no core field for any of this, but it has a slot. A card's capabilities can list extensions, each an AgentExtension with a uri, a description, a required flag and free-form params. One kind is what the extensions guide names "data-only": an extension that publishes structured information on the card without changing how requests are made. It also says "Agents shouldn't mark data-only extensions as required." That is lowercase guidance rather than an RFC-style MUST, and I follow it. The same guide says extensions are inactive by default, "providing a baseline experience for extension-unaware clients." From those two lines I infer that a client which does not know the extension can ignore it, since nothing in the request flow changes. That inference is mine, and the guide does not say it in so many words.

On a card, the terms sit three levels down, and only the last level is the agreed format:

d2
direction: down
classes: {
  proto: {style: {fill: "#95A5A6"; stroke: "#6E7B7C"; font-color: "#2C2C2A"}}
  ext: {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
  rev: {style: {fill: "#FFD93D"; stroke: "#C9A400"; font-color: "#2C2C2A"}}
}
card: "AgentCard (A2A 1.0)" {class: proto}
cap: "capabilities.extensions[ ]" {class: proto}
ext: "AgentExtension\nuri: urn:seamkit:seam-contract\nrequired: false" {class: ext}
params: "params.revisions (agreed format,\nnot protocol)" {
  label.near: top-center
  grid-columns: 2
  grid-gap: 10
  v7: "v7, effective 2026-06-01\n(in force, listed first)" {class: rev}
  v8: "v8, effective 2026-11-02\n(announced)" {class: rev}
}
card -> cap
cap -> ext
ext -> params

Grey is A2A, and the purple extension is a standard AgentExtension. Only the yellow revisions are the book's format, so a client that knows nothing about it still parses the card.

Inside that slot the format is the book's own, named urn:seamkit:seam-contract, and it makes no claim about where the protocol should go. Two companies agree on it in their partner agreement, the way they agree on a currency. On Northgate's side, the companion's publish() builds the extension:

python
def publish(*revisions: SeamTerms) -> AgentExtension:    """The extension a partner puts on its card: the revision in force first."""    extension = AgentExtension(        uri=EXTENSION_URI, required=False,  # "urn:seamkit:seam-contract"        description="Seam contract terms, current revision first")    extension.params.update({"revisions": [_plain(r) for r in revisions]})    return extension

Claims reads the revisions back with terms_of(card), which returns an empty tuple when the card carries none. The two Northgate revisions differ by one input row. v8's estimate_repair adds {"name": "vin", "type": "string", "required": true} to the two inputs v7 had, and its effective is 2026-11-02.

Claims' half is one TOML file per seam, kept in Claims' own repository and read by Python's built-in tomllib, so no new package is needed. Below is the complete Northgate file, meridian/expectations/repair_estimate.toml in the companion:

toml
# What Claims depends on from Northgate's estimate_repair. Claims owns this file.seam = "repair_estimate"owner = "Northgate"skill = "estimate_repair"sends = ["claim_id", "damaged_parts"]refuses = ["photo_url"]  # no Claims human photographs a carauth = ["mtls", "delegation"]skew_seconds = 30slo_seconds = 10.0[reads.estimate]into = "repair_estimate"type = "number"unit = "claim currency"

Each line is something Claims depends on. sends is the list that Part 2's RemoteAgentNode carried as a hand-typed SeamSpec.sends; the spec is now derived from this file. refuses writes down a decision Claims already made: Northgate may ask for a photo of frame damage, and nobody at Claims will take one. [reads.estimate] adds meaning to the field map, a number in the claim's currency.

Checking an A2A agent card at connect time: seven questions

check() takes one revision of the partner's terms, one seam's expectations and the caller's data-class policy, and returns every breach it finds. It does not stop at the first, so a revision that breaks three things is reported as three things, and the conversation with the partner happens once. The full function is 24 lines; it is seamkit/contract.py at the chapter-4 tag of the companion repository. Its opening shows the shape:

python
def check(terms: SeamTerms, expects: Expectations,          policy: CrossingPolicy) -> list[Breach]:    skill = terms.skills.get(expects.skill)    if skill is None:  # 1. the skill exists        return [_breach(terms, expects, "is not offered")]    found = [f"requires {f.name}, which this seam does not send"  # 2.             for f in skill.inputs if f.required and f.name not in expects.sends]    ...  # 3 to 7 append to found the same way    return [_breach(terms, expects, d) for d in found]

Its seven questions run in a fixed order, laid out in the grid below. Only the first can end the check early, because a skill that is not offered has no inputs to compare.

d2
grid-rows: 2
grid-columns: 4
grid-gap: 10
classes: {
  q: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  first: {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
  out: {style: {fill: "#FFD93D"; stroke: "#C9A400"; font-color: "#2C2C2A"; bold: true}}
}
q1: "1. Skill offered?\n(stops here if not)" {class: first}
q2: "2. Every required input\nis one we send" {class: q}
q3: "3. Every field we send is in\na class that may cross,\nand the partner accepts it" {class: q}
q4: "4. Every field we read is\npromised, required, on\nour type, scale and unit" {class: q}
q5: "5. Every question it may ask\nis one we answer or refuse" {class: q}
q6: "6. Its auth schemes are ones\nwe present, same clock skew" {class: q}
q7: "7. Its promised p95 fits\ninside our timeout" {class: q}
out: "Every breach collected,\none sentence each" {class: out}

Check 2 is the Northgate incident. Check 4 is where a partner that declares fraud_score on 0 to 1 instead of 0 to 100 is refused. Check 5 catches v7.4's new question, and it also catches a cleverer v8, one that asks for the VIN in input-required instead of requiring it as an input. Check 7 refuses a partner that promises no response time at all, since Claims waits ten seconds for an estimate and a partner with no stated p95 gives that number nothing to rest on. Comparing p95 with the timeout still accepts about one call in twenty timing out, by design.

Check 3 needs a word. My book groups the caller's fields into data classes, and gives each class a yes or no for each partner. Meridian defines six classes, and only two of them, claim and vehicle, may go to Northgate. A field crosses only if its class may cross to that owner, which is Meridian's decision, and the partner's terms accept that class, which is Northgate's commitment. Any field nobody classified is "unclassified", which no owner allows, so a new state field crosses nowhere until someone decides about it. Because the rule fails closed, "Northgate never sees the fraud score" becomes a test that can fail.

Catching A2A breaking changes before they take effect

The effective date is what turns a breaking change into a scheduled one. A card can carry the revision in force and every revision announced after it, so Northgate's v7 card can carry v8's terms weeks before v8 ships. held_to() checks every revision on the card and splits the result in two: breaches in the revision in force, and breaches in announced revisions.

I call a breach of the second kind a dated breach: a breach found in an announced revision that is not yet in force, logged with its effective date while the seam keeps running. Contract law has a related idea, anticipatory breach: one party shows, before its performance is due, that it will not perform. In a dated breach nobody has refused anything. The partner announced new terms, and the caller's code worked out, from data, that its own side will no longer satisfy them on a known date.

This is the test the chapter is named for, in the companion's tests/test_ch04_contract.py:

python
async def test_v8_breaks_the_seam_on_the_day_it_is_announced() -> None:    northgate = NorthgatePartner(release="v7", announces=NORTHGATE_V8)    conns = await connect_partners(A2APartners(northgate=northgate).apps())    seam = conns["repair_estimate"]    assert seam.breaches == ()  # v7 is in force: claims keep flowing today    [breach] = seam.upcoming    assert (breach.revision, breach.effective) == ("v8", date(2026, 11, 2))    assert breach.detail.endswith("requires vin, which this seam does not send")

Northgate runs v7 and announces v8 on the same card. Claims connects, and the seam is clean today, so claims keep flowing. The upcoming breach names the skill, the missing field and the date: estimate_repair requires vin, which this seam does not send, from 2 November. A Claims engineer can paste that sentence into an email to Northgate. There is time to act, but the obvious action does not work on its own. If Claims simply adds vin to its sends today, check 3 refuses the seam at once, because v7 in force does not accept vin. One expectations file cannot satisfy v7 and v8 together. The working pattern is expand and contract, and it needs Northgate: it publishes an interim v7.6, effective now, that accepts vin as optional. Against that card, Claims can add vin to sends and both v7.6 and v8 pass. The other path is to agree that v8 waits.

The four weeks on the middle edge are what the dated breach buys, and they exist because the terms carried a date. The fork at the bottom is the decision those weeks leave time for:

d2
direction: down
classes: {
  day: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  warn: {style: {fill: "#FFD93D"; stroke: "#C9A400"; font-color: "#2C2C2A"}}
  stop: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
  fix: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
}
a: "2026-10-05\nv8 announced\non the v7 card" {class: day}
w: "Claims connects:\ndated breach,\nrequires vin" {class: warn}
e: "2026-11-02\nv8 in force" {class: day}
s: "seam refuses\nbefore sending" {class: stop}
o: "no breach,\nestimates flow" {class: fix}
a -> w: "same day"
w -> e: "4 weeks to act"
e -> s: "not fixed"
e -> o: "Northgate accepts vin early\n(v7.6), or v8 delayed"

A2A agent card revisions: withdrawn, stacked and stale

Dated terms have a property no version label has: a partner can change its mind before the date. I ran three edge cases through held_to() on real cards, and one of them exposed a gap in the companion's code.

A withdrawn revision works without help. On 2026-10-05 the card carries v7 and v8, and Claims logs the dated breach. On 2026-10-20 Northgate withdraws v8, and the next connect reports no breach at all. The breach disappears silently, so a caller that wants to tell its engineers "you can stop collecting VINs" has to compare this connect's upcoming with the last one.

Stacked revisions also work. With v7, v8 and a v8.5 that makes vin optional again from 2026-12-01, the check reports one dated breach, v8's, and none for v8.5. The caller learns the exact window, one month, in which its seam would be refused.

Stale cards are the gap. The companion's held_to() never reads a clock: the first revision listed on the card is treated as in force, whatever its date. If Northgate lists v8 first by mistake on 2026-10-05, Claims refuses the seam a month early, which fails closed and is safe. If Northgate deploys v8 on 2026-11-02 but its card still lists v7 first, Claims keeps sending and meets v8 as PartnerRejected, the opening incident again. A date-aware variant, which I wrote for this article and which is not in the companion, closes that gap. It treats a revision whose effective date has passed on the caller's own UTC calendar as in force, whatever its position:

python
def held_to_on(day, revisions, expects, policy):    if not revisions:  # no terms: keep the companion's "publishes no terms" refusal        return held_to(revisions, expects, policy)    due = [r for r in revisions if r.effective <= day]    current = max(due, key=lambda r: r.effective) if due else revisions[0]    later = [r for r in revisions if r.effective > day and r is not current]    return held_to([current, *later], expects, policy)

On the stale card on 2026-11-03 it reports v8's breach as in force, so the seam refuses before sending instead of after. On the mistaken early listing it reports v8 as upcoming, which is the truth. It has one cost. If Northgate postpones v8 but leaves the card unchanged, the variant still treats v8 as in force on 2026-11-03 and refuses a seam that would have worked. That fails closed, and the fix belongs in the partner agreement: a postponed revision gets a new effective date on the card. Effective dates are calendar dates with no time zone, so caller and partner should agree in the partner agreement which calendar applies; I use UTC. The four cases, as each version of the check sees them:

d2
grid-rows: 5
grid-columns: 3
grid-gap: 10
classes: {
  head: {style: {fill: "#95A5A6"; stroke: "#6E7B7C"; font-color: "#2C2C2A"; bold: true}}
  case: {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
  ok: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  safe: {style: {fill: "#FFD93D"; stroke: "#C9A400"; font-color: "#2C2C2A"}}
  bad: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
}
h0: "Card on the day" {class: head}
h1: "held_to() (list order)" {class: head}
h2: "held_to_on() (caller's date)" {class: head}
k1: "v8 withdrawn\nbefore its date" {class: case}
a1: "breach gone at\nnext connect" {class: ok}
b1: "same" {class: ok}
k2: "v8 then v8.5\n(vin optional again)" {class: case}
a2: "one dated breach:\nv8 only" {class: ok}
b2: "same" {class: ok}
k3: "[v8, v7] listed\nearly by mistake" {class: case}
a3: "refuses a month early\n(fails closed)" {class: safe}
b3: "v8 upcoming:\ncorrect" {class: ok}
k4: "[v7, v8] still listed\nafter 2026-11-02" {class: case}
a4: "v8 still upcoming:\nsends, then rejected" {class: bad}
b4: "v8 in force:\nrefuses before sending" {class: ok}

A2A agent card versioning vs Pact, Sunset headers and deprecation scanners

Each family below solves part of the problem, and each one, read against the calendar, sits at one end of the dial: it either carries a date with no terms, or terms with no date, or both with one schedule for everybody. Four families come close.

Date-only signals. RFC 9745's Deprecation header and RFC 8594's Sunset header put a date on an HTTP response about a whole resource. RFC 9745 says "The act of deprecation does not change any behavior of the resource," and RFC 8594 says "Clients SHOULD treat Sunset timestamps as hints." OpenAI's deprecations page does the same for models, telling you to "check each model's optional shutdown_date field." RFC 9745 is a Standards Track RFC and RFC 8594 an Informational one. All three behave like the date-only gates from the calendar. OpenAI's date is per model, so a caller does get relevance for the models it uses, but only because one resource carries one change; a date on a skill that changes in several ways at once carries no such relevance.

Compatibility checks between versions. Pact's can-i-deploy gives either side a deploy-time gate, but only through a broker both sides publish to, and it is keyed on versions. Confluent's schema registry defines backward compatibility as "consumers using the new schema can read data produced with the last schema", a rule over two versions that applies the same way to every consumer. a2a-contract-test 0.1.5 validates agent cards offline in CI. Its own description says it covers "one practical offline contract shape, not the full space of A2A implementations or future protocol revisions", and it asks whether a card follows the protocol, which says nothing about whether one caller can still use it.

Schemas on the card. A2A issue #2180, opened 2026-08-25, drafts a schema contract extension with versioned contract ids and per-skill input and output rules. Issue #2396, opened 2026-10-27, proposes media-type schemas as a data-only extension, the slot the book uses. Both were still open on 2026-11-19. Neither carries effective dates or a caller-side check, and if one lands, terms in this format could travel inside it.

Consumer-side scans against announced removals. These are the nearest relatives. Pluto describes itself as a utility "to help users find deprecated Kubernetes apiVersions in their code repositories and their helm releases", and kube-no-trouble checks clusters for deprecated APIs. The consumer checks its own usage against what the upstream announced, which is the right shape. There is one upstream, though, publishing one public schedule for every user, and the consumer runs the scan before an upgrade it chose to make. GraphQL has the same shape for one API: graphql-inspector lists "Validates Operations and Fragments against a schema" among its features, so a client can test its own queries against a provider's next schema. That runs against one provider's next schema in CI, with no effective date and nothing fetched at runtime.

Provider-side relevance from traffic. A provider can also compute relevance per caller itself. Apollo's operation checks test a schema change against operations recorded from real clients, and a provider could send a deprecation notice only to the accounts that called the affected endpoint. Traffic would catch v8, since Claims never sends vin, and stay quiet on v9, since Claims never calls estimate_history. It cannot see the caller's own decisions: whether Claims' people answer adjuster_notes (v7.4), or how long Harbor waits (v7.5). Those live only in the caller's expectations. The notice also still arrives as prose, and only if the partner chooses to send it.

d2
grid-rows: 5
grid-columns: 4
grid-gap: 10
classes: {
  head: {style: {fill: "#95A5A6"; stroke: "#6E7B7C"; font-color: "#2C2C2A"; bold: true}}
  tool: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  yes: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  no: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
  some: {style: {fill: "#FFD93D"; stroke: "#C9A400"; font-color: "#2C2C2A"}}
}
h0: "Family" {class: head}
h1: "Says what changes,\nfor this caller" {class: head}
h2: "Effective date\nas data" {class: head}
h3: "Runs at the caller,\nno shared infrastructure" {class: head}
t1: "Deprecation / Sunset,\nshutdown_date" {class: tool}
a1: "no" {class: no}
b1: "yes" {class: yes}
c1: "yes" {class: yes}
t2: "Pact, schema registry,\na2a-contract-test" {class: tool}
a2: "Pact yes, others no" {class: some}
b2: "no" {class: no}
c2: "Pact and registry: no;\na2a-contract-test: yes" {class: some}
t3: "Pluto, kubent,\ngraphql-inspector" {class: tool}
a3: "yes, against one\npublic schedule" {class: yes}
b3: "version, not date" {class: no}
c3: "yes" {class: yes}
t4: "Dated terms + check()" {class: tool}
a4: "yes, per partner" {class: yes}
b4: "yes, per revision" {class: yes}
c4: "yes, at every connect" {class: yes}

The scanners are the row to read against the last one. They work because one vendor publishes one schedule that everybody can read. A seam between two companies inverts that. Northgate publishes terms for many insurers it does not coordinate with, the terms come from separate partner agreements, and Meridian cannot see what Northgate promised anybody else. No broker sits between them and no schedule is shared. What is left is a card each caller fetches at runtime. So the check has to run on the caller's side, at connect, against terms that carry their own dates. As of 2026-11-19 I found no tool or proposal that does that. The two experiments above show why it is needed. A signal that is identical for every caller leaves each caller unable to separate the revisions that break it from the ones that do not, and leaves the partner unable to label one revision correctly for two callers who need opposite answers on the same day. Relevance has to be computed per caller, from terms, and that is what dated terms on the card make possible.

How to handle an A2A agent card contract breach per seam

When a breach is in force, the tempting design is to fail at startup:

python
@asynccontextmanagerasync def lifespan(app: FastAPI):    conns = await connect_partners(partners)  # partners: the three A2A apps    if any(c.breaches for c in conns.values()):        raise SystemExit("partner contract breached")  # the whole server stays down    yield

A service that cannot meet a dependency's terms refuses to start, an alert fires, and someone fixes it. At a seam to another company, that design turns one partner's release into an outage of everything the caller does, including the claims that never reach Northgate. In Meridian's graph every claim goes screen, estimate, pay, so per-seam refusal does not pay a claim that needs an estimate. It keeps the process up, lets referrals and other flows finish, and lets the seam recover on the next connect without a restart.

Kubernetes documents the gentler, readiness-probe version of the same design, which takes the pod out of service instead of crashing it. Its probes page says that when an app depends on back-end services, "the readiness probe additionally checks that each required back-end service is available." A pod that fails readiness is removed from service. That makes sense when every request needs the back end, and readiness is decided per pod. A claims pod handles claims that need Northgate and claims that do not, and Northgate is one owner among three, so taking the pod out for one partner's breach puts the other two seams out of service with it. Two other sources name the alternative. Azure's bulkhead pattern says "Isolate the elements of an application into pools so that if one element fails, the others continue to function." The same idea applied inside one pipeline is fault isolation and circuit breaking for LLM calls. The AWS Builders' Library also warns that deep dependency checks in health checks can cause cascading failures.

So the breach is held per seam: that seam still connects, and the connection carries its breaches. self.partner in RemoteAgentNode is that connection, the object the earlier test held in its variable seam. The node's own self.seam is a different object, its SeamSpec. At the top of its send step, before a byte crosses, the node checks it:

python
async def _send(self, data: Mapping[str, Any],                link: Mapping[str, str] | None = None) -> Task:    if self.partner.breaches:  # held per seam: this one stops, the others run        self.log(self._record("send", tuple(data))(error=ContractBreach.__name__))        raise ContractBreach(            self.seam.name, "; ".join(b.detail for b in self.partner.breaches))    ...  # the Chapter 3 send, unchanged

data is the fields this seam sends. self._record("send", ...) builds the crossing record every send writes, and the second call fills in its error, so the refusal shows up in the seam's log next to the sends that worked.

In the companion, test_v8_in_force_stops_only_its_seam_and_sends_nothing deploys v8 itself. The clean claim CLM-1001 passes fraud screening, then the estimate node raises ContractBreach with "requires vin" in its message. Northgate's log of received tasks is empty, and the graph's completed list holds fraud_screening, so the seam with no breach still ran. Here are the same three seams under each design:

d2
grid-columns: 2
grid-gap: 40
classes: {
  run: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  stop: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
  off: {style: {fill: "#95A5A6"; stroke: "#6E7B7C"; font-color: "#2C2C2A"}}
}
fast: "Fail at startup (whole process)" {
  label.near: top-center
  grid-columns: 1
  grid-gap: 10
  f1: "fraud_screening (Risk): down" {class: off}
  f2: "repair_estimate (Northgate): down" {class: stop}
  f3: "payment (Finance): down" {class: off}
}
seam: "Refuse per seam" {
  label.near: top-center
  grid-columns: 1
  grid-gap: 10
  s1: "fraud_screening (Risk): runs" {class: run}
  s2: "repair_estimate (Northgate):\nContractBreach, nothing sent" {class: stop}
  s3: "payment (Finance): connected,\nnot reached by claims\nthat need an estimate" {class: run}
}

A card that carries no terms gets the same per-seam refusal, as the breach "Northgate publishes no terms", because the check treats a silent partner as one whose terms are unknown. What the claims that need a refused seam should do next, wait, route to a person, or use a fallback, is a separate decision for the caller.

Field tables vs JSON Schema for A2A agent card skill terms

JSON Schema is the obvious format for terms, and both open A2A proposals lean on it. I prefer a flat field table because of what the check has to do. It does not validate one document against one schema. It compares two descriptions, the partner's promise and the caller's dependency, and asks whether one satisfies the other.

For JSON Schema, that comparison is a research problem. Habib, Shinnar, Hirzel and Pradel built a subschema checker for exactly this question and published it at ISSTA 2021. Their preprint calls the question "non-trivial because of the richness of the JSON Schema specification language." In their ISSTA results the tool is correct whenever it gives an answer, and it gives one for 93.5% of the schema pairs in their evaluation, ahead of the previous state-of-the-art tool. Even a dedicated research tool could not answer every pair.

That result is about arbitrary schemas. A restricted JSON Schema subset (type, required, properties, enum, minimum and maximum) would make the comparison as easy as a table and stay close to issues #2180 and #2396, and it is a fair alternative. I still use a table, because units, the questions a skill may ask and p95 need custom keywords in either format.

d2
grid-rows: 4
grid-columns: 3
grid-gap: 10
classes: {
  head: {style: {fill: "#95A5A6"; stroke: "#6E7B7C"; font-color: "#2C2C2A"; bold: true}}
  good: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  bad: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
  some: {style: {fill: "#FFD93D"; stroke: "#C9A400"; font-color: "#2C2C2A"}}
}
h0: "" {style: {opacity: 0}}
h1: "Flat field table" {class: head}
h2: "Arbitrary JSON Schema" {class: head}
r1: "Does A satisfy B?" {class: head}
a1: "a loop over rows" {class: good}
b1: "a research problem:\n93.5% recall (ISSTA 2021)" {class: bad}
r2: "A breach reads as" {class: head}
a2: "one sentence a partner\nengineer understands" {class: good}
b2: "a failed subschema\nrelation" {class: some}
r3: "What you give up" {class: head}
a3: "nested objects,\nconditional fields" {class: some}
b3: "units, questions and\nlatency need custom keywords" {class: some}

What the table gives up sits in the bottom row of that grid: expressiveness. Northgate's photo shows the usual workaround. A field that is required only sometimes, such as a photo for frame damage, is usually a question the partner asks, and the terms declare it in asks. In return the table buys a check whose every breach is a sentence, like does not promise estimate as a required number in claim currency.

What an A2A contract check misses: behaviour drift under unchanged terms

Behaviour under unchanged terms. Every gate in my experiment missed one break: Northgate returning euros behind an unchanged v7 card. The companion's tests show the same limit from the other direction. In test_contract_a_card_that_states_0_1_is_refused_at_connect, Risk honestly publishes a fraud score on 0 to 1, and the check refuses the screening seam. In test_contract_0_82_under_an_unchanged_card_passes_every_check, Risk returns 0.82 behind a card that still says 0 to 100. Every check passes. So does the artifact check, the shape check Claims runs on each completed answer before writing it into state: 0.82 is a valid value on a 0 to 100 scale. The suspect claim is paid. The check reads declarations, and the declarations did not change. Catching that takes behavioural tests against the partner. Part 6 of this series is about testing partners you cannot deploy, and my book adds behavioural canaries in a later chapter. In the diagram, what the check sees is on the left. Every item on the right changes behaviour or trust while the declared terms stay the same.

d2
grid-columns: 2
grid-gap: 30
classes: {
  sees: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  blind: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
}
yes: "The check sees" {
  label.near: top-center
  grid-columns: 1
  grid-gap: 10
  y1: "a declared new required input" {class: sees}
  y2: "a declared change of scale or unit" {class: sees}
  y3: "a new question in asks" {class: sees}
  y4: "a card with no terms" {class: sees}
}
no: "The check cannot see" {
  label.near: top-center
  grid-columns: 1
  grid-gap: 10
  n1: "euros behind a card that says\nclaim currency" {class: blind}
  n2: "0.82 behind a card that says 0-100" {class: blind}
  n3: "forged terms on a fetched card" {class: blind}
  n4: "a partner's drift, when its\nterms exist only on paper" {class: blind}
}

Unreadable cards. Per-seam refusal holds only for cards that can be fetched and parsed. In the companion, connect() has no error handling around the card fetch or terms_of(), so an unreachable card or a malformed revision raises out of connect_partners and takes every seam down with it. A production version should turn a failed fetch or parse into a per-seam breach, such as "card unreadable".

The card as fetched. Everything here trusts the card it fetched. A forged card with permissive terms would pass every check. A2A cards can carry signatures, and which cards to trust is a separate question that the next chapter of my book takes up.

A partner that will not publish. Nothing in A2A obliges Northgate to carry Meridian's extension, so publishing terms is a clause of the partner agreement, and some partners will refuse. The expectations file is still worth writing, because it is the half that breaks you. For that case the companion's connect takes terms=, so you can pass in the terms a partner agreed to on paper. Then the check catches your own drift, such as an engineer adding a field to sends, but not the partner's.

A long-running process. Because the check runs at connect, a process that connected at startup holds the card it fetched until it reconnects. If Northgate ships v8 without announcing it first, a running Claims process meets v8 as PartnerRejected, exactly as in the opening. Announced revisions help only a caller that refetches the card, so a scheduled refetch is part of condition 2, not an extra. Even then the rejections arrive as errors on live tasks, and Part 4 takes up what a caller should do with a task that may or may not have run.

What it costs. On the companion's chapter-4 tag, at a2a-sdk 1.3.1, on 2026-11-18, I measured Northgate's card as compact JSON at 642 bytes with no terms, 1,384 with v7's, and 2,037 with v7's and v8's together. Reading the terms off the card took about 0.3 ms, and one check() 6 to 8 microseconds, on one laptop. The book's figures (673, 1,598 and 2,433 bytes, and about 3 microseconds) came from a different serialisation and an older run. Either way, both costs are paid once, when the caller connects.

How dated terms would have caught the v8 breaking change

Run the opening again with a contract. Northgate still bumps the version and edits the description, and no code acts on either one. But four weeks earlier, on 2026-10-05, it also put v8's terms on its v7 card, with effective: 2026-11-02. Claims' next connect logs a dated breach, estimate_repair requires vin, which this seam does not send, and the two companies have weeks to agree an interim revision that accepts vin early, or a delay. If nobody acts, v8 takes effect and one seam refuses before sending, while fraud screening keeps running. Four weeks early, the dated terms told Claims' code about v8, where the version bump had told only whoever was reading. A Sunset header on the same day would have warned Claims about v8 too, and about every harmless Northgate release announced the same way. A deprecation notice for v8 would have warned Claims too, and the same kind of signal would have stayed silent on v7.4 and fired on v9. That is notice without relevance. This does not cover a partner whose behaviour changes while its terms stay the same, and for that you still need a behavioural test and an error-rate alert.

Checklist: turning an A2A agent card into a contract

  • No code of yours treats a change of AgentCard.version or a skill description as telling it whether a seam still works.
  • Every seam you call has an expectations file in your own repository: the skill, what you send, what you read with type, scale and unit, the questions you answer or refuse, auth, and your timeout.
  • Your seam's send list and field map are derived from that file instead of typed a second time.
  • Your partner agreement names a terms format, published on the card as a data-only extension with required: false, in revisions with effective dates.
  • You check your expectations against every revision on the card at connect and on a daily refetch, and log each breach in an announced revision with its date.
  • A breach in force refuses that seam before anything is sent, while the process stays up and the other seams run.
  • A card with no terms gets the same refusal as a breach, unless you pass terms agreed on paper (terms=).
  • Every field you send has a data class, and an unclassified field crosses nowhere.
  • Your CI runs the same check on every change to an expectations file.
  • Your check decides which revision is in force from its own UTC calendar and the effective dates, not from the order the card lists them in.
  • No date-only signal, whether a Sunset header or a version label, gates a seam on its own: it gives notice without relevance.
  • You keep a per-seam error-rate alert anyway, because a partner can change behaviour under unchanged terms.

Going deeper: Chapter 4 of the book

This is Part 3 of the Federated AI Agents guide, a series that follows my book Federated AI Agents one chapter at a time. Chapter 4, "The Agent Card Is a Contract, Not a Brochure," is where this part comes from. This post adds the four-gate experiment, the GitHub Events API case and the comparison with date-only deprecation signals, and you can build the contract check without the book. Code for the chapter is the ch04-agent-card-is-a-contract tag of the companion repository. Its tests run with no network and no model key. I ran them at the book's pins, a2a-sdk 1.2.2 and langgraph 1.2.15, and again on a2a-sdk 1.3.1 and langgraph 1.2.22, and they pass on both.

Federated AI Agents: LangGraph and A2A for Agents You Don't Own, by Ranjan Kumar

References


Agentic AI

Follow for more technical deep dives on AI/ML systems, production engineering, and building real-world applications:


Books by Ranjan Kumar

Federated AI Agents cover

Federated AI Agents

Right-Sized AI cover

Right-Sized AI

Harness Engineering for Production AI Systems cover

Harness Engineering

The 7 GenAI Architectures cover

The 7 GenAI Architectures

Building Real-World Agentic AI Systems with LangGraph cover

Building Real-World Agentic AI Systems

The ChatML Handbook cover

The ChatML Handbook

The Chat Templates Handbook cover

The Chat Templates Handbook

Comments