Skip to main content
The Agent-to-User Interface (A2UI) is a specialized subsystem within Palyra designed to allow agents to drive rich, interactive user interfaces in the Web Console. Unlike static markdown responses, A2UI enables agents to construct and update complex UI components—such as forms, tables, and charts—using an incremental patching protocol based on RFC 6902 (JSON Patch).

​
Protocol and Data Structures

A2UI operates on a versioned document model where the state is managed as a JsonValue and modified via PatchOperation sequences.

​
PatchDocument and Operations

A PatchDocument is a collection of operations that describe mutations to the current UI state. It follows a strict schema to ensure compatibility and security.
TypeDescription
PatchDocumentThe root container for a patch, containing a version v and an array of ops. apps/web/src/a2ui/types.ts#65-68
PatchOperationA single mutation: add, remove, or replace. apps/web/src/a2ui/types.ts#76-80
PatchOperationKindLiteral string types: `“add""remove""replace”`. apps/web/src/a2ui/types.ts#70

​
JSON Pointer Implementation

The system implements a custom JSON Pointer resolver to navigate the document tree. It supports standard / delimiters and the - token for appending to arrays. Sources: apps/web/src/a2ui/types.ts#65-80, apps/web/src/a2ui/patch.ts#1-255

​
A2UI Rendering Engine

The A2uiRenderer is a React component that transforms a PatchDocument into a functional interface. It acts as the “Canvas” where agent-driven components are mounted.

​
Component Mapping

The renderer dispatches to specific UI components based on the type field in the component definition:

​
Data Flow: Agent to Renderer

The following diagram illustrates how an agent’s intent is transformed into a DOM update via the A2UI pipeline. A2UI Update Pipeline Sources: apps/web/src/a2ui/renderer.tsx#33-97, apps/web/src/a2ui/patch.ts#47-89, apps/web/src/a2ui/normalize.ts#1-10

​
Canvas State Management

The “Canvas” represents the persistent state of the A2UI document for a given session.
  1. Initial State: The canvas starts with a baseline document, often generated by createDemoDocument or fetched from the daemon. apps/web/src/a2ui/sample.ts#1-20
  2. State Accumulation: As patches arrive via the RunStream, the client applies them to the current state using applyPatchDocument. apps/web/src/a2ui/patch.ts#47-52
  3. Form Submission: When a user interacts with an A2uiForm, the onFormSubmit callback packages the values into an A2uiFormSubmitEvent, which is sent back to the agent as a tool response. apps/web/src/a2ui/renderer.tsx#148-154
Sources: apps/web/src/a2ui/renderer.tsx#125-177, apps/web/src/a2ui/patch.ts#47-89

​
Security and Sanitization

Because A2UI allows an LLM to drive the UI, strict security measures are implemented to prevent prototype pollution and Cross-Site Scripting (XSS).

​
Prototype Pollution Protection

The patch applier explicitly forbids tokens that could be used to modify the JavaScript object prototype.

​
Resource Budgeting

To prevent Denial of Service (DoS) via complex patches, the system enforces a PatchProcessingBudget.

​
Content Security Policy (CSP)

The Web Console enforces a strict CSP that prevents inline scripts and limits resource loading to 'self'. apps/web/index.html#9-11 Security Verification Logic Sources: apps/web/src/a2ui/patch.ts#16-16, apps/web/src/a2ui/patch.ts#78-84, apps/web/src/a2ui/tests/patch.security.test.tsx#8-31, apps/web/index.html#9-11

​
Layout and Styling

A2UI components use a specialized CSS layer to ensure they fit within the Console’s grid system. Sources: apps/web/src/styles.css#140-153