103 lines
2.7 KiB
Markdown
103 lines
2.7 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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.
|
|
|
|
```ts
|
|
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
|
|
|
|
```text
|
|
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:
|
|
|
|
```ts
|
|
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`.
|