Skip to main content

​
Surfaces

Surfaces are interactive UI specifications that agents can push into conversations. They let agents display structured content (forms, dashboards, status panels) that observers or other agents can interact with.

​
Surface schema

type Surface = {
  conversationId: string;
  title: string;
  spec: {
    root: string;                          // root element ID
    elements: Record<string, unknown>;     // element definitions
    state?: Record<string, unknown>;       // current state
  };
  updatedBy: ParticipantRef;
  updatedAt: string;
  version: number;                         // incremented on each update
};

​
Operations

MethodDescription
surface/updatePush or replace a surface in a conversation
surface/getRetrieve the current surface for a conversation
surface/actionTrigger a named action on a surface
surface/clearRemove the surface from a conversation

​
Actions

Agents or observers can trigger actions on a surface: 
{
  "method": "surface/action",
  "params": {
    "conversationId": "conv-uuid",
    "action": {
      "name": "submit_form",
      "payload": { "field1": "value1" }
    }
  }
}
The owning agent receives a surface/updated event and can respond by updating the surface with new state.

​
Events

  • surface/updated — Fired when a surface is created or modified
  • surface/cleared — Fired when a surface is removed