jiang
6a49d2209e
Move project and host queries into native MCP with host-owned OAuth/context, while retaining memory, skills, actions and publication plugins. Add nearby-model queries and explicit chat/task/learning model defaults. Adopt Responses HTTP/SSE and native steer/queue inbox delivery, preserving scoped session ownership, pending input edits and investigation communication. Disable local-provider discovery: Server /health allowed native vLLM to probe /v1/models on port 8000. A native before/after regression prevents recurrence. Validation: 170 focused Bun tests; service/plugin typechecks; native discovery, provider-discovery and input-inbox smoke checks; no paid model inference.
107 lines
3.6 KiB
Markdown
107 lines
3.6 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
|
|
|
|
生成接口为 `POST /api/v1/responses`。下方示例是会话状态订阅中的 UIEnvelope；Responses 生成流将同一业务数据放入 `tjwater.ui_envelope` 事件的 `data` 中，并携带 `response_id` 和 `sequence_number`。
|
|
|
|
运行中追加文本使用同一生成地址，`stream=false`，携带 `conversation`、`tjwater.delivery="steer" | "queue"` 和稳定的 `tjwater.input_id`。HTTP 202 的 `tjwater.response_input` 收件回执不是新的 Response 或处理成功证明。当前 Responses SSE 保持连接，用 `tjwater.user_input` 的 `pending` / `delivered` 状态同步输入，`delivered` 表示原生收件箱已取走而非任务完成。`GET /api/v1/session/:session_id/inputs` 返回待处理消息；PATCH 其 `/:input_id` 的 `delivery` 可在处理前切换模式，处理后返回409。恢复会话流使用同样的 `user_input` 业务事件和原生待处理列表。
|
|
|
|
```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/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.
|
|
|
|
Analysis evidence must come from validated request context or allowlisted
|
|
tools. This service does not bundle a local historical business dataset.
|
|
|
|
## 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`.
|