Behaviour for A2A v1.0 protocol extensions.

An extension module advertises a URI in its declaration/1, optionally participates in per-request activation via activate/3, and can hook into the request/response pipeline via handle_request/3 and handle_response/3. Configured on A2A.Plug and A2A.Client as a list of module() or {module(), keyword()} tuples.

See the A2A v1.0 extensions topic for protocol-level semantics. This module implements the data-only and profile extension categories; method extensions (registering new RPC methods) and state-machine extensions are not yet supported.

Defining an extension

defmodule MyApp.TimestampExtension do
  @behaviour A2A.Extension
  @uri "https://example.com/ext/timestamp"

  @impl true
  def declaration(_state) do
    %A2A.AgentExtension{uri: @uri, description: "Adds request timestamps"}
  end

  @impl true
  def activate(_requested_uris, _ctx, _state) do
    {:ok, System.system_time(:millisecond)}
  end

  @impl true
  def handle_response(task, _params, started_at) do
    {:ok, A2A.Extension.put_metadata(task, __MODULE__, %{started_at: started_at}),
     started_at}
  end
end

Activation model

At Plug/Client init time each configured extension's init/1 is called with its opts; the returned state is kept alongside the module. Per request, the server parses the A2A-Extensions header and for each configured extension whose declared URI is in the requested set, calls activate/3 with the requested URI list, the request context, and the init state. activate/3 may return {:ok, activation} to participate, :skip to opt out for this request, or {:error, error} to abort with a JSON-RPC error. The list of activated URIs is echoed in the response A2A-Extensions header.

Required extensions (required: true in declaration/1) that are not declared in the client's request header trigger ExtensionSupportRequiredError (-32008) before activation runs.

Hooks

Activated extensions can mutate the request or response:

• handle_request/3 — receives the decoded message, JSON-RPC params, and the extension's activation. Runs in declaration order before the request is dispatched to the agent.
• handle_response/3 — receives the task, JSON-RPC params, and the activation. Runs in declaration order after the agent replies and before the task is encoded.

Both callbacks are optional; data-only extensions implement neither.

Reading activations inside an agent

Activations are surfaced to the agent's handle_message/2 as context.extensions, a %{uri => activation} map. The A2A.Extension.fetch/2 and A2A.Extension.activated?/2 helpers look up by module rather than URI string.

def handle_message(message, context) do
  case A2A.Extension.fetch(context, MyApp.TimestampExtension) do
    {:ok, started_at} -> use_timestamp(message, started_at)
    :error -> handle_without(message)
  end
end

Configuring extensions

Server side, pass :extensions to A2A.Plug. The configured declarations are merged into capabilities.extensions on the served agent card, and the negotiation pipeline runs around every JSON-RPC dispatch.

# Standalone with Bandit
Bandit.start_link(
  plug: {A2A.Plug,
    agent: MyAgent,
    base_url: "http://localhost:4000",
    extensions: [A2A.Extension.Timestamp, {MyApp.Passport, issuer: "acme"}]}
)

# Or in a Phoenix router
forward "/a2a", A2A.Plug,
  agent: MyAgent,
  base_url: "http://localhost:4000/a2a",
  extensions: [A2A.Extension.Timestamp]

Client side, pass :extensions to A2A.Client.new/2. The configured URIs are sent in the A2A-Extensions request header on every call. A2A.Client.parse_extensions_header/1 and A2A.Client.activated/2 read the server's response header to discover which extensions actually ran.

client = A2A.Client.new("http://localhost:4000",
  extensions: [A2A.Extension.Timestamp])

{:ok, task} = A2A.Client.send_message(client, "hi")
task.metadata[A2A.Extension.Timestamp.uri()]
#=> %{"received_at" => ..., "completed_at" => ...}

Reference

A2A.Extension.Timestamp ships in-tree as a complete profile-extension example covering declaration/1, activate/3, handle_request/3, and handle_response/3. See examples/extensions.exs for an end-to-end runnable demo.