Agent-to-Agent Protocols (A2A)

The route

4 steps to Done

1. 01

   Define the protocol

   Write the message schemas and state machine before any agent code.

   Preview prompt + verify gate ▾ Hide ▴

   Define a minimal A2A protocol. Message envelope: {message_id, correlation_id, sender, recipient, type, timestamp, body}. Message types: task_submit {intent, payload, deadline}, task_ack {accepted: bool, reason?}, task_status {state, note}, task_result {ok, output, evidence?}, task_reject {reason, retryable: bool}. Task state machine: submitted -> accepted -> working -> (completed | failed); submitted -> rejected. Define per-intent timeout defaults and which failures are retryable. Document payload schemas for the demo intents: build_component and review_component. Deliver the protocol doc with a sequence diagram of the happy path and two failure paths.

   • ✓ Envelope and all message types specified
   • ✓ State machine covers rejection and failure
   • ✓ Two failure sequences diagrammed
2. 02

   Build the message layer

   Reliable-enough transport with full observability.

   Preview prompt + verify gate ▾ Hide ▴

   Implement the message layer. For v1 use a simple shared queue (Redis lists, a DB table, or an in-process bus) - the protocol matters more than the transport. Requirements: send/receive with the envelope schema validated on both ends; every message appended to a JSONL protocol log with correlation IDs; a per-agent inbox poll or subscription; deadline tracking that emits synthetic timeout events when an expected ack or result does not arrive. Write transport tests: deliver, validate-reject a malformed message, and fire a timeout for a silent recipient.

   • ✓ Schema validation on send and receive
   • ✓ All messages in the protocol log
   • ✓ Timeouts generated for silent recipients
3. 03

   Wrap agents as protocol endpoints

   Each agent's loop stays private; the protocol is its public face.

   Preview prompt + verify gate ▾ Hide ▴

   Wrap two agents as protocol endpoints. The builder agent: accepts build_component tasks, runs its internal loop (plan, code, self-check), and returns task_result with the artifact and a brief evidence note. The reviewer agent: accepts review_component tasks, evaluates the artifact against the payload's acceptance criteria, and returns either approval or a structured critique list (issue, location, severity, suggestion). Both: send task_ack on receipt, task_status when starting work, and reject tasks whose payload fails validation. The internal agent loops remain unchanged - only an adapter layer speaks protocol.

   • ✓ Ack and status sent at the right moments
   • ✓ Critiques are structured, not prose blobs
   • ✓ Invalid payloads rejected with reasons
4. 04

   Run the revision loop with failure injection

   The demo that matters: cooperation surviving imperfection.

   Preview prompt + verify gate ▾ Hide ▴

   Orchestrate the full flow: submit build_component to the builder; on result, submit review_component to the reviewer with the artifact; if the critique has blocking issues, submit a revision task to the builder including the structured critique; repeat up to 2 revision rounds; finish with the approved artifact or an honest 'unresolved after N rounds' outcome. Then inject failures and verify handling: (a) kill the reviewer mid-task - the timeout fires and the orchestrator reports it; (b) make the builder return an artifact violating the schema - the reviewer rejects with a machine-readable reason; (c) force max revisions - the loop exits honestly. Reconstruct one complete run from the protocol log by correlation ID as the final proof.

   • ✓ Revision round uses the structured critique
   • ✓ Timeout, rejection, and max-rounds all handled
   • ✓ Full run reconstructed from logs by correlation ID

Research-backed

Sources behind this flow