Getting Started with AUP
Build agent-driven UIs in three steps: define a node tree, bind data, handle events — no framework, no build step, no CSS.
Overview
AUP (Agentic UI Protocol) lets AI agents build user interfaces by composing a tree of semantic nodes. The runtime renders the tree, handles user interactions, and manages live data updates — no framework, no build step, no CSS required.
This guide walks you through three steps to build your first AUP interface:
1. Define
Compose a node tree from 18 cross-platform primitives. Each node has an id, type, and optional props and children.
2. Bind
Connect nodes to live data via src (read-only), bind (read-write), or state (client-local). Data changes propagate to the UI automatically.
3. Interact
Wire up events so user actions trigger server-side execution, client-side patches, or page navigation — all declarative, no imperative code.
Define a Node Tree
Every AUP interface starts as a tree of nodes. The root is typically a view container, with children that form the UI hierarchy. Each node has an id, a type, and optional props — that’s it.
Node Schema (7 core fields)
Only id and type are required. Everything else is optional:
| Field | Type | Description |
|---|---|---|
id | string | Unique node identifier. Must be unique across the entire tree. |
type | string | Primitive name: view, text, media, input, action, overlay, table, chart, map, calendar, time, chat, etc. |
props | object | Primitive-specific attributes. Each type has its own props schema. |
children | array | Child nodes. Containable types: view, overlay, chat, deck, ticker, frame. |
src | string | AFS path for read-only data binding. Client reads on mount and subscribes for live updates. |
bind | string | AFS path for read-write data binding. Value changes are written back to this path. |
events | object | Event bindings. Keys: click, change, send, sort, select, confirm, cancel, dismiss. |
Layout with view
The view type is the layout engine. Its layout prop controls how children are arranged:
columnVertical stack (default). Children flow top to bottom.rowHorizontal flow. Children sit side by side.gridResponsive auto-fill grid. Adapts to available width.stackLayered children. Each child occupies the same space.Add "mode": "card" for a card appearance with surface background and border. Combine layout directions with modes to build dashboards, forms, or any layout.
Live Demo: Dashboard
This dashboard is built entirely from AUP nodes — view containers with row/column layouts, text headings, chart visualizations, and table data, all composed into a single tree:
Bind Data
AUP nodes connect to data through three mechanisms. Both src and bind use AFS paths — the same path-based interface that agents use to access any data source (databases, APIs, files, IoT devices).
srcServer → ClientOne-way data flow. The client reads the AFS path on mount and subscribes for live updates. Ideal for charts, tables, maps — any display that reflects backend data. When the data changes on the server, the UI updates in real-time.
bindServer ↔ ClientTwo-way sync for input nodes. The input reads its initial value from the AFS path, and writes changes back when the user types. Other nodes reading the same path update in real time.
stateClient onlyFor transient state that doesn’t need persistence — whether an overlay is open, a toggle’s current value, or draft text. Maintained client-side with no server round-trip.
How Data Flows
src or bind pathsLive Demo: Contact Form
This form demonstrates bound inputs. Each field uses AUP’s input primitive with validation and submit handling — inputs write back to AFS paths on change:
Handle Events
When users interact with AUP nodes, events flow through the protocol. AUP supports three dispatch modes — each one is declarative, defined right in the node’s events field:
Server-Side Exec
Calls an AFS exec action on the server. The agent receives the event and can respond with aup_patch operations to update the UI — create, update, remove, or reorder nodes.
Client-Side Patch
Directly patches another node without a server round-trip. Use $args.* placeholders to pass event data into the target’s new properties. Perfect for filtering, toggling, or updating sibling nodes.
Page Navigation
Navigate to a named page by targeting _root with a page value. The session resolves the page tree and applies the new style from the app’s page resolver.
Event Lifecycle
aup_event with nodeId, event, dataaup_patch operations (create, update, remove, reorder)Supported Events (8)
| Event | Description |
|---|---|
click | Fired by action buttons |
change | Fired by input fields; carries the new value |
send | Fired by chat input |
sort | Fired by table header click |
select | Fired by table row click or overlay choice |
confirm | Fired by overlay confirm button |
cancel | Fired by overlay cancel button |
dismiss | Fired by overlay toast dismiss |
Live Demo: Interactive Portal
This portal combines all three dispatch modes — buttons trigger exec actions, selections update sibling nodes via target+set, and navigation links switch pages:
Core Primitives
AUP provides 18 cross-platform primitives that cover every UI pattern — from simple text to real-time video. Each primitive has a typed props schema and renders natively on every supported platform:
viewtextmediainputactionoverlaytablechartmapcalendartimechatsurfaceexplorereditorcanvasrtcafs-listSee the Primitives Reference for complete documentation with props schemas and rendered demos.
Next Steps
You now know the three building blocks of AUP: node trees, data binding, and event handling. Explore further: