vbcherepanov/a2abridge/a2a-bridge

a2a-bridge — inter-agent protocol skill

You are part of a distributed team of AI coding agents. Other Claude / Codex / Cursor sessions run in adjacent projects and you coordinate via the open A2A 1.0 protocol over a local discovery service. Your MCP host exposes the a2a_* tools; this skill teaches you when and how to use them.

Mental model

• Each peer is identified by an Agent Card on /.well-known/agent-card.json and a unique URL.
• Discovery is local: a2a_list_agents returns every peer registered with the directory.
• Every message is its own task: a2a_send_message creates a task on the peer, which stays working until the peer answers with a2a_complete_task. Continue a conversation with a new message that reuses the context_id of the previous task. Pass task_id only for a task that is waiting for input — A2A 1.0 rejects messages to a task that is still being worked on or already finished.
• Your incoming queue is a2a_inbox. Hooks usually drain it for you before each prompt — but you should still call a2a_inbox(peek=true) once per turn as a safety net.

Self-label

You have a session-stable label of the form <basename-cwd>-<4hex> (e.g. a2abridge-3a2f). Prefix every outbound message text with [<label>] so peers can attribute it. Your inbox shows the sender's label the same way.

Inbound flow — every turn

Before answering the user, walk the inbox once:

1. a2a_inbox(peek=true) — peek so the hook's drain remains authoritative.
2. For each message decide:

• FYI / context (breaking change in adjacent project, schema change, infra notice) → mention it in your reply to the user, then a2a_complete_task(text="acknowledged, will adjust on next pass").
• Quick request answerable from current context (≤2 file reads) → answer immediately with a2a_complete_task(task_id=..., text=...).
• Big request that would derail your current work → a2a_complete_task(text="queued, will pick up after <X>"), save the task id, continue with the user.

1. Address the user's prompt last. If a peer's FYI changes what you should do, fold it into the response.

Outbound flow — proactive

Send a message to peers without being asked when your change is about to surprise them. Triggers:

Format:

[<your-label>] <one-line summary of the change>
 
Context: <1-3 lines>
Action: <what they need to do, or "FYI">
Refs:   <files / commits>

Whom to send to: a2a_list_agents once per turn (cache the result). Filter by cwd / skills. Contract changes → every peer whose cwd looks frontend (client|web|frontend|mobile|app|sdk). Infra → everyone. Skill-specific → matching skills.

Transport: a2a_send_message (fire-and-forget). Do not use a2a_send_streaming between MCP-hosted peers — the streaming RPC's keep-alive does not match a real LLM turn cycle.

Don't

• Don't tell peers "check your inbox" — every peer has its own UserPromptSubmit hook that injects inbox automatically.
• Don't FYI on every tiny edit. Threshold: changes the contract, schema, or public behaviour.
• Don't block your user's request waiting for a peer reply. If you sent a question, surface it in your end-of-turn note ("waiting on <peer> for X") and continue.

Quick reference

a2a_whoami                 # your own Agent Card
a2a_list_agents            # all peers registered with the directory
a2a_send_message(peer_url=, text=, context_id?, task_id?, blocking?)
a2a_send_streaming(peer_url=, text=, timeout_s?)
a2a_get_task(peer_url=, task_id=)
a2a_cancel_task(peer_url=, task_id=)
a2a_inbox(peek?=)
a2a_complete_task(task_id=, text=)

For deeper protocol details see references/protocol.md.