Skip to main content
The A2UI (Agent-to-UI) subsystem is a specialized rendering engine within the Palyra Web Console that allows agents to push dynamic, interactive UI surfaces into the chat transcript. Instead of being limited to plain text or Markdown, agents can use A2UI to present structured data via tables, charts, and functional forms.

​
System Architecture

The A2UI lifecycle begins with an agent generating a JSON payload containing an A2uiDocument or a PatchDocument. The frontend receives these updates, applies security sanitization, processes any incremental patches, and renders the final state using a set of React components.

​
Natural Language to Code Entity Mapping

The following diagram maps high-level UI concepts to the specific code entities that implement them. UI Component Mapping Sources: apps/web/src/a2ui/renderer.tsx#90-93, apps/web/src/a2ui/patch.ts#47-52, apps/web/src/a2ui/types.ts#4-11

​
JSON Patch Application

A2UI supports incremental updates via a versioned JSON Patch implementation (v1). This allows agents to modify existing UI surfaces (e.g., updating a progress bar or adding a row to a table) without re-sending the entire document.

​
Patch Processing Pipeline

The applyPatchDocument function apps/web/src/a2ui/patch.ts#47-89 executes the following steps:
  1. Validation: Ensures the patch uses version v: 1 and contains at least one operation apps/web/src/a2ui/patch.ts#53-58.
  2. Budget Check: Validates that the number of operations and path lengths are within the DEFAULT_PATCH_BUDGET to prevent DoS attacks apps/web/src/a2ui/patch.ts#59-64.
  3. Cloning: Creates a deep clone of the current state using cloneJsonValue to maintain immutability apps/web/src/a2ui/patch.ts#66.
  4. Sequential Application: Iterates through ops (add, replace, remove) and resolves JSON pointers to target containers apps/web/src/a2ui/patch.ts#69-86.

​
Security Sanitization

Security is enforced at the patch level to prevent Prototype Pollution. Sources: apps/web/src/a2ui/patch.ts#16-16, apps/web/src/a2ui/patch.ts#245-251, apps/web/src/a2ui/renderer.tsx#73-73, apps/web/src/a2ui/tests/patch.security.test.tsx#9-30

​
Renderer Implementation

The A2uiRenderer component apps/web/src/a2ui/renderer.tsx#33-59 acts as the entry point for the UI surface. It iterates over the components array in an A2uiDocument and renders the appropriate React component based on the type field.

​
Component Types

TypeReact ImplementationDescription
textComponentBodyRenders plain text with optional semantic tone (e.g., success, error) apps/web/src/a2ui/renderer.tsx#68-71.
markdownSanitizedMarkdownRenders safe HTML from Markdown strings apps/web/src/a2ui/renderer.tsx#72-73.
tableA2uiTableUses EntityTable to display sortable, structured data apps/web/src/a2ui/renderer.tsx#99-123.
formA2uiFormRenders interactive inputs (text, select, checkbox, number) apps/web/src/a2ui/renderer.tsx#130-177.
chartA2uiBarChartVisualizes numeric series as bar charts apps/web/src/a2ui/renderer.tsx#92-93.

​
Form Interaction and Data Flow

When an agent renders a form, the A2uiForm component manages local state for all fields. Upon submission, it triggers the onFormSubmit callback, which packages the values into an A2uiFormSubmitEvent to be sent back to the agent. A2UI Form Data Flow Sources: apps/web/src/a2ui/renderer.tsx#148-154, apps/web/src/a2ui/renderer.tsx#157-175, apps/web/src/a2ui/patch.ts#47-52

​
Testing and Quality Assurance

A2UI employs two primary testing strategies to ensure stability and security.

​
Snapshot Tests

The A2uiRenderer is verified using snapshot-style tests in renderer.snapshot.test.tsx. These tests:

​
Security Regression Tests

The patch.security.test.tsx file contains a suite of “bad patches” designed to test the robustness of the pointer resolution logic against prototype pollution apps/web/src/a2ui/tests/patch.security.test.tsx#9-30. Sources: apps/web/src/a2ui/tests/renderer.snapshot.test.tsx#11-51, apps/web/src/a2ui/tests/patch.security.test.tsx#8-31