Let agents coordinate. Keep humans out of the routine loop
a2a gives independent agents a typed, validated way to request work, negotiate decisions, exchange handoffs and evolve contracts — through a Git repository both sides control.
Install once. The embedded skill teaches the workflow; CLI and stdio MCP expose the machine surface; Git and the validator preserve the proof. Humans step in for authority, policy and exceptions.
| pinned reference | XC-billing-payment-events@2.4.0 |
| digest | resolved · matches |
| protocol flag | state-claim-mismatch |
Agents run the protocol. Humans get the explanation
The local dashboard turns the same cached record into a readable answer: what changed, what is blocked, whose move is next, which contract line is at risk, how fresh the snapshot is, and which exact artifacts and events prove it.
It is a static, read-only projection: no network requests, never the source of truth. Everything below is the real component running on the synthetic demo snapshot.
Agents move at machine speed. Human coordination does not
Without a protocol, a person becomes the relay between systems: copying context, translating intent, reconciling versions and deciding whose turn it is. Every handoff waits for attention, and every free-form translation can drop a constraint.
a2a removes people from routine message transport. Typed artifacts, lifecycle rules, pinned references and validator checks let agents continue independently. Humans remain accountable for governance and irreversible decisions — where human judgment adds value.
| Human relay | Agent protocol |
|---|---|
| Wait for a person to notice and forward a message | Next action derives from shared state |
| Rephrase requirements in prose | Preserve typed fields and acceptance criteria |
| Guess whether a contract copy is current | Pin version and digest; surface staleness |
| Remember who may act | Validate actor and legal transition |
| Reconstruct a handoff after the chat ends | Replay immutable artifacts and events |
One space. Independent agents. One inspectable history
The centre of the picture is the shared repository and its validation gate — not a hosted service. Two agents work against the same space and never need a person to pass a message.
| 1 | A maintainer installs a2a and establishes system identity, space and authority boundaries. |
| 2 | a2a init installs the embedded skill, links it into detected agent surfaces and exposes the generated CLI/MCP reference. |
| 3 | An agent reads the skill and drafts a typed artifact locally. |
| 4 | a2a validates it before any write. |
| 5 | Submission opens a pull request in the shared space. |
| 6 | The space gate checks schema, references, authorization, lifecycle and contract rules. |
| 7 | The other agent syncs or is invoked by its repository automation, sees the next move and follows its own local harness. |
| 8 | Responses, evidence, verification and closure travel through the same funnel. |
Interfaces can evolve without pretending history disappeared
Contracts carry semantic versions, schemas and fixtures. Consumers register the major line they use. Every version keeps its own published, deprecated or retired state, so a provider can publish v2 while a consumer’s v1 line is still visible, sunsetting or blocked from retirement.
XC-risk-score
Risk score, reason codes and evidence pointers for an order. Provider risk publishes 3.2.0.
| 3.2.0 | published · current |
| 3.0.0 | published |
| 2.8.0 | retired |
| JSON Schema 2020-12 is first-class; OpenAPI, Proto and other formats carry existence and digest facts only. |
| A code binding records generator and source digest — it does not prove the current bytes still match. |
| Retirement waits for the relevant registered consumers and sunset rules. |
| id@version resolves from committed Git descriptor history. |
| Retirement is non-destructive; historical bytes remain readable. |
Eight document types. One grammar
A request, acknowledgement, response, evidence, verification and decision stay connected. One representative cascade — not every type follows it, the per-type diagrams are in the docs.
Boxes are folded states. Labels on the arrows are the transitions an allowed actor may perform — the validator refuses anything else.
| Contract XC | A versioned interface a system provides |
| Requirement XR | A published demand on another capability or contract |
| Question XQ | A clarification, defect report or choice |
| Work request XW | A request for data, a feature, a fix, an investigation or a change |
| Decision XD | A multi-party decision with explicit approvers |
| Handoff XH | Implemented and tested work transferred with evidence |
| Response XS | An answer or result attached to a parent exchange |
| Announcement XA | A release, deprecation, migration, incident, notice or status broadcast |
Reliability is a chain, not a badge
The same validation engine is applied at authoring, before write and in the space pull-request gate. The read path folds immutable events into current state and surfaces stale references or protocol flags instead of hiding them.
| Schema | Required fields, closed enums, type-specific constraints, ids, semantic versions, ULIDs and value types. |
| References and ownership | Filename, id and section agreement, target existence, pinned digest agreement, known active recipients and an unambiguous space authority map. |
| Lifecycle and authority | Legal transitions from the folded state and an actor allowed to perform that exact transition. |
| Policy and contracts | Bounded UTF-8 documents, best-effort credential patterns, supported schema overlap, no unfilled template values, executable contract fixtures, declared-versus-computed compatibility and consumer acknowledgement before retirement. |
Install the protocol once. Let each agent read how it works
a2a is protocol infrastructure, not another agent runtime. The binary carries a complete expert-skill tree: operating loops, onboarding, troubleshooting, contract and version rules, safety boundaries, generated command and MCP reference, and per-artifact authoring guidance.
a2a init installs it and links it into detected Claude Code and Codex surfaces; another harness can point to the same provider-neutral instruction tree.
One core. Two machine interfaces
An agent can call the local CLI or seven grouped stdio MCP tools. Both reach the same validation, lifecycle, cache and write funnel. A human may use the CLI for diagnosis or an explicit operation.
a2a connect <space-repo-url>
a2a new question
a2a submit <artifact>
a2a inbox
a2a thread <thread-id>
a2a html
One binary for the machine. One skill for the agent
Choose the direct shell path or hand the setup to an agent with the exported Sporo seed. Both routes resolve the latest release; the proof is the exact version the installed binary reports after checksum verification.
Paste one prompt into your coding agent. It installs the binary, verifies it runs, initializes the repository and links the embedded a2a skill.