a2ui

The a2ui surface (Agent-to-UI) allows a machine to render itself as an interactive component inside a host application. Where the page surface serves a full web page and a2a exchanges structured data between agents, a2ui bridges the gap: it provides a component contract that a host application can embed, with typed props and governed updates.

Overview

A2UI is for machines that need to appear inside another application’s interface rather than on their own page. A dashboard widget, an inline approval form, a status indicator, or an embedded search panel are all A2UI use cases. The machine declares which component it renders, what props it provides, and how it handles user interactions. The host application mounts the component and receives governed updates.

Syntax

expresses
  a2ui
    component: "order_status_card"
    props: ["order_id", "status", "last_updated"]

A complete machine with an A2UI surface:

machine order_status_widget

  accepts
    order_id as text, is required

  responds with
    status as text
    last_updated as text
    items as list

  ensures
    permissions
      allowed to
        reason, http

  implements
    ask fetch, from: "@mashin/actions/http/get"
      url: "https://api.internal.com/orders/${input.order_id}"
      returns
        status as text
        last_updated as text
        items as list
      assuming
        status: "shipped"
        last_updated: "2 hours ago"
        items: [{name: "Widget A", qty: 2}]

  expresses
    a2ui
      component: "order_status_card"
      props: ["order_id", "status", "last_updated", "items"]

Configuration options

Config	Required	Default	Description
component	Yes	-	Component name used by the host application to mount the widget
props	No	All responds with fields	List of output fields exposed as component props

Component naming

The component name is a contract between the machine and the host application. The host application uses this name to look up the rendering template. Mashin provides default renderers for common patterns (cards, tables, forms), and host applications can register custom renderers.

Props

When props is specified, only those fields from the machine’s output are passed to the component. This allows a machine to compute more than it exposes, keeping the component interface focused. When props is omitted, all fields from responds with are passed.

Embedding

Host applications embed A2UI components using the mashin client SDK. The SDK handles invoking the machine with inputs, rendering the component with the returned props, subscribing to updates (if the machine also has a websocket surface), and forwarding user interactions back to the machine.

Governance

Every A2UI render and interaction is governed:

1. The host application authenticates with the cell
2. Inputs are validated against the machine’s accepts contract
3. Governance permissions from ensures are checked
4. The machine executes
5. A SurfaceAccess event is recorded with :a2ui surface in the behavioral ledger
6. Props are returned to the component

User interactions within the component (button clicks, form submissions) trigger new machine invocations, each individually governed and recorded.

Example

A machine with both A2UI and API surfaces:

machine approval_widget

  accepts
    request_id as text, is required

  responds with
    title as text
    status as text
    can_approve as boolean

  implements
    ask fetch, from: "@mashin/actions/http/get"
      url: "https://api.internal.com/approvals/${input.request_id}"
      returns
        title as text
        status as text
        can_approve as boolean
      assuming
        title: "Deploy to production"
        status: "pending"
        can_approve: true

  expresses
    a2ui
      component: "approval_card"
      props: ["title", "status", "can_approve"]
    api
      path: "/api/approvals"
      method: "GET"
      authentication: "bearer_token"

The A2UI surface provides an embeddable card; the API surface provides programmatic access. Same machine, same governance.

For live updates, combine A2UI with a websocket surface on the same machine. The component mounts with the initial value and updates in real time via the WebSocket.

See also

• expresses - Parent section for all surfaces
• page - Full web page surface (Kanvas)
• a2a - Agent-to-Agent protocol surface
• websocket - WebSocket surface (for live A2UI updates)