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

Current agent-ui@1 support is intentionally limited to three trusted shapes:

registered_component for frontend-registered business panels.
chart for the echarts-safe-subset chart grammar.
map_action for the WebGIS map adapter.

The Agent must not return executable JS, JSX, HTML, CSS, or arbitrary component source. The frontend renders only allowlisted components, chart specs, and map actions.

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.

map_action is a WebGIS-specific extension, not a general command channel. It is valid only on map_overlay; every action and parameter set must be validated by the frontend before it can affect MapLibre state. Invalid map actions should fall back to fallbackText.

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

view_history parameters must include start_time and end_time ISO8601 timestamps with start_time < end_time. When the Agent needs historical monitoring values for analysis or a chart, it should call query_monitoring_readings first, then use view_history only to open the frontend panel.

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.

3.2 KiB Raw Blame History