Architecture
How a2a-wrapper is structured, from the shared core to the per-backend executors. The request path through the Express server, the executor, the session manager and the backend SDK.
Layers
┌────────────────────────────────────────────────────────────────────────┐
│ @a2a-wrapper/core │
│ Logger · Config · Events · Server · Session · CLI · Sub-Agents · │
│ Memory · Schema │
└──────────────────────────────┬─────────────────────────────────────────┘
▼
┌────────────────────────────────────────────────────────────────────────┐
│ Wrapper packages (one executor each) │
│ a2a-copilot → GitHub Copilot SDK a2a-claude → Claude Agent SDK │
│ a2a-codex → OpenAI Codex SDK a2a-opencode → OpenCode Server │
│ a2a-antigravity → Antigravity SDK (Python bridge) │
└────────────────────────────────────────────────────────────────────────┘All protocol and spec-version logic lives in @a2a-wrapper/core and nowhere else in the monorepo. Each wrapper implements a single A2AExecutor interface plus a thin config and CLI layer.
Request path
A2A client (orchestrator, inspector, curl)
│ JSON-RPC or REST over HTTP
▼
Express server (from core's createA2AServer)
├─ /.well-known/agent-card.json agent card
├─ /a2a/jsonrpc JSON-RPC (message/send, message/stream, …)
├─ /a2a/rest HTTP+JSON
└─ /health health check
▼
Executor (backend-specific)
├─ SessionManager contextId → backend session
├─ Event publishing backend events → A2A status / artifact events
└─ Backend SDK Copilot, Claude, Codex, OpenCode, Antigravity
▼
The backend's model and tools (MCP servers, shell, file edits)Some wrappers also expose /context and /context/build, which read and build a context.md description of the workspace.
What core provides
| Area | What it does |
|---|---|
| Config | Loads the JSON file and merges layers: defaults, file, environment, CLI flags |
| Server | Builds the agent card, mounts the JSON-RPC and REST routes, handles version negotiation |
| Sessions | Maps contextId to a backend session with optional TTL cleanup |
| Events | Publishes task status, artifacts and sideband trace events |
| CLI | Parses common flags and starts the server with graceful shutdown |
| Memory | Writes instruction and skill files into the workspace at startup |
| Sub-agents | Lets an agent call other A2A agents as MCP tools |
What a wrapper provides
A wrapper implements A2AExecutor: initialize(), shutdown() and execute(), plus optional cancelTask(). It maps the backend's session model and events onto A2A tasks. To write your own, see build your own wrapper.
Why a shared core
The A2A SDK and specification evolve. Keeping all spec-version logic in one package means a major SDK upgrade, such as the move to A2A v1.0, changes one package and every wrapper benefits. Core also re-exports the SDK types wrappers need, so wrappers never import the SDK directly.
What is A2A?
The Agent2Agent (A2A) protocol is an open standard for agents to discover each other, exchange tasks, stream results and collaborate, regardless of which framework or vendor built them. How it relates to MCP, and what it gives a2a-wrapper users.
Agent cards
How a2a-wrapper builds and serves an A2A agent card for discovery. The agentCard config block, skills, version-aware responses, and optional JWS-signed cards.