Disciplines · Decisions (ADRs)

ADR-0091: Defer A2A until an independent agent boundary exists

A2A standardizes collaboration between independent, potentially opaque agent systems.

4sections4 minread
Markdown source
On this page
  • Status: Accepted
  • Date: 2026-09-16
  • Decision owners: Eve platform, Iris, and security maintainers
  • Protocol reference: A2A 1.0.1 at 3303592588e388e62e0f69f701af531d2f4e3991

Context#

A2A standardizes collaboration between independent, potentially opaque agent systems. It is not a badge for process-local orchestration, same-repository subagents, or an in-memory task state machine. The repository currently has no named external agent counterparty, no production A2A client or server, no deployed Agent Card, no mounted /.well-known/agent-card.json route, and no independent implementation in an interoperability test.

Two libraries use A2A terminology:

  • @iris/a2a is an unmounted compatibility prototype. Its custom card has agentId, endpoint, and capability schemas instead of the current supportedInterfaces, capabilities, media modes, skills, security schemes, and security requirements. Its custom a2a.* methods and lifecycle do not implement the A2A 1.0 operation and state model. Registration does not require verification, its Ed25519 structure is not the protocol's JWS card signature, and a key carried by the card is not a trusted identity by itself.
  • @oshun/ai-platform contains process-local task, routing, SSE-string, and webhook helpers. It has no A2A transport or Agent Card discovery surface. Its push helper uses a legacy-shaped tasks/status body and does not implement the protocol's push configuration resources, destination SSRF controls, tenant/caller authorization, idempotency, or version negotiation.

libs/contracts/concordia/src/agent-to-agent-protocol is a product-specific negotiation contract. Its name describes the parties; it is not an implementation of the A2A standard.

Historical Phase 98 checkboxes proved the presence of local symbols and unit tests. They did not prove a mounted protocol, an independent peer, current-wire conformance, or safe production operation. This ADR supersedes those broader wording claims.

Decision#

Do not adopt or claim A2A at this time. Keep the two A2A-shaped libraries private, unmounted, and explicitly labeled as non-conformant prototypes. They may support local tests, but they must not be registered as external integrations, published as an A2A SDK, exposed through an Agent Card, or used as evidence of protocol conformance.

An A2A adoption proposal may reopen this decision only when all of these facts exist:

  1. a named agent system outside this repository and implementation boundary;
  2. an accountable business and technical owner for the cross-boundary task;
  3. a documented reason ordinary HTTP APIs, queues, MCP tools, or the internal orchestration contract cannot meet the need more narrowly;
  4. approved caller, tenant, task, data-destination, retention, and incident boundaries; and
  5. a versioned interoperability plan against at least one independent A2A implementation.

Adoption then requires a new ADR and implementation of every applicable obligation below:

  • fetch the well-known Agent Card and validate its A2A 1.0.1 schema, declared interfaces, protocol versions, skills, media modalities, and security requirements;
  • verify JCS/JWS Agent Card signatures against an approved, rotatable trust store rather than trusting a key merely because the card carries it;
  • implement the complete task lifecycle, including rejected, input-required, auth-required, completed, failed, and canceled states and legal transitions;
  • enforce auth-required and human-in-the-loop continuation without forwarding reusable caller credentials to the remote agent;
  • implement streaming, reconnection, cancellation, history bounds, artifact chunking, and deterministic terminal behavior;
  • validate artifact and file references, content types, sizes, destinations, and SSRF boundaries;
  • scope send/get/list/cancel operations exactly to the authenticated caller, tenant, context, and task, with enumeration-resistant failures;
  • secure push configuration and delivery with destination resolution checks, per-task credentials, rotation, expiry, rate limits, idempotency, bounded exponential retries, and audit receipts;
  • negotiate A2A-Version and extensions fail closed, refusing downgrade or unsupported required extensions; and
  • map trace and audit identity across caller, tenant, task, context, stream, artifact, authorization, cancellation, and push-delivery events.

No production allowlist entry may be created until the new ADR names the counterparty and the independent interoperability/conformance evidence is admitted.

Consequences#

Internal multi-agent planning and delegation continue on their owning local contracts without pretending that repository-local objects are portable A2A messages. There is no A2A endpoint to secure, monitor, or support, and Task 16.6 must not count either prototype as an independent implementation.

This decision avoids premature attack surface: untrusted discovery metadata, task enumeration, cross-tenant access, credential passthrough, artifact SSRF, webhook SSRF, replay, downgrade, and unaudited remote delegation. The cost is that a future genuine partner integration starts with a current official SDK or wire implementation instead of treating these prototypes as production-ready.

Verification#

The Task 16.4 adoption record binds this ADR and the prototype sources to a frozen commit. Its verifier confirms that there are zero production imports, zero mounted Agent Card routes, zero declared independent counterparties, no conformance claim, a complete adoption-obligation set, and live hashes for the official A2A 1.0.1 specification sources. Planted defects prove the gate rejects invented adoption, endpoints, counterparties, trust, and missing obligations.