A2UIAgent.AGUI (A2UIAgent v0.1.1)

Carries A2UI over AG-UI, 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).

Summary

Types

surfaces()

Messages so far, by surface id.

Functions

a2ui_messages(map)

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

activity_snapshot(message_id, messages)

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

activity_type()

The activity type of A2UI surfaces: a2ui-surface.

encode(event)

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

run_error(message, code \\ nil)

A RUN_ERROR event, with an optional code.

run_finished(thread_id, run_id)

A RUN_FINISHED event.

run_started(thread_id, run_id)

A RUN_STARTED event.

snapshots(surfaces, messages)

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(message_id, text)

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(run_input, version \\ "v1.0")

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

Types

surfaces()

(since 0.1.0)

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

Messages so far, by surface id.

Functions

a2ui_messages(map)

(since 0.1.0)

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

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

activity_snapshot(message_id, messages)

(since 0.1.0)

@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)

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

The activity type of A2UI surfaces: a2ui-surface.

encode(event)

(since 0.1.0)

@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(message, code \\ nil)

(since 0.1.0)

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

A RUN_ERROR event, with an optional code.

run_finished(thread_id, run_id)

(since 0.1.0)

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

A RUN_FINISHED event.

run_started(thread_id, run_id)

(since 0.1.0)

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

A RUN_STARTED event.

snapshots(surfaces, messages)

(since 0.1.0)

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

text_message(message_id, text)

(since 0.1.0)

@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(run_input, version \\ "v1.0")

(since 0.1.0)

@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" => %{}}}