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

Carries A2UI over [AG-UI](https://docs.ag-ui.com), the event protocol
between agents and their front ends, the way AG-UI's A2UI middleware
and the renderers built on it (CopilotKit, assistant-ui) do. A2UI does
not define this binding itself.

A surface travels as `ACTIVITY_SNAPSHOT` events of the activity type
`a2ui-surface`, whose content holds the surface's A2UI messages under
`a2ui_operations`. A snapshot replaces the activity it names, so each
one carries every message of its surface so far; `snapshots/2` keeps
them per surface:

    {events, surfaces} = A2UIAgent.AGUI.snapshots(%{}, messages)
    Enum.map(events, &A2UIAgent.AGUI.encode/1)

A user's action starts a new run with no new user message; it arrives
in the run's input, under `forwardedProps.a2uiAction.userAction`, which
`user_action/2` reads.

AG-UI carries no renderer capabilities: the agent writes for the
catalogs it is configured with (`A2UIAgent.Generator.create_processor/3`
with `nil` capabilities activates them all).

# `surfaces`
*since 0.1.0* 

```elixir
@type surfaces() :: %{optional(String.t()) => [map()]}
```

Messages so far, by surface id.

# `a2ui_messages`
*since 0.1.0* 

```elixir
@spec a2ui_messages(map()) :: [map()] | nil
```

The A2UI messages of an event: those of an `a2ui-surface` activity
snapshot, else `nil`.

# `activity_snapshot`
*since 0.1.0* 

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

An `ACTIVITY_SNAPSHOT` event holding `messages`, the whole state of
the activity `message_id`.

    iex> A2UIAgent.AGUI.activity_snapshot("a2ui-surface-s1", [])
    %{
      "type" => "ACTIVITY_SNAPSHOT",
      "messageId" => "a2ui-surface-s1",
      "activityType" => "a2ui-surface",
      "content" => %{"a2ui_operations" => []},
      "replace" => true
    }

# `activity_type`
*since 0.1.0* 

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

The activity type of A2UI surfaces: `a2ui-surface`.

# `encode`
*since 0.1.0* 

```elixir
@spec encode(map()) :: iodata()
```

An event as AG-UI's HTTP binding sends it: one server-sent event whose
data is the event's JSON.

# `run_error`
*since 0.1.0* 

```elixir
@spec run_error(String.t(), String.t() | nil) :: map()
```

A `RUN_ERROR` event, with an optional code.

# `run_finished`
*since 0.1.0* 

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

A `RUN_FINISHED` event.

# `run_started`
*since 0.1.0* 

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

A `RUN_STARTED` event.

# `snapshots`
*since 0.1.0* 

```elixir
@spec snapshots(surfaces(), [map()]) :: {[map()], surfaces()}
```

Adds `messages` to `surfaces` and returns a snapshot for each surface
they touch, in the order first touched, with the activity id
`a2ui-surface-<surfaceId>`. A surface whose messages end with its
`deleteSurface` is dropped after its snapshot, so that it starts over
if it is created again. Messages that name no surface are left out.

# `text_message`
*since 0.1.0* 

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

The events of an assistant message with `text`: `TEXT_MESSAGE_START`,
`TEXT_MESSAGE_CONTENT` and `TEXT_MESSAGE_END`. Empty text has no
events, since a content event needs a non-empty delta.

# `user_action`
*since 0.1.0* 

```elixir
@spec user_action(map(), String.t()) :: map() | nil
```

The user action a run's input carries, as an A2UI `action` message of
`version`, or `nil` when the run was started otherwise.

    iex> A2UIAgent.AGUI.user_action(%{"forwardedProps" => %{"a2uiAction" => %{"userAction" =>
    ...>   %{"name" => "book", "surfaceId" => "s", "context" => %{}}}}})
    %{"version" => "v1.0", "action" => %{"name" => "book", "surfaceId" => "s", "context" => %{}}}

---

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