通用约定
本文介绍 DolphinX API 的整体调用规范，为应用层实现提供统一协议、认证、错误、分页和流式处理规则。
1. 请求格式
本节主要说明 HTTP API 的请求格式。DolphinX API 还支持 WebSocket 调用；HTTP 与 WebSocket 的字段映射规则见 WebSocket 协议。
HTTP API 默认使用 JSON 作为请求和响应格式。客户端应按以下约定构造请求：
- Content-Type: application/json
-
公共请求头：
- x-agent-id：可选，指定 agentId，与请求体或查询参数中的 agentId 等效。
- x-session-id：可选，指定 sessionId。
2. 认证与权限机制
DolphinX API 复用 DolphinDB 的登录态和当前用户身份。HTTP 调用通常先通过 DolphinDB 登录接口（/api/login）获得会话或 token；WebSocket 连接可在握手时携带 Authorization: Bearer <token>。服务端以认证上下文中的当前用户作为 userId，开发者不应在业务 payload 中传入 userId 来伪造身份。权限不足时返回 BUS_PERMISSION_DENIED，未登录或登录态失效时返回 BUS_UNAUTHENTICATED。
常见权限如下：
| 权限 | 说明 |
|---|---|
| AGENT_INVOKE | 可调用指定 ACTIVE Agent 的接口，包括
/session/create、/chat/completions、workspace/*、skill/*、/network/fetch、/mcp/tools/call
等。 |
| AGENT_ADMIN | 管控权限。可配置 Agent、权限、LLM、Skill、MCP、Memory 等。 |
| DolphinDB admin | DolphinDB 内置的系统级管理员，拥有内置资源初始化和全局授权能力。 |
3. 响应格式
非流式响应统一采用 envelope 结构。envelope 指包裹 data 字段的 JSON 对象，而 data 字段存储了业务数据。为了不重复展示外层公共字段，后续章节中的响应示例只展示 data 字段中的内容。实际调用 API 时，拿到的是完整 envelope，需要从 data 字段中取业务数据。
envelope 结构：
{
"type": "RESPONSE",
"msgId": "...",
"correlationId": "<requestId>",
"action": "<action>",
"agentId": "<agentId>",
"sessionId": "<sessionId>",
"data": { ... },
"headers": { "...": "..." }
}
- type：返回的类型。
- msgId：服务端生成的消息 ID。
- correlationId：用于关联请求和响应。若请求中没有提供 x-request-id 或 WebSocket requestId，服务端会自动生成。
- action：调用的接口。
- agentId：Agent ID。
- sessionId：会话 ID。
- data：业务数据。
- headers：envelope 内的业务元信息字段，不是 HTTP response headers；仅在服务端 envelope headers 非空时返回。
响应可能包含本文未列出的兼容字段、诊断字段或内部字段；这些字段不属于对外稳定契约，开发者不应依赖。
错误响应示例如下，详细的错误码说明参考错误码。
{
"type": "ERROR",
"msgId": "...",
"correlationId": "<requestId>",
"action": "<action>",
"agentId": "<agentId>",
"sessionId": "<sessionId>",
"error": {
"code": "<BusErrorCode>",
"message": "<错误描述>",
"reason": "<业务原因，可选>",
"providerStatus": "<LLM provider HTTP 状态码，可选>",
"providerCode": "<LLM provider 错误码，可选>",
"retryable": "<true|false，可选>"
},
"headers": {
"busErrorCode": "<BusErrorCode>",
"httpStatus": "<HTTP 状态码>",
"llmProviderStatus": "<LLM provider HTTP 状态码，可选>",
"providerCode": "<LLM provider 错误码，可选>",
"retryable": "<true|false，可选>"
}
}4. 分页参数
列表类接口统一支持以下参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| offset | int | 否 | 跳过前 offset 条数据，必须为非负整数。默认值为 0。 |
| limit | int | 否 | 返回条数上限，必须为非负整数。0 表示返回空列表，默认值为 100。 |
分页参数支持 URL 查询参数传递或通过 JSON 请求体传入。
5. 流式响应（HTTP SSE / WebSocket）
对于支持流式响应的 HTTP API，可以通过请求参数 stream 控制响应的返回方式：
stream=true（默认）：响应返回 Server-Sent Events（SSE），即服务端边生成内容边返回。stream=false：响应返回 envelope，即服务端生成全部内容后再返回。
WebSocket 调用时需要在请求帧的 payload.stream 中指定该参数。
HTTP SSE 和 WebSocket 使用同一套 envelope 类型，只是外层传输格式不同。典型事件序列如下：
[可选的 EVENT ...]
↓
STREAM_START
↓
[STREAM_CHUNK / STREAM_REASONING / EVENT ...]
↓
STREAM_END 或 STREAM_ERROR5.1 HTTP SSE
SSE 响应头：
Content-Type: text/event-stream; charset=UTF-8
Cache-Control: no-cache
Connection: keep-alive
X-Agent-Bus-Streaming: true每个 SSE 事件的 data 字段都是一条完整的 envelope，由 type 表示当前阶段。应先按 SSE 事件分帧，再解析 data 字段中的 JSON；不要把多个 chunk 拼成一个 JSON 解析。
对 HTTP SSE 客户端来说，chunk / reasoning_delta 只用于实时展示；传输快结束时 stream_end 中的 STREAM_END.data 会包含完整响应结果，业务处理应使用这份数据，不要自行拼接 chunk。
| SSE event | envelope 类型 | 说明 |
|---|---|---|
| event | EVENT | 业务过程事件，如上下文压缩进度。 |
| stream_start | STREAM_START | 流式请求已开始。 |
| chunk | STREAM_CHUNK | 正文或结构化增量。 |
| reasoning_delta | STREAM_REASONING | 可展示 reasoning 增量。 |
| stream_end | STREAM_END | 流式请求成功结束。 |
| stream_error | STREAM_ERROR | 流式请求中途失败，发送后关闭响应。 |
流式响应帧示例：
event: stream_start
data: {"type":"STREAM_START","msgId":"...","correlationId":"req_001","action":"chat.completions","agentId":"agent_xxx","sessionId":"sess_001","data":{"requestId":"req_001","model":"<resolved-model>"}}
event: chunk
data: {"type":"STREAM_CHUNK","msgId":"...","correlationId":"req_001","action":"chat.completions","agentId":"agent_xxx","sessionId":"sess_001","data":{"content":"你好"}}
event: stream_end
data: {"type":"STREAM_END","msgId":"...","correlationId":"req_001","action":"chat.completions","agentId":"agent_xxx","sessionId":"sess_001","data":{"requestId":"req_001","content":"你好","finishReason":"stop","usage":{"totalTokens":20}}}5.2 WebSocket
WebSocket 流式返回时不会包装成 SSE 文本格式，也没有 event、data 这些行。服务端会把每个流式事件作为一条独立的 envelope 消息发回同一个 WebSocket 连接。客户端用响应里的 correlationId 匹配请求时传入的 requestId。
对 WebSocket 客户端来说，STREAM_CHUNK / STREAM_REASONING 只用于实时展示；在传输快结束时， STREAM_END.data 会包含完整响应结果，业务处理应使用这份数据。
请求示例：
{
"type": "REQUEST",
"requestId": "req_001",
"action": "chat.completions",
"agentId": "agent_xxx",
"sessionId": "sess_001",
"payload": {
"message": "你好",
"stream": true
}
}
流式响应帧示例：
{"type":"STREAM_START","msgId":"...","correlationId":"req_001","action":"chat.completions","agentId":"agent_xxx","sessionId":"sess_001","data":{"requestId":"req_001","model":"<resolved-model>"}}
{"type":"STREAM_CHUNK","msgId":"...","correlationId":"req_001","action":"chat.completions","agentId":"agent_xxx","sessionId":"sess_001","data":{"content":"你好"}}
{"type":"STREAM_END","msgId":"...","correlationId":"req_001","action":"chat.completions","agentId":"agent_xxx","sessionId":"sess_001","data":{"requestId":"req_001","content":"你好","finishReason":"stop","usage":{"totalTokens":20}}}5.3 错误语义
- 若 HTTP SSE 开始前失败，服务端返回普通错误响应 envelope，并使用对应 HTTP status。
- 若 HTTP SSE 开始后失败，HTTP status 已经发送，服务端会返回
event: stream_error，data 字段的 type 为 STREAM_ERROR，随后关闭响应。 - WebSocket 失败时返回 ERROR 或 STREAM_ERROR JSON 帧；correlationId 仍对应请求帧中的 requestId。
- 收到 STREAM_END 或 STREAM_ERROR 后，本次流式请求结束，不会再有后续事件。
5.4 客户端处理建议
- 流式 envelope 的顶层 headers 与非流式含义一致，仅在服务端 envelope headers 非空时返回。
- SSE 响应体统一使用 UTF-8 编码。客户端应按字节读取并显式按 UTF-8 解码后，再做事件分帧和 JSON 解析。
- 客户端应忽略未知的
EVENT.action，避免服务端新增过程事件时造成兼容性问题。