Agent Wire v1.1 + A2A Hardening Spec

Date: 2026-05-06 Status: Draft for implementation planning Supersedes / extends: docs/specs/2026-04-28-agent-wire-protocol.md, docs/specs/2026-05-01-hcs-streaming-wire-protocol.md Related: docs/specs/2026-04-27-google-agent-sdk-a2a.md, docs/plans/2026-04-27-a2a-gateway.md

---

Agent Wire is RedKey's internal coordination protocol. A2A is the external interoperability protocol for agent-to-agent collaboration. This spec uses A2A v1.0 as a hardening reference for Agent Wire without replacing RedKey's HCS-first architecture.

The intended outcome is:

```text Internal RedKey agents -> Agent Wire v1.1 events -> HCS canonical stream -> Supabase read model -> Studio / runners / evaluators

External A2A callers -> A2A gateway -> translation to/from Agent Wire v1.1 -> same HCS canonical stream ```

This keeps one internal source of truth. A2A becomes a boundary binding, not a second execution model.

---

Do both hardening tracks together at the schema/spec level:

1. Upgrade Agent Wire from a typed message envelope into a typed streaming protocol. 2. Borrow A2A's task, context, message, artifact, streaming, and capability concepts where they improve internal RedKey clarity. 3. Make the protocol deterministic by requiring state-machine contracts, JSON Schemas, golden fixtures, conformance tests, and reducer tests before production implementation.

Do not implement a separate A2A streaming subsystem. RedKey streaming remains HCS-backed Agent Wire. The A2A gateway later maps that stream to A2A SendStreamingMessage, SubscribeToTask, TaskStatusUpdateEvent, and TaskArtifactUpdateEvent.

---

Agent Wire v1.1 must be implemented as contracts that code validates, not prose that agents interpret.

Required pipeline:

``text spec -> state-machine contract -> JSON Schema -> golden fixtures -> conformance tests -> implementation -> reducer/state tests -> HCS event record ``

Rules:

• Prose explains why. Structured contracts define what is valid.
• Agents may draft specs, fixtures, and code, but validation decides authority.
• Every event type must have a JSON Schema before producers emit it.
• Every event type must have at least one valid golden fixture.
• Every important invalid case must have a named invalid fixture.
• Every state transition must be represented in a state-machine contract.
• Reducer tests must prove ordered Wire events reduce to exact task/artifact/project state.
• A2A mapping must be conformance-tested from Agent Wire events, not hand-waved in prose.

The first v1.1 implementation should create these directories:

``text schemas/agent-wire/v1.1/ fixtures/agent-wire/v1.1/ contracts/agent-wire/v1.1/ tests/conformance/agent-wire/ tests/reducers/agent-wire/ ``

Minimum schema files:

``text schemas/agent-wire/v1.1/envelope.schema.json schemas/agent-wire/v1.1/stream.schema.json schemas/agent-wire/v1.1/state.schema.json schemas/agent-wire/v1.1/task-created.schema.json schemas/agent-wire/v1.1/task-available.schema.json schemas/agent-wire/v1.1/task-claimed.schema.json schemas/agent-wire/v1.1/task-started.schema.json schemas/agent-wire/v1.1/task-blocked.schema.json schemas/agent-wire/v1.1/artifact-ready.schema.json schemas/agent-wire/v1.1/task-complete.schema.json schemas/agent-wire/v1.1/task-failed.schema.json schemas/agent-wire/v1.1/task-cancelled.schema.json ``

Minimum fixture files:

``text fixtures/agent-wire/v1.1/task-created.valid.json fixtures/agent-wire/v1.1/task-available.valid.json fixtures/agent-wire/v1.1/task-claimed.valid.json fixtures/agent-wire/v1.1/task-started.valid.json fixtures/agent-wire/v1.1/artifact-ready.valid.json fixtures/agent-wire/v1.1/task-complete.valid.json fixtures/agent-wire/v1.1/task-complete.invalid-missing-artifact.json fixtures/agent-wire/v1.1/task-complete.invalid-verification-fail.json fixtures/agent-wire/v1.1/task-blocked.valid.json fixtures/agent-wire/v1.1/task-failed.valid.json fixtures/agent-wire/v1.1/task-cancelled.valid.json ``

Minimum contract files:

``text contracts/agent-wire/v1.1/task-state-machine.json contracts/agent-wire/v1.1/event-state-map.json contracts/agent-wire/v1.1/a2a-task-state-map.json ``

The implementation is not conformant until tests prove:

• Every valid fixture validates against the event schema and envelope schema.
• Every invalid fixture fails for the expected reason.
• Every event maps to exactly one normalized state category.
• Every allowed transition is accepted by the state machine.
• Every disallowed transition is rejected by the state machine.
• The reducer can replay ordered Wire events into exact task state.
• The reducer records artifact counts and artifact IDs from artifact.ready.
• task.complete.payload.artifact_ids references all required final artifacts.
• task.complete.payload.verification.mechanical must be pass.
• Agent Wire task/artifact events map cleanly to A2A task/artifact events.

Reducer tests should use this shape:

``json { "name": "happy path with one artifact", "events": [ "task.created", "task.available", "task.claimed", "task.started", "artifact.ready", "task.complete" ], "expected": { "task_state": "completed", "terminal": true, "artifact_count": 1, "blocked": false, "verification": { "mechanical": "pass" } } } ``

No LLM interpretation is allowed in reducer tests. Input is ordered Wire events. Output is exact state.

---

• Do not replace HCS as the canonical coordination stream.
• Do not expose raw internal memory, model traces, runner logs, or tools through A2A.
• Do not make internal Agent Wire conform exactly to A2A if doing so weakens RedKey's proof, attribution, or marketplace model.
• Do not build the A2A gateway in this spec. This document defines the internal protocol hardening that makes that gateway straightforward later.

---

| A2A concept | Agent Wire v1.1 use | |---|---| | Task | RedKey agent_tasks row plus HCS task stream | | Message | Typed coordination message or human/agent input | | Part | Structured payload part inside a message or artifact reference | | Artifact | Durable output object with lineage, hash, and version | | contextId | RedKey context_id, grouping related tasks/messages | | referenceTaskIds | RedKey reference_task_ids, linking continuation or dependency tasks | | Task status events | RedKey lifecycle events with normalized state category | | Artifact update events | RedKey artifact.* events | | Agent Card | RedKey Agent Card discipline for identity, skills, modes, constraints, and auth | | Extensions | Namespaced RedKey metadata instead of ad hoc payload growth |

---

Every meaningful internal coordination event should use the v1.1 envelope.

``json { "wire": "1.1", "wire_id": "wire_01HZY...", "type": "task.started", "sender": "agent:quinn-03", "ts": "2026-05-06T16:00:00Z", "stream": { "stream_id": "task:0.0.8830671:attempt:1", "stream_seq": 12, "context_id": "project:knowledgevault-m01r", "correlation_id": "project:knowledgevault-m01r", "causation_id": "wire_01HZX...", "reference_task_ids": ["0.0.8830669"], "parent_task_id": "0.0.8830668" }, "state": { "category": "working", "terminal": false }, "payload": {}, "extensions": {} } ``

| Field | Required | Purpose | |---|---:|---| | wire | yes | Protocol version. Current target: 1.1. | | wire_id | yes | Globally unique event ID. | | type | yes | RedKey event name, e.g. task.started, artifact.ready. | | sender | yes | agent:<slug>, runner:<id>, system, or human:<id>. | | ts | yes | Producer timestamp. HCS consensus timestamp remains canonical after submission. | | stream | yes | Stream identity, ordering, context, and causality. | | state | yes for task events | Normalized lifecycle category. | | payload | yes | Type-specific structured data. | | extensions | no | Namespaced RedKey or future A2A-compatible metadata. |

The listener must persist HCS metadata separately from the signed/logged Wire body:

``json { "hcs": { "topic_id": "0.0.8830671", "sequence_number": 42, "consensus_timestamp": "2026-05-06T16:00:01.123456789Z", "running_hash": "..." } } ``

HCS metadata is the proof layer. The Wire body is the coordination event.

HCS should carry coordination facts, commitments, references, and proof metadata. It should not carry working content.

Good HCS content:

• task lifecycle events: task.created, task.available, task.claimed, task.started, task.blocked, task.complete
• inbox and routing events that decide what work exists and who may act on it
• artifact reference events: artifact.ready with URI, version, hash, and readiness metadata
• review/gate events that affect scheduling or release
• compact health/capacity events that affect orchestration

Bad HCS content:

• raw model output, drafts, scratch notes, transcripts, verbose logs, or token streams
• large artifacts or document bodies
• private memory contents
• secrets, credentials, API responses with sensitive content, or hidden prompts

The value of streaming through HCS is not content storage. The value is deterministic ordering, claim arbitration, auditability, replay, recovery, and cross-agent coordination. Supabase mirrors this stream for fast reads and product UI, but HCS remains the canonical event source.

---