Agent UI Protocol

Summary

agent-ui@1 is the experimental frontend protocol for Agent-driven UI. The Agent never returns executable frontend code. It invokes trusted opencode tools; the service maps those tool calls to UIEnvelope payloads; the frontend validates and renders known components, charts, and map actions.

SSE Event

event: ui_envelope
data: {
  "session_id": "session-id",
  "envelope_id": "env-id",
  "created_at": 1710000000000,
  "envelope": {}
}

Envelope Types

type UISurface = "chat_inline" | "side_panel" | "canvas" | "map_overlay";

type UIEnvelope =
  | {
      kind: "registered_component";
      schemaVersion: "agent-ui@1";
      component: string;
      surface: UISurface;
      props: unknown;
      data?: unknown;
      fallbackText?: string;
    }
  | {
      kind: "chart";
      schemaVersion: "agent-ui@1";
      grammar: "echarts-safe-subset";
      surface: "chat_inline" | "side_panel" | "canvas";
      spec: unknown;
      data: unknown;
      fallbackText?: string;
    }
  | {
      kind: "map_action";
      schemaVersion: "agent-ui@1";
      action: string;
      surface: "map_overlay";
      params: unknown;
      fallbackText?: string;
    };

Registry

GET /api/v1/agent/chat/ui-registry

The registry returns the allowed chart grammar, registered components, and map actions. Unknown components/actions should be rejected by the frontend.

Initial mappings:

show_chart -> chart
locate_features -> map_action
zoom_to_map -> map_action
render_junctions -> map_action
apply_layer_style -> map_action
view_history -> registered_component: HistoryPanel
view_scada -> registered_component: ScadaPanel

render_junctions accepts only a render_ref. The frontend must resolve the full payload through:

GET /api/v1/agent/chat/render-ref/:render_ref?session_id=:session_id

State Persistence

Assistant messages may contain:

uiEnvelopes?: Array<{
  envelopeId: string;
  createdAt: number;
  envelope: UIEnvelope;
  renderStatus: "pending" | "rendered" | "fallback" | "error";
  error?: string;
}>;

tool_call and artifacts remain deprecated compatibility/debug surfaces. New frontends should consume ui_envelope and uiEnvelopes.

2.3 KiB Raw Blame History