Plug for serving A2A agents over HTTP.

Handles agent card discovery (GET), JSON-RPC dispatch (POST), and SSE streaming. Works standalone with Bandit or mounted inside Phoenix via forward.

Usage

# In a Phoenix router:
forward "/a2a", A2A.Plug, agent: MyAgent, base_url: "http://localhost:4000/a2a"

# Standalone with Bandit:
Bandit.start_link(plug: {A2A.Plug, agent: MyAgent, base_url: "http://localhost:4000"})

Options

• :agent — GenServer name or pid of the agent (required)
• :base_url — the public URL of the agent endpoint. Required unless always provided at runtime via put_base_url/2. When nil, agent card requests raise ArgumentError.
• :agent_card_path — path segments for the agent card endpoint (default: [".well-known", "agent-card.json"]). Set to false to disable built-in agent card serving — useful when you want to serve the card from a custom route using A2A.get_agent_card/2.
• :json_rpc_path — path segments for the JSON-RPC endpoint (default: [])
• :agent_card_opts — keyword options forwarded to A2A.JSON.encode_agent_card/2
• :metadata — static metadata merged into every JSON-RPC call (default: %{}). Useful for deployment-level metadata like %{"env" => "prod"}. Overridden per-request by put_metadata/2.

Per-Request Overrides

Use put_base_url/2 and put_metadata/2 in an upstream plug or Phoenix pipeline to set per-request values. These are stored in conn.private[:a2a] following the Ash/Absinthe convention.

plug :set_tenant_a2a

defp set_tenant_a2a(conn, _opts) do
  conn
  |> A2A.Plug.put_base_url("https://#{conn.host}/a2a")
  |> A2A.Plug.put_metadata(%{"tenant_id" => conn.assigns.tenant_id})
end

Metadata Merge Order

Metadata is merged in three layers (later wins):

1. :metadata from init/1 (static defaults)
2. put_metadata/2 on conn (per-request)
3. "metadata" from JSON-RPC params (per-call from client)