Files

T

jiang 6a49d2209e feat(agent): unify MCP tools and adopt Responses delivery

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.

2026-10-19 18:46:58 +08:00

3.6 KiB

Raw Blame History

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 业务事件和原生待处理列表。

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/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:

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