# Architecture (/docs/concepts/architecture)



## Layers [#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 [#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 [#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 [#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](/docs/guides/build-a-wrapper).

## Why a shared core [#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.