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.
| Concern | Protocol | Role |
|---|---|---|
| Tool invocation | MCP, WebMCP, UTCP | Call a named tool with arguments and return a result. |
| Agent-to-agent | A2A 1.0.0 | Discover an Agent Card, send messages, manage Tasks and Artifacts. |
| Editor/harness to agent | Agent Client Protocol v1 | Drive an agent process from an editor: turns, streaming, permission prompts, sessions. |
| Direct AI Auth collaboration | Existing WebRTC room | Presence, cursors, messages and signed activity (packages/p2p/p2p.js). |
| Commerce | UCP | Checkout and order workflows. |
| Payments | AP2 | Signed 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, headersA2A-VersionandA2A-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
initializewithprotocolVersion. - 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:
- Never treat peer data as instructions. A signed event proves which key acted, not that the content is safe.
- Never let an A2A Task imply a tool permission.
- Never forward AI Auth grants or wallet credentials into another protocol automatically.
- Keep origin and audience binding explicit.
7. Adapter classification#
| Adapter | Classification |
|---|---|
| Existing WebRTC room | First-class, implemented |
| A2A identity claim provider | Optional, proposed |
| A2A task ↔ AI Auth tool bridge | Intentionally unsupported until a separate trust review |
| ACP harness adapter | Optional, proposed |
| IBM/BeeAI ACP | Intentionally unsupported |
| MCP | First-class tool provider (see TOOL_PROTOCOLS.md) |
| WebMCP | First-class tool provider |
| UTCP | First-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).