A2a Wrapper

a2a-wrapper

[](https://github.com/shashikanth-gs/a2a-wrapper/actions/workflows/ci.yml) [](https://github.com/shashikanth-gs/a2a-wrapper/actions/workflows/publish.yml) [](https://github.com/shashikanth-gs/a2a-wrapper/blob/badges/.github/badges/downloads-detail.json) [](LICENSE) [](https://nodejs.org)

A monorepo of A2A protocol wrappers that turn production AI backends into standalone, interoperable agents. Drop a JSON config file in, get a fully spec-compliant A2A server out.

> Speaks A2A v1.0 natively, backward compatible with v0.3.x clients. Every wrapper here negotiates protocol version per request — v1.0-aware orchestrators get the native wire format, and anything still on v0.3.x keeps working with zero config changes. See [Protocol Versions](packages/core/README.md#protocol-versions) for how it works.

> The pattern: MCP is the vertical rail — how agents access tools. A2A is the horizontal rail — how agents talk to each other. This repo adds the horizontal rail to multiple AI backends.

Packages

| Package | Stable | Canary | Description | |---|---|---|---| | [@a2a-wrapper/core](packages/core/) | [](https://www.npmjs.com/package/@a2a-wrapper/core) | [](https://www.npmjs.com/package/@a2a-wrapper/core/v/canary) | Shared infrastructure — logging, config loading, event publishing, server factory, session management, CLI scaffold | | [a2a-copilot](a2a-copilot/) | [](https://www.npmjs.com/package/a2a-copilot) | [](https://www.npmjs.com/package/a2a-copilot/v/canary) | A2A wrapper for GitHub Copilot SDK. Supports Bring Your Own Model (BYOK) — Ollama, OpenAI, Anthropic, Azure, vLLM, or any OpenAI-compatible endpoint | | [a2a-opencode](a2a-opencode/) | [](https://www.npmjs.com/package/a2a-opencode) | [](https://www.npmjs.com/package/a2a-opencode/v/canary) | A2A wrapper for OpenCode — multi-provider out of the box (Anthropic, OpenAI, GitHub Copilot, and more) | | [a2a-claude](a2a-claude/) | [](https://www.npmjs.com/package/a2a-claude) | [](https://www.npmjs.com/package/a2a-claude/v/canary) | A2A wrapper for Claude Code — fully spec-compliant agent powered by the official @anthropic-ai/claude-agent-sdk | | [a2a-codex](a2a-codex/) | [](https://www.npmjs.com/package/a2a-codex) | [](https://www.npmjs.com/package/a2a-codex/v/canary) | A2A wrapper for OpenAI Codex SDK — repository-scoped software engineering agent with sandboxing, MCP, and multi-agent delegation | | [a2a-antigravity](a2a-antigravity/) | [](https://www.npmjs.com/package/a2a-antigravity) | [](https://www.npmjs.com/package/a2a-antigravity/v/canary) | A2A wrapper for Google Antigravity SDK — Node/TypeScript public server with a managed Python SDK subprocess, Gemini auth, policies, MCP, and sideband traces |

Both badges are live — Stable reflects the latest approved release (npm install ), Canary reflects the most recent successful merge to main (npm install @canary). See [Release Process](CONTRIBUTING.md#release-process) for how the pipeline works.

Feature Comparison

All five wrappers share the same core: A2A v1.0 native + v0.3.x backward-compatible protocol support, sub-agent delegation, MCP tool integration, and JSON config with env/CLI overrides. Where they differ:

| | Provider flexibility | Streaming | Sandboxing / Docker | |---|---|---|---| | a2a-copilot | BYOK — Ollama, OpenAI, Anthropic, Azure, vLLM, any OpenAI-compatible endpoint | SSE | Docker-ready | | a2a-opencode | Multi-provider native — Anthropic, OpenAI, GitHub Copilot, and more, switch in one config line | SSE with auto-reconnect + polling fallback | Docker-ready | | a2a-claude | Claude models via @anthropic-ai/claude-agent-sdk | Streaming | Docker-ready; permission-mode guardrails (headless-safe by default) | | a2a-codex | OpenAI Codex models via @openai/codex-sdk | Streaming | Docker-ready; read-only / workspace-write / danger-full-access sandbox modes | | a2a-antigravity | Gemini models via the Google Antigravity Python SDK | SSE-compatible | Node/Python bridge — no published Docker image yet |

Backend Flexibility

Several wrappers are provider-flexible — you are not locked into a single vendor:

• a2a-opencode is multi-provider out of the box. OpenCode natively routes to Anthropic, OpenAI, GitHub Copilot, local models, and more — switch provider with one line in config.json.
• a2a-copilot supports custom providers via GitHub Copilot's BYOK ("Bring Your Own Key") capability. Point it at a local Ollama instance, OpenAI, Anthropic, Azure OpenAI, Azure AI Foundry, vLLM, or any OpenAI-compatible endpoint using the copilot.provider config block. See the [a2a-copilot BYOK section](a2a-copilot/README.md#bring-your-own-model-byok) for setup and model requirements.
• a2a-antigravity exposes Google Antigravity through A2A while keeping the public package Node-based. It creates a managed Python environment for google-antigravity via a2a-antigravity setup, then uses Gemini API key or Vertex/ADC auth.

> Note on local models (a2a-copilot): the agentic loop requires the model to support native tool calling. Some small/older local models emit tool calls as plain text and won't work. Use a tool-capable model (e.g. qwen3.6, llama3.3). Full details in the [BYOK section](a2a-copilot/README.md#bring-your-own-model-byok).

Architecture

┌────────────────────────────────────────────────────────────────────────┐
│                          @a2a-wrapper/core                             │
│      Logger · Config · Events · Server · Session · CLI                 │
│      Sub-Agents · Memory · Schema                                      │
└──────────────────────────────┬─────────────────────────────────────────┘
                               │
                               ▼
┌────────────────────────────────────────────────────────────────────────┐
│ Wrapper packages                                                       │
│  • a2a-copilot      → GitHub Copilot SDK                               │
│  • a2a-opencode     → OpenCode Server                                  │
│  • a2a-claude       → Claude Code SDK                                  │
│  • a2a-codex        → OpenAI Codex SDK                                 │
│  • a2a-antigravity  → Google Antigravity SDK via Python bridge         │
└────────────────────────────────────────────────────────────────────────┘

Each wrapper implements a single A2AExecutor interface and a thin config/CLI layer. Everything else — A2A protocol compliance, Express server wiring, agent card building, session TTL management — comes from @a2a-wrapper/core.

Calling Other A2A Agents (Sub-Agents)

Any parent agent can delegate to other A2A agents by declaring them under subAgents in its config.json. The wrapper spawns a2a-mcp-skillmap as a stdio MCP server and registers it under the reserved a2a-subagents key. Each remote skill becomes a callable MCP tool — the LLM dispatches to them like any other tool.

> Bridge: a2a-mcp-skillmap — the open-source bridge that fetches A2A agent cards, projects each skill as an MCP tool, and serves them over stdio or HTTP. See that repo for the full bridge documentation, config schema reference, response modes, session continuity, and OpenTelemetry integration.

{
  "subAgents": {
    "agents": [
      {
        "name": "coding",
        "agentCardUrl": "https://coding.example.com/.well-known/agent-card.json",
        "auth": { "mode": "bearer", "token": "${CODING_AGENT_TOKEN}" }
      },
      {
        "name": "research",
        "agentCardUrl": "https://research.example.com/",
        "endpointUrlOverride": "https://research.internal.local/.well-known/agent-card.json"
      }
    ],
    "options": {
      "responseMode": "artifact",
      "probeTimeoutMs": 5000,
      "syncBudgetMs": 30000
    }
  }
}

The LLM sees coding__ and research__ tools. When subAgents is absent the parent starts normally with no side effects.

Try it: [examples/a2a-subagents-scenario/](examples/a2a-subagents-scenario/) — a self-contained runnable example with two fake sub-agents, a parent config, and a 26-assertion end-to-end test. No API keys required.

# First time (or after changing packages/core): build @a2a-wrapper/core.
# Its dist/ output is git-ignored and is NOT produced by `npm install`.
npx turbo run build

cd examples/a2a-subagents-scenario
./start-all.sh

Quick Start

# Clone the monorepo
git clone https://github.com/shashikanth-gs/a2a-wrapper.git
cd a2a-wrapper

# Install all dependencies
npm install

# Build all packages so @a2a-wrapper/core is compiled to dist/
# (dist/ is git-ignored and is NOT produced by `npm install`)
npx turbo run build

# Run a specific wrapper
cd a2a-copilot
npm run dev -- --config agents/example/config.json

# Or
cd a2a-opencode
npm run dev -- --config agents/example/config.json

# Or
export ANTHROPIC_API_KEY=sk-... WORKSPACE_DIR=/path/to/repo
cd a2a-claude
npm run dev -- --config agents/example/config.json

# Or
export OPENAI_API_KEY=sk-... WORKSPACE_DIR=/path/to/repo
cd a2a-codex
npm run dev -- --config agents/example/config.json

# Or
export GEMINI_API_KEY=... WORKSPACE_DIR=/path/to/repo
cd a2a-antigravity
npm run dev -- setup
npm run dev -- --config agents/example/config.json

Development

This monorepo uses npm workspaces, Turborepo for task orchestration, and Changesets for versioning.

# Install dependencies for all packages
npm install

# Build all packages (core builds first, then wrappers in parallel)
npx turbo run build

# Run tests across all packages
npx turbo run test

# Type-check all packages
npx turbo run typecheck

# Clean build artifacts
npx turbo run clean

Turborepo caches build outputs — unchanged packages are skipped on subsequent runs.

Working on a Specific Package

You can scope Turborepo to a single package with --filter:

# Build only core
npx turbo run build --filter=@a2a-wrapper/core

# Test only a2a-copilot
npx turbo run test --filter=a2a-copilot

# Build a2a-opencode and its dependencies
npx turbo run build --filter=a2a-opencode...

# Test only a2a-antigravity
npx turbo run test --filter=a2a-antigravity

Changesets Workflow

Every PR that changes package behavior should include a changeset:

# Create a new changeset (interactive prompt)
npx changeset

The CLI will ask which packages were affected, the semver bump type (patch / minor / major), and a summary. Commit the generated file with your PR.

Every merge to main (with or without a changeset) publishes affected packages under the canary npm tag automatically — see [Release Channels](#packages) above. Changesets themselves accumulate on a long-lived "Version Packages" PR that the Changesets bot keeps up to date; merging it — whenever a maintainer decides a stable release is ready — is the first of two gates before anything publishes under latest. See [Release Process](CONTRIBUTING.md#release-process) for the full pipeline.

Adding a New Wrapper

Adding a new A2A wrapper (e.g. a2a-claude) requires no changes to the root config or core package:

1. Create the directory at the repo root following the a2a- naming convention:

`` a2a-claude/ ├── package.json ├── tsconfig.json ├── src/ │ ├── index.ts │ ├── cli.ts │ └── claude/ │ ├── executor.ts # Implements A2AExecutor │ ├── session-manager.ts │ └── config/ │ ├── types.ts # Extends BaseAgentConfig │ └── defaults.ts └── agents/ └── example/ └── config.json ``

1. Implement the A2AExecutor interface from @a2a-wrapper/core. This is the only interface your wrapper needs — it handles task execution for your backend. Define your backend config type extending BaseAgentConfig and set up config defaults.

1. Wire it up with createCli() from @a2a-wrapper/core to get a fully functional CLI with config loading, server startup, and agent card generation out of the box.

1. Add sub-agents support (optional, ~10 lines) — call bootstrapSubAgents() inside executor.initialize() and provide a toXxxMcpEntry() adapter that maps the canonical SynthesizedMcpDescriptor to your wrapper's MCP entry shape. See a2a-copilot/src/copilot/executor.ts for a reference implementation.

1. Set up package.json with:

• name set to a2a-
• @a2a-wrapper/core as a dependency ("*")
• publishConfig.access set to "public"
• build, test, and typecheck scripts

1. Run npm install at the repo root to link the new package. The a2a-* workspace glob in the root package.json automatically picks up the new directory.

1. Verify everything works:

``bash npx turbo run build test typecheck ``

1. Create a changeset for the initial release:

``bash npx changeset ``

See the [core package README](packages/core/README.md) for the full API guide.

Roadmap

• OpenTelemetry observability — optional distributed tracing/metrics for task lifecycle and HTTP requests, via @opentelemetry/api (no-op by default, zero cost unless a host app registers a real SDK/exporter). Not yet implemented.

Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

License

[MIT](LICENSE) © a2a-wrapper contributors

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shashikanth-gs
• Source: shashikanth-gs/a2a-wrapper
• License: MIT
• Homepage: https://a2a-wrapper.allsrc.dev

Install and usage instructions live in the source repository linked above.