API 列表

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

请求方法和地址

GET /agent-bus/v1/agent/accessible

请求参数

请求示例

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
}

根据 Agent ID 获取指定 Agent。

请求方法和地址

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

请求参数

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/agent/${agentId}" \
  -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"
}

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

请求方法和地址

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

请求参数

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/agent/${agentId}/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
}

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

请求方法和地址

POST /agent-bus/v1/session/create

请求参数

请求示例

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"
  }

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

请求方法和地址

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

请求参数

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/session/${sessionId}" \
  -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"
}

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

请求方法和地址

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

请求参数

请求示例

curl -X PUT "${BASE_URL}/agent-bus/v1/session/${sessionId}" \
  -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"
}

删除指定会话。

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

请求方法和地址

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

请求参数

请求示例

curl -X DELETE "${BASE_URL}/agent-bus/v1/session/${sessionId}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_delete"

响应示例

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

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

请求方法和地址

GET /agent-bus/v1/session/list

请求参数

请求示例

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
}

声明待上传附件的元数据；实际上传需要使用分片上传接口。

请求方法和地址

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

请求参数

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/session/${sessionId}/attachments" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_upload_init" \
  -d "{
    \"filename\": \"architecture.png\",
    \"mimeType\": \"image/png\",
    \"byteSize\": 417996,
    \"sha256\": \"${file_sha256}\",
    \"extra\": \"image of DolphinDB architecture\"
  }"

响应示例

响应字段说明参考 SessionAttachmentInfo。除了 SessionAttachmentInfo，还额外包含分片信息 partSize、partCount 和 uploadedPartCount。

{
   "attachmentId": "img_e80e3523ea5ad6bae8f6b2c0985daeb0",
   "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
   "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-0d47a9dfb001",
   "userId": "admin",
   "filename": "architecture.png",
   "mimeType": "image/png",
   "kind": "image",
   "byteSize": 417996,
   "sha256": "72d9842aaef8ee95b52dd60eba7896b439c10d2c7174675bd9b0977d2f80f53c",
   "uploadStatus": "UPLOADING",
   "parseStatus": "NOT_APPLICABLE",
   "indexStatus": "NOT_APPLICABLE",
   "parseError": null,
   "indexError": null,
   "schemaVersion": 2,
   "extra": "image of DolphinDB architecture",
   "createTime": "2026.09.03 11:23:43.301",
   "updateTime": "2026.09.03 11:23:43.301",
   "partSize": 4194304,
   "partCount": 1,
   "uploadedPartCount": 0
}

分片上传附件实际数据。

请求方法和地址

PUT /agent-bus/v1/session/{sessionId}/attachments/{attachmentId}/parts/{partNo}

请求参数

请求示例

curl -X PUT "${BASE_URL}/agent-bus/v1/session/${sessionId}/attachments/${attachmentId}/parts/0" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Content-Type: application/octet-stream" \
    -H "X-Part-SHA256: ${PART_SHA256}" \
    --data-binary "@${PART}"

响应示例

响应字段说明参考 SessionAttachmentInfo。除了 SessionAttachmentInfo，还额外包含分片信息 partSize、partCount 和 uploadedPartCount

{
  "attachmentId": "img_e80e3523ea5ad6bae8f6b2c0985daeb0",
  "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-0d47a9dfb001",
  "userId": "admin",
  "filename": "architecture.png",
  "mimeType": "image/png",
  "kind": "image",
  "byteSize": 417996,
  "sha256": "72d9842aaef8ee95b52dd60eba7896b439c10d2c7174675bd9b0977d2f80f53c",
  "uploadStatus": "UPLOADING",
  "parseStatus": "NOT_APPLICABLE",
  "indexStatus": "NOT_APPLICABLE",
  "parseError": null,
  "indexError": null,
  "schemaVersion": 2,
  "extra": "image of DolphinDB architecture",
  "createTime": "2026.09.03 11:23:43.301",
  "updateTime": "2026.09.03 11:23:43.301",
  "partSize": 4194304,
  "partCount": 1,
  "uploadedPartCount": 1
}

验证分片数量、每片大小和整个附件的 SHA-256，解析附件并建立索引，完成附件上传。

请求方法和地址

POST /agent-bus/v1/session/{sessionId}/attachments/{attachmentId}/complete

请求参数

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/session/${sessionId}/attachments/${attachmentId}/complete" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_upload_complete"

响应示例

响应字段说明参考 SessionAttachmentInfo。

• 图片上传成功：返回 uploadStatus=COMMITTED，解析和索引状态为 NOT_APPLICABLE。

• 文档解析成功：返回 parseStatus=PARSED、indexStatus=INDEXING。

• 文档解析失败：返回 parseStatus=PARSE_FAILED 和 parseError，可再次调用该接口进行重试。

• 索引建立成功：返回 indexStatus=READY

• 索引建立失败：返回 indexStatus=INDEX_FAILED，可调用 index 接口进行重试。

{
  "attachmentId": "img_e80e3523ea5ad6bae8f6b2c0985daeb0",
  "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-0d47a9dfb001",
  "userId": "admin",
  "filename": "architecture.png",
  "mimeType": "image/png",
  "kind": "image",
  "byteSize": 417996,
  "sha256": "72d9842aaef8ee95b52dd60eba7896b439c10d2c7174675bd9b0977d2f80f53c",
  "uploadStatus": "COMMITTED",
  "parseStatus": "NOT_APPLICABLE",
  "indexStatus": "NOT_APPLICABLE",
  "parseError": null,
  "indexError": null,
  "schemaVersion": 2,
  "extra": "image of DolphinDB architecture",
  "createTime": "2026.09.03 11:23:43.301",
  "updateTime": "2026.09.03 14:22:34.651"
}

在附件解析成功（parseStatus=PARSED）但索引建立失败时，可以调用本接口进行重试。

请求方法和地址

POST /agent-bus/v1/session/{sessionId}/attachments/{attachmentId}/index

请求参数

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/session/${sessionId}/attachments/${attachmentId}/index" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_index"

响应示例

响应字段说明参考 SessionAttachmentInfo。

{
  "attachmentId": "doc_20c06b45a8f42998ddab4846343a25c8",
  "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-0d47a9dfb001",
  "userId": "admin",
  "filename": "README.md",
  "mimeType": "text/markdown",
  "kind": "text",
  "byteSize": 91,
  "sha256": "d49c9511f1e7314af7f2488005c05eedc99a0716558fc19aa226cae05e1254d6",
  "uploadStatus": "COMMITTED",
  "parseStatus": "PARSED",
  "indexStatus": "READY",
  "parseError": null,
  "indexError": null,
  "schemaVersion": 2,
  "extra": "README file for the project",
  "createTime": "2026.09.03 14:34:55.178",
  "updateTime": "2026.09.03 14:46:48.644"
}

列举指定会话中的附件。

请求方法和地址

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

请求参数

请求示例

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

响应示例

items 数组中每个元素都对应一个附件的信息，字段说明请参考 SessionAttachmentInfo。

{
  "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
  "items": [
     {
        "attachmentId": "img_e80e3523ea5ad6bae8f6b2c0985daeb0",
        "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
        "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-0d47a9dfb001",
        "userId": "admin",
        "filename": "architecture.png",
        "mimeType": "image/png",
        "kind": "image",
        "byteSize": 417996,
        "sha256": "72d9842aaef8ee95b52dd60eba7896b439c10d2c7174675bd9b0977d2f80f53c",
        "uploadStatus": "COMMITTED",
        "parseStatus": "NOT_APPLICABLE",
        "indexStatus": "NOT_APPLICABLE",
        "parseError": null,
        "indexError": null,
        "schemaVersion": 2,
        "extra": "image of DolphinDB architecture",
        "createTime": "2026.09.03 11:23:43.301",
        "updateTime": "2026.09.03 14:22:34.651"
            }
  ],
  "offset": 0,
  "limit": 100,
  "size": 1
}

获取指定附件的信息。

请求方法和地址

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

请求参数

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/session/${sessionId}/attachments/{attachmentId}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_info"

响应示例

响应字段说明参考 SessionAttachmentInfo。

{
  "attachmentId": "doc_20c06b45a8f42998ddab4846343a25c8",
  "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-0d47a9dfb001",
  "userId": "admin",
  "filename": "README.md",
  "mimeType": "text/markdown",
  "kind": "text",
  "byteSize": 91,
  "sha256": "d49c9511f1e7314af7f2488005c05eedc99a0716558fc19aa226cae05e1254d6",
  "uploadStatus": "COMMITTED",
  "parseStatus": "PARSED",
  "indexStatus": "READY",
  "parseError": null,
  "indexError": null,
  "schemaVersion": 2,
  "extra": "README file for the project",
  "createTime": "2026.09.03 14:34:55.178",
  "updateTime": "2026.09.03 14:46:48.644"
}

直接返回上传时的原始文件字节，不返回 JSON envelope，也不进行 Base64 编码。附件必须处于 uploadStatus=COMMITTED 状态；解析和索引状态不影响下载。

请求方法和地址

GET /agent-bus/v1/session/{sessionId}/attachments/{attachmentId}/content

请求参数

请求示例

OUTPUT='./downloaded-file'
curl -i GET "$BASE_URL/agent-bus/v1/session/${sessionId}/attachments/${attachmentId}/content" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_download" \
  --output "${OUTPUT}"

响应示例

HTTP/1.1 200 OK
Content-Length: 91
X-Content-SHA256: d49c9511f1e7314af7f2488005c05eedc99a0716558fc19aa226cae05e1254d6
X-Agent-Bus-Streaming: false
Content-Type: text/markdown
Access-Control-Expose-Headers: Content-Disposition, X-Content-SHA256
Content-Disposition: attachment; filename="README.md"; filename*=UTF-8''README.md
Access-Control-Allow-Origin: *
Connection: close

# 测试附件上传

这是一份 md 文件，文件大小很小，用于上传测试。

在附件中检索指定内容。

请求方法和地址

POST /agent-bus/v1/session/{sessionId}/attachments/retrieve

请求参数

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/session/${sessionId}/attachments/retrieve" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_retrieve" \
  -d "{
    \"query\": \"测试\",
    \"attachmentIds\": [\"${attachmentId}\"]
  }"

响应示例

{
  "retrievalId": "ret_bcc831d2-1861-e5b9-e244-ee69cf714298",
  "resultStatus": "OK",
  "items": [
    {
       "chunkId": "chk_909c5cf36fe6736745fd69fce0a8dc36",
       "content": "# 测试附件上传",
       "source": {
           "attachmentId": "doc_20c06b45a8f42998ddab4846343a25c8",
           "fileName": "README.md",
           "pageNo": null
                }
     },
    {
         "chunkId": "chk_c87b675323193785f1fe7855c47b86de",
         "content": "这是一份 md 文件，文件大小很小，用于上传测试。",
         "source": {
             "attachmentId": "doc_20c06b45a8f42998ddab4846343a25c8",
             "fileName": "README.md",
             "pageNo": null
                }
          }
      ]
}

删除指定的附件。

请求方法和地址

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

请求参数

请求示例

curl -X DELETE "$BASE_URL/agent-bus/v1/session/${sessionId}/attachments/${attachmentId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_delete"

响应示例

deleted=true 表示逻辑删除已经生效且后台清理任务已提交。

{
   "attachmentId": "img_b17760a09aeba5eb7ae6a56f04e8e7a3",
   "deleted": true
}

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

请求方法和地址

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

请求参数

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/skill/${agentId}/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
}

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

请求方法和地址

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

请求参数

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/skill/${skillId}/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 内容..."
}

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

请求方法和地址

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

请求参数

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/skill/${skillId}/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 编码。

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

请求方法和地址

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

请求参数

请求示例

curl -X GET "${BASE_URL}/agent-bus/v1/skill/${skillId}/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 时，只返回对应行范围。
• 非文本文件不支持按行读取，始终返回完整原始内容。
• 大文件建议使用分段读取控制响应大小。

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

请求方法和地址

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

请求参数

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/skill/${skillId}/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做查找。

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

请求方法和地址

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

请求参数

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/skill/${skillId}/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
}

列举与指定 Agent 绑定的活跃知识库。

请求方法和地址

POST /agent-bus/v1/knowledge/available

请求参数

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/knowledge/available" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: knowledge_available" \
  -d "{
    \"agentId\": \"${agentId}\",
    \"sessionId\": \"${sessionId}\"
    }"

响应示例

items 数组中每个元素都对应一个知识库，每个元素包含以下三个字段：

• knowledgeBaseId：知识库 ID，用于后续 retrieve 和 read 接口

• name：知识库名称

• description：知识库描述

{
  "items": [
    {
      "knowledgeBaseId": "kb_c0566aa1-e175-5ba6-ef4f-ff93ae4cbb0d",
      "name": "产品手册",
      "description": "测试"
    }
  ]
}

根据指定内容检索知识库。一次请求仅能检索一个知识库；需要跨库检索时，可先调用 available 接口，再分别调用多次 retrieve 接口并自行编排结果。

请求方法和地址

POST /agent-bus/v1/knowledge/retrieve

请求参数

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/knowledge/retrieve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: knowledge_retrieve" \
  -d "{
    \"agentId\": \"${agentId}\",
    \"knowledgeBaseId\": \"${knowledgeBaseId}\",
    \"query\": \"测试\"
  }"

响应示例

items 数组中每一个元素为知识库中与检索内容匹配的 chunk 信息，字段说明请参考 ChunkInfo；如果 items 为空，表示知识库中无相关内容。

{
   "retrievalId": "ret_ea36ee47-073e-caa0-4847-d64b5536f6d6",
   "resultStatus": "OK",
   "items": [
     {
        "chunkId": "chk_249b86f3bbea9c810625581497941915",
         "content": "# 测试附件上传",
         "source": {
             "documentId": "doc_5eeaa1fb2afd07d21110cbfa45c141cf",
             "fileName": "README.md",
             "pageNo": null
                }
     },
     {
         "chunkId": "chk_e033d9d3a223caa93c668e8a32ee86e7",
         "content":  "这是一份 md 文件，文件大小很小，用于上传测试。",
         "source": {
             "documentId": "doc_5eeaa1fb2afd07d21110cbfa45c141cf",
             "fileName": "README.md",
             "pageNo": null
                }
      }
  ]
}

根据指定 chunkId 读取该 chunk 及相邻 chunk 的信息。

请求方法和地址

POST /agent-bus/v1/knowledge/read

请求参数

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/knowledge/read" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: knowledge_read" \
  -d "{
    \"agentId\": \"${agentId}\",
    \"knowledgeBaseId\": \"${knowledgeBaseId}\",
    \"chunkId\": \"${chunkId}\",
    \"before\": 1,
    \"after\": 1
  }"

响应示例

item 是指定 chunk 的信息；before 和 after 数组中的元素是指定 chunk 相邻前后的 chunk 信息，其元素结构与 item 相同，字段说明请参考 ChunkInfo。

{
  "item": {
    "chunkId": "chk_249b86f3bbea9c810625581497941915",
    "content": "# 测试附件上传",
    "source": {
       "documentId": "doc_5eeaa1fb2afd07d21110cbfa45c141cf",
       "fileName": "README.md",
       "pageNo": null
            }
    },
    "before": [],
    "after": [
       {
          "chunkId": "chk_e033d9d3a223caa93c668e8a32ee86e7",
           "content": "这是一份 md 文件，文件大小很小，用于上传测试。",
           "source": {
               "documentId": "doc_5eeaa1fb2afd07d21110cbfa45c141cf",
               "fileName": "README.md",
               "pageNo": null
           }
        }
    ]
}

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

请求方法和地址

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

请求参数

请求示例

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
}

读取指定 Workspace 文件的内容。

请求方法和地址

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

请求参数

请求示例

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 获取足够上下文。

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

请求方法和地址

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

请求参数

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/workspace/${sessionId}/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"
}

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

请求方法和地址

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

请求参数

请求示例

curl -X DELETE "${BASE_URL}/agent-bus/v1/workspace/${sessionId}/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
}

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

请求方法和地址

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

请求参数

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/workspace/${sessionId}/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 读取目标行附近内容。

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

请求方法和地址

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

请求参数

请求示例

curl -X POST "${BASE_URL}/agent-bus/v1/workspace/${sessionId}/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 失败时，整个请求失败且原文件保持不变。

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

请求方法和地址

POST /agent-bus/v1/llm/complete

请求参数

LLMMessage 结构：

请求示例

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
  }
}

服务端根据请求中的 agentId 或 sessionId 解析对应 Agent 和用户，在调用 LLM Provider 前检查 Token 预算。如果预算不足，会在调用 Provider 前返回错误：

{
  "error": {
    "code": "BUS_LLM_QUOTA_EXCEEDED",
    "message": "LLM_TOKEN_BUDGET_EXCEEDED: model token budget exceeded: agentId=agent_xxx, llmConfigId=llm_xxx, projectedTokens=4096, remainingTokens=1024"
  }
}

预算不足时不会调用 LLM Provider，因此不会增加 LLM usage。

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

请求方法和地址

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

请求参数

请求示例

例 1：获取序列号 1-100 之内的消息

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"

例 2：获取最新的 50 条消息

curl -X GET "${BASE_URL}/agent-bus/v1/session/${sessionId}/messages?limit=50&from=tail" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_messages"

例 3：从第 100 条消息开始往前获取 50 条消息

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

例 4：从第 150 条消息开始往后获取 50 条消息

curl -X GET "${BASE_URL}/agent-bus/v1/session/${sessionId}/messages?startSeq=150&limit=50&from=front" \
  -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
}