This series grew into a book: Federated AI Agents. Chapter 16 covers this part. Where the chapter goes further is at the end of this article.
For five minutes on a Tuesday, an insurer's claims graph sent every clean motor claim to its own desk assessors, because its circuit breaker had decided the repair network that prices those claims was failing. Nothing was wrong with the repair network. What had changed was how it said no.
Northgate's code release that morning changed nothing on its Agent2Agent (A2A) agent card. Its digest still began sha256:0291cde8df52 and its declared terms were still revision v7.4. Inside, an engineer had tidied the parts check. When a claim listed a part Northgate does not price, such as a wing mirror, the old code called reject() on the task. The new code raised ValueError("no price for mirror") from the price matcher, which is how most Python codebases write validation.
Meridian Mutual's claims team (Claims from here on) owns the graph that calls Northgate. On the estimate seam its send returns as soon as the task exists, and its node reads the task again until it ends. It counts a task that ends failed against Northgate, on whichever read it finds it, and three in a minute open the breaker. Within a minute three mirror claims ended failed where the day before they had ended rejected. That opened the breaker, and the next clean claim, CLM-1001, a bumper and a door, went to a desk assessor.
Meridian and Northgate are this series' fictional running example. Nothing in the mechanism is invented: it is the book's companion code and the A2A Python SDK itself, and every experiment below ran on a2a-sdk 1.3.1 and langgraph 1.2.24, both current as of 2026-11-20.
Claims had tested the seam. The consumer-driven contract I wrote for the mirror request in pact-python 4.2.0 passed the release, because it checked the answer to the send, and on this seam that answer is TASK_STATE_SUBMITTED whatever the task does next.
I call this a blame flip: a partner change that moves a failure mode from one outcome class to another, so the caller's code now blames the other side, while the card, the declared terms and the artifact schema stay as they were.
Nobody at Northgate decided to start failing those claims. A2A's Python SDK decided. In a2a-sdk 1.3.1 a task reaches TASK_STATE_REJECTED through one call, TaskUpdater.reject(). Every exception that escapes an agent's executor after the task exists is recorded as TASK_STATE_FAILED, the SDK's own InvalidParamsError included.
This part's claim: an A2A task records the fault for a refused request as one bit, rejected or failed. The protocol leaves that bit to the partner, and the Python SDK sets it by code path. So a partner's coding style can move the caller's blame with no declared change, and the only test a caller can write that sees it before release reads the bit off the task, per request, and runs against the partner's release candidate. Unless the partner stages candidates where the caller can reach them, that means the partner runs it.
An HTTP framework is no different about a stray raise: a ValueError from a FastAPI 0.165 handler answers 500. Where they part is the deliberate path. raise HTTPException(status_code=400) still answers 400, so an HTTP partner that refuses on purpose keeps the caller's fault on the status line. The A2A SDK's deliberate caller-fault exception, InvalidParamsError, ends the task FAILED. No exception in the A2A Python SDK produces rejected. Refusing must be written on purpose, and a raise moves the request to the partner's side of the line.
None of the surrounding parts is new. Martin Fowler wrote up contract tests against test doubles in 2011. Ian Robinson put consumer expectations into the provider's build in 2006, which is what Pact automates. Tian Pan has argued for agent providers running consumers' cases in CI, failures included. A 2026 A2A testing guide from TestMu AI already tells clients to treat rejected and failed differently. And outcomes that arrive on a later read are old too: an HTTP 202 Accepted with polling, or a long-running operation in Google's AIP-151, puts the result on a later call, and teams already test the final state of an operation rather than its 202.
What those designs do not have is a two-value fault bit that the provider's framework picks by default. AIP-151 sends errors that stop an operation starting back on the call, and failures during the run go in the operation as a status with a canonical code. TestMu's advice is aimed at the client, and Claims' client already treated the two states differently. That is exactly why it broke. Telling them apart is the partner's job to keep, so it has to be a contract term, tested where the partner releases.
A2A rejected vs failed: what the spec defines and what it leaves to the partner
The A2A protocol buffer gives the two states one comment each, and the words matter, so here they are in full:
// Indicates that a task has finished with an error. This is a terminal state.TASK_STATE_FAILED = 4;// Indicates that the agent has decided to not perform the task.// This may be done during initial task creation or later once an agent// has determined it can't or won't proceed. This is a terminal state.TASK_STATE_REJECTED = 7;Both are terminal. Neither says which business condition belongs in which state, and "can't or won't proceed" overlaps "finished with an error". A partner that answers an unpriced part failed is inside the spec, and so is one that answers it rejected. Northgate could argue in good faith that Tuesday's release fixed a mislabelled state. Implementations already disagree on the line. Rasa, run as an A2A agent, answers a request outside its jurisdiction rejected and an internal error failed. AG2's client raises A2ATaskRejectedError and A2ATaskFailedError as separate exceptions and attaches no fault to either.
So the fault a state stands for is the caller's convention. Meridian's companion code writes it down as a table it calls outcome classes, the class being what Claims' code does with a task's final state:
# seamkit/contracttest.py (companion, tag ch16-testing-agents-you-cant-deploy)CLASSES = {"completed": "answered", "input-required": "asks", "rejected": "rejected", "auth-required": "asks authority", "failed": "failed", "canceled": "failed"}# outcome_of() appends the field asked for: "asks photo_url"The diagram shows what each class sets in motion at Claims.
grid-rows: 5
grid-columns: 3
grid-gap: 14
h1: "Task state" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"; bold: true}}
h2: "Outcome class" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"; bold: true}}
h3: "What Claims does" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"; bold: true}}
s1: "completed" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
c1: "answered" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
a1: "reads the estimate" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
s2: "input-required" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
c2: "asks photo_url" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
a2: "asks a person, resumes the task" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
s3: "rejected" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
c3: "rejected: Claims' side" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
a3: "adjuster note; never counted" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
s4: "failed" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
c4: "failed: Northgate's side" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
a4: "counted by the breaker" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
The yellow and red rows are the ones a blame flip swaps. One terminal state is left out on purpose. The companion maps canceled to the failed class, so a blocking send counts it, but the read-side count later in this part skips it, because Claims cancels its own tasks. On a seam like the estimate seam, canceled is a mixed class. Only the left column comes from the protocol. Claims owns the middle and right columns, which is why no protocol-level check can tell that a row has moved. In this series' terms, which class each failure mode lands in is an unwritten term of the seam. Part 3 built a check that reads the partner's declared terms on its card. It has nothing to read here, because nobody declared this one.
Breakers in other ecosystems draw the same line in configuration. Resilience4j's ignoreExceptions lists exceptions that "neither count as a failure nor success". Polly's ShouldHandle predicate decides which results the breaker handles at all. Claims' breaker ignores rejected for the same reason Resilience4j users list their business exceptions there. On Tuesday, Claims' own refused requests came back failed, so the breaker counted them against Northgate and opened.
Flips also run in the other direction. In December 2021 a Genesys Cloud user reported that POST /api/v2/quality/evaluations/query/ had started answering a page that does not exist with 400 instead of 500, without notice, and asked whether there was any way to hear about such changes in advance. A Genesys developer-engagement manager replied that a 400 typically means the caller has sent the service something incorrect. Same request, same body shape, and the fault moved from the provider to the caller. That one moved on the status line, where a test would at least look. In A2A it moves inside the body.
How the A2A Python SDK turns a validation exception into a failed task
The opening's release did not call failed() anywhere. It raised. To see what the SDK does with that, I replaced Northgate's explicit rejection of an unpriced part with three common ways of writing validation, each raised after the task exists, and sent the mirror claim once with a send that blocks and once with a send that returns at once. Then I listed Northgate's own tasks. On a2a-sdk 1.3.1 and on 1.2.2 the results are the same:
| Northgate's unpriced-part branch | Blocking send answers | Northgate's task store |
|---|---|---|
updater.reject() (before the release) | TASK_STATE_REJECTED | REJECTED |
price lookup raises KeyError('mirror') | JSON-RPC error -32603 | FAILED |
raise ValueError("no price for mirror") | JSON-RPC error -32603 | FAILED |
raise InvalidParamsError(...) (the SDK's own) | JSON-RPC error -32602 | FAILED |
| any of the above, send returns at once | TASK_STATE_SUBMITTED | as above |
The SDK source says why. TASK_STATE_REJECTED is written in one place, TaskUpdater.reject(). The executor's failure path (_mark_task_as_failed in active_task.py) writes TASK_STATE_FAILED for any exception that escapes, a behaviour a2a-python PR #1106 made durable in release 1.1.2. No exception type maps to rejected. A Strands Agents issue on its A2A executor proposed mapping exceptions and errors to failed too. Under this SDK, then, refusing a request is something an agent's code must do on purpose, and any refactor that turns the refusal into a raise produces a blame flip without anyone choosing one.
The last row is the incident in the opening. The estimate seam's send returns as soon as the task exists, so Claims saw SUBMITTED, read the task again, and found FAILED. I replayed that release on the companion's own incident harness, the contained graph whose estimate send returns at once, as Claims' does, swapping the executor's class in place so the card stayed byte for byte the same:
E6 before: repair_estimate: PartnerRejected: TASK_STATE_REJECTED (x3)E6 breaker after 3 refused: closedE6 after: repair_estimate: PartnerFailed: TASK_STATE_FAILED (x3)E6 breaker after 3 refactored: open | card unchanged: TrueE6 next clean claim CLM-1001 asked of: claims/desk_assessor for repair_estimateThe InvalidParamsError row deserves a name. A caller whose send blocks is told -32602, "invalid params", which reads as the caller's own fault. Every later read that finds the task says FAILED, the partner's fault. For this caller those reads are ListTasks or the partner's own view, since the send returned no id. I call that a split verdict: one request, two outcome classes, depending on which read the caller makes. The -32603 rows are not split in the protocol's own words, since an internal error on the send and a failed task in the store both point at the partner. The companion's node splits them anyway. Its _post in seamkit/remote.py raises any JSON-RPC error on a send as PartnerRejected, so a blocking Claims would have counted Tuesday's refactor as its own refusal and never seen the failed task. In every row the caller holds no id for the task. Below are the two halves of the -32602 case.
grid-rows: 1
grid-gap: 40
send: "Read 1: the blocking send" {
label.near: top-center
style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}
grid-columns: 1
grid-gap: 14
a: "JSON-RPC -32602\ninvalid params" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
b: "reads as Claims' fault;\nno task id returned" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
}
later: "Read 2: ListTasks, the partner's view" {
label.near: top-center
style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}
grid-columns: 1
grid-gap: 14
a: "TASK_STATE_FAILED" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
b: "reads as Northgate's fault;\nthe task Claims never got an id for" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
}
A caller whose send blocks and anyone who reads the task later (Claims' own reconciliation, an auditor, Northgate's support desk) get answers that are each consistent and together assign the same request to both owners. Under Part 4's rules, a JSON-RPC error is not one of the no-answer signals that allow a resend under the key, so the companion's node records a refusal it never got, PartnerRejected, and the failed task at Northgate is an orphan. From Claims' side, only the outward reconciliation pass from Part 4, which starts from the partner's task list, can find it.
What every check sees when an A2A partner changes behaviour under the same card
To put each check side by side I started with the tidy version of the flip, on a blocking send. The companion has a planted switch, fail_unpriced(), that fails the same request with an explicit failed() call. It changes one attribute on the executor and nothing on the card, and it gives every check a task to look at. The next two sections add the refactor and the send that returns at once. The claim is CLM-R03, a synthetic claim for one mirror:
release in force: card digest sha256:0291cde8df52 terms v7.4 connect (Part 3 check) ok: True CLM-R03 -> TASK_STATE_REJECTED (schema-valid Task); membership regex: True conformance: [] partner-run suite: []flip (fail_unpriced): card digest sha256:0291cde8df52 terms v7.4 connect (Part 3 check) ok: True CLM-R03 -> TASK_STATE_FAILED (schema-valid Task); membership regex: True conformance: [] partner-run suite: [('CLM-R03: rejected', 'expected rejected, got failed')]stub (built from the recording): suite -> []The output is identical on a2a-sdk 1.2.2, the book's pin. Here it is as a grid, with one row per check.
grid-rows: 9
grid-columns: 3
grid-gap: 10
g0: "Check" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"; bold: true}}
r0: "Release in force" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"; bold: true}}
f0: "Planted failed() switch" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"; bold: true}}
g1: "Card digest diff" {style: {fill: "#FFFFFF"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
r1: "same" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
f1: "same" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
g2: "Declared terms (Part 3)" {style: {fill: "#FFFFFF"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
r2: "v7.4, no breach" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
f2: "v7.4, no breach" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
g3: "Task parses against the A2A schema" {style: {fill: "#FFFFFF"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
r3: "valid" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
f3: "valid" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
g4: "Protocol conformance (7 behaviours)" {style: {fill: "#FFFFFF"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
r4: "pass" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
f4: "pass" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
g5: "Pact like() over the task" {style: {fill: "#FFFFFF"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
r5: "pass" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
f5: "pass" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
g6: "State in the set of legal states" {style: {fill: "#FFFFFF"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
r6: "pass" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
f6: "pass" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
g7: "Claims' suite on Claims' stub" {style: {fill: "#FFFFFF"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
r7: "pass" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
f7: "pass (the stub never moved)" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
g8: "Claims' suite on Northgate's build" {style: {fill: "#FFFFFF"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
r8: "pass" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
f8: "FAIL: expected rejected, got failed" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
Seven of the eight rows stay green across the flip, each for its own reason. Nothing declared moved, so the digest and terms rows hold. Both releases return a valid task. Conformance, the companion's conformance() in seamkit/contracttest.py, covers seven protocol behaviours: card, send, read, cancel, resume, key and push. Northgate kept every one. Both Pact rows get their own section next. As for the stub, it answers from a recording made before Tuesday, and no recording can know what Northgate did next.
That holds for the protocol project's own conformance kit too, the A2A Protocol Technology Compatibility Kit (TCK). It grades a server against the specification's MUST, SHOULD and MAY requirements over gRPC, JSON-RPC and HTTP+JSON. TestMu AI's guide is direct about what that leaves out: "It does not check whether the agent gives good answers, stays on policy, or avoids hallucinating." A server can pass all of it while answering an unpriced part failed, because which state a business condition ends in is not in the spec for a kit to check.
The bottom row is a test Claims wrote and Northgate ran. Of the checks in this grid it is the only one that went red. A pinned pact, run the same way, is next.
Why Pact's like() matcher passes the blame flip on an A2A task
Pact's guidance on response matching is to be loose. Its matching page says "You want to be as loose as possible with the matching for the response", and that "it doesn't matter what value the provider actually returns during verification, as long as the types match." Its consumer guide adds "Avoid asserting on exact values unless necessary." For an HTTP API that advice is safe, because Pact matches the status code exactly by default, and its guide on contract tests tells you to pin how a validation fails: one scenario expecting a 400 with any error string. On HTTP the outcome class sits on the status line, which a pact pins.
An A2A task over JSON-RPC answers HTTP 200 whether it completed, was refused or failed. I captured both releases' answers to CLM-R03 on the wire. They have the same status code, the same JSON-RPC envelope and the same task fields. The differences are status.state and a status message on the failed task carrying {"error": "no price for a part"}. So the class moved off the status line into a string in the body, the part a pact matches loosely.
grid-rows: 1
grid-gap: 40
http: "An HTTP API" {
label.near: top-center
style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}
grid-columns: 1
grid-gap: 14
line: "status line: 400 or 500\npinned exactly by default" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
body: "body: error message\nmatched loosely, like()" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"}}
}
a2a: "An A2A task over JSON-RPC" {
label.near: top-center
style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}
grid-columns: 1
grid-gap: 14
line: "status line: 200 every time\npinned, carries nothing" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"}}
body: "body: result.task.status.state\nREJECTED or FAILED\nmatched loosely, like()" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
}
On the left, the class sits where Pact pins by default. On the right, the line Pact pins carries nothing, and the class sits under the matcher Pact tells you to keep loose. Pact's type matching also cascades. The Pact JS reference says like on an object means "all values and child object values will be matched according to types," unless something more specific overrides it. That wording documents Pact JS's V2 like. My pact-python 4.2.0 run below uses the V4 specification and shows the same cascade. Wrap the task in like() and status.state is matched as "a string", which TASK_STATE_FAILED is.
Pact's matching gotchas page does warn that "A change in the provider enum can easily break the compatibility of the API", and suggests an anchored alternation over the legal values. For a task state that means a regex over the A2A states, and both REJECTED and FAILED are in the set, so a membership check passes the flip as well. What the caller depends on is one value per recorded request. Pact V4 does add a statusCode matcher that accepts a class of status codes, such as any success. For a string inside the body, the nearest equivalent is a regex you write yourself, which is what the pinned pact below does.
Here is the pinned variant from my experiment. The only difference from the loose pact is one matcher on one field. pact-python 4.2's match module has no equality matcher, so an anchored regex is the way to pin one value inside like():
from pact import Pact, matchdef task_answer(pin_state: bool): """The response half of the CLM-R03 interaction.""" state = (match.regex("TASK_STATE_REJECTED", regex="^TASK_STATE_REJECTED$") if pin_state else "TASK_STATE_REJECTED") return match.like({"result": {"task": {**TASK, "status": {"state": state}}}, "id": REQUEST["id"], "jsonrpc": "2.0"})pact = Pact("claims", "northgate").with_specification("V4")(pact.upon_receiving("an estimate for a part Northgate does not price") .with_request("POST", "/").with_header("A2A-Version", "1.0") .with_body(REQUEST, "application/json") .will_respond_with(200) .with_body(task_answer(pin_state=True), "application/json"))# the loose pact is the same interaction with task_answer(pin_state=False)REQUEST is the JSON-RPC SendMessage body I captured for CLM-R03, and TASK is the captured task's id and contextId. I verified three pacts with pact-python's Verifier against the companion's Northgate, served over HTTP by uvicorn on a free port, with a fresh deployment for each release:
release in force: Northgate answers TASK_STATE_REJECTED typed PASS pinned PASS exact FAIL $.result.task.id -> Expected '68b0...' to be equal to '9539...'candidate (fail_unpriced): Northgate answers TASK_STATE_FAILED typed PASS pinned FAIL $.result.task.status.state -> Expected 'TASK_STATE_FAILED' to match '^TASK_STATE_REJECTED$' exact FAILThe exact pact, with no matchers, fails the release in force because every task gets a fresh id, which is the brittleness Pact's advice exists to avoid. Typed, the pact passes both releases. Only the pinned one tells the two releases apart.
Pact's loose-body default is the wrong default for any protocol that answers 200 for every outcome, and A2A is one. Pact's own rule, "Only make assertions about things that would affect your consumer if they changed", already says to pin the state, and teams that wrap the task in like() are following the default over the rule. TestMu's guide frames rejected against failed as a client retry problem: a client that retries a rejection loops. The opening shows it is a contract problem. Claims retried nothing, and its breaker still opened on a partner that was healthy.
An alarm on a sudden rise in rejections, or in failures, would also notice a flip, from the other side. It notices after the fact, on production traffic, and only once a baseline exists. Pinned, the test notices on the candidate.
Contract testing async A2A tasks with Pact: key the check to the task
The pinned pact above caught the planted switch because that pact used a blocking send, and a blocking send returns the task in its final state. Claims' estimate seam does not block. So I ran every check against three Northgate builds: the release in force, the planted explicit failed(), and Tuesday's refactor, which raises. Each build got both send shapes, and each pact had its own messageId. On the send that returns at once, the pinned pact is pinned to TASK_STATE_SUBMITTED, the only state Northgate's send returns, because its executor creates the task before it validates anything. Against Northgate it cannot fail by construction, and that is the finding: the send has nothing worth pinning. The last column is a check keyed to the task: send the way the seam sends, then read the task with GetTask until it ends.
| Northgate build | Blocking send: typed pact | pinned pact | Claims' suite | Send at once: typed pact | pinned pact | Task-keyed read |
|---|---|---|---|---|---|---|
| release in force | pass | pass | pass | pass | pass | REJECTED |
planted failed() | pass | fail | fail | pass | pass | FAILED |
| refactor (raises) | fail | fail | raised InternalError | pass | pass | FAILED |
On a blocking seam the refactor is loud to a pact, though Claims' node reads the JSON-RPC error as a rejection. The send comes back as a JSON-RPC error with no result.task, so even the typed pact fails on a missing key, and only the planted switch is quiet enough to need the pinned one. On a seam whose send returns at once, both pacts pass all three builds, the pinned one included, because the send answers TASK_STATE_SUBMITTED in each. A suite that reads only the send has nothing to compare, since every request answers the same. Only the task-keyed read tells them apart.
grid-rows: 1
grid-gap: 40
call: "Keyed to the call (the send)" {
label.near: top-center
style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}
grid-columns: 1
grid-gap: 14
s: "SendMessage, returns at once" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
a: "answer: SUBMITTED\n(refused or failed, same answer)" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"}}
w: "Pact interaction and send-guarded\nbreaker: pass every build" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
}
task: "Keyed to the task (later reads)" {
label.near: top-center
style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}
grid-columns: 1
grid-gap: 14
g: "GetTask until the task ends\n(or a push)" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
f: "final state: REJECTED or FAILED" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
r: "task-keyed check, read-side breaker\ncount, reconciliation: see the flip" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
}
Everything that looks at the answer to the send sits in the first box and passes, and blame flips show up only in the second. A push notification would also land in the second box, carrying the final state; I did not measure the push path here. The usual model of a contract test is a request and the response it produces, which is the model Pact's interactions encode. For an A2A seam whose send returns early, that unit is wrong: the response a test can pin is not where the outcome is.
Pact can reach the task, and I ran the fair version to be sure. It is a GetTask interaction pinned to ^TASK_STATE_REJECTED$, given a provider state, "a CLM-R03 estimate task has ended". The task id is injected from that state with generate.provider_state("${taskId}"). The partner's state handler runs the skill with a send that returns at once, waits for the task to end and returns its id. Against the three builds it passed the release in force and failed both flips with "Expected 'TASK_STATE_FAILED' to match '^TASK_STATE_REJECTED$'". So the thing to drop is the Pact interaction on SendMessage, not Pact. The sequence below is what that verification does for one recorded request.
That version has a real cost. Every recorded request needs a state handler the partner writes and runs. In pact-python 4.2.0 a Python function handler's return value is discarded, so the injected id needs a URL handler, an HTTP endpoint the partner serves during verification. My first attempt used a function handler, sent the example id, and got TASK_NOT_FOUND on every build. A task-keyed checker that drives the real send and read needs none of that, which is why it is the one I would hand a partner first.
sequenceDiagram
participant V as Pact verifier
participant H as Northgate state URL handler
participant N as Northgate candidate
V->>H: POST state "a CLM-R03 estimate task has ended"
H->>N: SendMessage CLM-R03, returnImmediately
N-->>H: task id, SUBMITTED
H->>N: GetTask until terminal
N-->>H: REJECTED or FAILED
H-->>V: {"taskId": "..."}
Note over V,H: pact-python 4.2.0 discards a function handler's return value, so the id comes back over HTTP
V->>N: GetTask, id = injected taskId
N-->>V: status.state
Note over V: pinned to ^TASK_STATE_REJECTED$
A2A partner sandbox vs mock: why both miss the blame flip
Before Tuesday, Claims had two answers to "how do we test against a partner we cannot deploy?": Northgate's sandbox and a fake. Both are common, and both missed the flip for structural reasons. Neither was badly built.
Northgate's sandbox runs Northgate's real code, which makes it feel like the strongest test there is. It runs the release in force. Until Tuesday that was the old parts check, so the sandbox rejected the mirror right up to the release that changed it. Northgate's sandbox also fails only when it is broken. Some vendors' sandboxes take trigger values, such as Stripe's test card numbers that produce a decline on demand, but those give you the failures the vendor chose to offer, on the release in force. Nobody at Claims could ask Northgate's for a lost answer or a 12-second stall. A partner that deploys each candidate to a staging environment Claims can reach, and says when, changes this: Claims' own scheduled task-keyed run would then see the flip before release. Northgate's staging runs the release in force, so only Northgate's pipeline can.
The fake is the hand-written double almost every team has somewhere:
class FakeNorthgate: """Claims' test double for the estimate seam: answers whatever its writer imagined.""" def estimate_repair(self, claim_id: str, damaged_parts: list[str]) -> dict: prices = {"bumper": 1200.0, "door": 1800.0, "frame": 5300.0} if not set(damaged_parts) <= set(prices): raise RuntimeError("unpriced part") # which A2A state is this? nobody asked return {"estimate": sum(prices[p] for p in damaged_parts), "notes": ""}It looks useful because it can fail on demand. But its failure is a Python exception, not a task in any A2A state, so the one property the flip changed is a property the fake never had. A better fake works at the wire, with respx or WireMock returning a real task, REJECTED and all. It still misses Tuesday, for the reason the stub does: it is frozen. What it lacks next to the stub is anything that keeps it true, with no terms check at build time and no recording stamp. A fake that cannot fail leaves every failure path untested. A fake that fails the way its writer guessed tests Claims against a Northgate nobody runs. Nawaz Dhandala of OneUptime puts the end state of an unmaintained mock as one that "quietly becomes fiction". This one was fiction from the first commit, a second Northgate written by Claims and kept true by nobody.
Laid out side by side, the options sort cleanly by the two things a test of a seam needs: failing on demand, and seeing the partner's next release.
grid-rows: 6
grid-columns: 4
grid-gap: 10
h0: "Test against" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"; bold: true}}
h1: "Fails on demand" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"; bold: true}}
h2: "Sees the next release" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"; bold: true}}
h3: "Saw the flip" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"; bold: true}}
a0: "Partner production" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
a1: "no" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
a2: "only once shipped" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
a3: "after the fact" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
b0: "Partner sandbox" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
b1: "no" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
b2: "no: release in force" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
b3: "no" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
c0: "Hand-written fake" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
c1: "yes, invented shapes" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
c2: "no" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
c3: "no" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
d0: "Partner stub (Claims' CI)" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
d1: "yes, from a script" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
d2: "no: the recording" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
d3: "no" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
e0: "Claims' suite in Northgate's CI" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
e1: "no" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
e2: "yes: the candidate" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
e3: "yes, before release" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
Blue rows are code Claims owns and purple rows are Northgate's deployments, the colours this series has used since Part 1. No single row is green in both middle columns. A stub Claims builds can fail on demand. A suite Claims writes and Northgate runs sees the next release. This is Part 1's ownership gate, priced by its cadence question: a partner that owns its releases ships on a schedule you cannot run ahead of.
A seam contract test for an A2A partner: outcome class pinned, fields typed
The book's name for Claims' half of the right way is a seam contract test. It is a consumer-driven test written from what the caller reads and what it has recorded. It asserts the outcome class of the answer and the type and range of each field the caller reads, never the value. As a file, the suite is plain JSON that Claims publishes across the owner line. Here are two of the eight entries in its tests array:
[{ "name": "CLM-R01: answered", "skill": "estimate_repair", "request": {"claim_id": "CLM-R01", "damaged_parts": ["bumper", "door"]}, "outcome": "answered", "reads": { "estimate": {"type": "number", "required": true, "unit": "claim currency"}, "notes": {"type": "string", "required": true} }},{ "name": "CLM-R03: rejected", "skill": "estimate_repair", "request": {"claim_id": "CLM-R03", "damaged_parts": ["mirror"]}, "outcome": "rejected", "reads": {}}]The rejection test has no reads. Its whole assertion is the outcome class, which is exactly the property the typed pact gave away. No number is pinned in the answered test. A suite that asserted CLM-R01 at 3,000 would go red on every legitimate price change, and a partner whose build goes red on Claims' suite every quarter learns to mark it non-blocking. Pact's pending-pacts feature exists because, without it, "any failing pact (eg. ones with new features) will cause the provider's build to break". So the suite asserts only what Claims' code branches on.
Running it needs nothing of Claims' but the file and a small checker. The companion's verify() reads the class off the answer to a blocking send. It caught the planted switch, and on the refactor it raised InternalError instead of returning a failure. The checker I would hand a partner is keyed to the task instead. It sends the way Claims' seam sends, reads until the task ends, and gives a send that produced no task a class of its own:
import asyncioimport uuidimport httpx# CANCELED is folded into failed here; the read-side breaker count still skips it.CLASS = {"COMPLETED": "answered", "INPUT_REQUIRED": "asks", "REJECTED": "rejected", "AUTH_REQUIRED": "asks authority", "FAILED": "failed", "CANCELED": "failed"}OPEN = {"SUBMITTED", "WORKING"}async def rpc(http: httpx.AsyncClient, method: str, params: dict) -> dict: body = {"jsonrpc": "2.0", "id": str(uuid.uuid4()), "method": method, "params": params} return (await http.post("/", json=body, headers={"A2A-Version": "1.0"})).json()async def outcome(http: httpx.AsyncClient, skill: str, request: dict, budget_s: float, every_s: float = 0.02) -> str: """The class this request ends in, read off the task, not off the send.""" message = {"messageId": str(uuid.uuid4()), "role": "ROLE_USER", "parts": [{"data": request}], "metadata": {"skill": skill}} sent = await rpc(http, "SendMessage", {"message": message, "configuration": {"returnImmediately": True}}) if "error" in sent: return f"no task (JSON-RPC {sent['error']['code']})" task_id = sent["result"]["task"]["id"] for _ in range(int(budget_s / every_s)): read = await rpc(http, "GetTask", {"id": task_id}) if "error" in read: return f"unreadable (JSON-RPC {read['error']['code']})" status = read["result"]["status"] state = status["state"].removeprefix("TASK_STATE_") if state in OPEN: await asyncio.sleep(every_s) continue found = CLASS.get(state, f"unknown {state}") if found == "asks": # name the field asked for, as the suite does parts = status.get("message", {}).get("parts", [{}]) found += " " + parts[0].get("data", {}).get("needs", "") return found return "still open"http is an httpx.AsyncClient pointed at the deployment under test, and every send carries a fresh messageId, for a reason the stub-drift section comes back to. budget_s is how long the checker waits for the task to end, and it is a seam term, not a test setting. I ran it with one second against an in-process Northgate. Against Northgate's staging, where the assessor desk can take about 21 minutes on a frame, a one-second budget turns every slow request into still open. So the budget comes from the completion time the seam's terms declare, and a still open result is a finding about those terms. An asks result names the field asked for, so it compares with the suite's asks photo_url. Run against the three builds, for the unpriced CLM-R03, the priced CLM-R01 and the frame-only CLM-R02 (R03, R01 and R02 below):
release in force R03 rejected PASS R01 answered R02 asks photo_urlplanted failed() R03 failed FAIL R01 answered R02 asks photo_urlrefactor (raise) R03 failed FAIL R01 answered R02 asks photo_urlBoth flips now fail the same way, failed where the suite says rejected, on the send shape the seam actually uses. A full checker also tests each field an answered test reads by type and range, as the companion's violations() does, and I left that part out to keep the listing short. It is a sketch in other ways too. It speaks only the JSON-RPC binding at POST /, it does not guard against an empty parts list or a 5xx that is not JSON, and it sends no credentials. The estimate seam's terms declare mTLS and delegation, so a partner running it in CI needs a test credential.
The two halves of the right way meet in one file, the suite, which is the only artifact Claims sends across the line:
grid-rows: 1
grid-columns: 3
grid-gap: 24
claims: "Claims (Meridian)" {
label.near: top-center
style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}
grid-columns: 1
grid-gap: 16
exp: "expectations + recordings" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
file: "suite file: 8 tests\noutcome class + field types" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
ci: "Claims' CI, every change:\ngraph + suite vs the stub" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
}
cross: "the only artifact Claims\nsends across the owner line\n(published to Northgate)" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
ng: "Northgate" {
label.near: top-center
style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}
grid-columns: 1
grid-gap: 16
copy: "the same suite file" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"}}
rc: "Northgate's CI, each candidate:\ntask-keyed check vs the candidate" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
red: "CLM-R03: expected rejected,\ngot failed: release held" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
}
Claims' CI runs the suite against Claims' stub on every change, which tests Claims' handling of every answer the suite and the stub allow. Northgate's pipeline runs the same file against the release candidate. Because Northgate's staging runs the release in force, that right-hand run is the only run of Claims' expectations that executes Northgate's next release before it ships. In the companion, the test that stands in for Northgate's CI passes the release in force, then fails the planted candidate with exactly one failure, CLM-R03: rejected, expected rejected, got failed. The task-keyed checker fails the refactored candidate the same way. The same file against Claims' stub passes, as it would have all Tuesday morning.
A red build at Northgate leaves the choice with Northgate. Its engineers can put the rejection back. They can also conclude that failed is correct, which the spec's wording allows, and tell Claims before the release, so Claims changes its outcome class table instead of its breaker finding out claim by claim.
Between two teams of one company, this is a CI rule one pull request can add. Between companies it has to be written into the agreement. Every insurer that calls Northgate hands over its suite, Northgate runs all of them before each release and sends back the results, and holding a release on a red result stays Northgate's call. I would not expect a partner to sign that except for suites that are short, rarely change, and never pin anything the partner is entitled to change. That is the commercial case for outcome classes over values.
The partner stub: a stand-in A2A server that fails only from a script
The other half is the partner stub: a stand-in A2A server, built only from what Claims holds. That means the card it fetched, the partner's terms, recordings of real answers, and a fault script. Claims runs its own graph against it in CI. The stub's job is narrower than a fake's, and two rules are what make it trustworthy.
First, every answer in the stub is held to the partner's terms when the stub is built. An answer comes from a recording of a synthetic claim sent to Northgate's staging, from an answer a person accepted for a golden task, or from a script for an answer the terms allow that Claims has never seen, such as a refused undo. Whatever its source, if the terms in force do not allow the exchange, the stub refuses to build. A scripted estimate of "3,000" as a string stops the build with "estimate is '3,000', not estimate as a required number in claim currency". A scripted question for a VIN stops it too, because terms v7.4 declare only photo_url as something the skill may ask for.
Second, a failure is never a reply. A recorded or scripted exchange may end completed, input-required, auth-required or rejected. An exchange that ends failed refuses to build with "a failed task is a fault, not an answer: script it as one". Failures go into a separate fault script, where every test that uses one names it. OneUptime's piece on mock drift makes the same separation for HTTP mocks, calling failure injection "client-resilience tools, not evidence of provider behavior" and asking for synthetic 500s and timeouts to be labelled as test scenarios "so nobody mistakes them for a provider guarantee". A send that matches nothing recorded is rejected with "no recording for estimate_repair", never answered with an invented value.
direction: down
inputs: "What Claims holds" {
label.near: top-center
style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}
grid-rows: 1
grid-gap: 12
card: "card as fetched" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"}}
terms: "terms v7.4" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"}}
rec: "recordings" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"}}
faults: "fault script" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"}}
}
check: "build-time check:\nevery exchange held to the terms" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
refuse: "out of contract, or a failed\nexchange: the stub refuses to build" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
stub: "partner stub (Claims' code)" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
order: "For each send, in order" {
label.near: top-center
style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}
grid-rows: 1
grid-gap: 12
o1: "1. a fault the\nscript names" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
o2: "2. first matching exchange:\nrecorded, canary, scripted" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
o3: "3. rejected:\nno recording" {style: {fill: "#95A5A6"; stroke: "#6F7E7F"; font-color: "#2C2C2A"}}
}
inputs -> check
check -> refuse: "breach"
check -> stub: "clean"
stub -> order
Nothing of Northgate's code enters the stub. The companion holds the stub to that with a test that imports the stub package in a fresh interpreter and finds no Northgate module loaded. What separates it from a fake is the fork under the yellow check. A fake accepts whatever its writer types. Here, any answer the partner's terms would not allow stops the build. The per-send order at the bottom means a fault is always visible in the test that injected it.
With failures on a script, every failure path earlier parts of this series built can run in CI without a partner to misbehave. A lost answer is a lose_answer fault on the first send: the stub does the work and drops the reply, and Claims should find the task by its key and estimate once, a resend inside the key window from Part 4. A restore() while a task is open removes every task and key, and Claims should report the task not found and resend nothing, since a resend after a restore is how Part 4's clean-ledger duplicate begins. A compensated undo, an undo that leaves a residue (owed 6,500), and a refused undo ("the repair of CLM-R07 has started at SHOP-7") are scripted answers, because a refusal is a reply the terms allow, in the stub's sense and not Part 2's answer that writes state. Of the undo outcomes, only a late one is a fault: 12 seconds of slow on cancel_booking, which Part 5's compensator should settle as uncompensated for a person, with no retry. The 12 seconds cost no wall-clock time, because the stub's clock is the drill's shared clock, and the companion's 36 stub and contract tests run in about ten seconds.
Circuit breaker on an async A2A seam: the failure the send never sees
A circuit breaker is usually drawn as a guard around a call, and on an async A2A seam that picture is the same call-keyed mistake as a pact on the send. Running the fault script against the stub found it in Claims' own code, which is the strongest argument for the stub. On a blocking seam, the send waits for a terminal state, so a failed task comes back as the send's answer, and Claims' breaker, which is asked on every send, counts it. On the estimate seam, the send returns once the task exists (Northgate's assessor desk can take about 21 minutes on a frame), so the send comes back submitted well inside its timeout. When the task fails seconds afterwards, nothing but the next read can notice. In the companion's node a read never asks the breaker, because a read is not a call that should be refused under an open breaker. Until the fix below, a read did not tell the breaker anything either.
I ran three priced claims against a stub scripted with Fault("fail"), so that every task ends failed, in four configurations. Each run produced three PartnerFailed errors, so Claims saw every failure. What differed was the breaker:
| Send shape | Read-side count | Breaker after 3 failed tasks |
|---|---|---|
| blocking | off | open |
| returns once the task exists | off | closed |
| blocking | on | open |
| returns once the task exists | on | open |
Ten recorded refusals (CLM-R03), run once against the shipped breaker, left it closed, as designed. The opening's breaker opened because the companion's node already has the read-side count, the last row. Without it, the second row's mechanism says Tuesday's release would have tripped nothing. I measured that row with a scripted failure, though, not with the refactored executor. Each mirror claim would have gone to an adjuster on its own as a partner failure, and no signal would have said anything had changed.
A fair objection is that the breaker is half the incident. It counted a deterministic failure on one input, the same mirror with the same status message, as a sign of Northgate's health, and three is a low threshold. Reading the partner's message text to tell the cases apart is off the table, because this series quotes a partner's free text and never parses it. Counting failed tasks is right: without the read-side count the flip is silent, and silence is worse than an early opening. What was wrong is the unwritten class, which is this part's claim. With rejected for an unpriced part written down as a term and tested, the count would have kept working on the failures it exists for.
grid-rows: 1
grid-gap: 40
block: "Blocking send" {
label.near: top-center
style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}
grid-columns: 1
grid-gap: 14
s: "send waits for the end" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
a: "answer: failed" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
b: "breaker asked: counts 1" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
}
push: "Send returns once the task exists" {
label.near: top-center
style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}
grid-columns: 1
grid-gap: 14
s: "send returns" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
a: "answer: submitted, in time" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
r: "later read: failed" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
b: "breaker never asked: counts 0" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
fix: "fix: a read that finds a new\nfailure counts it once" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
}
In the diagram, the send that returns early succeeds, and the failure arrives on a path the breaker was built not to watch. The fix in the companion is three lines in the node's read branch:
# RemoteAgentNode.__call__ (seamkit/remote.py); the send branch is aboveelse: # a task exists: read it, never send a second one task = await self._get(entry["task_id"]) if (self.breaker and entry["state"] != "failed" and state_name(task.status.state) == "failed"): self.breaker.failed_later(seamkit.ledger.CLOCK()) # never sent: readfailed_later counts the failure without touching the in-flight count, which the send already settled. A canceled task is not counted on a read, because Claims cancels tasks itself when it stops a partner. That leaves one case Part 5 sent here uncovered: a cancel the partner starts itself. The companion's stub has no fault for it, and the read-side count would skip it as if Claims had cancelled, so it needs a term of its own. Detection now lags by however long the next read takes to happen, so on a push seam the cadence of Claims' backstop poll bounds it.
I found no source describing a send-guarded breaker that misses failures arriving after the send, so treat this as a measured finding about the companion's design. Microsoft's Circuit Breaker pattern page points the other way. It lists, among the cases where the pattern may not fit, "a message-driven or event-driven architecture, because they often route failed messages to a dead letter queue for manual or deferred processing." For an A2A seam whose send returns early, an alarm on the rate of tasks that end failed, computed over reads, is a reasonable alternative to a breaker. Before production tells you, the cheapest way to find out whether yours does is a stub that can fail a task after its send returned.
Keeping a partner stub true: recording stamps and stub drift
Left alone, a stub turns into the hand-written fake within a few releases. A recording describes Northgate on the day it was made, so each one carries a stamp of three things: the card digest the caller's trust policy accepted, the terms revision in force, and the behaviour version that the caller's canaries last accepted. A scheduled job compares the stamp with the partner Claims is connected to now. Against a Northgate on release v8 it reports two lines, starting "card digest" and "terms revision", as the companion's test_a_recording_goes_stale_when_the_partner_moves asserts. When a person accepts a new canary baseline it reports the behaviour version that moved. The book calls a stub whose recordings have aged past their partner stub drift.
Record and replay tools know this problem: VCR.py's all record mode exists to "force VCR to re-record a cassette", and Hoverfly's Diff mode compares a live response with the stored simulation. What the stamp adds is a reason to re-record that the caller can check without calling the partner's production.
grid-rows: 3
grid-columns: 1
grid-gap: 18
r1: "1. Claims' CI, every change: graph + fault catalogue + suite, against the stub" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
r2: "2. Claims, on a schedule: conformance + suite against Northgate's staging; stamp vs card: stale?" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
r3: "3. Northgate's CI, each release candidate: Claims' suite - the only run that can hold a partner release" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
Claims' CI run is fast and goes on every change. The scheduled run checks the stub against staging. Only Northgate's run sees a release before it ships, because Northgate's staging runs the release in force. When the scheduled run finds a stale stamp, it files a finding for a person and leaves the build alone: Northgate moved legitimately, the recording now describes a partner that no longer exists, and someone at Claims re-records against staging, reads the diff and decides whether Claims' code needs to change.
One gotcha from my Pact experiment belongs here. A pact replays the request it recorded, including its messageId. Northgate honours a repeated key inside its window, as Part 4 asked partners to, so when I verified the candidate on a deployment that had already seen the release-in-force verification, Northgate handed back the first task, REJECTED, and the pinned pact passed a release it should have failed. A fresh deployment per verification fixed it. The same thing happened again when four pacts shared one messageId, and the send-at-once pacts got a finished task back. Against a partner that honours keys, a replayed contract test needs a fresh key or a fresh store, or it tests the key index instead of the release.
What an A2A seam contract test cannot catch
The suite asserts outcome class, type and range, and that choice gives away three things, each worth naming before a partner signs up to run it.
grid-rows: 3
grid-columns: 2
grid-gap: 14
l1: "A value moves inside its type:\nEUR for claim currency, 0.82 on a 0-100 scale" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
m1: "behavioural canaries on golden tasks\n(book Chapter 15)" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
l2: "A model-backed partner decides\nthe outcome class differently run to run" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
m2: "pin only classes decided by code;\nmeasure the rest as a rate" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
l3: "The partner will not run your suite\nor marks it non-blocking" {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
m3: "a clause in the agreement;\nyour scheduled run against staging" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
Part 3 left the top row open. Its card check passed a Northgate that started returning estimates in EUR, and a fraud score of 0.82 where Claims expected 0 to 100. A seam contract test passes both too. The companion's field checks cover type and bounds, and its unit is a label nobody checks, while 0.82 is inside 0 to 100. That is the price of never asserting values. A changed value needs a canary that compares answers on golden tasks against an accepted baseline, which the book builds in Chapter 15.
Agent testing raises the middle row. Tian Pan notes that "you can't assert exact string equality against an LLM output", and a model deciding whether to refuse will not give one outcome class per request every time. In the companion, the refusal comes from deterministic validation code, so its suite does not flake. For a skill where a model decides, pin the classes that code decides and track the model-decided share as a rate.
Ownership, where this series started, sets the bottom row. Northgate owes Claims nothing it did not agree to. Claims' suite runs in Northgate's pipeline only if the partner agreement says so, and until it does, Claims' scheduled run against staging is the closest substitute, one release late.
Checklist: testing an A2A partner you cannot deploy
- For every partner skill you call, write down which task state each failure mode you handle should end in, and what your code does with each. That table is your outcome classes. Ask the partner to state it as a dated term on its card, so Part 3's connect-time check can read it and a change to it becomes a dated breach.
- Ask each partner whether its agent refuses a request with an explicit
reject()or by raising. Under the A2A Python SDK, a raise endsfailed, and a blocking caller may be told -32602 about the same task, a split verdict. - Key every contract test to the task: send the way your seam sends, read the task until it ends, within a wait budget taken from the seam's declared completion time, and pin its outcome class per recorded request as a value. A check on the send's answer, a type matcher over the task, or a regex over the legal states each pass a blame flip somewhere in the call-keyed vs task-keyed table.
- Assert type and range for every field you read, and no values. Leave values to canaries.
- Publish the suite as a file to each partner. Make the partner's run of it on every release candidate a clause of the agreement, with the result reported back to you.
- Build your stub only from the card, the terms, recordings of synthetic requests against staging, and scripted answers the terms allow. Refuse to build on any exchange the terms do not allow.
- Put every failure in a fault script, never in a recording, and run each earlier failure path against it: lost answer, repeated key, restore from backup, refused and partial undo, late undo, partner failure.
- On every seam whose send returns before the task ends, check that a task failing after the send reaches your breaker or your failure-rate alarm.
- Check that a JSON-RPC error with no task id gets a class of its own in your code and in your suite runner. It is not a refusal, and it may leave a failed task at the partner.
- Stamp every recording with the card digest, terms revision and behaviour version, and re-record when a scheduled check finds any of them moved.
- Verify replayed contract tests against a fresh deployment or with fresh keys, or a partner that honours repeated keys will replay the old answer.
Federated AI agents series recap
This is the last part, so here is the seam it has been building, laid out by the property each part hardened.
grid-rows: 6
grid-columns: 2
grid-gap: 12
p1: "Part 1: ownership is the only gate" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
q1: "where a seam belongs at all; owner seam vs ownerless seam" {style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
p2: "Part 2: the call as a LangGraph node" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
q2: "state: the thread link, read never resend" {style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
p3: "Part 3: the card as a contract" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
q3: "contract: dated terms, brochure fields, dated breach" {style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
p4: "Part 4: retries and reconciliation" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
q4: "failure: key windows, clean-ledger duplicate" {style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
p5: "Part 5: compensation across owners" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
q5: "authority: compensation link, stranded undo" {style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
p6: "Part 6: testing what you cannot deploy" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
q6: "all of the above, run against a stub; the blame flip, caught at the partner" {style: {fill: "#F2F4F4"; stroke: "#95A5A6"; font-color: "#2C2C2A"}}
Each earlier part left paths that are hard to exercise against a real partner. A thread link that must read and never resend after a paused task. A dated breach that refuses one seam. A clean-ledger duplicate that only an outward pass finds. A stranded undo that the compensation link prevents. The failure paths among them, from Parts 4 and 5, run here on demand against the stub, without the partner. It is also where the seam's one unwritten term gets written down. An A2A task's outcome class is decided after the call that started it, and under the A2A Python SDK a partner's ordinary refactor can move a refusal into a failure without anyone choosing it. The check that sees it before it ships is keyed to the task, pins the class per recorded request, and is run by the partner on its release candidate. The fifth property this series named in Part 1, accountability, is the book's last part: receipts a partner countersigns, who pays for a residue, and audit evidence across companies.
Going deeper: Chapter 16 of the book
This is Part 6 of the Federated AI Agents guide, a series that follows my book Federated AI Agents one chapter at a time. Chapter 16, "Testing Agents You Can't Deploy," is where this part comes from. This post adds the Pact experiment, the call-keyed against task-keyed table and the task-keyed checker, the grid of what every check sees across the flip, the SDK measured with four ways of writing validation, the split verdict, the refactored release replayed on the companion's incident harness, and the breaker measured with and without the read-side count. You can build the stub and the suite without the book. Code for the chapter is the ch16-testing-agents-you-cant-deploy tag of the companion repository. Its tests run with no network and no model key. I ran its 36 Chapter 16 tests 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.24, and they pass on both. The Pact, SDK, breaker and refactor experiments are my own scratch scripts on that tag, not part of the companion.
References
- A2A Project. (2026). Agent2Agent (A2A) Protocol Specification, v1.0.1. Section 4.1.3 (TaskState). https://a2a-protocol.org/latest/specification/
- A2A Project. a2a.proto,
TaskState. https://github.com/a2aproject/A2A/blob/main/specification/a2a.proto - A2A Project. a2a-tck: A2A Protocol Technology Compatibility Kit (accessed 2026-11-20). https://github.com/a2aproject/a2a-tck
- a2aproject. a2a-python (a2a-sdk) 1.3.1, and PR #1106, "fix: persist early producer failure as FAILED with originating message". https://github.com/a2aproject/a2a-python/pull/1106 (PyPI: https://pypi.org/project/a2a-sdk/1.3.1/)
- a2aproject. a2a-python source at 1.3.1:
a2a/server/tasks/task_updater.py(reject()) anda2a/server/agent_execution/active_task.py(_mark_task_as_failed). https://github.com/a2aproject/a2a-python - JSON-RPC Working Group. (2013). JSON-RPC 2.0 Specification, section 5.1 (error codes -32602, -32603). https://www.jsonrpc.org/specification
- Google. AIP-151: Long-running operations. https://google.aip.dev/151
- FastAPI. Handling Errors (
HTTPException,RequestValidationError). https://fastapi.tiangolo.com/tutorial/handling-errors/ - LangChain. LangGraph 1.2.24. https://pypi.org/project/langgraph/1.2.24/
- Fowler, M. (2011, January 12). ContractTest. https://martinfowler.com/bliki/ContractTest.html
- Robinson, I. (2006, June 12). Consumer-Driven Contracts: A Service Evolution Pattern. https://martinfowler.com/articles/consumerDrivenContracts.html
- Pact. Matching. https://docs.pact.io/getting_started/matching (accessed 2026-11-20)
- Pact. Matching gotchas. https://docs.pact.io/getting_started/matching/gotchas (accessed 2026-11-20)
- Pact. Consumer tests. https://docs.pact.io/consumer (accessed 2026-11-20)
- Pact. Contract tests vs functional tests. https://docs.pact.io/consumer/contract_tests_not_functional_tests (accessed 2026-11-20)
- Pact. Pact JS: matching. https://docs.pact.io/implementation_guides/javascript/docs/matching (accessed 2026-11-20)
- Pact. Provider states. https://docs.pact.io/getting_started/provider_states (accessed 2026-11-20)
- Pact. Pending pacts. https://docs.pact.io/pact_broker/advanced_topics/pending_pacts (accessed 2026-11-20)
- Pact Foundation. Pact specification, version 4 (
statusCodematcher). https://github.com/pact-foundation/pact-specification/tree/version-4 - Strands Agents. sdk-python issue #1371, A2A task states and mapping exceptions to
failed. https://github.com/strands-agents/sdk-python/issues/1371 - Pact Foundation. pact-python 4.2.0. https://pypi.org/project/pact-python/
- Goyal, S. (2026). A2A Protocol Testing. TestMu AI. https://www.testmuai.com/blog/a2a-protocol-testing/
- Rasa. Rasa as an A2A agent. https://rasa.com/docs/reference/architecture/rasa-as-a2a-agent/
- AG2. A2A advanced usage. https://docs.ag2.ai/docs/user-guide/a2a/advanced/
- Pan, T. (2026, May 5). Prompt Contract Testing. https://tianpan.co/blog/2026/05/05/prompt-contract-testing-multi-agent-coordination
- Dhandala, N. (2026, August 24). How to Stop Mock APIs from Drifting Away from the Real Provider. OneUptime. https://oneuptime.com/blog/post/2026-08-24-stop-mock-api-drift
- Genesys Cloud Community (migrated developer forum thread). (2021, December 15). API response status code is changed from 500 to 400. https://community.genesys.com/discussion/api-response-status-code-is-changed-from-500-to-400
- Resilience4j. CircuitBreaker. https://resilience4j.readme.io/docs/circuitbreaker
- Polly. Circuit breaker resilience strategy. https://www.pollydocs.org/strategies/circuit-breaker.html
- Microsoft. Circuit Breaker pattern. Azure Architecture Center. https://learn.microsoft.com/en-us/azure/architecture/patterns/circuit-breaker (accessed 2026-11-20)
- Stripe. Testing: declined payments. https://docs.stripe.com/testing#declined-payments (accessed 2026-11-20)
- respx. RESPX (mock HTTPX). https://lundberg.github.io/respx/
- WireMock. Stubbing. https://wiremock.org/docs/stubbing/
- VCR.py. Usage: record modes. https://vcrpy.readthedocs.io/en/latest/usage.html
- Hoverfly. Diff mode. https://docs.hoverfly.io/en/latest/pages/keyconcepts/modes/diff.html
- Kumar, R. (2026). federated-langgraph-a2a-companion, tag
ch16-testing-agents-you-cant-deploy. https://github.com/ranjankumar-gh/federated-langgraph-a2a-companion/tree/ch16-testing-agents-you-cant-deploy - Kumar, R. (2026). Federated AI Agents. Chapter 15, "Contract Version, Behaviour Version." https://federatedagents.ranjankumar.in/?utm_source=ranjankumar.in&utm_medium=blog&utm_campaign=federated-ai-agents&utm_content=federated-ai-agents-a2a-contract-testing-outcome-class
- Kumar, R. (2026). Federated AI Agents. Chapter 16, "Testing Agents You Can't Deploy." https://federatedagents.ranjankumar.in/?utm_source=ranjankumar.in&utm_medium=blog&utm_campaign=federated-ai-agents&utm_content=federated-ai-agents-a2a-contract-testing-outcome-class (book page on this site: /federated-ai-agents)
Related Articles
- A2A Agent Card Versioning: a Version Bump Is Not a Contract
- LangGraph interrupt() Re-Sends Your A2A Task on Resume
- A2A, MCP, or Subgraph? 'Deployed Separately' Is the Wrong Reason
- A2A Idempotency: Your Retry Key Lives in Partner Memory







