a2ui-core/dev.ynagai.a2ui.core.protocol

Package-level declarations

Types

A2uiFormatException

class A2uiFormatException(message: String, cause: Throwable? = null) : SerializationException

Thrown when a payload is well-formed JSON but does not describe a valid A2UI structure.

A2uiJson

object A2uiJson

The Json configurations this library parses and emits A2UI payloads with.

AccessibilityAttributes

@Serializable

data class AccessibilityAttributes(val label: DynamicString? = null, val description: DynamicString? = null, val live: LiveRegion? = null, val hidden: DynamicBoolean? = null)

Attributes that describe an element to assistive technology.

Action

@Serializable(with = ActionSerializer::class)

sealed interface Action

An interaction handler: either dispatch an event to the agent, or run a function locally.

ActionEvent

@Serializable

data class ActionEvent(val name: String, val userMessage: DynamicString? = null, val context: Map<String, DynamicValue>? = null)

The event an Action.Event dispatches to the agent.

ActionMessage

@Serializable(with = ActionMessageSerializer::class)

data class ActionMessage(val name: String, val surfaceId: String, val sourceComponentId: ComponentId, val timestamp: String, val context: JsonObject, val userMessage: String? = null, val metadata: Metadata? = null, val additional: Map<String, JsonElement> = emptyMap()) : RendererToAgentMessage

Reports a user-initiated action back to the agent.

AgentCapabilities

@Serializable(with = AgentCapabilitiesSerializer::class)

data class AgentCapabilities(val v1: AgentCapabilitiesV1, val otherVersions: Map<String, JsonElement> = emptyMap())

What an agent can generate, advertised to renderers.

AgentCapabilitiesV1

@Serializable(with = AgentCapabilitiesV1Serializer::class)

data class AgentCapabilitiesV1(val supportedCatalogIds: List<String>? = null, val acceptsInlineCatalogs: Boolean? = null, val additional: Map<String, JsonElement> = emptyMap())

The v1.0 half of AgentCapabilities.

AgentFunctionResponseMessage

@Serializable(with = AgentFunctionResponseMessageSerializer::class)

data class AgentFunctionResponseMessage(val response: FunctionResponse) : AgentToRendererMessage

The agent's response to a callAgentFunction the renderer sent.

AgentToRendererMessage

@Serializable(with = AgentToRendererMessageSerializer::class)

sealed interface AgentToRendererMessage

A message from the agent to the renderer.

AllowedCallers

@Serializable

enum AllowedCallers : Enum<AllowedCallers>

Which side of the connection may invoke a catalog function.

BoundValue

@Serializable(with = BoundValueSerializer::class)

sealed interface BoundValue : DynamicValue, DynamicString, DynamicNumber, DynamicBoolean, DynamicStringList

A value resolved against the surface at render time rather than carried literally on the wire: either a DataBinding into the data model or a FunctionCall.

CallAgentFunctionMessage

@Serializable

data class CallAgentFunctionMessage(val surfaceId: String, val functionCallId: CallId, val callFunction: FunctionCall) : RendererToAgentMessage

Asks the agent to run a function remotely on the renderer's behalf.

CallId

typealias CallId = String

The identifier of a single function invocation, echoed back on its response.

CallRendererFunctionMessage

@Serializable

data class CallRendererFunctionMessage(val functionCallId: CallId, val callFunction: FunctionCall) : AgentToRendererMessage

Asks the renderer to run a function locally on the agent's behalf.

CatalogDefinition

@Serializable(with = CatalogDefinitionSerializer::class)

data class CatalogDefinition(val catalogId: String, val protocolVersion: String? = null, val title: String? = null, val description: String? = null, val instructions: String? = null, val components: Map<String, ComponentDefinition> = emptyMap(), val functions: Map<String, FunctionDefinition> = emptyMap(), val schemaKeywords: Map<String, JsonElement> = emptyMap())

A collection of component and function definitions that a surface renders against.

Checkable

@Serializable

data class Checkable(val checks: List<CheckRule>? = null)

The checks mixin that catalog schemas fold into input components.

CheckRule

@Serializable

data class CheckRule(val condition: BoundValue, val message: String? = null)

One validation check on an input component. condition evaluates to a ValidationResult.

Child

typealias Child = ComponentId

A reference to one child component, by id.

ChildList

@Serializable(with = ChildListSerializer::class)

sealed interface ChildList

The children of a container: either a fixed list of ids, or a template expanded once per item of a list in the data model.

Component

@Serializable(with = ComponentSerializer::class)

data class Component(val id: ComponentId, val component: String, val catalogId: String? = null, val accessibility: AccessibilityAttributes? = null, val metadata: Metadata? = null, val properties: Map<String, JsonElement> = emptyMap())

One component of a surface: the envelope properties every component has, plus the properties its catalog defines.

ComponentDefinition

@Serializable(with = ComponentDefinitionSerializer::class)

data class ComponentDefinition(val schema: JsonObject, val allowedParents: List<String>? = null, val allowedChildren: List<String>? = null, val metadata: Metadata? = null)

A catalog's definition of one component: a JSON Schema for its properties, plus the two keywords that constrain where it may sit in the tree.

ComponentId

typealias ComponentId = String

The identifier of a component, unique within its surface.

CreateSurfaceMessage

@Serializable

data class CreateSurfaceMessage(val surfaceId: String, val catalogId: String? = null, val sendDataModel: Boolean? = null, val components: List<Component>? = null, val dataModel: JsonObject? = null, val metadata: SurfaceMetadata? = null) : AgentToRendererMessage

Creates a surface and begins rendering it.

DataBinding

@Serializable

data class DataBinding(val path: String) : BoundValue

A JSON Pointer into the surface's data model.

DeleteSurfaceMessage

@Serializable

data class DeleteSurfaceMessage(val surfaceId: String) : AgentToRendererMessage

Deletes a live surface.

DynamicBoolean

@Serializable(with = DynamicBooleanSerializer::class)

sealed interface DynamicBoolean

A boolean, a DataBinding, or a FunctionCall.

DynamicNumber

@Serializable(with = DynamicNumberSerializer::class)

sealed interface DynamicNumber

A number, a DataBinding, or a FunctionCall.

DynamicString

@Serializable(with = DynamicStringSerializer::class)

sealed interface DynamicString

A string, a DataBinding, or a FunctionCall.

DynamicStringList

@Serializable(with = DynamicStringListSerializer::class)

sealed interface DynamicStringList

An array of strings, a DataBinding, or a FunctionCall.

DynamicValue

@Serializable(with = DynamicValueSerializer::class)

sealed interface DynamicValue

A value that may be a literal of any JSON type, a DataBinding, or a FunctionCall.

Extensions

typealias Extensions = Map<String, JsonElement>

Vendor extension metadata.

FunctionCall

@Serializable

data class FunctionCall(val call: String, val catalogId: String? = null, val args: Map<String, JsonElement>? = null) : BoundValue

An invocation of a catalog function, or of the @index system function.

FunctionCallValidationSchema

data class FunctionCallValidationSchema(val raw: JsonObject)

The JSON Schema a catalog gives for one function's wire-level FunctionCall.

FunctionDefinition

@Serializable(with = FunctionDefinitionSerializer::class)

data class FunctionDefinition(val schema: FunctionCallValidationSchema, val returnType: ReturnType, val allowedCallers: AllowedCallers? = null, val requiresUserActivation: Boolean? = null)

A catalog's definition of one function.

FunctionError

@Serializable

data class FunctionError(val code: String, val message: String)

The failure half of a FunctionResponse.

FunctionResponse

@Serializable(with = FunctionResponseSerializer::class)

sealed interface FunctionResponse

The response to a callRendererFunction or callAgentFunction invocation.

LiveRegion

@Serializable

enum LiveRegion : Enum<LiveRegion>

How assistive technology should announce updates to an element (WAI-ARIA aria-live).

Metadata

@Serializable

data class Metadata(val extensions: Extensions? = null)

The metadata envelope carried by surfaces, components, catalogs, and renderer actions.

RendererCapabilities

@Serializable(with = RendererCapabilitiesSerializer::class)

data class RendererCapabilities(val v1: RendererCapabilitiesV1, val otherVersions: Map<String, JsonElement> = emptyMap())

What a renderer can render, sent to the agent alongside its messages.

RendererCapabilitiesV1

@Serializable(with = RendererCapabilitiesV1Serializer::class)

data class RendererCapabilitiesV1(val supportedCatalogIds: List<String>, val inlineCatalogs: List<CatalogDefinition>? = null, val additional: Map<String, JsonElement> = emptyMap())

The v1.0 half of RendererCapabilities.

RendererDataModel

@Serializable(with = RendererDataModelSerializer::class)

data class RendererDataModel(val version: String = A2ui.PROTOCOL_VERSION, val surfaces: Map<String, JsonObject>)

The data models of every live surface, for synchronising them back to the agent.

RendererErrorMessage

@Serializable(with = RendererErrorMessageSerializer::class)

sealed interface RendererErrorMessage : RendererToAgentMessage

A renderer-side error.

RendererFunctionResponseMessage

@Serializable(with = RendererFunctionResponseMessageSerializer::class)

data class RendererFunctionResponseMessage(val response: FunctionResponse) : RendererToAgentMessage

The renderer's response to a callRendererFunction the agent sent.

RendererToAgentMessage

@Serializable(with = RendererToAgentMessageSerializer::class)

sealed interface RendererToAgentMessage

A message from the renderer to the agent.

ReturnType

@Serializable

enum ReturnType : Enum<ReturnType>

What a catalog function hands back to its caller.

Severity

@Serializable

enum Severity : Enum<Severity>

How severely a failed check should be reported.

Surface

object Surface

The reserved canonical container component that every surface is implicitly rooted in.

SurfaceMetadata

@Serializable

data class SurfaceMetadata(val extensions: Extensions? = null)

Surface-level metadata on a createSurface message.

UpdateComponentsMessage

@Serializable

data class UpdateComponentsMessage(val surfaceId: String, val components: List<Component>) : AgentToRendererMessage

Replaces or extends the component tree of a live surface.

UpdateDataModelMessage

@Serializable

data class UpdateDataModelMessage(val surfaceId: String, val path: String? = null, val value: JsonElement) : AgentToRendererMessage

Writes value into a live surface's data model.

ValidationErrorCode

@Serializable

enum ValidationErrorCode : Enum<ValidationErrorCode>

The three reserved codes that select the structured error shape.

ValidationResult

@Serializable(with = ValidationResultSerializer::class)

data class ValidationResult(val valid: Boolean, val code: String? = null, val message: String? = null, val severity: Severity? = null, val additional: Map<String, JsonElement> = emptyMap())

What a check's condition evaluates to.