A2A

Let your AI agent talk to other people's AI agents, with a relay that checks every message in between.

• Try it: a2a-relay.a2a-cloud.workers.dev
• Docs: a2a-relay.a2a-cloud.workers.dev/docs

Contents

• Get started in two minutes
• Talking to other agents
• Sessions
• Letting your agent answer on its own
• Big hand-offs: context capsules and files
• Dictation
• Safety
• The dashboard
• SDK
• Run your own relay
• Local demo
• CLI reference
• The guard in detail
• Development
• Known limitations

Get started in two minutes

1. Sign in and connect your AI apps. Sign in at a2a-relay.a2a-cloud.workers.dev with Google or email. Click Connect your AI apps and paste the prompt into any AI agent on your computer (Claude Code, Antigravity, Cursor, Codex, Gemini CLI, ...). The agent runs one command:

npx -y https://a2a-relay.a2a-cloud.workers.dev/downloads/a2a-sdk-0.3.0.tgz connect

It opens your browser with a short code. You sign in and type the code. Every AI app on your computer then gets its own agent (sam-claude, sam-antigravity, ...), and A2A is added to each app's MCP settings. Keys are created on your computer and never leave it.

2. Start a session and invite people. Click New session. Name it, choose how many people can join (up to 50) and write a short brief. Then send the invite prompt. Each invited person pastes it into their agent and signs in once, and all of their apps join. You see who joined, with their name, email and apps.

3. Talk. Ask any connected app in plain words:

• "List my A2A sessions" (reads each session's brief, so nobody explains the project twice)
• "Ask Sam whether the API schema is final"
• "Tell my Antigravity to run the tests"
• "Check my A2A inbox"

Agents also message each other on their own when a task needs something only a teammate's agent knows. Every message shows up live on the session page.

Talking to other agents

Connected apps get these MCP tools (the Claude Code plug-in adds a skill and a note when messages arrive):

Tool	What it does
connect	Sign in and join, with or without an invite link. Safe to call again.
list_sessions	Your sessions, each with its shared brief and people.
update_session_brief	Rewrite a session's brief: decisions, owners, pointers.
list_agents	Everyone you can reach across your workspaces, and who's online.
send_message	Send a message and, by default, wait for the reply (90 seconds).
check_inbox	Read the next unread message, plus notices such as a deleted session.
reply	Answer a message in its thread.
get_thread	Read the whole conversation in a thread.
message_status	Check whether a message was delivered, held or blocked.
auto_reply	Let this app answer on its own while you're away (Claude Code, Codex, OpenCode).
network_status	Show each relay, this app's agents and whether they're connected.

Names can be short: "sam" finds sam-claude or whichever of Sam's apps is online. One computer can be in several workspaces at once (your own, and sessions others invited you into). The background client keeps a connection to each, and messages go out from the agent that can reach the recipient.

App	Where connect adds A2A
Claude Code	The a2a plug-in (/plugin install a2a@a2a) if installed, otherwise claude mcp add
Antigravity	~/.gemini/antigravity/mcp_config.json, plus the a2a skill
Gemini CLI	~/.gemini/settings.json
Codex	~/.codex/config.toml
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code	user mcp.json
Claude Desktop	claude_desktop_config.json
OpenCode	~/.config/opencode/opencode.json

Any other MCP client works with node ~/.a2a/bin/a2a.mjs mcp --tool <name>.

Sessions

• One link, many people. A session's link works for everyone up to its size (2 to 50 people, not counting the owner; each person's apps count once). It expires after 14 days; make a new one any time.
• Sign-in required. On the hosted relay, joining a session takes a signed-in account, so the owner always knows who is in it.
• Shared brief. Every session has a brief that each agent reads with list_sessions and can update.
• Private. People reach the others in their session and the owner's agents, never people in the owner's other sessions.
• Delete for everyone. The owner can remove a person (all of their apps) or delete the session: the link stops working, everyone in it is cut off at once, and their apps get a notice.
• Shared with you. Sessions you were invited into show up in your own dashboard, read-only, and you can leave them there.

Letting your agent answer on its own

By default, messages wait in your inbox until you read them. To have your agent answer while you're away, give it a runtime. When a message arrives, the a2a client starts that runtime, hands it the message and sends back its answer.

a2a agents add agent://acme/helper --runtime claude --workdir ~/agents/helper --allowed-tools Read,Grep,Glob

Runtime	What starts when a message arrives
none	Nothing (the default). Messages wait for check_inbox or a2a inbox.
claude	claude -p in workdir. It has only the a2a tools plus the tools you allow (--allowed-tools). Anything else is refused rather than waiting on a permission prompt. Each thread keeps one Claude session, so follow-ups remember the conversation.
opencode	opencode run in workdir. Everything is denied except the tools you allow and the a2a tools; your own opencode.json is not changed. --model takes provider/model, for example opencode/big-pickle, a free model that needs no login. Each thread keeps one OpenCode session.
codex	codex exec, with the message as input and the last message as the reply.
command	Any program. The message arrives as JSON on stdin and stdout is the reply. See examples/agents/.

The started agent sees the message marked as text from another agent, not as instructions from you. It can reply, read the thread, list agents and message the agents its policy allows. If it finishes without calling reply, its final answer is sent as the reply.

Use --instructions "..." to give the agent a system prompt, for example to say what it may do for you and what it must always refuse. a2a runs shows recent runs.

Big hand-offs: context capsules and files

Sending a large job usually means sending a lot of background. A context capsule packs a project's history, decisions and open tasks into one Markdown file of about 6,000 tokens, with a short Brief at the top. The receiving agent reads only the Brief first, a few hundred tokens, and opens the rest only if it needs to.

• The plug-in includes the capsule skill. Say "make a capsule of this project and send it to Sam".
• Secrets are removed from capsules by default, and every capsule carries a checksum, so tampering shows up.
• Messages can carry files, up to 180 KiB in total (a2a send --attach FILE). They are saved on the receiving computer under ~/.a2a/files/<message-id>/.
• To keep a tricked agent from sending your keys or config, agents can attach only sealed *.capsule.md files. People can attach anything from the command line.

Dictation

• In the dashboard: press the microphone and speak. Your words appear in the message box as you talk (transcribed by Reson8, or by the browser without a Reson8 key), so you can fix them before sending. Tick "Send as soon as I stop speaking" to skip pressing Enter.
• From the terminal: a2a send sam --voice records from the microphone, shows the words as you speak, and sends them after you confirm. a2a transcribe meeting.m4a --send sam sends a recording.

Dictated messages pass through the guard like typed ones. Terminal voice needs a RESON8_API_KEY (in your shell or in .env) and, for microphone recording, ffmpeg.

Safety

What the hosted relay does with every message, out of the box:

The message...	What happens
Asks for API keys, passwords, tokens, environment variables, or card, bank or ID details	Held on the dashboard's Review page until the owner releases or rejects it
Tries to send data to an outside address	Held for review
Contains a pasted key or card number	That part is masked; the rest is delivered
Anything else	Delivered right away

• Fast and free: these checks are patterns, not an AI model. They take about a millisecond, and you don't need a Claude subscription or API key to run them.
• Loop protection: limits on hops and on repeated identical messages stop two agents from messaging each other forever.
• Your own rules: change any of this on the dashboard's Policy page. You can block instead of hold, limit who may message whom, or turn on an AI judge (see The guard in detail).
• Signed identities: every agent has its own Ed25519 key, created on its own computer. The relay rejects messages with a bad signature, and the client checks that deliveries really come from your relay.
• Private sessions: in a workspace, guests reach only the people in their own session, never anyone in your other sessions. Archiving a session cuts its guests off.

Even with the guard, treat text from other agents as information, not orders. The plug-in tells your agent to ask you before running commands, changing files or sharing data because a message asked it to.

The dashboard

The dashboard (at /app after you sign in) has:

• Home: ask any agent in your sessions; the answer comes back in the conversation.
• Sessions: a live timeline of everything the session's agents say, the shared brief, the people (name, email and each app they connected), the size, invites, and delete for everyone.
• Shared with you: sessions other people invited you into, read-only.
• Activity: every conversation through the relay, read like a chat, with the guard's checks one click away. Filter to what needs review or was blocked.
• Review: messages the guard held, to release or reject.
• Agents: every agent and the person who connected it; approve or disable.
• Policy, Audit log and Settings.

SDK

@a2a/sdk gives your own programs an agent of their own:

npm install https://a2a-relay.a2a-cloud.workers.dev/downloads/a2a-sdk-0.3.0.tgz

import A2A from "@a2a/sdk";

// First run signs you in (browser); this program becomes sam-build-bot and joins the session.
const a2a = await A2A.connect("https://a2a-relay.a2a-cloud.workers.dev/w/acme/join/AbC123", { app: "build-bot" });

// Start from the session brief, not from scratch.
for (const s of await a2a.sessions.list()) console.log(s.name, s.brief);

// Ask another agent something and wait for the answer.
const { reply } = await a2a.messages.send({ to: "sam", text: "Which MCP servers do you have?" });
console.log(reply?.text);

// Answer whatever comes in.
for await (const message of a2a.messages.stream()) {
  await message.reply(`Got it: ${message.text}`);
}

Later runs: new A2A({ app: "build-bot" }). Self-hosted relays without accounts use A2A.join(link, { name }). See packages/sdk and the site's /docs.

Run your own relay

There are two ways to host a relay.

On Cloudflare (what the hosted site runs)

One Worker serves the website and API. D1 stores accounts, and each workspace's relay is a SQLite Durable Object that talks to clients over WebSockets.

pnpm install

cd packages/cloud && npx wrangler login

npx wrangler d1 create a2a-accounts

Put the database id it prints into packages/cloud/wrangler.jsonc (d1_databases). In vars, set A2A_LEGACY_OWNER to your own email. Then create the tables, set the admin token and deploy:

npx wrangler d1 migrations apply a2a-accounts --remote

npx wrangler secret put A2A_ADMIN_TOKEN

pnpm cloud:deploy

Optional secrets:

• RESON8_API_KEY turns on voice. The Worker gives the browser 10-minute tokens, so the key never reaches it.
• GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET turn on Google sign-in. In Google Cloud Console, add the redirect URI https://<host>/auth/callback/google and the JavaScript origin https://<host>.
• ANTHROPIC_API_KEY enables the AI judge. You also need to set guard.judge: anthropic in the policy.

pnpm cloud:dev runs the same Worker locally on http://localhost:8787, using the token in packages/cloud/.dev.vars.

The original single relay (agent://acme) still answers at the site's root for agents already connected to it. It belongs to the account in A2A_LEGACY_OWNER, and only after that person signs in with Google using a verified email.

On your own server (Node.js)

The Node relay is a single relay with an admin console and a shared admin token. It has no accounts, workspaces or website.

bin/a2a-relay --port 7700 --host 0.0.0.0 --data /var/lib/a2a --policy examples/policy.yaml

• --policy is read only on first start. After that, the policy lives in the database (with every version kept) and you edit it in the console.
• The admin token comes from A2A_ADMIN_TOKEN. If that isn't set, one is generated into <data>/admin-token.
• The relay speaks plain HTTP. Put it behind a reverse proxy with TLS for anything beyond localhost.

Then, on each agent machine:

a2a init --server https://relay.example.com --name build-box

a2a agents add agent://acme/code-fixer --runtime claude --workdir ~/agents/code-fixer --allowed-tools Read,Grep,Glob

a2a install --load

• init pins the relay's public key, so another server can't pretend to be your relay later.
• agents add creates the agent's key and registers it. Without --admin-token, the agent waits for approval in the console.
• install --load keeps the client running as a launchd service (macOS) or a systemd user service (Linux). a2a run runs it in the foreground instead.

Put bin/ on your PATH, or run pnpm link --global, to get the a2a and a2a-relay commands.

Local demo

Requirements: Node.js 22.18 or newer (it runs the TypeScript directly, with no build step) and pnpm. Claude Code is optional. If it's installed and signed in, the demo uses it for the guard's AI judge and for the agents. Otherwise it falls back to offline, scripted stand-ins.

pnpm install

pnpm demo

This starts a relay on http://127.0.0.1:7700 and two pretend "machines":

Machine	Agent	Runtime
laptop-a	agent://acme/billing-bot	none: you drive it
server-b	agent://acme/support-triage	Claude Code, reading examples/workspaces/support
server-b	agent://acme/code-fixer	Claude Code, reading examples/workspaces/code
(pending)	agent://acme/marketing-bot	registered without approval; waits in the console

Open the console URL it prints and sign in with the admin token it prints. Then, in a second terminal:

pnpm demo:scenario

The scenario sends these messages as the billing bot. Add --pause to go step by step, or --step N to run one.

#	Message	What happens
1	Refund question	Delivered; Claude Code reads the tickets and answers
2	Follow-up in the same thread	The same Claude session continues, so it remembers
3	"Ignore all previous instructions..."	Blocked by the scanners in about 1 ms; the AI judge never runs
4	Question containing a Stripe key	Key masked; the rest is delivered and answered
5	Injection hidden in base64	Decoded, then blocked
6	"Deploy the pricing page to production"	The scanners find nothing; the AI judge holds it as out of scope. Release or reject it in the console
7	Billing bot messages code-fixer	Blocked: the policy doesn't link them
8	Bug report that needs engineering	support-triage asks code-fixer through the relay, then answers; every hop is checked

With real Claude Code agents, steps 1, 2, 4 and 8 take about 15 to 40 seconds each (that's agent time). The AI judge adds 3.5 to 5 seconds per message.

To use your own Claude Code session as the billing bot, add the MCP server the demo prints:

claude mcp add a2a-demo -- node --disable-warning=ExperimentalWarning /path/to/A2A/packages/client/src/cli.ts --home /path/to/A2A/.demo/laptop-a mcp

CLI reference

a2a is the whole client (command line, background client and MCP server) in one file: plugin/bin/a2a.mjs. Rebuild it with pnpm build:plugin. Settings live in ~/.a2a/config.yaml, or in the folder named by A2A_HOME.

Get started
  a2a connect [invite-link] [--app ID ...] [--name NAME] [--no-install]
  a2a login | logout | apps

Setup by hand
  a2a join <invite-link> [--name NAME] [--runtime none|claude|codex|opencode] [--workdir DIR] [--force]
  a2a init --server URL [--name NAME]
  a2a agents add <address> [--runtime none|claude|codex|opencode|command] [--command "..."] [--workdir DIR]
                           [--allowed-tools Read,Grep] [--model NAME] [--instructions TEXT]
                           [--display-name NAME] [--description TEXT] [--admin-token T] [--default]
  a2a agents list
  a2a install [--load]

Running
  a2a start [--restart] | stop | run | info | runs
  a2a mcp [--tool APP | --agent ADDRESS]
  a2a hook [--tool APP]

Messaging
  a2a send <to> <text|-> [--from A] [--scope S] [--thread T] [--wait SECONDS] [--notify] [--json] [--attach FILE ...]
  a2a send <to> --voice [--language en] [--seconds N] [--yes]
  a2a transcribe <audio-file> [--language en] [--send <to>]
  a2a transcribe --live [--language en] [--seconds N]
  a2a reply <message-id> <text|->
  a2a status <message-id> | thread <thread-id> | inbox [--next --wait N] | directory
  a2a sessions | brief <session-id> <text|->

a2a send always waits for the guard's decision, and exits with code 2 if the message was blocked or rejected. Commands other than run, init, agents and install talk to the running background client over a local socket. That client holds the relay connection, the keys and the outbox.

The guard in detail

Stage	What it does
1 Envelope checks	Valid signature, registered and approved agents, a policy link for this sender, recipient and scope, rate limits, hop limit, message limit and repeated-content loops.
2 Normalize and scan	Normalizes Unicode, strips invisible and direction-changing characters, flags look-alike letters and decodes base64, hex and percent-encoded text. Then scans for secrets, card numbers, ID numbers, injection phrasing, credential requests, destructive commands and attempts to send data out.
3 AI judge (optional)	Gets the scope description, the recent thread, the scanner findings and the message (with secrets masked). It returns a checked, structured verdict.
4 Escalation	If the judge isn't confident enough, a stronger model decides. If that one isn't sure either, the message is held for a person.

The hosted relay runs stages 1 and 2 only (guard.judge: off). Choose a judge with guard.judge in the policy:

• anthropic uses the Anthropic API: claude-haiku-5-5, escalating to claude-sonnet-5-5.
• claude-cli runs claude -p with every tool, MCP server and customization turned off.
• auto (Node relay) picks the API if ANTHROPIC_API_KEY is set, then a signed-in claude CLI, then an offline heuristic judge.

Rules that always hold:

• The AI judge can only make a decision stricter than the pattern checks, never more lenient.
• The judge has no tools. If it errors, times out or returns something invalid, the message is held. The guard never lets a message through because something failed.
• Senders get only a short reason code (instruction_override, out_of_scope, ...), never the judge's reasoning, so they can't tune their wording against it. Senders with too many blocks in an hour are throttled.
• The recipient gets the cleaned, masked text. Every delivery is signed by the relay. When the guard changed nothing, it also carries the sender's own signature.

Evaluation

packages/guard/evals/cases.jsonl has 105 labelled messages: normal support and engineering traffic, secrets, injections (plain, encoded, invisible-character and look-alike versions), social engineering and out-of-scope requests.

pnpm eval

pnpm eval --judge claude-cli

Judge	Cases	Exactly right	Harmful delivered	Harmless held or blocked	Latency p50 / p95
Offline (patterns + heuristic)	89	89	0	0	under 1 ms
Claude CLI (Haiku, then Sonnet)	105	100	0	0	3.6 s / 4.8 s

The offline run skips the 16 cases that need judgment about scope or intent. All five AI-judge mismatches are "held instead of blocked" (or the reverse); none of those messages is delivered either way. pnpm eval fails if any harmful message is delivered, so it can gate CI.

Development

pnpm test

pnpm typecheck

node scripts/smoke-cloud.mjs [origin] runs the whole hosted flow against a running Worker (pnpm cloud:dev): two people sign up, one invites the other, connect signs in and joins with two apps, then messages, briefs, "shared with you", the size limit and delete for everyone.

pnpm test runs 61 tests. They cover:

• protocol and signing;
• guard stages and rules;
• relay policy (forgery, replay, links, hop, loop and rate limits, throttling, thread access);
• end-to-end runs with a real relay and two clients;
• sessions: sign-in, size limits, several apps per person, briefs, delete for everyone;
• one computer in several workspaces, and writing each AI app's MCP config;
• attachments and capsules;
• the OpenCode runtime;
• voice transcription against a stand-in Reson8 server.

packages/
  protocol/   message format, canonical JSON, Ed25519 signing, request auth
  guard/      policy, normalization, scanners, judges, pipeline, eval set
  server/     the relay: HTTP API, WebSocket delivery, SQLite storage, admin API (Node)
  cloud/      the Cloudflare Worker: website, accounts, workspaces, one Durable Object per relay
  client/     the a2a client: background client, runtimes, MCP server, CLI, service install
  sdk/        @a2a/sdk, a small TypeScript client
  web/        website, docs and dashboard (served by the Worker)
  console/    admin console for the Node relay (static, no build step)
plugin/       Claude Code plug-in: bundled client, a2a and capsule skills, hooks
examples/     policy, demo agents and workspaces
demo/         pnpm demo and pnpm demo:scenario
docs/         design plan (docs/plan.html)
test/         node:test suites

Known limitations

• The Codex runtime is untested. It's written against codex exec, but Codex wasn't installed on the build machine. The Claude Code, OpenCode, command and none runtimes are tested end to end.
• Workspaces connect through sessions. An agent reaches people in the same workspace or session; a computer joins other workspaces by joining their sessions (one connection each).
• App configs are edited, not managed. connect writes the a2a entry into each app's MCP settings. Files with comments (some VS Code setups) are left alone with a note to add it by hand.
• Antigravity, Cursor, Windsurf, VS Code and Gemini CLI were set up from their documented config locations and tested against those files, not with each app running.
• The Node relay has a single shared admin token. Accounts and Google sign-in exist only on the Cloudflare version. Both record admin actions, including every read of a message body, in the audit log.
• Password sign-ups don't verify email. Only Google sign-in counts as a verified identity.
• The offline heuristic judge is for testing and CI. Out-of-scope detection needs an AI judge.