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.

There are currently no Agent tool mappings for charts, components, or map actions. The protocol types remain documented for compatibility and future allowlisted actions.

Historical monitoring values for analysis come from the project source/ directory.

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.7 KiB Raw Permalink Blame History