[dbernheisel]

Summary

• Add the agent router macro and the Phantom.A2A.Agent behaviour. A router serves A2A agents and uses the same connect/2 for MCP and A2A.
• Add Phantom.A2A.Plug. It serves the JSON-RPC binding and the HTTP+JSON binding, agent cards, extended cards, and SSE streams through PubSub.
• Resolve agents at runtime from routes with path params, such as ":org/:agent_key". Static agents match first. A static agent path followed by one segment gives the tenant.
• Add push notifications. Phantom.A2A.Push checks each webhook URL against private networks and connects to the address that it checked. Phantom.A2A.Push.Delivery sends the events of a task to each webhook in order, with retries. A maximum of 100 events wait for each webhook.
• Add Phantom.A2A.Client (optional :req) for calls to other agents, and list_agents/2.
• Add Phantom.A2A.Bridge. It serves the MCP tools of a router as an A2A agent and changes MCP tasks into A2A tasks.
• Add the A2A guide (guides/a2a.md), a README section, telemetry spans, and the conformance tests for the server, the client, and the bridge.
• Deferred: run Router.call_tool/4 in a supervised task, so that late tool replies do not stay in the HTTP process. Add demand control to Client.stream_message/3. Send 401 instead of -32007 when an anonymous client asks for an extended card.

Evidence

Phantom.A2A.Plug runs in Bandit at /a2a. Phantom.A2A.Client calls it over HTTP. The router has an echo agent and a bridge for one MCP tool, add.

iex

iex> {:ok, client} = Client.new("http://127.0.0.1:4099/a2a/echo/agent-card.json")
iex> {client.binding, client.url, client.card.name}
{:jsonrpc, "http://127.0.0.1:4099/a2a/echo", "Echo"}

iex> Client.send_message(client, "hello")
{:ok,
 %Phantom.A2A.Message{
   message_id: "01a19cc4-00d3-734f-9892-b645808248fc",
   role: :agent,
   context_id: "PNA46Re8WPFEWDEPcG1NM8Zc1Z7GAVky",
   parts: [%Phantom.A2A.Part{text: "echo: hello", ...}],
   ...
 }}

iex> {:ok, tools} = Client.new("http://127.0.0.1:4099/a2a/tools/agent-card.json")
iex> Enum.map(tools.card.skills, & &1.id)
["add"]

iex> Client.send_message(tools, Message.user([Part.data(%{"tool" => "add", "arguments" => %{"a" => 2, "b" => 40}})]))
{:ok,
 %Phantom.A2A.Message{
   role: :agent,
   parts: [%Phantom.A2A.Part{text: "42", ...}],
   ...
 }}

iex> Client.send_message(tools, Message.user([Part.data(%{"tool" => "add", "arguments" => %{"a" => "two"}})]))
{:error, %Phantom.A2A.Error{code: -32602, message: "Invalid Params"}}

Configuration: the router option a2a: [push_retry_backoff: [...]] sets the retry delays in milliseconds. The default is 1, 5, and 30 seconds. a2a: [allow_private_push_urls: true] permits private webhook addresses. The default is false.