DOCUMENTATION · v0.12.2

Agent interoperability

Status: boundary decision and proposed adapter classification. No A2A/ACP protocol client, task state machine or session semantics are implemented. Additive classification helpers ship as the optional ./agent-interop subpath; they treat Agent Cards and peer data as untrusted and deny task-derived tool authority. Research date: 2026-11-19.

1. Separation principle#

Tool protocols invoke capabilities on resources. Agent communication coordinates independent agents. These are different trust boundaries and must not be collapsed.

ConcernProtocolRole
Tool invocationMCP, WebMCP, UTCPCall a named tool with arguments and return a result.
Agent-to-agentA2A 1.0.0Discover an Agent Card, send messages, manage Tasks and Artifacts.
Editor/harness to agentAgent Client Protocol v1Drive an agent process from an editor: turns, streaming, permission prompts, sessions.
Direct AI Auth collaborationExisting WebRTC roomPresence, cursors, messages and signed activity (packages/p2p/p2p.js).
CommerceUCPCheckout and order workflows.
PaymentsAP2Signed mandates and payment authorization.

AI Auth sits below these as identity and delegated authority. It must not own Agent Cards, Task state machines, prompt turns or agent JSON-RPC bindings.

2. A2A (agent-to-agent)#

Verified from primary sources:

  • A2A 1.0.0 is released, Apache-2.0, under the Linux Foundation / Agentic AI Foundation.
  • Canonical model in spec/a2a.proto: Task, TaskStatus/TaskState, Message, Role, Part, Artifact. Operations include Send/Stream Message, Get/List/Cancel/Subscribe Task, push notification configuration and Get Extended Agent Card.
  • Discovery uses an Agent Card: JSON metadata with skills, endpoint and auth requirements, served at a well-known URI; signed Agent Cards use JWS. Media type application/a2a+json, headers A2A-Version and A2A-Extensions.
  • Bindings: JSON-RPC over HTTP(S), gRPC, HTTP+JSON/REST. Security schemes in the Agent Card include API key, HTTP auth, OAuth 2.0, OIDC and mTLS.

Decision: optional adapter, not core. AI Auth may supply a verifiable identity claim to an A2A interaction, but it must not reimplement Agent Cards, Task state or transport bindings. No automatic mapping from an A2A Task to a tool call.

3. Agent Client Protocol (harness integration)#

Verified from primary sources:

  • ACP standardizes communication between code editors/IDEs and coding agents; it is explicitly LSP-like: any Client can use any Agent.
  • Stable protocol version is 1; ACP v2 is a Draft. Remote HTTP/WebSocket support is work in progress.
  • JSON-RPC 2.0 over stdio for local agents; capabilities negotiated at initialize with protocolVersion.
  • Apache-2.0, official SDKs in Kotlin, Java, Python, Rust and TypeScript.
  • Scope: prompt turns, streaming updates, tool calls, permission requests, filesystem/terminal access, sessions, elicitation, diffs and plans.

Decision: optional harness adapter, not core. AI Auth's MCP command already runs inside harnesses; ACP compatibility belongs at that boundary. AI Auth must not duplicate ACP session or permission semantics.

4. Historical Agent Communication Protocol#

Verified from primary sources:

  • The IBM/BeeAI Agent Communication Protocol is a different technology with the same acronym.
  • It was archived read-only on 27 August 2025 after merging into A2A; final release v1.0.3. It used OpenAPI 3.1.1 REST and SSE (/agents, /runs).
  • The ACP documentation explicitly describes it as an "unrelated project with the same acronym" and "not related to the Agent Client Protocol".

Decision: do not revive or implement it. When a document says "ACP", spell out which protocol is meant.

5. Agentic Commerce Protocol (a third ACP)#

ACP also names the Agentic Commerce Protocol developed by Stripe and OpenAI for programmatic checkout between buyers, agents and businesses. It is open source under Apache-2.0, works over REST or MCP, and uses a merchant-of-record model with secure payment credential handoff. It is unrelated to both the Agent Client Protocol and the archived IBM/BeeAI Agent Communication Protocol.

Decision: commerce concern, not an agent-communications adapter. Model it in COMMERCE_PAYMENTS.md alongside UCP and AP2, never as a tool permission. The PR's interoperability RFC calls out the same disambiguation.

6. Existing AI Auth messaging#

packages/p2p/p2p.js, packages/agent/runtime.js and packages/mcp/bridge.js already provide room presence, signed message/text events, receipts and agent-provided tools over WebRTC. That path remains first-class for AI Auth-native collaboration.

Rules for any interop adapter:

  1. Never treat peer data as instructions. A signed event proves which key acted, not that the content is safe.
  2. Never let an A2A Task imply a tool permission.
  3. Never forward AI Auth grants or wallet credentials into another protocol automatically.
  4. Keep origin and audience binding explicit.

7. Adapter classification#

AdapterClassification
Existing WebRTC roomFirst-class, implemented
A2A identity claim providerOptional, proposed
A2A task ↔ AI Auth tool bridgeIntentionally unsupported until a separate trust review
ACP harness adapterOptional, proposed
IBM/BeeAI ACPIntentionally unsupported
MCPFirst-class tool provider (see TOOL_PROTOCOLS.md)
WebMCPFirst-class tool provider
UTCPFirst-class tool provider

8. Acceptance criteria#

  • Two independently running agents can identify one another using existing AI Auth identity.
  • An A2A adapter, if built, interoperates with an independent A2A implementation.
  • No confusion between tool invocation and agent task delegation in tests or logs.
  • Existing direct WebRTC collaboration tests continue to pass (tests/p2p-transport.test.mjs, tests/wheel-*.test.mjs).
On this page