A2A (plugin)
Status: supported via plugin as a direct-message channel for agent-to-agent dialogue using the A2A 1.0 JSON-RPC protocol. Two WednesdayAI gateways (or any A2A 1.0 agent) can hold isolated, per-item conversations. Text only.Plugin required
A2A ships as a bundled plugin. The gateway enables it at startup oncechannels.a2a is
configured; to enable it explicitly:
Quick setup
A2A connects gateways, so a working setup involves two sides. The example below uses two gateways namedastro and tardis on one Tailscale tailnet; both hosts run the
WednesdayAI gateway and each configures the other as a peer.
- Put both hosts on one tailnet (or any private network with TLS). Do not expose the A2A route publicly; see Security.
- Expose the gateway with Tailscale Serve (HTTPS in front of the local gateway), or bind
the gateway to the tailnet interface with
gateway.bind: "tailnet". - Generate one bearer token per direction on each side:
openssl rand -hex 32. Store them as env vars, for exampleA2A_TARDIS_TOKENandA2A_ASTRO_TOKEN. - Configure
channels.a2aon both gateways.astrosends totardiswithpeers.tardis.url;tardissends back withpeers.astro.url. - Restart the gateway once to load the plugin. Later changes under
channels.a2ahot-reload the channel, so token rotation does not need a restart.
astro (~/.openclaw/openclaw.json):
tardis with a peer named astro (token: "${A2A_ASTRO_TOKEN}",
url: "https://astro.<tailnet>.ts.net/a2a/v1", outboundToken: "${A2A_TARDIS_TOKEN}").
Routes served by each gateway:
POST /a2a/v1— JSON-RPC (SendMessage,GetTask, plus A2A 0.3 dotted aliases such asmessage/send).GET /.well-known/agent-card.jsonandGET /.well-known/agent.json— unauthenticated agent card listing agent ids only.
Configuration reference
There is a single default account; no
accounts map.
Session isolation
Each inbound message gets a session key built from the peer name and the A2AcontextId
(dm scope per-account-channel-peer). Two peers never share a session, and the same peer
with two contextIds gets two sessions, including ids that differ only in case. Messages
for one item run one after another, so each gets its own reply. A message send to
<peer>:<contextId> is recorded in the same item session as the replies.
Peer text is command-inert: messages starting with / are rejected
(TASK_STATE_REJECTED), and slash commands, ! bash, inline directives and reset/abort
words inside a message are never executed, even when commands.allowFrom allows every
sender.
Routing a peer to an agent
Without a binding, peer traffic goes to the default agent. Bind a peer explicitly:<peer> and the contextId, with <peer> as the
parent peer, so a binding on the bare peer name matches every context of that peer.
Handler choice per peer:
- Bound to a restricted agent (recommended, for example
sdm):- Peer text runs only with that agent’s tools and workspace. Give it read access to
docs, memory search and the
messagetool, and noexec. - Escalations go through that agent’s own channel binding (for example a Discord
#factory-querieschannel or a Telegram topic). A human answers there, and the agent relays withmessagetoa2a:<peer>:<ctx>. - Blast radius if the peer is compromised: that agent’s tools only.
- Cost: the bound agent does not see
main’s private memory unless memory is shared.
- Peer text runs only with that agent’s tools and workspace. Give it read access to
docs, memory search and the
- Unbound (the default agent catches it):
- Best context, and the human replies in their normal DM.
- But every peer message runs with the default agent’s full toolset (including
exec), and its workload gains a new untrusted input. Choose this only if the default agent is already tool-restricted.
Item dialogues and the contextId convention
One A2AcontextId per item gives one isolated session per item on each gateway. Targets
are <peer>[:<contextId>]; omitting the context uses default.
For ticket-driven workflows use factory.<repo>.<issue>, for example
tardis:factory.WednesdayAI-core.1234. The factory can then hold one thread of dialogue
per issue and the session history stays scoped to that item.
Reply forwarding and loop cap
- Default (
replyDelivery: "task"): the reply is returned to the caller as the JSON-RPC task result. Nothing is forwarded. - With
replyDelivery: "message": final replies are also sent back to the peer automatically (the peer needs aurl). Each forwarded reply carries a hop counter in thewednesdayai.hopmetadata; forwarding stops oncesession.agentToAgent.maxPingPongTurns(default5, max5) is reached, and an empty reply (NO_REPLY) ends the exchange. Failed forwards are logged and the task stays completed.
Security
- Tailnet only. Run the A2A route on a private network (WireGuard tailnet or
equivalent) with Tailscale Serve in front of the gateway, or
gateway.bind: "tailnet". Never expose/a2a/v1through Tailscale Funnel or any public proxy. - Per-peer tokens in both directions.
peers.<name>.tokenauthenticates inbound requests from that peer;peers.<name>.outboundTokenauthenticates this gateway to the peer. Tokens are compared constant-time (hashed, all peers checked) and invalid tokens return401. Changingchannels.a2arestarts only the A2A channel, so rotating a token needs no gateway restart; tasks still running at that moment fail. - Rate limiting. Requests are rate-limited per peer (
rateLimitPerMinute, default 30,0disables). - No commands. Peer text never runs commands, bash, directives or reset/abort
triggers, regardless of
commands.allowFrom. - Bounded egress. Outbound requests are SSRF-guarded and pinned to the peer url host; redirects are not followed. The bound agent’s toolset is the blast radius of a compromised peer.
- The agent card endpoint is unauthenticated by design and lists agent ids only.
- Requests are capped: 1 MiB body (
413), 64 KiB text per message (longer text is truncated with a marker), and batches of at most 30. At most 500 tasks are kept; finished tasks are evicted oldest first, and when 500 are still running, newSendMessagecalls fail with-32000“Task capacity reached”.
Limitations
- Text only; no media or file parts.
- No streaming, push notifications, or task cancellation; push-config methods fail with
-32003and cancel with-32004. - Tasks live in memory: a gateway restart fails in-flight tasks (
TASK_STATE_FAILED). - HMAC request signing is not implemented; bearer tokens over an encrypted tailnet are the current auth model.
- A run that fails locally (for example a missing provider key) fails the task
(
TASK_STATE_FAILED, “Agent run failed”); the local error text is never sent to the peer.
Factory example
A factory gateway (tardis) asks a production gateway (astro) when a unit blocks, and
resumes on the relayed answer.
On astro (answers, bound to the tool-restricted sdm agent):
tardis (asks, bound to the factory agent):