ai-elements-genui/dev.ai.elements.genui.a2ui

Package-level declarations

Types

object A2ui

A2UI protocol constants.

data class A2uiAction(val surfaceId: String, val name: String, val sourceComponentId: String, val context: JsonObject, val userMessage: String? = null, val timestamp: String = Instant.now().toString(), val dataModel: JsonElement? = null)

A user action on a surface, as the A2UI renderer-to-agent action message (toMessage).

A2uiCatalog

@Immutable

class A2uiCatalog(val id: String, val components: Map<String, A2uiComponent>, val functions: Map<String, A2uiFunction>, val protocolVersion: String = A2ui.VERSION)

A component catalog (A2UI §"The component catalog"): the component types and functions a surface may use, rendered natively. Basic is the A2UI Basic Catalog; extend adds or replaces components and functions — your design system's components, under your own catalog id.

A2uiComponent

fun interface A2uiComponent

Renders one component type of a catalog.

A2uiDataError

class A2uiDataError(message: String) : RuntimeException

A data model write that cannot apply (e.g. through a primitive value).

A2uiEffects

fun interface A2uiEffects

Side effects functions may ask the host for (only openUrl in the Basic Catalog).

A2uiExpressionError

class A2uiExpressionError(message: String) : RuntimeException

An expression that cannot be evaluated (unknown function, disallowed URL…).

A2uiFunction

class A2uiFunction(val callableByAgent: Boolean = false, val agentOnly: Boolean = false, val invoke: (args: JsonObject, context: DataContext?) -> JsonElement?)

A catalog function. invoke gets resolved args (formatString gets them raw, to interpolate itself) and the calling scope (null when the agent calls it via callRendererFunction).

A2uiParseError

class A2uiParseError(message: String) : RuntimeException

A formatString template that does not parse.

A2uiState

@Stable

class A2uiState(val catalog: A2uiCatalog = A2uiCatalog.Basic, catalogs: List<A2uiCatalog> = emptyList())

The renderer side of an A2UI session: feed it agent-to-renderer messages (process), render its surfaces with A2uiSurfaceView. Messages it must answer (function responses, errors) come back from process as renderer-to-agent messages for the transport to send.

A2uiSurface

@Stable

class A2uiSurface

One A2UI surface: its components (an adjacency list keyed by id; root mounts first) and its data model. Both are Compose state, so a surface re-renders as messages arrive and as inputs write through two-way bindings.

BasicComponents

object BasicComponents

The A2UI Basic Catalog in Material 3, per the basic catalog implementation guide: invisible containers add no spacing, leaves and outlined containers carry a uniform LeafMargin, colours come from the theme (LocalContentColor), cards are outlined so nesting stays readable.

BasicFunctions

object BasicFunctions

The Basic Catalog's renderer-side functions (A2UI v1.0 basic catalog implementation guide).

ChildRef

@Immutable

class ChildRef

A child to place: its component and the data scope it renders in.

ComponentScope

@Stable

class ComponentScope

What a component renderer sees: its properties resolved in its data scope, its children, two-way binding writes and action dispatch.

DataContext

class DataContext

Where a component evaluates its dynamic values (A2UI "evaluation scope"): absolute paths resolve from the surface's data model; relative paths from base, the item a list template is rendering (at index). Resolves Dynamic* values: literals, {"path": …} bindings and {"call": …} function calls, including formatString ${…} interpolation.

Functions

a2uiRenderer

fun a2uiRenderer(catalog: A2uiCatalog = A2uiCatalog.Basic, catalogs: List<A2uiCatalog> = emptyList(), capacity: Int = 32, onAction: (A2uiAction) -> Unit): DataRenderer

Renders the chat's A2UI parts (DataPart.A2UI, whatever transport brought them) natively. Register it with AiElementsRenderers(data = mapOf(DataPart.A2UI to a2uiRenderer { chat.send(it) })).

A2uiSurfaceView

@Composable

fun A2uiSurfaceView(surface: A2uiSurface, modifier: Modifier = Modifier, catalog: A2uiCatalog = A2uiCatalog.Basic, onAction: (A2uiAction) -> Unit = {}, catalogs: List<A2uiCatalog> = emptyList())

Renders an A2UI surface natively with catalog (default: the Basic Catalog); nothing until its root component arrives. onAction receives the user's actions as renderer-to-agent messages (A2uiAction.toMessage) for the transport to send back; links open through LocalUriHandler.

send

fun ChatController.send(action: A2uiAction): Boolean

Send a user's A2UI action to the agent, as a user turn the transports map onto their A2UI binding (AG-UI forwardedProps.a2uiAction, an A2A application/a2ui+json part, an AI SDK data-a2ui part). Its text is the action's userMessage, else its name.

toDataParts

fun A2uiAction.toDataParts(): List<DataPart>

This action as the data parts of a user turn: the A2UI action message (DataPart.A2UI) and, when the surface asked for it, its data model (DataPart.A2UI_DATA_MODEL).