跳到主要内容

配置 API 接入

概述

API 接入用于让 Super App、BI 后端等第三方应用调用当前智能体。应用可以发起和继续对话、读取会话历史与交付文件，也可以查询运行轨迹、停止运行及提交回复反馈。

配置入口位于智能体配置页的「发布与集成 > 渠道入口」。本文介绍接入配置和最小调用流程；完整接口参数、响应与文件上传方式，可在「API 接入」区域点击「查看接入文档」查看。

使用前提与执行身份

  • 已准备好目标智能体，当前账号有权编辑该智能体。
  • 创建接入的账号已配置业务所需的 BI 凭据和连接器，并能在 DecideX 中正常使用该智能体。
  • 第三方应用能够安全保存调用凭证，并为用户提供稳定的用户标识。
注意

API 会话使用创建接入账号的身份、BI 凭据和记忆执行。建议使用专用账号创建接入，并为该账号配置所需连接器和数据权限。

「外部用户身份验证」用于关联外部用户身份及会话记录，不会把执行权限切换为该外部用户的权限。第三方应用需要自行控制哪些用户可以调用，以及向哪些用户展示返回的数据。

创建 API 接入

  1. 打开目标智能体的配置页，进入「发布与集成 > 渠道入口」，在「API 接入」区域点击添加按钮。

  2. 填写「接入名称」，建议包含应用名称及环境，例如「经销商经营门户 - 生产环境」。

  3. 按下表配置浏览器来源、身份验证与执行详情，点击「创建 API 接入」。

    新建 API 接入与配置选项

配置项填写方式与作用
接入名称用于区分第三方应用及环境
浏览器允许来源（Origin 白名单）浏览器直连时填写发起请求页面的 Origin，每行一个。格式为协议、域名及端口，不包含路径，例如 https://portal.example.com 或 http://localhost:3000。填写第三方页面的来源，而不是 API 接口地址
外部用户身份验证默认「关闭（仅调用凭证）」；选择「Galaxy Token 验证」后，创建会话还需携带可验证的 Galaxy 用户 Token
允许查看执行详情默认不开启。开启后向调用方开放所属会话的操作说明、命令、输出和错误，可能包含业务数据及运行环境信息；不返回原始协议包和内部推理
加入白名单将页面显示的「当前 DecideX 页面 Origin」加入列表；接入其他站点时，仍需填写该站点的实际 Origin

推荐由第三方应用后端保存凭证并调用 DecideX，浏览器只请求第三方应用后端。不携带 Origin 的后端请求不使用浏览器来源白名单；浏览器直连时，请求 Origin 必须与白名单匹配。

生成与保存调用凭证

  1. 在创建的 API 接入下点击「生成凭证」。
  2. 点击「复制」，立即将凭证保存到第三方应用后端的安全配置中。关闭展示窗口后，无法再次查看该凭证的完整明文。
  3. 在请求中通过 Authorization: Bearer <调用凭证> 携带凭证。

一个接入可以生成多个凭证。若未保存明文，可重新生成凭证并更新调用方配置；不再使用的旧凭证应吊销。

风险提示

调用凭证代表该 API 接入的调用权限。不要将长期凭证放入公开文档、截图、前端代码、URL 或日志。浏览器直连仅适合受控内部场景，Origin 白名单不能代替用户身份验证和应用侧权限控制。

配置外部用户身份

调用会话接口时，第三方应用需提供稳定的外部用户 ID。DecideX 按 API 接入和外部用户 ID 隔离会话，同一用户续聊或查询历史时应保持 ID 一致。

请求头用途
Authorization填写 Bearer <调用凭证>，用于识别并授权 API 接入
Decidex-External-User-Id第三方应用侧的稳定用户 ID，例如 portal-user-10086；不是 DecideX 用户 ID
Decidex-External-User-Token开启「Galaxy Token 验证」后，创建会话时提供 Galaxy 签发的当前用户 JWT；续聊已有会话不需要此请求头

开启「Galaxy Token 验证」时，Token 中的 sub 必须与 Decidex-External-User-Id 一致。系统验证后为用户建立本地身份并关联会话记录，但会话仍以创建接入账号的身份与权限执行。

外部用户 ID 应由可信后端确定，不应允许普通用户随意替换为他人的 ID。查询模型列表不涉及用户会话，只需调用凭证，无需外部用户 ID。

验证 API 调用

在「API 接入」区域点击「查看接入文档」，按当前环境的接口说明接入。下面以同步对话为例，验证新建会话和续聊。

创建会话并发送首条消息

将 DECIDEX_BASE_URL 设置为当前 DecideX 部署地址，将 SERVICE_AGENT_TOKEN 设置为已安全保存的调用凭证。以下示例适用于关闭外部用户身份验证的接入；开启时需另加 Decidex-External-User-Token 请求头。

curl -sS "$DECIDEX_BASE_URL/api/service-agent/chat" \
  -H "Authorization: Bearer $SERVICE_AGENT_TOKEN" \
  -H "Decidex-External-User-Id: portal-user-10086" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "你能帮我完成哪些业务分析？",
    "newSession": { "title": "业务分析咨询" }
  }'

接口完成本轮回答后，返回 sessionId、runId、用户消息、智能体回复和交付文件等信息。检查 assistantMessage.content 是否正常，并保存 sessionId 用于续聊。

示例未指定模型，系统优先使用智能体配置的有效默认模型，否则使用平台默认模型。需要指定模型及推理档位时，先通过 GET /api/service-agent/models 查询可用选项。

继续已有会话

保持相同 API 接入和外部用户 ID，将返回的 sessionId 放入下一次请求。

curl -sS "$DECIDEX_BASE_URL/api/service-agent/chat" \
  -H "Authorization: Bearer $SERVICE_AGENT_TOKEN" \
  -H "Decidex-External-User-Id: portal-user-10086" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "替换为上一轮返回的 sessionId",
    "message": "请进一步说明分析所需的数据。"
  }'

newSession 与 sessionId 必须二选一，不能同时填写或都不填写。系统不会自动复用最近会话。结果不确定时，不要自动重试新建会话请求，以免创建重复会话；若失败响应已返回 sessionId，应保留该 ID 继续处理。

接入更多会话能力

能力使用方式
异步对话使用 POST /api/service-agent/chat/async，立即获取会话和运行 ID，再轮询运行轨迹；运行结束后读取消息及交付文件
会话历史查询当前外部用户的会话列表及指定会话的消息
工作轨迹根据会话和运行 ID 查询阶段、步骤和状态；开启「允许查看执行详情」后，可读取额外的操作详情
停止运行使用停止接口，停止指定会话中尚未结束的运行；需要运行中停止能力时采用异步对话
回复反馈对已成功完成的回复提交、修改或撤销点赞、点踩反馈
交付文件使用响应中返回的文件地址，携带相同鉴权信息读取或下载

具体路径、参数和响应格式见页面中的「查看接入文档」。

管理接入与凭证

在「渠道入口 > API 接入」中找到对应接入，可执行以下操作。

操作作用与注意事项
修改并保存调整接入名称、允许来源、外部用户身份验证和执行详情设置后，点击「保存」
生成凭证为接入生成新的调用凭证。更换凭证时，先更新调用方并验证成功，再吊销旧凭证
吊销吊销选定凭证，后续使用该凭证的请求将无法通过鉴权；吊销后不能恢复
停用／启用停用后阻止该接入的后续调用，需要恢复时重新启用
删除永久删除接入、全部调用凭证及外部会话列表映射，外部应用无法继续原会话；底层审计记录仍保留，此操作不可恢复
刷新重新加载接入列表，查看当前状态及最近使用情况

停用接入或吊销凭证不等于停止已启动的运行。需要终止运行时，应使用停止运行接口。

常见问题

问题检查方式
凭证无效或调用被拒绝检查请求头、接入是否启用、凭证是否已吊销或过期，以及创建接入账号是否仍可用
浏览器调用失败，后端调用正常核对实际请求 Origin 与白名单，包括协议、域名及端口；不要填写带路径的页面 URL
开启身份验证后无法创建会话检查是否携带有效的 Galaxy 用户 Token，且 sub 与外部用户 ID 一致
无法读取或继续已有会话确认调用凭证属于原 API 接入，外部用户 ID 与创建会话时一致，且会话 ID 正确
能返回回答，但无法获取业务数据检查创建接入账号的 BI 凭据、连接器、数据权限及智能体配置；外部用户身份验证不会改变执行身份
看不到命令、输出或错误详情检查是否开启「允许查看执行详情」。关闭时只返回精简轨迹；开启后也不返回内部推理和原始协议包