Skip to main content

Guides

Composed UI

Composed UI is the interface an agent composes for a person, drawn natively, with consent. When an agent shows a person something, a recipe card, an order to confirm or a summary to act on, it composes it as data in Ouro's composed tree, and Ouro HX draws it. The tree is interface as validated data: each node names one of Ouro HX's components, every prop is checked against the catalog, and every button is one of your app's declared actions, pressed with that action's consent.validate A sender can't relabel a button, loosen its consent or add a component the catalog lacks: the validator refuses the tree and says which node and why.forged

The tree is Ouro's own. MCP Apps and A2UI are formats it speaks, not formats it depends on: an agent can send the tree itself, or send A2UI messages that the A2UI adapter turns into the same tree.formats

What a tree is

{
  "id": "card",
  "component": "Card",
  "props": {},
  "children": [
    { "id": "title", "component": "Heading", "props": { "text": "Lemon orzo", "level": 1 }, "children": [] },
    { "id": "time", "component": "DescriptionList", "props": { "items": [{ "term": "Time", "detail": "25 min" }] }, "children": [] },
    {
      "id": "save",
      "component": "ActionButton",
      "props": { "action": "save_recipe", "label": "Save recipe", "consent": "write", "press": "run", "input": { "recipe": "rcp_lemon_orzo" }, "emphasis": "primary" },
      "children": []
    }
  ]
}

The components are Ouro HX's: Card, Stack, Heading, Text, Image, Badge, List, DescriptionList, Separator and Alert, the fields TextField, Checkbox and Select, plus ActionButton when your catalog has actions.componentsfield-components A component joins the catalog only when web and Apple both draw it and a conformance case covers it.joins

What a button does

An ActionButton names one of your actions and the input the agent prepared. Its label, consent class and what pressing it does come from your action's declaration, never from the agent (the one action model):button

  • read and write run when the person presses.run
  • consequential asks the person to confirm, on a sheet that shows each value the agent prepared under the field's own label, and runs only once they do.confirm
  • person-only takes the person to your app's own screen; it carries no input and sends nothing.handoff

A press says the person made it (by: "person").by-person An agent never presses a button through the screen: it calls the action through its own door, its MCP tool or CLI command, and a person-only action answers it with a typed refusal.agent-press

What a field does

A TextField, Checkbox or Select asks the person for an answer. Its value is a JSON pointer, such as /servings, into a data model that travels beside the tree: structuredContent.ouro.data in an MCP tool result, or the surface's data model in A2UI. The field starts with what the data holds there and writes the person's answer back: a number field writes a number, a checkbox true or false, and a select the chosen option's text.fields

An ActionButton input bound to the same path, {"@path": "/servings"}, sends what the person entered when they press, and a consequential button's confirm sheet shows it before anything runs. A field writes only the data model: nothing runs until the person presses a button.bound

Updating a card

An agent changes a card it already showed by sending only what changed, not the whole tree. In Ouro's tree, an MCP tool result carries structuredContent.ouro.update (core's mcpAppTreeUpdateResult): each of its nodes replaces the tree's node with the same id, children and all, and each of its data entries sets the data model at a JSON pointer, with null deleting the value.update An update is all or nothing: an id the tree lacks, an id that a template's instances share, a pointer that names an object's prototype or a node that would relabel a button is refused, and nothing in it applies.update-refused OuroMcpApp then shows the same short alert as a tree that fails the checks, and tells the agent why.update-refused

In A2UI, the same changes are updateComponents and updateDataModel messages: A2UISurface draws them when you pass it the longer list of messages.a2ui-update Either way, what the person entered stays, except where the update changed the value, or the list item it is in: there the agent's value wins.keeps

How a tree reaches the screen

The tree, from your own code or server
Web: ComposedSurface
Apple: ComposedSurface, from ComposedTree (1.1.0)apple-tree
Windows: OuroComposedSurface
OuroComposedSurface
The tree, in an MCP tool result's structuredContent.ouro
Web: OuroMcpApp, inside any MCP Apps host
Apple: ComposedTree (1.1.0), then ComposedSurfaceapple-tree
Windows: OuroComposedSurface, from OuroComposedResult.From
OuroComposedSurface, from OuroComposed.read
An update to the card it shows, in structuredContent.ouro.update
Web: OuroMcpAppupdate
Apple: ComposedSurface(results:catalog:) (1.2.0)apple-update
Windows: OuroComposedSurface (v0.3.0), or its Updatewindows-update
OuroComposedState (v0.3.0), with receive or updateandroid-update
A2UI messages
Web: A2UISurface
Apple: OuroA2UI, which draws the tree with ComposedSurface
Windows: Not read: send the tree
Not read: send the tree

Each draws the same tree with the same components and the same consent.draws Core holds the tree, its validator and the adapters (ouro-composed.mts, ouro-mcp-app.mts, ouro-a2ui.mts), which your app vendors from a core release; core's guide says how, and how to generate your catalog from your actions.vendor

Which platforms draw it

Every kit draws the tree natively: web and Apple, and Windows and Android with OuroComposedSurface, which read the tree itself rather than A2UI messages.kits Every renderer passes the same conformance cases from core, so a card looks and behaves alike wherever it is drawn.platforms

Ouro's kits are written in their platforms' own toolkits: React on the web, SwiftUI on Apple, WinUI 3 on Windows and Compose on Android.native There is no Flutter, React Native or other cross-platform kit, on purpose: agents now write each platform's native app, so sharing one implementation no longer pays for the compromise in how it feels.native

Claim sources