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

The A2UI extension of the [A2A protocol](https://a2a-protocol.org):
extension URIs and their negotiation, and A2UI messages carried in A2A
parts.

Parts are the JSON objects of A2A's JSON-RPC binding:

    %{"kind" => "text", "text" => "Here is your form."}
    %{"kind" => "data", "data" => message, "metadata" => %{"mimeType" => "application/a2ui+json"}}

Each A2UI message travels in a data part of its own, the shape the
reference SDKs, sample agents and clients exchange. `a2ui_messages/1`
also reads a data part whose `data` is a list of messages, the shape
the extension specification describes.

`A2UIAgent.A2A.Server` answers A2A requests with these helpers, and
`A2UIAgent.A2A.Plug` serves them over HTTP.

# `part`
*since 0.1.0* 

```elixir
@type part() :: %{required(String.t()) => term()}
```

An A2A part, as a JSON object.

# `a2ui_messages`
*since 0.1.0* 

```elixir
@spec a2ui_messages([term()]) :: [map()]
```

The A2UI messages that `parts` carry, in order. A data part may hold one
message or a list of them.

The MIME type may also be a property of the part itself rather than of
its metadata, as some sample clients send it.

# `a2ui_part`
*since 0.1.0* 

```elixir
@spec a2ui_part(map() | [map()], String.t() | nil) :: part()
```

A data part holding `data` (an A2UI message, or a list of them), marked
with the MIME type of `version` (see `mime_type/1`).

# `a2ui_part?`
*since 0.1.0* 

```elixir
@spec a2ui_part?(term()) :: boolean()
```

Whether `part` is a data part marked as A2UI, with either MIME type in
its metadata.

# `activate`
*since 0.1.0* 

```elixir
@spec activate([String.t()], [String.t()]) :: {:ok, String.t(), String.t()} | :none
```

Activates the newest A2UI extension that is both requested and
advertised: `{:ok, uri, version}`, or `:none`.

# `advertised_extensions`
*since 0.1.0* 

```elixir
@spec advertised_extensions(map()) :: [String.t()]
```

The A2UI extension URIs an agent card advertises.

# `agent_extension`
*since 0.1.0* 

```elixir
@spec agent_extension(String.t(), keyword()) :: map()
```

The A2UI entry for an agent card's `capabilities.extensions`.

Options: `:accepts_inline_catalogs` (default `false`) and
`:supported_catalog_ids` (default `[]`). Each appears in `params` only
when it differs from its default, and `params` only when it is not
empty.

# `chunk_parts`
*since 0.1.0* 

```elixir
@spec chunk_parts(struct(), String.t(), String.t() | nil) ::
  {:ok, struct(), [part()]} | {:error, A2UICore.Error.t()}
```

Reads the next chunk of a streamed response with `parser` and returns
the A2A parts it completes, with the parser to read the next chunk.

# `extension_base_uri`
*since 0.1.0* 

```elixir
@spec extension_base_uri() :: String.t()
```

The URI every A2UI extension URI starts with.

# `extension_uri`
*since 0.1.0* 

```elixir
@spec extension_uri(String.t()) :: String.t()
```

The extension URI of a version, for example
`"https://a2ui.org/a2a-extension/a2ui/v1.0"` for `"1.0"` or `"v1.0"`.

# `extension_version`
*since 0.1.0* 

```elixir
@spec extension_version(String.t()) :: String.t() | nil
```

The version an A2UI extension URI names, or `nil` for any other URI.

# `mime_type`
*since 0.1.0* 

```elixir
@spec mime_type() :: String.t()
```

The MIME type that marks a data part as A2UI.

# `mime_type`
*since 0.1.0* 

```elixir
@spec mime_type(String.t() | nil) :: String.t()
```

The MIME type for parts of a protocol version: `"application/a2ui+json"`
from v0.9.1 on, the older `"application/json+a2ui"` before it and when
the version is unknown (`nil`).

# `requested_extensions`
*since 0.1.0* 

```elixir
@spec requested_extensions([term()]) :: [String.t()]
```

The A2UI extension URIs among `values`: extension URIs, or
comma-separated lists of them as the `X-A2A-Extensions` header carries.

# `response_parts`
*since 0.1.0* 

```elixir
@spec response_parts(struct(), String.t(), String.t() | nil, keyword()) :: [part()]
```

Parses a complete model response with `parser` (a format parser, see
`A2UIAgent.RequestProcessor.parser/1`) into A2A parts.

A response that does not parse is logged and yields no parts. Option:
`:fallback_text` — the text part to answer with when there are no
parts, for example the response itself.

# `select_newest`
*since 0.1.0* 

```elixir
@spec select_newest([String.t()], [String.t()]) :: String.t() | nil
```

The newest extension URI that is both requested and advertised, or
`nil`. Versions compare as SemVer, so `v1.10.0` is newer than `v1.2.0`.

# `text_part`
*since 0.1.0* 

```elixir
@spec text_part(String.t()) :: part()
```

A text part.

# `to_parts`
*since 0.1.0* 

```elixir
@spec to_parts([text: String.t(), a2ui: [map()]], String.t() | nil) :: [part()]
```

The A2A parts for parsed response parts (`{:text, text}` and
`{:a2ui, messages}`): a text part for each non-empty text and a data
part for each message.

---

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