# `A2A.Plug`
[🔗](https://github.com/actioncard/a2a-elixir/blob/main/lib/a2a/plug.ex#L2)

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)

# `get_base_url`

```elixir
@spec get_base_url(Plug.Conn.t()) :: String.t() | nil
```

Returns the per-request base URL, or `nil` if not set.

# `get_metadata`

```elixir
@spec get_metadata(Plug.Conn.t()) :: map() | nil
```

Returns the per-request metadata, or `nil` if not set.

# `put_base_url`

```elixir
@spec put_base_url(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Stores a per-request base URL in `conn.private[:a2a]`.

Use this in an upstream plug or Phoenix pipeline to override the
`base_url` configured at init time.

# `put_metadata`

```elixir
@spec put_metadata(Plug.Conn.t(), map()) :: Plug.Conn.t()
```

Stores per-request metadata in `conn.private[:a2a]`.

This metadata is merged between the init-time `:metadata` and the
per-call JSON-RPC `"metadata"` field.

---

*Consult [api-reference.md](api-reference.md) for complete listing*