Frequently asked questions

a2a-wrapper is a set of Node.js packages that expose Claude, OpenAI Codex, GitHub Copilot, OpenCode and Google Antigravity as standalone agents over the open A2A (Agent2Agent) protocol. You write a JSON config file and get a spec-compliant A2A server that any A2A client can discover and call.

MCP standardizes how an AI application connects to external tools, data and workflows. A2A standardizes how independent agents communicate and collaborate as peers. The A2A project describes the two as complementary: MCP gives each agent depth, and A2A gives a system of agents reach.

No. A JSON config file and one command start a server. You only write code to call the agent (any HTTP client works) or if you want to build a new wrapper for another backend.

Developers who want to combine coding agents into workflows: for example Claude implementing a feature while Codex writes the tests, coordinated by an orchestrator. It is also useful if you already run an A2A orchestrator and want real coding agents as execution nodes.

No. It is an independent open-source project. Claude, Codex, GitHub Copilot and Google Antigravity are products of their respective owners, and you need your own access to each backend you wrap.

a2a-wrapper is free and MIT licensed. You pay only for whatever backend you connect to, such as your Copilot plan, Anthropic or OpenAI usage, or nothing extra if you use a local model.

A2A is an open standard for communication between AI agents, giving agents built by different vendors or frameworks a common language. Google introduced it in April 2025 and contributed it to the Linux Foundation, which announced the Agent2Agent Protocol Project in June 2025 to provide neutral governance. It builds on HTTPS, JSON-RPC and Server-Sent Events, and the current specification version is 1.0.0.

MCP is for connecting an agent to tools and resources that have well-defined inputs and outputs. A2A is for agents, which are more autonomous and can reason and hold multi-turn conversations, to communicate and collaborate as peers. The A2A project's own example: a shop-manager agent uses A2A to talk to customers and suppliers, while a mechanic agent uses MCP to drive its diagnostic tools. In a multi-agent system you normally use both.

No. The A2A project describes the two protocols as complementary, not competing: MCP deepens a single agent by connecting it to tools, while A2A connects agents across boundaries. Wrapping a coding agent with a2a-wrapper leaves its MCP tools in place and adds the A2A layer on top.

An agent card is a JSON document that acts as a digital business card for an A2A server. It carries the agent's identity, service endpoint, capabilities, supported authentication schemes and skills. The discovery guidance recommends serving it at https://{agent-server-domain}/.well-known/agent-card.json, following RFC 8615. Other strategies are curated registries and direct configuration. Every a2a-wrapper agent serves its card at that path automatically.

Put each behind an A2A server with its a2a-wrapper package, then have an orchestrator send tasks to them. For example, Claude implements a feature and Codex writes the tests, coordinated by a small planner script. Because they all speak A2A, any A2A-capable orchestrator works, and you can swap agents without changing the orchestration.

Install a2a-claude, write a JSON config, and start it. It wraps the official Claude Agent SDK and serves an A2A agent card, JSON-RPC and REST endpoints, so any A2A client can send it tasks. Use permissionMode to control what it may do.

Yes, through a2a-codex, a2a-copilot and a2a-opencode. Each one exposes its backend as an A2A server configured with a JSON file, with backend-specific controls such as Codex sandbox modes, Copilot bring-your-own-model providers, and OpenCode multi-provider routing.

To build a custom agent from scratch, use an official A2A SDK. The A2A repository lists SDKs for Python (a2a-sdk), Go (a2a-go), JavaScript (@a2a-js/sdk), Java, .NET and Rust. To expose an existing coding agent such as Claude, Codex or Copilot, a2a-wrapper generates the server from a config file with no protocol code.

When Google announced A2A in April 2025, more than 50 technology partners contributed, including Salesforce, SAP and ServiceNow and consulting firms such as Accenture, Deloitte and McKinsey. When the Linux Foundation launched the Agent2Agent Protocol Project in June 2025, it named Google Cloud, AWS, Cisco, Microsoft, Salesforce, SAP and ServiceNow among the supporters. Check the A2A project for current adoption.

Yes. The A2A protocol repository is licensed under the Apache License 2.0 and is described as an open source project under the Linux Foundation, contributed by Google. a2a-wrapper, which implements the protocol for coding agents, is a separate project under the MIT license.

Agent cards declare supported authentication schemes in a security field aligned with OpenAPI, such as OAuth 2.0, OpenID Connect and API keys sent in HTTP headers. Credentials are obtained outside the protocol, and the A2A guidance says a server must authenticate every incoming request and that production traffic must use HTTPS. a2a-wrapper agents do not enforce inbound authentication themselves, so to follow that guidance put a gateway or reverse proxy that authenticates requests and terminates TLS in front of any agent that is reachable beyond localhost.

No. A2A is designed so agents collaborate without exposing their internal logic, memory or proprietary tools. A caller sees messages, tasks and artifacts. A server-generated contextId groups related tasks into a conversation, and each wrapper uses it to keep that agent's own session history.

Fetch the agent card and call /health with curl, then send a message/send request to /a2a/jsonrpc. You can also point an A2A inspector at the server; a2a-wrapper buffers artifacts by default, which works well with inspectors. Turn on sideband events to see tool calls and reasoning.

Common patterns are an implementer agent plus a tester or reviewer agent, a planner that splits a large change across specialist agents, read-only review agents that audit a repository, and mixing vendors so each task goes to the agent that does it best. The A2A project frames this as specialized agents collaborating on complex tasks without custom point-to-point integrations.

Node.js 20 or newer, and credentials for the backend you want to wrap: a GitHub account with Copilot access for a2a-copilot, an Anthropic key for a2a-claude, an OpenAI key or codex login for a2a-codex, and so on.

Install the package globally with npm, for example "npm install -g a2a-copilot", then start it with "a2a-copilot --config ./config.json". You can also run it without installing through npx. The five packages are a2a-copilot, a2a-claude, a2a-codex, a2a-opencode and a2a-antigravity.

Fetch the agent card at /.well-known/agent-card.json, and the health endpoint at /health. If both respond, send a message/send request to /a2a/jsonrpc to get a real answer.

If you have GitHub Copilot, a2a-copilot is the quickest to try. If you want the most capable multi-step coding agent, use a2a-claude. If you want a sandboxed repository agent, use a2a-codex. If you want to choose among many model providers, use a2a-opencode.

Yes. The software-engineering-crew example has a --mock mode that starts stand-in agents, so you can see the planner delegate work without any model calls or credentials.

A2A v1.0 natively, with backward compatibility for v0.3.x clients. The A2A specification lists 1.0.0 as the latest released version, with 0.3.0 among the earlier ones. The server negotiates per request, so old and new clients both work with no configuration.

No. Clients that send the A2A-Version header get the matching shape, and clients that send nothing get a v0.3-style agent card. The protocolVersion field in the config is informational only.

The A2A specification defines JSON-RPC, gRPC and HTTP+JSON/REST protocol bindings. a2a-wrapper agents serve JSON-RPC (at /a2a/jsonrpc) and HTTP+JSON/REST (under /a2a/rest), plus the agent card at /.well-known/agent-card.json.

Yes. A2A supports request/response with polling, streaming over Server-Sent Events, and push notifications. a2a-wrapper agents advertise and support streaming: use message/stream for a stream of status updates and artifact chunks, or message/send with blocking enabled to wait for the final result. By default artifacts are buffered into one complete artifact for maximum client compatibility; you can enable incremental chunks if your client supports them.

The specification defines these task states: submitted, working, input-required, auth-required, completed, failed, canceled and rejected (written TASK_STATE_* in v1.0). Completed, failed, canceled and rejected are terminal; input-required and auth-required mean the task is waiting on the caller.

Yes, as an opt-in. A2A v1.0 JWS-signed agent cards (RFC 7515) are supported: configure signing with a private key read from an environment variable and the card is signed automatically. Unsigned cards are the default.

Not by default. The A2A endpoint has no built-in authentication, the default bind address is 0.0.0.0, and the agents can edit files and run commands. The A2A project says a server must authenticate every request and use HTTPS in production, so bind to 127.0.0.1 for local use, run in a container with a scratch workspace, and put an authenticating, TLS-terminating proxy in front of anything shared.

Not for the inbound A2A endpoint today. Outbound calls to other agents and MCP servers support bearer tokens, API keys and custom headers read from environment variables. To protect the endpoint itself, use a reverse proxy or gateway that enforces authentication, as the A2A guidance expects of a production server.

Use the backend controls: permissionMode in a2a-claude (plan for read-only), sandboxMode in a2a-codex (read-only or workspace-write), Antigravity policies, and a container with a scratch workspace for any wrapper. Avoid bypassPermissions and danger-full-access outside an isolated environment.

In environment variables, never in config.json. Config fields that need a secret use ${ENV_VAR} substitution, and unset variables are left visible so a misconfiguration is obvious.

Yes. An agent that reads untrusted files, web pages or issue text can be steered by that content, and with shell access that matters. Do not give an agent with write access untrusted input and anything valuable to damage.

Privately, through GitHub Security Advisories on the repository. Please do not open a public issue for a security problem.

GitHub Copilot (a2a-copilot), Claude (a2a-claude), OpenAI Codex (a2a-codex), OpenCode (a2a-opencode) and Google Antigravity (a2a-antigravity). All are built on the shared @a2a-wrapper/core package.

Yes. a2a-copilot supports bring-your-own-key providers such as Ollama, vLLM, OpenAI, Anthropic and Azure, and a2a-opencode is multi-provider. The model must support native tool calling; some small local models print tool calls as plain text and will not work.

Yes. a2a-claude passes the Bedrock and Vertex authentication environment variables through to the Claude Agent SDK untouched, so set whichever your deployment needs.

Google Antigravity's SDK is Python. The wrapper keeps the public A2A server in Node, for the same surface as the other wrappers, and runs the SDK in a private managed Python subprocess. Run "a2a-antigravity setup" once to create the Python environment.

The model you configured is not enabled for your account. Set the model to "auto" for a2a-copilot so Copilot chooses one your plan includes, or pick a model your plan has.

Yes, in two ways. An external orchestrator can call several agents, as the crew example does. Or a wrapper agent can declare sub-agents so its own model calls other A2A agents as tools.

You list remote A2A agents under subAgents in the config. The wrapper starts the a2a-mcp-skillmap bridge as an MCP server, and each remote skill appears to the model as a tool named {name}__{skillId}.

It complements them. Use the framework for orchestration, state and memory, and call the wrappers as A2A execution nodes. Any orchestrator that can make HTTP calls, or that has an A2A client, can drive a wrapper.

They can, but give each agent its own workspace or branch when they work in parallel to avoid conflicting changes. The crew example uses one shared scratch repository deliberately, because the agents work one after the other.

Each A2A contextId maps to a persistent backend session. Send the same contextId on every message in a conversation. An optional TTL can expire sessions; when one expires the next turn starts fresh.

Yes. a2a-copilot, a2a-claude, a2a-codex and a2a-opencode ship Dockerfiles, built from the monorepo root. Codex needs extra privileges inside a container for its shell sandbox, and a2a-antigravity has no published image yet.

Enable sideband events. Wrappers emit tool calls, reasoning summaries, file changes and usage as A2A trace artifacts, or send them to an HTTP collector or a custom sink such as Kafka.

Yes, tasks can be cancelled with tasks/cancel (CancelTask in v1.0), and cancellation is idempotent. The maximum time for one prompt is set with timeouts.prompt in milliseconds; use streaming for long-running work. A2A is designed for tasks that range from quick requests to work that takes hours or days.

Stable releases are reviewed and approved manually and are what npm install gives you. Canary releases are published automatically after every merge to main that passes CI; they are unreviewed and meant for trying a fix early, not for production.

Read the contributing guide, then open an issue or a pull request on GitHub. Adding a wrapper for a new backend is a well-trodden path because the shared core handles the protocol.

On GitHub: open an issue with the package and version, your Node version, a redacted config and the logs. Discussions are enabled for questions and ideas.

Yes. The site publishes llms.txt and llms-full.txt, serves every page as Markdown (append .md or send Accept: text/markdown), and runs a read-only docs MCP server at /mcp with search and page-reading tools.