Testing Multi-Agent Handoffs as Contracts

A multi-agent demo can look excellent while the handoffs are quietly broken. The researcher finds the right evidence. The delivery agent writes a convincing recommendation. Somewhere between them, a restriction disappears, an old artifact becomes current, or two agents both decide they own the next action.

I’d treat that boundary like an API contract. Test what crosses it, who can accept it, and what happens when acceptance fails. Evaluating each agent’s answer in isolation leaves the most interesting failure modes conveniently off the scorecard.

Anthropic’s August 2026 research offers a useful warning: bounded, tool-like delegation and open-ended peer coordination are different problems. Its experiments describe coordination failures even among capable agents. That is evidence for testing the interaction, not a prediction that every multi-agent system will fail.

Start with one handoff you can explain

Consider a hypothetical research-to-delivery workflow. A research agent collects approved supplier documentation. A delivery agent turns that evidence into an implementation brief for a human reviewer. Neither may contact suppliers, alter a purchasing record, or publish the brief.

The researcher’s job ends when an evidence package is durably available. The delivery agent’s job begins when it accepts that exact package. A coordinator owns the transition and records acceptance. Until then, a successful research task is useful progress, not proof that delivery has started.

A2A v1.0 supplies the communication model: an Agent Card advertises capabilities and interaction requirements; messages carry exchanges; tasks track work; artifacts hold outputs. A contextId groups related interactions. Those structures help agents communicate. They do not define your evidence schema or decide whether a brief is fit for review.

Pin the protocol version and compatible interface in your integration tests. Then put the business contract above that transport. The following is an application-level example, not an A2A wire payload:

{
  "contractVersion": "research-brief/1",
  "handoffId": "handoff-042",
  "workflowId": "supplier-review-17",
  "sourceTaskId": "research-task-8",
  "artifact": {
    "id": "evidence-12",
    "version": 3,
    "digest": "<verified content digest>"
  },
  "objective": "Draft an implementation brief for human review",
  "constraints": [
    "Use approved sources only",
    "Do not contact suppliers",
    "Do not publish"
  ],
  "requiredOutput": "implementation-brief/1",
  "nextOwner": "delivery-agent",
  "deadline": "<absolute timestamp>"
}

Keep the envelope small enough to validate. Store evidence records behind the referenced artifact: source URL, retrieval time, relevant claim, limitations and any required access classification. Make the objective and constraints explicit rather than expecting the receiver to reconstruct them from a transcript.

Acceptance needs more than valid JSON

A schema check catches a missing artifact version. It will not catch a perfectly formed package answering the wrong question.

For this workflow, I’d require the receiver to verify that the artifact exists, its digest matches, its contract version is supported, and its evidence addresses the requested supplier decision. An empty evidence array should produce a clear rejection or clarification request. It should not become an invitation to improvise.

Test capability discovery too. Advertise a skill the receiver cannot perform, remove a required content type, and change the supported contract version. Assert that routing stops before work begins, with enough diagnostic detail for the coordinator to choose another supported path. Silently falling back to a generic agent makes compatibility failures much harder to see.

Treat provenance as part of acceptance. In a fixture, substitute an older evidence artifact while keeping the surrounding prose unchanged. The receiver should reject the mismatch or explicitly request the intended revision. The same test should fail if the artifact is inaccessible to that receiver. A URL is not evidence that its contents can be read.

Carry the authorization boundary across the handoff

A2A’s enterprise guidance separates authentication from conversational content and leaves authorization enforcement to the server. That distinction matters: an agent saying “the user approved this” is not a credential.

In this design, the coordinator binds the handoff to an authenticated principal and the permitted operation in trusted application state. The receiving service checks those permissions itself. Do not copy a broad upstream bearer token into a prompt or evidence package. Use an appropriate scoped credential or delegation mechanism outside the generated text.

Build a negative fixture with valid research output but no permission to access the underlying supplier record. Another fixture should put a different tenant’s record behind the artifact reference. Both must stop before the protected read or write. Inspect backend audit events and record versions; a polite refusal in the generated answer is insufficient if the tool call already happened.

Keep trace identifiers, source-task references and artifact lineage so an operator can reconstruct the transfer. Avoid logging credentials or unnecessary source content. Observability should explain a decision without creating a second, less protected copy of the data.

Break the transition, then inspect the effects

The most valuable tests interrupt the gap between “sent” and “accepted.” Use a small harness with a coordinator, a controllable receiver and a fake business-record API that records attempted effects. Start with deterministic fixtures; then repeat the same cases with the real model and tools.

• Dropped context: remove “do not publish” from the receiver’s input. The trusted policy should still block publication, and the missing required constraint should prevent acceptance.
• Duplicate delivery: deliver the same handoff twice, including after a coordinator restart. Expect one accepted work item and one resulting brief, with both deliveries visible in the audit trail.
• Lost acknowledgement: let the receiver accept the package, then drop its response. The coordinator should reconcile the recorded acceptance before submitting new work.
• Ambiguous ownership: let both agents propose the next step. Only the coordinator’s committed assignment should authorize it; neither proposal should independently trigger an action.
• Stale completion: deliver a late result from an earlier attempt after a newer artifact has been accepted. Preserve it for diagnosis without letting it overwrite the accepted revision.

A2A v1.0 permits implementations to use messageId for duplicate detection; sending a message is not an unconditional exactly-once guarantee. For this workflow, I’d add a durable application handoff ledger with a unique acceptance key and a guarded ownership transition. Enforce a corresponding uniqueness rule at the side-effect boundary. A deduplicated chat message does little good if the business API still creates two records.

Define timeout behavior explicitly. A deadline can stop new work without proving that a remote action failed. Query the receiver’s durable state and reconcile the observed effects. If the result remains uncertain, retain the attempt for investigation rather than giving a second agent permission to repeat it.

A2A’s task lifecycle also matters here: terminal tasks do not restart, and follow-up refinements become separate tasks. Keep your application’s accepted artifact version explicit when doing that follow-up. A new task should not silently erase the history of the previous result.

Measure the boundary, not just the answer

Track accepted handoffs per eligible attempt, duplicate work items, unauthorized effects, missing evidence, time awaiting ownership, and human repair effort. For every injected failure, define the expected state transition and permitted effects before running the test. Otherwise a team can accidentally count a graceful-looking failure as success.

Keep structural and semantic checks separate. Contract parsing, artifact existence and duplicate prevention should have deterministic assertions. Whether the evidence actually supports the brief needs a domain-specific rubric and calibrated human review. A model can help evaluate the latter, but it should not be the only witness to whether a forbidden API call occurred.

Nieve’s agentic workflow work centers on integrating customizable agents with existing infrastructure. At that boundary, my recommendation is straightforward: start with one explicit handoff, a durable acceptance record and a handful of adversarial fixtures. Add more agents when the existing boundary is observable and testable. Another agent is rarely the missing assertion.

Key takeaways

• Define an application-level handoff contract with a clear objective, constraints, artifact version and next owner.
• Validate evidence and provenance as well as schema compatibility; a fluent response is not acceptance.
• Enforce authorization in trusted services and test protected records and actual tool effects.
• Inject duplicates, lost acknowledgements, dropped constraints and stale results; reconcile uncertainty before retrying.
• Measure coordination failures and repair effort alongside individual answer quality.