配置单个智能体的 API 接入
适用场景
当业务系统需要通过后端调用一个指定的智能体时,可在该智能体下创建 API 接入。例如,经销商门户可以用同一个经营分析智能体回答不同经销商的问题。接入凭证绑定该智能体,不能通过更改 Agent ID 调用其他智能体。
如果目标是在观远 BI 超级应用中添加悬浮助手或内嵌聊天框,请直接参考 在 Super App 中嵌入智能体:由组织统一配置接入,无需先完成本文步骤。
使用前提
准备好目标智能体,并确认当前账号有权编辑它。第三方应用应有自己的后端,用于保存调用凭证、识别登录用户并发起请求。
创建接入并生成凭证
选择执行身份
先决定智能体应按谁的权限回答问题。这项选择决定应用后端需要传哪些凭据。
| 执行身份 | 适用场景 | 配置前准备 |
|---|---|---|
| 渠道 owner(默认) | 应用统一使用创建接入账号的权限、BI 凭据和记忆。例如,由专用服务账号提供固定范围的查询。 | 确认该账号可访问所需资源;应用自行控制哪些用户可以调用和查看结果。 |
| 系统用户 | 每位用户按自己的身份和 BI 权限提问。例如,不同经销商只能查询自己有权访问的数据。 | 后端能取得当前登录用户的 BI 用户 ID 和有效 BI Token,并确认用户有权使用目标智能体。 |
「系统用户」通过目标 BI 环境验证用户。Galaxy 部署使用组织的内置 BI 环境;Internal 部署使用智能体指定的 BI 环境,未指定时使用组织默认环境,该环境须已启用。
在渠道入口创建接入
- 打开目标智能体配置页,进入「发布与集成 > 渠道入口」,点击「API 接入」区域的添加按钮。
- 填写「接入名称」,例如「经销商门户 - 生产」,并选择上一步确定的「执行身份」。
- 按需设置以下两项,然后点击「创建 API 接入」:
- 浏览器允许来源:推荐由第三方应用后端调用。后端请求不携带
Origin时无需填写;浏览器直连时,按行填写第三方页面的来源,如https://portal.example.com,不要包含页面路径。 - 允许查看执行详情:仅在可信调用方需要排查问题时开启。详情可能包含命令、业务输出及错误信息。来源白名单不能代替应用的用户授权。
- 浏览器允许来源:推荐由第三方应用后端调用。后端请求不携带
生成并保存调用凭证
在刚创建的接入下点击「生成凭证」,立即复制并保存到第三方应用的后端配置。完整凭证只在生成时显示一次,不要写入浏览器代码、页面 URL 或日志。业务请求使用 Authorization: Bearer <调用凭证> 标明是哪个接入。
验证首次调用与续聊
准备用户身份
以下变量均由第三方应用后端提供:
DECIDEX_BASE_URL:当前 DecideX 实例地址,末尾不带/。SERVICE_AGENT_TOKEN:上一步生成的调用凭证。可先用此凭证请求GET /api/service-agent/access;返回的scope应为AGENT。这一步只验证接入凭证,不代表某个业务用户已获授权。EXTERNAL_USER_ID:「渠道 owner」模式填写第三方系统为当前登录用户分配的稳定 ID;「系统用户」模式填写 BI 用户 ID,必须与用户 Token 验证出的身份一致。
下面两条命令按默认的「渠道 owner」模式编写。使用「系统用户」时,两条命令都要额外加上 -H "Decidex-External-User-Token: $BI_USER_TOKEN",其中 BI_USER_TOKEN 是当前登录用户的有效 BI Token,不是接入凭证,也不是另行签发给 DecideX 的登录令牌。读取该会话历史、轨迹或文件时同样需要验证用户身份。
创建会话并发送首条消息
向同步对话接口传入 newSession。单智能体凭证已确定目标,所以不必另传 agentId。
curl -sS "$DECIDEX_BASE_URL/api/service-agent/chat" \
-H "Authorization: Bearer $SERVICE_AGENT_TOKEN" \
-H "Decidex-External-User-Id: $EXTERNAL_USER_ID" \
-H "Content-Type: application/json" \
-d '{"newSession":{"title":"经销商经营分析"},"message":"你可以帮我分析哪些经营问题?"}'
检查返回的 assistantMessage.content,并保存 sessionId。如果响应中已返回会话 ID,请先查看该会话,避免重复创建。
继续已有会话
将上一步返回的 ID 填入 sessionId。使用相同接入和用户身份,不再传 newSession。
curl -sS "$DECIDEX_BASE_URL/api/service-agent/chat" \
-H "Authorization: Bearer $SERVICE_AGENT_TOKEN" \
-H "Decidex-External-User-Id: $EXTERNAL_USER_ID" \
-H "Content-Type: application/json" \
-d '{"sessionId":"替换为首轮返回的会话 ID","message":"针对刚才的问题,我需要准备哪些数据?"}'
确认返回的是同一会话的后续回复。验证「系统用户」接入时,再以实际业务用户提问,核对可见数据范围是否符合其 BI 权限。
接入更多会话能力
如需异步对话、查询历史、查看运行轨迹、停止运行、提交反馈或读取交付文件,点击「渠道入口 > API 接入 > 查看接入文档」,按当前实例的接口说明调用。单智能体接入若按「系统用户」查询会话列表,应显式传 executionIdentity=EXTERNAL_USER;Internal 部署还需传目标 biEnvironmentId。
管理接入与凭证
- 修改执行身份:只影响新建会话。已有会话继续按创建时的身份执行和验证。
- 轮换凭证:先生成新凭证,在后端替换并验证调用,再吊销旧凭证。已吊销的凭证不能重新启用。
- 停用或删除:暂时下线时停用接入或凭证;确认不再使用时再删除接入。删除后无法通过该入口继续已有会话。停用或吊销不会自动停止已启动的运行;需要中止时使用停止接口。
常见问题
| 现象 | 优先检查 |
|---|---|
| 凭证被拒绝 | 确认应用后端传的是本接入的调用凭证,接入与凭证均已启用,凭证未被吊销。 |
| 「系统用户」能创建会话,但续聊失败 | 核对续聊使用的接入、会话 ID 和外部用户 ID;在请求中重新携带该用户的有效 BI Token。 |
| 能对话,但返回的数据不符合预期 | 「渠道 owner」检查创建接入账号的数据权限和连接器;「系统用户」检查目标 BI 环境、实际登录用户的权限及智能体可用的数据资源。 |
| 浏览器调用失败,后端调用正常 | 核对第三方页面的协议、域名和端口是否匹配允许来源。 |