A2A Serve

Turn opencode, Claude Code, or any ACP coding agent into a sandboxed A2A agent that people, messengers, and other agents can call.

Warning

A2A Serve is pre-1.0. Commands, flags, and config.yaml keys may change; stored state always migrates forward. Read Security and Known Limitations before exposing an agent to other people.

• Use your agent from your phone: message it on Telegram, Discord, or email and approve edits or commands from chat.
• Talk to it: send voice notes and get voice replies, through OpenAI, Gemini or a speech server you run.
• Share an agent with your team: expose it on Tailscale, an Agent Mesh relay, or a public URL with pairing codes or Google sign-in.
• Let agents call other agents: delegate tasks to contacts, peers, and webhook nodes while keeping tokens outside the sandbox.
• Package repeatable setups: bundle instructions, skills, MCP servers, and schedules into a one-command recipe.

Quickstart

Install a2a-serve and the a2a CLI on macOS or Linux:

brew tap a2aproject/a2a-cli https://github.com/a2aproject/a2a-cli
brew install a2aproject/a2a-cli/a2a-serve && a2a-serve doctor --fix

Without Homebrew:

curl -fsSL https://raw.githubusercontent.com/a2aproject/a2a-serve/main/install.sh | sh

To build from main with Go 1.26+, see Getting Started.

Start an agent in your project directory and send it a task:

# Claude Code (or: opencode --model <provider/model> --secret <KEY>)
a2a-serve start claude --secret ANTHROPIC_API_KEY --detach
a2a send -a "$(a2a-serve status --url=local)" "What does this project do?"

Without Docker, install the agent on your machine and add --sandbox local. Follow Getting Started to approve tool calls, connect Telegram, and invite callers.

Examples

1. Serve a Coding Agent: pair with an agent, approve tool calls, and call a second agent.
2. Tailscale, Telegram, and Grok: expose the agent on Tailscale and Telegram and add a webhook node.
3. Agent Mesh Relay: connect two agents through a local relay without Tailscale.
4. Observability Agent: run a read-only production assistant from a Grafana recipe.
5. Relay on Cloud Run: deploy a persistent relay with Cloud SQL and Secret Manager.
6. Talk to Your Agent on Telegram: send voice notes to the agent and get voice replies.

User Guide

Area	Guides
Setup & sandbox	Getting Started · Supported Agents · Running · Config · Secrets · Sandbox
Extend & operate	MCP and Skills · Recipes · Schedules · Backups · Shell Completion
Access & approvals	Approvals · Inspector · Identities · Email Sign-In
Networks & chat	Networks · Relays · Messengers · Voice
Multi-agent	Agent2Agent · Webhook Nodes
Architecture & reference	Architecture · Sandboxing · Access Model · Security · Agent Mesh · Agent Directory · Commands · Config File · HTTP Routes · Approval Messages · Audio Messages · Output · a2a CLI

Known Limitations

• API keys passed with --secret are readable inside the sandbox. They are environment variables in every agent container that a sandbox rule gives them to. A tricked agent or any caller allowed to approve commands can read the keys their container gets. --inject-model-key and --inject-header keep a key out of the sandbox, and the server adds it to the agent's HTTPS requests to its host (Secrets). The agent can still spend such a key through that host, so give it a key with a spending limit (#235, and Security).
• The sandbox can reach any public host. A tricked agent can send the files it can read to any host on the internet. It can't reach the tailnet or the LAN unless you allow them, and --egress allowlist limits it to the hosts you list (Network).
• A cloned repository can configure the agent you start in it. a2a-serve start takes the command, image, mounts, environment variables, and MCP servers from the project's .a2a/config.yaml and .mcp.json. Read both before starting an agent in a repository you did not write.
• Agent images follow the latest agent releases at publish time, so the same tag can carry different agent versions over time.

Contributing

Open an issue or pull request to share suggestions, questions, or edge cases. See the Contributing guide and Code of Conduct.

License

A2A Serve is licensed under the Apache License 2.0.