API 列表

本文以 HTTP 调用为例，介绍 DolphinX API 的请求方法、接口地址、请求参数、请求示例及响应示例。HTTP 与 WebSocket 的字段映射关系见 WebSocket 协议。

注：

执行 curl 示例前需获取 BASE_URL 和 TOKEN：

BASE_URL='http://<host>:<port>'  # 部署了 DolphinX 的 Server 地址
TOKEN='<dolphindb-token>' # DolphinDB 登录 token，通过 /api/login 接口获取

1. Agent 发现与可用配置

1.1 获取可访问的 Agent

获取当前用户可访问的 Agent。

请求方法和地址

GET /agent-bus/v1/agent/accessible

请求参数


参数	类型	必填	说明
status	int	否	Agent 状态值。 0（默认值）：REGISTERED（已注册） 1：ACTIVE（已激活） 2：SUSPENDED（已挂起） 3：DELETED（已删除）注：设置 `status=1` 或不设置该参数时返回 ACTIVE Agent；设置为 0、2 或 3 时返回空列表。
offset	int	否	跳过前 offset 条数据，必须为非负整数。默认值为 0。
limit	int	否	返回条数上限，必须为非负整数。0 表示返回空列表，默认值为 100。

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/agent/accessible?offset=0&limit=100" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_agent_accessible"

响应示例

items 数组中每个元素都对应一个 Agent 的信息，字段说明请参考 AgentInfo。size 表示 items 数组的长度，即可访问的 Agent 的数量。

{
  "items": [
    {
      "agentId": "agent_builtin_xxx",
      "agentName": "DolphinDB Coding Agent",
      "description": "用于 DolphinDB 开发、调试、脚本生成和数据分析的内置编程助手。",
      "status": 1,
      "statusName": "ACTIVE",
      "systemPrompt": "你是 DolphinDB Coding Agent，负责替用户完成 DolphinDB 相关的代码编写、调试、脚本生成、数据分析和问题排查。\r\n\r\n能执行就直接执行，尽量把工作推进到可用结果，而不是只给建议。回答要直接、可靠、便于复查；信息不足时只问必要问题，不臆造表结构、接口或运行结果。",
      "llmConfigId": "llm_f5796495-21ce-8990-4e40-xxx",
      "contextConfig": {
        "includeSkillCatalog": true,
        "includeMemory": true
      },
      "memoryConfig": {
        "embeddingEnabled": false
      },
      "config": {
        "builtin": true,
        "builtinVersion": "2026.06.02",
        "agentKind": "coding"
      },
      "version": 3,
      "schemaVersion": 1,
      "extra": "",
      "createTime": "2026.06.29 14:20:30.596",
      "updateTime": "2026.06.29 14:22:09.107",
      "myPermission": "AGENT_ADMIN"
    }
  ],
  "offset": 0,
  "limit": 100,
  "size": 1
}

1.2 获取指定 Agent

根据 Agent ID 获取指定 Agent。

请求方法和地址

GET /agent-bus/v1/agent/{agentId}

请求参数


参数	类型	必填	说明
agentId	string	是	Agent ID。

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/agent/agent_xxx" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_agent_get"

响应示例

返回指定 Agent 的信息，字段说明请参考 AgentInfo。

{
  "agentId": "agent_builtin_xxx",
  "agentName": "DolphinDB Coding Agent",
  "description": "用于 DolphinDB 开发、调试、脚本生成和数据分析的内置编程助手。",
  "status": 1,
  "statusName": "ACTIVE",
  "systemPrompt": "你是 DolphinDB Coding Agent，负责替用户完成 DolphinDB 相关的代码编写、调试、脚本生成、数据分析和问题排查。\r\n\r\n能执行就直接执行，尽量把工作推进到可用结果，而不是只给建议。回答要直接、可靠、便于复查；信息不足时只问必要问题，不臆造表结构、接口或运行结果。",
  "llmConfigId": "llm_f5796495-21ce-8990-4e40-xxx",
  "contextConfig": {
    "includeSkillCatalog": true,
    "includeMemory": true
  },
  "memoryConfig": {
    "embeddingEnabled": false
  },
  "config": {
    "builtin": true,
    "builtinVersion": "2026.06.02",
    "agentKind": "coding"
  },
  "version": 3,
  "schemaVersion": 1,
  "extra": "",
  "createTime": "2026.06.29 14:20:30.596",
  "updateTime": "2026.06.29 14:22:09.107"
}

1.3 获取可选择的 LLM

根据 Agent ID 获取指定 Agent 下可选择的 LLM。

请求方法和地址

GET /agent-bus/v1/agent/{agentId}/llm/selectable

请求参数


参数	类型	必填	说明
agentId	string	是	Agent ID。

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/agent/agent_xxx/llm/selectable" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_agent_llm_selectable"

响应示例

items 数组中每个元素都对应一个 LLM 的信息，字段说明请参考 SelectableLlmInfo。size 表示 items 数组的长度，即可选择的 LLM 的数量。

{
  "defaultLlmConfigId": "llm_f5796495-21ce-8990-xxx",
  "items": [
    {
      "llmConfigId": "llm_f5796495-21ce-8990-xxx",
      "name": "gpt",
      "providerId": "provider_d69bdb29-70e7-f9ab-cc42-xxx",
      "provider": {
        "providerId": "provider_d69bdb29-70e7-f9ab-cc42-xxx",
        "name": "gpt",
        "adapterType": "openai-compatible",
        "baseUrl": "https://xxx",
        "apiKey": "***************************************************",
        "enabled": true,
        "schemaVersion": 1,
        "extra": "",
        "createTime": "2026.06.29 14:21:42.339",
        "updateTime": "2026.06.29 14:21:42.339"
      },
      "model": "gpt-5.5",
      "capability": "chat",
      "embeddingDimension": 0,
      "embeddingMetric": "",
      "embeddingNormalize": false,
      "requestPath": "/v1/chat/completions",
      "defaultParams": {},
      "contextWindow": null,
      "maxConcurrency": null,
      "rateLimitRPM": null,
      "timeoutMs": null,
      "retryConfig": {},
      "enabled": true,
      "schemaVersion": 1,
      "customData": "{\"tool_call\":true}",
      "extra": "",
      "createTime": "2026.06.29 14:22:01.843",
      "updateTime": "2026.06.29 14:22:01.843",
      "source": "agent",
      "isAgentDefault": true,
      "fallbackPriority": 0,
      "participatesInFallback": true
    }
  ],
  "size": 1
}

2. 会话管理

2.1 创建会话

使用指定 Agent 创建一个会话。

请求方法和地址

POST /agent-bus/v1/session/create

请求参数


参数	类型	必填	说明
agentId	string	是	处于 ACTIVE 状态的 Agent 的 ID。
title	string	否	会话标题。
llmConfigId	string	否	当前用户在指定 Agent 下，可选 LLM 配置的 ID。
metadata	object	否	JSON 格式的自定义元数据。DolphinX 不对该数据进行处理。

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/session/create" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_create" \
  -d '{"agentId":"agent_xxx","title":"测试会话"}'

响应示例

响应字段说明参考 SessionInfo。

{
    "sessionId": "8280cfd0-92c6-6bae-1844-xxx",
    "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-xxx",
    "userId": "admin",
    "llmConfigId": "",
    "title": "测试会话",
    "metadata": {},
    "schemaVersion": 1,
    "extra": "",
    "createTime": "2026.06.30 10:54:22.665",
    "updateTime": "2026.06.30 10:54:22.665"
  }

2.2 获取会话

根据会话 ID 获取指定会话。

请求方法和地址

GET /agent-bus/v1/session/{sessionId}

请求参数


参数	类型	必填	说明
sessionId	string	是	会话 ID。

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/session/8280cfd0-92c6-6bae-1844-xxx" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_get"

响应示例

响应字段说明参考 SessionInfo。

{
  "sessionId": "8280cfd0-92c6-6bae-1844-xxx",
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-xxx",
  "userId": "admin",
  "llmConfigId": "",
  "title": "测试会话",
  "metadata": {},
  "schemaVersion": 1,
  "extra": "",
  "createTime": "2026.06.30 10:54:22.665",
  "updateTime": "2026.06.30 10:54:22.665"
}

2.3 更新会话

更新指定会话的信息。只有会话 owner 才有权限更新。

请求方法和地址

PUT /agent-bus/v1/session/{sessionId}

请求参数


参数	类型	必填	说明
sessionId	string	请求地址已提供会话 ID 时可不设置该参数	会话 ID。若同时在请求地址和请求体中设置，ID 必须保持一致。
title	string	否	会话标题。
llmConfigId	string	否	当前用户在指定会话对应的 Agent 下，可选 LLM 的配置 ID。为空时表示清除原有的 LLM 配置。
metadata	object	否	JSON 格式的自定义元数据。只能整体替换。

请求示例

curl -X PUT "${BASE_URL}/agent-bus/v1/session/8280cfd0-92c6-6bae-1844-xxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_update" \
  -d '{"title":"更新后的会话标题","metadata":{"source":"curl-demo"}}'

响应示例

响应字段说明参考 SessionInfo。

{
  "sessionId": "8280cfd0-92c6-6bae-1844-xxx",
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-xxx",
  "userId": "admin",
  "llmConfigId": "",
  "title": "更新后的会话标题",
  "metadata": {"source": "curl-demo"},
  "schemaVersion": 1,
  "extra": "",
  "createTime": "2026.06.30 10:54:22.665",
  "updateTime": "2026.06.30 10:54:22.665"
}

2.4 删除会话

删除指定会话。

只有会话 owner 才有权限删除会话。
删除后对应的会话消息和 Workspace 会被彻底删除。
对不存在的 sessionId 返回 deleted=true。
删除开始后，无法在该会话中发送新消息。
删除会话后，调用对应的 GET /session/{sessionId} 和 GET /session/{sessionId}/messages 接口返回 BUS_SESSION_NOT_FOUND。

请求方法和地址

DELETE /agent-bus/v1/session/{sessionId}

请求参数


参数	类型	必填	说明
sessionId	string	是	会话 ID。

请求示例

curl -X DELETE "${BASE_URL}/agent-bus/v1/session/8280cfd0-92c6-6bae-1844-xxx" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_delete"

响应示例

{
  "sessionId": "8280cfd0-92c6-6bae-1844-xxx",
  "deleted": true
}

2.5 列举会话

列举当前用户创建的会话。该接口不支持跨用户会话查询。

请求方法和地址

GET /agent-bus/v1/session/list

请求参数


参数	类型	必填	说明
agentId	string	是	Agent ID。也可以在请求地址中或通过 x-agent-id 请求头指定 ID。
offset	int	否	跳过前 offset 条数据，必须为非负整数。默认值为 0。
limit	int	否	返回条数上限，必须为非负整数。0 表示返回空列表，默认值为 100。

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/session/list?agentId=agent_xxx&offset=0&limit=100" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_list"

响应示例

items 数组中每个元素都对应一个会话的信息，字段说明请参考 SessionInfo。size 表示 items 数组的长度，即会话的数量。

{
  "items": [
    {"sessionId": "100d1675-0a36-70a0-cf48-xxx",
    "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-xxx",
    "userId": "admin",
    "llmConfigId": "",
    "title": "测试会话",
    "metadata": {},
    "schemaVersion": 1,
    "extra": "",
    "createTime": "2026.06.30 10:44:55.744",
    "updateTime": "2026.06.30 10:44:55.744"
    }],
    "offset": 0,
    "limit": 100,
    "size": 1
}

3. 对话补全

在指定会话中推进一轮对话。可以提交新的用户消息，也可以提交工具调用的执行结果。DolphinX 会自动完成权限校验、会话写入、上下文组装、模型选择、LLM 调用、助手回复落库和 token 消耗记录。

接口支持流式和非流式返回，默认流式返回。自动组装与手动组装共用同一个请求地址，通过请求体中是否包含 assemblyConfig 参数切换：

不包含 assemblyConfig 时进行自动组装，适合常规对话。
包含 assemblyConfig 时进行手动组装，适合调用方自行控制上下文块、工具定义或临时指令的场景。

请求方法和地址

POST /agent-bus/v1/chat/completions

请求参数


参数	类型	必填	说明
sessionId	string	是	会话 ID，必须属于当前登录用户。
message	string	条件必填	用户消息文本，会被自动追加到会话历史中。message 和 toolResults 必须且只能提供一个。
toolResults	ToolResult[]	条件必填	工具执行结果列表，必须对应上一轮 LLM 返回的 toolCalls。message 和 toolResults 必须且只能提供一个。
stream	bool	否	是否流式返回，默认值为 true。
contextEvent	bool	否	是否在流式响应中返回上下文处理过程事件，默认值为 false。仅对 `stream=true` 的 HTTP SSE 和 WebSocket 请求生效。注：开启后，自动摘要/上下文压缩等过程会以 EVENT 事件返回，便于前端展示“正在压缩上下文”等状态；这些事件不是 LLM 回复内容。
includeReasoning	bool	否	是否返回思考过程，默认值为 false。
tools	ToolDefinition[]	否	应用层工具定义列表，使用 OpenAI function calling 格式。
activeSkillNames	string[]	否	本次请求主动加载的技能名称列表。只用于显式注入这些技能的详细指令，不表示模型自主选择的技能，也不维护渐进式加载状态；后续是否继续加载由调用方决定。
llmConfigId	string	否	本次请求使用的 LLM 配置 ID，临时覆盖会话或 Agent 默认配置。
model	string	否	临时覆盖本次请求中的模型名称。通常应通过 llmConfigId 选择模型，仅在同一 LLM 配置下需要临时指定兼容模型名时使用。该参数不改变 llmConfigId、权限校验、上下文窗口或备用 LLM 配置切换策略
temperature	double	否	临时覆盖本次采样温度，取值范围为 [0, 2]。值越低输出越稳定，值越高输出越发散。
maxTokens / max_tokens / max_completion_tokens	int	否	临时覆盖本次输出 token 上限；也会影响上下文组装时预留的输出预算。三个参数等价，建议只传一个。
topP / top_p	double	否	临时覆盖 nucleus sampling 参数，取值范围为 (0, 1]。值越小输出越收敛。两个参数等价，建议只传一个。
stop	string / string[]	否	临时设置本次停止序列；生成内容命中任一序列时停止。
extensions	object	否	直接透传到模型服务提供方的参数。
assemblyConfig	object	否	手动组装配置，由应用层控制上下文构成。仅在需要手动组装时设置该参数。assemblyConfig 的内部结构参考下方表格。

assemblyConfig 结构：


参数	类型	必填	说明
systemPrompt	string	否	自定义系统提示词，覆盖 Agent 默认的系统提示词。
contextBlocks	ContextBlock[]	否	自定义上下文块列表，按 position 插入组装管线。详情参考见下方 ContextBlock 结构与手动组装流程。
tools	ToolDefinition[]	否	应用层工具定义列表，使用 OpenAI function calling 格式。
activeSkillNames	string[]	否	本次请求主动加载的技能名称列表。只用于显式注入这些技能的详细指令，不表示模型自主选择的技能，也不维护渐进式加载状态；后续是否继续加载由调用方决定。
excludeSkillNames	string[]	否	排除的技能名称列表。
noSkillCatalog	bool	否	是否跳过技能目录自动注入，默认值为 false。

ToolResult 结构：


参数	类型	必填	说明
toolCallId / tool_call_id	string	是	工具调用 ID，需与上一轮 LLM 返回的 `toolCalls[].id` 一致。
content	string	否	工具执行结果的文本内容。

ContextBlock 结构：


参数	类型	必填	说明
name	string	是	块标识符，仅用于校验和调试，不注入提示词。
content	string	是	注入的文本内容。
position	string	否	文本插入位置，可选值为 after_system、before_history（默认值）、before_current_turn。

自动组装

以下步骤由 DolphinX 在后台完成，调用方只需提交本轮 message 或 toolResults。

校验会话权限，并解析本次要使用的 LLM 配置。
加载 Agent 配置、系统提示词、技能目录、显式加载的技能详细指令和相关记忆。
必要时执行自动摘要。
通过上下文窗口检查后，将当前轮输入写入会话并调用 LLM。
将模型输出和 token 消耗写入会话，并返回本次响应。

手动组装

after_system 的 block 会顺序追加到前一条系统提示词末尾；若本次组装没有系统提示词，after_system 会转化为首条 role=system 消息。
before_history 会包装成应用参考上下文，插入到 latest summary 之后、raw history 之前。
before_current_turn 会包装成应用运行时上下文并折叠进当前轮 message。
after_system 用于全局规则，before_history 用于本轮参考资料，before_current_turn 用于需要贴近当前轮的运行时状态或动态快照。

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/chat/completions" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_chat_completions" \
  -d '{"sessionId":"sess_001","message":"你好，请介绍一下 DolphinX。","stream":false}'

响应示例

自动组装和手动组装的响应 data 结构一致。stream=false 时该结构作为 HTTP JSON envelope 的 data 返回；stream=true 时完整结果在 STREAM_END.data 返回。

reasoning 表示 LLM 提供商返回的可展示思考过程，只用于展示，不保证完整或等价于模型内部推理；DolphinX 只在 includeReasoning=true 时提取并返回，不必持久化存储。

{
  "requestId": "req_xxx",
  "sessionId": "sess_001",
  "model": "gpt-4",
  "llmConfigId": "llm_actual",
  "content": "这是 LLM 的回复...",
  "reasoning": "LLM 提供商返回的可展示思考过程；未开启或未返回时为空",
  "toolCalls": [
    {
      "id": "call_xxx",
      "type": "function",
      "function": {
        "name": "search_database",
        "arguments": "{\"query\":\"SELECT ...\"}"
      }
    }
  ],
  "finishReason": "stop",
  "usage": {
    "promptTokens": 1200,
    "completionTokens": 300,
    "totalTokens": 1500
  },
  "latencyMs": 2500,
  "metadata": {
    "llmConfigId": "llm_actual",
    "requestedLlmConfigId": "llm_requested",
    "fallbackApplied": false
  }
}

流式响应中，STREAM_CHUNK.data.content 是正文增量，toolCallDeltas 是工具调用增量；增量可能不完整，只用于实时展示。执行工具、入库或业务判断以 STREAM_END.data.toolCalls 为准。
STREAM_REASONING.data.reasoning 只在 includeReasoning=true 且 LLM 提供商返回可展示思考过程时出现。
metadata 记录本次实际使用的 LLM 配置。fallbackApplied=true 表示首选 LLM 配置调用失败后，DolphinX 改用了备用 LLM 配置；此时会额外返回 fallbackFromLlmConfigId（原配置 ID）、fallbackReason（失败原因）和 fallbackStatusCode（失败状态码）。
context.compaction 事件只在 contextEvent=true 且本次请求实际触发上下文压缩时返回，可能出现在 STREAM_START 之前；普通 HTTP JSON 响应会忽略 contextEvent。

4. 技能管理

4.1 获取 Agent 的技能目录

获取指定 Agent 下当前用户可见、可由 LLM 发现的技能摘要。调用 /chat/completions 时，DolphinX 默认会将技能目录注入上下文，调用方通常无需手动调用本接口。本接口主要用于预览、调试或自定义上下文组装。手动组装模式下可通过 assemblyConfig.noSkillCatalog=true 关闭自动注入。

请求方法和地址

GET /agent-bus/v1/skill/{agentId}/catalog

请求参数


参数	类型	必填	说明
agentId	string	是	Agent ID。

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/skill/agent_xxx/catalog" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_skill_catalog"

响应示例

响应字段说明参考 SkillInfo。

{
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-xxx",
  "userId": "admin",
  "catalog": 
    [
      {
        "skillId": "sk_6d9fbb7a-9597-7a97-ed4b-a5cccea178a1",
        "name": "ddb-ml",
        "description": "DolphinDB Web 侧机器学习数据工作流单技能。用于元数据发现、数据预览、过滤、聚合、join、字段角色推断、数据清洗、特征工程、分类、回归和聚类任务；不覆盖调查报告、时序报告或数据库管理。",
        "argumentHint": ""
      },
        ...
    ],"size": 4
}

4.2 获取技能主指令

返回指定技能的主指令内容。

请求方法和地址

GET /agent-bus/v1/skill/{skillId}/instruction

请求参数


参数	类型	必填	说明
skillId	string	是	技能 ID。
agentId	string	是	Agent ID。

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/skill/skill_xxx/instruction?agentId=agent_xxx" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_skill_instruction"

响应示例

{
  "skillId": "skill_xxx",
  "name": "search-database",
  "description": "Search distributed tables",
  "instruction": "完整的 Skill 主指令 Markdown 内容..."
}

4.3 列出技能包文件

返回技能包内文件清单，只包含文件元信息，不返回文件内容。

请求方法和地址

GET /agent-bus/v1/skill/{skillId}/files/list

请求参数


参数	类型	必填	说明
skillId	string	是	技能 ID。
agentId	string	是	Agent ID。

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/skill/skill_xxx/files/list?agentId=agent_xxx" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_skill_files_list"

响应示例

{
  "skillId": "skill_xxx",
  "items": [
    {
      "skillId": "skill_xxx",
      "filePath": "references/model-selection-guide.md",
      "size": 2048,
      "isText": true,
      "lineCount": 80
    }
  ],
  "size": 1
}

响应字段说明

filePath：技能包文件相对于根目录的路径。
isText：表示服务端是否按文本文件处理；非文本文件读取时会返回完整原始内容的 base64 编码。

4.4 获取技能包单个文件

获取技能包内指定文件的内容。

请求方法和地址

GET /agent-bus/v1/skill/{skillId}/files/get

请求参数


参数	类型	必填	说明
skillId	string	是	技能 ID。
agentId	string	是	Agent ID。
filePath	string	是	技能包文件相对于根目录的路径。
lineStart	int	否	文本文件 1-based 起始行；默认值为 0，表示读取完整文件。
lineLimit	int	否	读取行数；默认值为 120，最大值为 300。
raw	bool	否	兼容参数；响应中的 content 始终为原始文件内容的 base64 编码。

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/skill/skill_xxx/files/get?agentId=agent_xxx&filePath=references/model-selection-guide.md&lineStart=1&lineLimit=120" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_skill_files_get"

响应示例

{
  "skillId": "skill_xxx",
  "filePath": "references/model-selection-guide.md",
  "isText": true,
  "lineCount": 42,
  "raw": false,
  "lineStart": 1,
  "lineEnd": 42,
  "encoding": "base64",
  "content": "<base64 内容>",
  "size": 1024
}

文本文件指定 lineStart / lineLimit 时，只返回对应行范围。
非文本文件不支持按行读取，始终返回完整原始内容。
大文件建议使用分段读取控制响应大小。

4.5 检索技能包文本文件

在技能包文本文件中按字符串查找内容。该接口适合工具按需读取，避免将全量文件装配进上下文。

请求方法和地址

POST /agent-bus/v1/skill/{skillId}/files/search

请求参数


参数	类型	必填	说明
skillId	string	是	技能 ID。
agentId	string	是	Agent ID。
query	string	条件必填	搜索单个字符串，1 到 1024 字节。query、all、any 必须且只能提供一个。
all	string[]	条件必填	多个字符串全部匹配才命中。最多 5 个，每个 1 到 1024 字节。
any	string[]	条件必填	多个字符串中，任意一个匹配即命中。最多 5 个，每个 1 到 1024 字节。
scope	string	否	匹配粒度，可选值： file（整个文件）或 line（单行），默认值为 file。
caseSensitive	bool	否	是否大小写敏感，默认值为 false。
filePaths	string[]	否	限定搜索的技能包内相对路径列表。
extensions	string[]	否	限定文件后缀，如 [".md", ".json"]。
contextLines	int	否	每个命中行前后的上下文行数，默认值为 3，最大值为 10。
maxResults	int	否	命中总数安全阈值，默认值为 1000，最大值为 5000。
maxPerFile	int	否	单个文件命中数安全阈值，默认值为 200，最大值为 1000。

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/skill/skill_xxx/files/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_skill_files_search" \
  -d '{"agentId":"agent_xxx","query":"DolphinDB","scope":"line","contextLines":2,"maxResults":20}'

响应示例

{
  "skillId": "skill_xxx",
  "terms": ["RSI"],
  "mode": "query",
  "scope": "file",
  "resultCount": 1,
  "skippedCount": 0,
  "matches": [
    {
      "skillId": "skill_xxx",
      "filePath": "refs/indicators/rsi.json",
      "size": 668,
      "isText": true,
      "lineCount": 24,
      "line": 3,
      "column": 12,
      "term": "RSI",
      "text": "\"name\": \"RSI\"",
      "before": ["{"],
      "after": [" \"period\": 14"]
    }
  ],
  "skipped": []
}

用于在技能包文本文件中按字符串查找内容，适合工具按需读取，避免将全量文件装配进上下文。
仅检索文本文件；非文本文件或超过可检索大小上限的文本文件会出现在 skipped 中，reason 可能为 non_text 或 too_large。
搜索词按字面量子串匹配，不拆词、不支持 regex、不打分；大小写由 caseSensitive 控制。
scope=file 按整文件判断是否满足条件，例如 all=["foo","bar"] 只要求同一文件内同时出现；响应仍返回实际命中的行。scope=line 按单行判断是否满足条件，例如 all=["foo","bar"] 要求同一行内同时出现。
结果按技能包文件顺序和行号稳定返回，不做相关性排序。
命中数量超过 maxResults 或 maxPerFile 时返回错误，不返回部分结果；调用方应使用更精确的pattern做查找。

4.6 批量获取技能包文件

批量获取技能包内指定文件的内容。

请求方法和地址

POST /agent-bus/v1/skill/{skillId}/files/batchGet

请求参数


参数	类型	必填	说明
skillId	string	是	技能 ID。
agentId	string	是	Agent ID。
filePaths	string / string[]	是	相对于技能包根目录的文件路径。传单个字符串时按一个文件处理；传空数组返回空列表。

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/skill/skill_xxx/files/batchGet" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_skill_files_batch_get" \
  -d '{"agentId":"agent_xxx","filePaths":["SKILL.md","reference.md"]}'

响应示例

{
  "skillId": "skill_xxx",
  "items": [
    {
      "skillId": "skill_xxx",
      "filePath": "SKILL.md",
      "encoding": "base64",
      "content": "<base64 内容>",
      "size": 2048
    }
  ],
  "size": 1
}

5. Workspace 管理

Workspace 是面向 Agent 的会话级临时文本文件区。它用于保存中间代码、脚本和局部修改结果，避免模型在对话中反复全量输出文件内容。

通用约束

Workspace 由 sessionId 定位，当前用户必须是该会话的创建者。
文件在单个会话 Workspace 内平铺，不支持子目录。name 只能是普通文件名，不能包含 /、\、..，不能以 . 开头。
read/search/write/replace 只面向 UTF-8 文本文件。
单 workspace 默认限制为 100 个文件、5 MiB 总大小、512 KiB 单文件大小；其中总大小由部署参数 maxAgentWorkspaceBytes 控制。读取和搜索有服务端保护上限。

Workspace 文件 hash

Workspace 中的 hash 值是读 Workspace 文件时 DolphinX 侧返回的字段，Agent 在进行文件修改操作时需要带着此 hash 值，用于确保待修改的文件和之前读取时是一样的（防止陈旧读）。

格式：

xxh64:<16位hex>:<size>

调用 workspace.replace 修改文件时，必须把上次从同一文件的 workspace.read、workspace.search、workspace.write 或 workspace.replace 拿到的 hash 放入请求体。
服务端执行 workspace.replace 前会重新读取当前文件并计算 hash；如果请求中的 hash 与当前文件 hash 不一致，请求会被拒绝，错误为 REPLACE_REJECTED、error.reason="stale_file"。客户端应重新 read 或 search 后再生成替换请求。

可获得和使用 hash 的接口：


接口	是否返回 hash	如何使用
workspace.read	是，响应字段 hash	表示被读取文件的完整内容摘要，可直接作为后续 `workspace.replace.hash`。
workspace.search	是，每个 `matches[].hash`	表示对应 `matches[].name` 文件的完整内容摘要，可作为修改该文件时的 `workspace.replace.hash`。
workspace.write	是，响应字段 hash	表示写入后的完整文件摘要，可作为后续 `workspace.replace.hash`。
workspace.replace	请求必须携带 hash；成功响应返回新 hash	请求中的 hash 用于陈旧读检测；响应中的新 hash 应用于后续继续修改同一文件。

5.1 列出 Workspace 文件

列出当前会话 Workspace 根目录下的普通文件。

请求方法和地址

GET /agent-bus/v1/workspace/{sessionId}/files

请求参数


参数	类型	必填	说明
sessionId	string	是	会话 ID。

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/workspace/sess_001/files" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_workspace_list"

响应示例

{
  "items": [
    {
      "name": "main.dos",
      "type": "file",
      "size": 2048,
      "updateTime": "2026-05-21T10:00:00.000"
    }
  ],
  "size": 1
}

5.2 读取 Workspace 文件

读取指定 Workspace 文件的内容。

请求方法和地址

GET /agent-bus/v1/workspace/{sessionId}/file

请求参数


参数	类型	必填	说明
sessionId	string	是	会话 ID。
name	string	是	文件名，不支持路径。
startLine	int	否	起始行，1-based；缺省从第 1 行开始。
endLine	int	否	结束行，闭区间；缺省读到文件尾。

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/workspace/sess_001/file?name=main.dos&startLine=1&endLine=120" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_workspace_read"

响应示例

{
  "name": "main.dos",
  "content": "def main(){\n return 1\n}\n",
  "size": 1024,
  "lineCount": 42,
  "startLine": 1,
  "endLine": 3,
  "hash": "xxh64:4f9a2c18b7e301d2:1024"
}

size 是完整文件字节数，lineCount 是完整文件行数。
请参考本小节开头关于 hash 的说明。
构造 workspace.replace.replacements[].old 时，应从本接口返回的 content 中精确复制旧片段；多行替换或换行敏感修改应优先使用 workspace.read 获取足够上下文。

5.3 写入 Workspace 文件

创建文件或整体写入文件。小范围修改优先使用 workspace.replace。

请求方法和地址

POST /agent-bus/v1/workspace/{sessionId}/file

请求参数


参数	类型	必填	说明
sessionId	string	是	会话 ID。
name	string	是	文件名，不支持路径。
content	string	是	UTF-8 文本内容。

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/workspace/sess_001/file" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_workspace_write" \
  -d '{"name":"main.dos","content":"def main(){\n  return 1\n}\n"}'

响应示例

{
  "name": "main.dos",
  "created": true,
  "changed": true,
  "size": 31,
  "hash": "xxh64:4f9a2c18b7e301d2:31"
}

5.4 删除 Workspace 文件

删除当前会话 Workspace 内的指定文件。不支持目录删除、递归删除、批量删除、通配符删除或清空 Workspace。

请求方法和地址

DELETE /agent-bus/v1/workspace/{sessionId}/file

请求参数


参数	类型	必填	说明
sessionId	string	是	会话 ID。
name	string	是	文件名，不支持路径。

请求示例

curl -X DELETE "${BASE_URL}/agent-bus/v1/workspace/sess_001/file" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_workspace_delete" \
  -d '{"name":"main.dos"}'

响应示例

{
  "name": "main.dos",
  "deleted": true,
  "size": 2048
}

5.5 搜索 Workspace 文件

在 Workspace 文本文件中按字符串定位内容。该接口适合工具按需读取。

请求方法和地址

POST /agent-bus/v1/workspace/{sessionId}/search

请求参数


参数	类型	必填	说明
sessionId	string	是	会话 ID。
query	string	条件必填	搜索单个字符串，1 到 1024 字节。query、all、any 必须且只能提供一个。
all	string[]	条件必填	多个字符串全部匹配才命中。最多 5 个，每个 1 到 1024 字节。
any	string[]	条件必填	多个字符串任意一个匹配即命中。最多 5 个，每个 1 到 1024 字节。
scope	string	否	匹配粒度，可选值： file（整个文件）或 line（单行），默认值为 file。
caseSensitive	bool	否	是否大小写敏感，默认值为 false。
names	string[]	否	限定搜索的文件名列表。
extensions	string[]	否	限定文件后缀，如 [".dos", ".md"]。
contextLines	int	否	每个命中行前后的上下文行数，默认值为 0，最大值为 10。
maxResults	int	否	命中总数安全阈值，默认值为 1000，最大值为 5000。
maxPerFile	int	否	单个文件命中数安全阈值，默认值为 200，最大值为 1000。

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/workspace/sess_001/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_workspace_search" \
  -d '{"query":"submitOrder","scope":"line","contextLines":1,"maxResults":20}'

响应示例

{
  "terms": ["submitOrder", "RSI"],
  "mode": "all",
  "scope": "file",
  "resultCount": 1,
  "skippedCount": 0,
  "matches": [
    {
      "name": "main.dos",
      "hash": "xxh64:4f9a2c18b7e301d2:1024",
      "line": 37,
      "column": 12,
      "term": "submitOrder",
      "text": "submitOrder(account, symbol, qty)",
      "before": ["if(rsi < 30){"],
      "after": ["}"]
    }
  ],
  "skipped": []
}

用于在 Workspace 文本文件中按字符串定位内容，适合工具按需读取。
仅检索 UTF-8 文本文件；超过单文件大小上限或非 UTF-8 文件会出现在 skipped 中，reason 可能为 too_large 或 invalid_utf8。
搜索词按字面量子串匹配，不拆词、不支持 regex、不打分；大小写由 caseSensitive 控制。
scope=file 按整文件判断是否满足条件，例如 all=["foo","bar"] 只要求同一文件内同时出现；响应仍返回实际命中的行。
scope=line 按单行判断是否满足条件，例如 all=["foo","bar"] 要求同一行内同时出现。
命中数量超过 maxResults 或 maxPerFile 时返回错误，不返回部分结果；调用方应缩小范围后重试。
请参考本小节开头关于hash的说明。
workspace.search 适合定位文件和行号；搜索返回的 text、before、after 是按行组织的上下文。需要构造多行或换行敏感的 old 片段时，应再调用 workspace.read 读取目标行附近内容。

5.6 局部修改 Workspace 文件

使用精确旧片段对 Workspace 文件进行局部替换。请求必须携带文件 hash，用于陈旧读检测。

请求方法和地址

POST /agent-bus/v1/workspace/{sessionId}/replace

请求参数


参数	类型	必填	说明
sessionId	string	是	会话 ID。
name	string	是	要修改的已有文件名，不支持路径。
hash	string	是	文件 hash，格式如 `xxh64:<16位hex>:<size>`。
replacements	object[]	是	有序替换列表，不能为空。
replacements[].old	string	是	精确旧片段，不能为空。
replacements[].new	string	是	新片段，可以为空字符串；空字符串表示删除旧片段。
replacements[].replaceAll	bool	否	是否替换所有匹配，默认值为 false。

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/workspace/sess_001/replace" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_workspace_replace" \
  -d '{"name":"main.dos","hash":"xxh64:<hash>:<size>","replacements":[{"old":"return 1","new":"return 2"}]}'

响应示例

{
  "name": "main.dos",
  "changed": true,
  "lineCount": 3,
  "replacementCount": 2,
  "occurrenceCount": 5,
  "hash": "xxh64:7c1d0b2a9910ef43:1048"
}

多条 replacement 按数组顺序应用。如果有多条 replacement，第二条会在第一条替换后的内容里执行。所以如果第一条生成了某些新文本，第二条也可能匹配到这些新文本。
replaceAll=false 时，old 必须恰好出现一次；0 次或多次都拒绝。
replaceAll=true 时，old 必须至少出现一次，服务端替换所有非重叠匹配。
任意一条 replacement 失败时，整个请求失败且原文件保持不变。

6. 发起外部网络请求

通过 DolphinX 访问外部 HTTP(S) 资源。DolphinX 负责安全校验、限流、发起请求和返回原始 HTTP 响应摘要；页面解析、检索排序、重定向处理等逻辑由应用层负责。

请求方法和地址

POST /agent-bus/v1/network/fetch

请求参数


参数	类型	必填	说明
agentId	string	条件必填	Agent ID。
method	string	是	仅支持 "GET" 和 "POST"，大小写不敏感。
url	string	是	完整的 http:// 或 https:// URL。目前仅允许访问 dolphindb.cn、dolphindb.com 及其子域名，按域名边界匹配。仅允许默认端口：HTTP 80、HTTPS 443；不跟随 3xx 重定向。URL 不允许包含空格、控制字符、fragment、userinfo 或 IP literal host。
headers	object	否	透传到目标站点的请求头，值必须为标量字符串。请求头会做安全过滤；禁止设置 Host、Content-Length、Transfer-Encoding、Connection、认证/Cookie/代理相关头、Accept-Encoding 以及 hop-by-hop 头。DolphinX 固定使用 Accept-Encoding: identity。
body	string	否	POST 请求体。GET 请求不允许携带 body。仅文本类、未压缩响应会返回 body；二进制、未知类型或非 identity 编码响应会设置 `bodyOmitted=true`。文本 body 按 UTF-8 返回；如需安全修正会设置 `bodyUtf8Sanitized=true`。
timeoutMs	int	否	请求超时时间，默认值为 10000，最大值为 30000。
maxBodyBytes	long	否	响应 body 最大读取字节数，默认值为 2097152，最大值为 33554432。 body 被截断时 `truncated=true`。PDF 等二进制资源只返回状态码、响应头和 content type，不返回 body。

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/network/fetch" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_network_fetch" \
  -d '{"agentId":"agent_xxx","method":"GET","url":"https://docs.dolphindb.cn/zh/","timeoutMs":10000,"maxBodyBytes":1048576}'

响应示例

响应字段说明参考 NetworkFetchResponse。

{
  "url": "https://docs.dolphindb.cn/zh/tutorials/in_memory_table.html",
  "method": "GET",
  "statusCode": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "text/html; charset=utf-8"
  },
  "contentType": "text/html; charset=utf-8",
  "contentEncoding": "",
  "body": "<!doctype html>...",
  "truncated": false,
  "bodyOmitted": false,
  "bodyUtf8Sanitized": false,
  "latencyMs": 321
}

7. 调用 MCP 工具

执行 /chat/completions 返回的 MCP tool call。

请求方法和地址

POST /agent-bus/v1/mcp/tools/call

请求参数


参数	类型	必填	说明
sessionId	string	是	会话 ID，必须属于当前登录用户；DolphinX 从会话解析所属 Agent。
toolName / name	string	是	要执行的 MCP 合成工具名，通常来自上一轮 `toolCalls[].function.name`。
arguments	object	否	工具参数 JSON object；未传时使用空对象。

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/mcp/tools/call" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_mcp_tools_call" \
  -d '{"sessionId":"sess_001","toolName":"mcp_server_tool_name","arguments":{"query":"DolphinDB"}}'

响应示例

响应字段说明参考 McpToolCallResult。

{
  "ok": true,
  "isError": false,
  "truncated": false,
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

本接口只负责执行已绑定 MCP Server 中的 tools，不用于配置 MCP Server 或绑定关系；配置类能力由 DolphinX 管控系统维护，不作为外部开发者 API 发布。
toolName 是 DolphinX 生成的合成工具名，用于避免不同 MCP Server 的工具名冲突。应用侧通常直接使用 LLM 返回的 toolCalls[].function.name，不需要解析该名称。
当 MCP Server 返回工具级错误时，接口仍可能返回 ok=false 或 isError=true 的业务结果；调用方应将响应内容作为 tool result 回填给模型，由模型继续处理。

8. 生成会话摘要

DolphinX 会在 chat.completions 上下文过长时自动做上下文压缩。该接口仅用于需要手动压缩的场景。

请求方法和地址

POST /agent-bus/v1/session/{sessionId}/summary

请求参数


参数	类型	必填	说明
sessionId	string	是	会话 ID。
instructions	string	否	额外的摘要指令，追加到摘要 prompt 中。
llmConfigId	string	否	本次摘要优先使用的 LLM 配置 ID。
force	bool	否	是否强制生成，默认值为 false。为 true 时最新 summary 之后的全部 raw 历史纳入本次摘要。
metadata	object	否	自定义元数据，JSON 格式。DolphinX 只负责透传。

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/session/sess_001/summary" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_summary" \
  -d '{"force":false,"instructions":"请保留本轮会话中的数据库路径、表名和关键结论。"}'

响应示例

响应字段说明参考 SummaryResult。

{
  "sessionId": "sess_001",
  "generated": true,
  "reason": "",
  "trigger": "manual",
  "summaryUpToSeqNum": 50,
  "messageId": "msg_xxx",
  "sequenceNum": 51,
  "role": "system",
  "contentType": "summary",
  "content": "摘要内容...",
  "metadata": {
    "summaryUpToSeqNum": 50,
    "trigger": "manual"
  }
}

9. 预览上下文

预览上下文组装结果但不调用 LLM。可用于检查 token 预算分配、确认技能和记忆是否正确注入。

请求方法和地址

POST /agent-bus/v1/context/preview

请求参数


参数	类型	必填	说明
sessionId	string	是	会话 ID，必须属于当前登录用户可读范围。
message	string	条件必填	用户消息文本。message 和 toolResults 必须且只能提供一个。
toolResults	ToolResult[]	条件必填	工具执行结果列表，必须对应上一轮 LLM返回的 toolCalls。
tools	ToolDefinition[]	否	工具定义列表。存在 assemblyConfig 时请改放到 `assemblyConfig.tools`。
activeSkillNames	string[]	否	本次主动加载的技能名称。存在 assemblyConfig 时请改放到 `assemblyConfig.activeSkillNames`。
llmConfigId	string	否	用于解析上下文窗口和 token 预算的 LLM 配置 ID。
assemblyConfig	object	否	手动组装配置，结构同 Chat Completions 的手动组装模式。
maxTokens / max_tokens / max_completion_tokens	int	否	输出 token 预留预算；三个字段等价，建议只传一个。

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/context/preview" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_context_preview" \
  -d '{"sessionId":"sess_001","message":"请预览这轮请求会组装哪些上下文。","maxTokens":1024}'

响应示例

{
  "agentId": "agent_001",
  "sessionId": "sess_001",
  "assemblyMode": "auto",
  "messages": [
    {
      "role": "system",
      "content": "..."
    },
    {
      "role": "user",
      "content": "当前问题"
    }
  ],
  "tools": [],
  "estimatedTokens": 4200,
  "detail": {
    "assemblyMode": "auto",
    "historyMode": "summary-first",
    "memoriesIncluded": 2,
    "messagesIncluded": 8,
    "skillsInCatalog": 3,
    "activeInstructions": 1,
    "toolsIncluded": 2,
    "summaryIncluded": true,
    "summaryUpToSeqNum": 40,
    "historyFromSeq": 41,
    "historyToSeq": 48
  },
  "tokenBreakdown": {
    "systemPrompt": 200,
    "skillCatalog": 300,
    "skillInstructions": 600,
    "memoryContext": 300,
    "summaryMessage": 120,
    "historyMessages": 2200,
    "externalContext": 0,
    "userMessage": 50,
    "toolDefinitions": 430
  }
}

detail 字段说明


字段	类型	说明
assemblyMode	string	"auto" 或 "manual"。
memoriesIncluded	int	实际注入到上下文中的记忆条数。
messagesIncluded	int	实际包含的历史消息条数。
skillsInCatalog	int	技能目录中包含的技能数。
activeInstructions	int	已加载的技能详细指令数。
toolsIncluded	int	工具定义数量。
historyMode	string	历史组装模式，固定为 "summary-first"。
summaryIncluded	bool	本次是否注入了 latest summary。
summaryUpToSeqNum	long	本次使用的 latest summary 覆盖边界；未使用 summary 时为 0。
historyFromSeq	long	raw tail 起始序列号。
historyToSeq	long	raw tail 结束序列号。

tokenBreakdown 字段说明


字段	类型	说明
systemPrompt	int	系统提示词估算 token 数。
skillCatalog	int	技能目录估算 token 数。
skillInstructions	int	技能详细指令估算 token 数。
memoryContext	int	记忆内容估算 token 数。
summaryMessage	int	latest summary 估算 token 数。
historyMessages	int	历史消息估算 token 数。
externalContext	int	contextBlocks 等外部上下文估算 token 数。
userMessage	int	当前用户消息估算 token 数；若本轮仅提供 toolResults 则为 0。
toolDefinitions	int	工具定义估算 token 数。

10. 底层接口

10.1 LLM Complete（直接调用 LLM）

绕过上下文组装，直接发送消息给 LLM。适用于应用自行与 LLM 交互的场景。

请求方法和地址

POST /agent-bus/v1/llm/complete

请求参数


参数	类型	必填	说明
agentId	string	条件必填	Agent ID。
sessionId	string	否	会话 ID。
messages	LLMMessage[]	是	完整的消息列表，由应用层自行构建，直接发送给 LLM。
tools	ToolDefinition[]	否	工具定义列表，使用 OpenAI function calling 格式。
model	string	否	临时设置本次请求的模型名。
stream	bool	否	是否流式返回，默认值为 true。
includeReasoning	bool	否	是否返回思考过程，默认值为 false。
llmConfigId	string	否	LLM 配置 ID。
requestId	string	否	请求追踪 ID，不指定时自动生成。
temperature	double	否	临时覆盖本次采样温度，范围为 [0, 2]。值越低输出越稳定，值越高输出越发散。
maxTokens / max_tokens / max_completion_tokens	int	否	临时覆盖本次输出 token 上限。三个字段等价，建议只传一个。
topP / top_p	double	否	临时覆盖 nucleus sampling 参数，范围为 (0, 1]。值越小输出越收敛。两个参数等价，建议只传一个。
stop	string / string[]	否	临时设置本次停止序列。生成内容命中任一序列时停止。可传字符串或字符串数组。
persistMessage	bool	否	仅在指定 sessionId 时有效；为 true 时把模型回复追加到该会话。
extensions	object	否	直接透传到模型服务提供方的参数。

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/llm/complete" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_llm_complete" \
  -d '{"agentId":"agent_xxx","messages":[{"role":"user","content":"你好，请用一句话介绍 DolphinX。"}],"stream":false}'

响应示例

响应结构同 Chat Completions 响应。

{
  "requestId": "req_xxx",
  "sessionId": "sess_001",
  "model": "gpt-4",
  "llmConfigId": "llm_actual",
  "content": "这是 LLM 的回复...",
  "reasoning": "",
  "toolCalls": [],
  "finishReason": "stop",
  "usage": {
    "promptTokens": 1200,
    "completionTokens": 300,
    "totalTokens": 1500
  },
  "latencyMs": 2500,
  "metadata": {
    "llmConfigId": "llm_actual",
    "requestedLlmConfigId": "llm_requested",
    "fallbackApplied": false
  }
}

10.2 获取消息列表

获取指定会话的消息列表。

请求方法和地址

GET /agent-bus/v1/session/{sessionId}/messages

请求参数


参数	类型	必填	说明
sessionId	string	是	会话 ID。
startSeq	long	否	起始序列号，默认值为 1。
endSeq	long	否	结束序列号，默认值为 MAX。

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/session/sess_001/messages?startSeq=1&endSeq=100" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_messages"

响应示例

响应字段说明参考 MessageInfo。

{
  "sessionId": "sess_001",
  "items": [
    {
      "messageId": "msg_xxx",
      "sessionId": "sess_001",
      "agentId": "agent_xxx",
      "sequenceNum": 1,
      "role": "user",
      "contentType": "text",
      "content": "你好",
      "metadata": {},
      "createTime": "2026.06.30 10:54:22.665"
    }
  ],
  "size": 1
}