A2UI System Architecture
The A2UI system bridges the gap between raw agent output and interactive React components. It uses a JSON-based document format that can be updated incrementally via patches.A2UI Document Model
AnA2uiDocument consists of a surface identifier and a collection of components apps/web/src/a2ui/renderer.tsx#24-26. Supported components include:
- Text & Markdown: For formatted narrative output apps/web/src/a2ui/renderer.tsx#68-73.
- Lists & Tables: For structured data presentation apps/web/src/a2ui/renderer.tsx#74-89.
- Forms: For capturing user input (checkboxes, selects, text, numbers) apps/web/src/a2ui/renderer.tsx#90-91.
- Charts: For data visualization apps/web/src/a2ui/renderer.tsx#93.
Data Flow: Agent to UI
The following diagram illustrates how an agent’s intent is transformed into a rendered React component in theapps/web environment.
A2UI Rendering Pipeline
Sources: apps/web/src/a2ui/renderer.tsx#33-59, apps/web/src/a2ui/tests/renderer.snapshot.test.tsx#8-12
Form Handling and State
TheA2uiForm component manages its own internal state using useState to track values for various A2uiFormField types apps/web/src/a2ui/renderer.tsx#130-135. When a user submits the form, it packages the data into an A2uiFormSubmitEvent containing the componentId and the current values apps/web/src/a2ui/renderer.tsx#148-154.
Workspace Patch System
The Workspace Patch system provides a fail-closed mechanism for agents to modify files within the user’s workspace. It is designed to prevent directory traversal and enforce strict resource limits.Safety & Resource Limits
All patch operations are governed byWorkspacePatchLimits, which are enforced before any filesystem mutation occurs crates/palyra-common/src/workspace_patch.rs#19-21.
| Limit | Default Value | Description |
|---|---|---|
max_patch_bytes | 256 KB | Maximum size of the incoming patch string crates/palyra-common/src/workspace_patch.rs#33. |
max_files_touched | 64 | Maximum number of unique files a single patch can modify crates/palyra-common/src/workspace_patch.rs#34. |
max_file_bytes | 2 MB | Maximum size allowed for any single file after patching crates/palyra-common/src/workspace_patch.rs#35. |
max_preview_bytes | 16 KB | Limit for the redacted preview returned in outcomes crates/palyra-common/src/workspace_patch.rs#36. |
Execution Flow & Rollback
Theapply_workspace_patch function follows a “Plan-then-Execute” pattern crates/palyra-common/src/workspace_patch.rs#207-211:
- Parsing: The patch string is parsed into
PatchOperationvariants (Add, Update, Delete) crates/palyra-common/src/workspace_patch.rs#159-163. - Validation: Paths are checked against
workspace_rootsto prevent traversal (e.g., using..) crates/palyra-common/src/workspace_patch.rs#113-116. - Planning: A
PatchPlanis generated, calculating SHA256 hashes of files before modification crates/palyra-common/src/workspace_patch.rs#184-187. - Atomic Execution: Files are written. If an error occurs, the system attempts a best-effort rollback crates/palyra-common/src/workspace_patch.rs#136-137.
Redaction Policy
To prevent leaking sensitive information in logs or UI previews, the system applies aWorkspacePatchRedactionPolicy crates/palyra-common/src/workspace_patch.rs#44-48.
- Pattern Redaction: Strings matching keywords like
api_key,secret, orpasswordare masked crates/palyra-common/src/workspace_patch.rs#14-15. - File Markers: Files like
.env,.pem, orid_rsatrigger aggressive redaction crates/palyra-common/src/workspace_patch.rs#16-17.
Integration with Tools
Thepalyra.process.run tool utilizes the ProcessRunnerToolInput structure to execute commands within the workspace crates/palyra-common/src/process_runner_input.rs#7-17. This integration ensures that even low-level process execution follows the same security and pathing constraints as the patch system.
Input Parsing
Theparse_process_runner_tool_input function enforces a strict JSON schema, rejecting any unknown fields to prevent “argument injection” style attacks crates/palyra-common/src/process_runner_input.rs#26-31.
Sources:
crates/palyra-common/src/workspace_patch.rsapps/web/src/a2ui/renderer.tsxcrates/palyra-common/src/process_runner_input.rsfuzz/fuzz_targets/workspace_patch_parser.rs