# `A2UIAgent.A2A.Server`
[🔗](https://github.com/a2ui-elixir/a2ui/blob/v0.1.1/umbrella/apps/a2ui_agent/lib/a2ui_agent/a2a/server.ex#L1)

Answers the A2A JSON-RPC methods `message/send` and `message/stream`
for an agent that writes A2UI.

    case A2UIAgent.A2A.Server.handle(body, &MyAgent.run/1, generator: generator) do
      {:reply, response, extensions} -> # send the response as JSON
      {:stream, events, extensions} -> # send each event as a server-sent event
    end

`extensions` lists the extension URIs activated for the request, for
the `X-A2A-Extensions` response header. `A2UIAgent.A2A.Plug` does all
of this over HTTP.

## The agent

The agent is a function of an `A2UIAgent.A2A.Request`, or a module
implementing `A2UIAgent.A2A.Agent`. It returns:

  * `{:ok, output}` or `{:ok, output, state}` — the model's response,
    as a string or an enumerable of streamed chunks, and the state the
    task ends in (`"input-required"` unless the `:final_state` option
    says otherwise);
  * `{:error, reason}` — the task fails, with `reason` as its status
    message.

## Requests and answers

The server reads the message into an `A2UIAgent.A2A.Request` and
negotiates catalogs for the renderer. Given a generator and renderer
capabilities (from the message metadata, else the
`:default_capabilities` option), the request carries an
`A2UIAgent.RequestProcessor`: the agent gives its prompt to the model,
and its parser reads the model's output into a text part for each run
of text and an A2UI data part for each message. Without a processor
the output is answered as text. Capabilities that name none of the
agent's catalogs fail the task.

`message/send` answers with the finished task, whose status message
holds every part. A response that does not parse is answered as text.
`message/stream` answers with a stream of JSON-RPC responses: the
task (`submitted`), a `working` status update for each chunk that
completes parts, and a final status update. A stream that stops
parsing fails the task. A format that reads a response only once it
is complete (`A2UIAgent.Express`) answers with one `working` update
at the end of the stream, holding every part.

## Options

  * `:generator` — an `A2UIAgent.Generator`, or a list of them (one per
    protocol version, in order of preference; the first that
    negotiates wins).
  * `:default_capabilities` — the capabilities to negotiate when the
    message carries none.
  * `:extensions` — the extension URIs the client requested in the
    `X-A2A-Extensions` header.
  * `:advertised` — the A2UI extension URIs the agent advertises
    (`A2UIAgent.A2A.advertised_extensions/1` of its agent card).
  * `:final_state` — the state a task ends in (default
    `"input-required"`).
  * `:id_generator` — a zero-arity function that returns new task,
    context and message ids (default: random UUIDs).
  * `:clock` — a zero-arity function that returns the ISO 8601
    timestamp of a task status (default: the current time).

# `agent`
*since 0.1.0* 

```elixir
@type agent() :: (A2UIAgent.A2A.Request.t() -> agent_result()) | module()
```

An agent: a function of the request, or an `A2UIAgent.A2A.Agent` module.

# `agent_result`
*since 0.1.0* 

```elixir
@type agent_result() ::
  {:ok, String.t() | Enumerable.t()}
  | {:ok, String.t() | Enumerable.t(), String.t()}
  | {:error, term()}
```

What an agent returns for a request.

# `error_response`
*since 0.1.0* 

```elixir
@spec error_response(term(), integer(), String.t()) :: map()
```

A JSON-RPC error response.

# `handle`
*since 0.1.0* 

```elixir
@spec handle(term(), agent(), keyword()) ::
  {:reply, map(), [String.t()]} | {:stream, Enumerable.t(), [String.t()]}
```

Answers a decoded JSON-RPC request body.

A body that is not a JSON-RPC 2.0 request, names another method or has
no `params.message` object gets a JSON-RPC error response (codes
-32600, -32601 and -32602).

---

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