# 常见问题

关于点金智能体 Open API 的常见问题与解答。

## 环境与部署

**Q: 生产环境的 Base URL 是什么？**

`https://router.fis.aliyuncs.com/finx`

**Q: 接口超时建议设多少？**

普通接口建议 connectTimeout=10s, readTimeout=30s；SSE 流式接口建议 timeout=300s（5 分钟），因为智能体可能长时间思考。

## 认证与鉴权

**Q: 调用运行类接口报「身份相关错误」怎么办？**

API 接入**必须携带 `X-Principal-Id` 请求头**，这是区别于页面访问的关键点。所有运行类接口（创建会话/上传附件/提交对话/订阅事件）都需要此 Header。

**Q: API Key 的格式是什么？如何安全存储？**

格式为 `dk_` 前缀，仅在创建时明文展示一次。建议通过环境变量存储，不要硬编码在代码中。

**Q: Authorization 和 X-Principal-Id 的关系是什么？**

二者缺一不可。`Authorization` 标识应用身份（API Key），`X-Principal-Id` 标识操作主体（为每个最终用户/场景分配独立主体）。

## 身份与访问模式

**Q: App 模式和 User 模式有什么区别？**

User 模式面向终端用户，通过智能工作台或 IM 渠道直接使用，身份由平台自动管理。App 模式面向开发者，通过 API Key 接入，开发者自行创建和维护 Principal（身份主体）来隔离数据。详见 [身份主体与用户](/docs/quickstart/principal.md)。

**Q: App 模式下，我有 1000 个用户，需要创建 1000 个 Principal 吗？**

取决于是否需要对话数据互相隔离。需要隔离就为每个用户创建独立 Principal；不需要隔离则共享一个即可。

**Q: 一个 App 创建了 3 个 Agent，可以服务 1000 个用户吗？**

可以。Agent 决定"用哪个 AI"，Principal 决定"数据归谁"。为用户创建对应的 Principal，每次调用 API 时传入对应 Principal ID 即可。

**Q: 两种模式的 AI Agent 能力有区别吗？**

没有区别。底层调用同一套 Agent 引擎，只是接入方式和身份管理方式不同。

**Q: 通过API调用接入时，开发者需要维护用户 ID 与 Principal ID 的映射关系吗？**

是的。平台不感知开发者系统内部的用户体系，只提供 Principal 作为身份隔离标识。开发者创建 Principal 后，需在自己系统中记录「用户 A ↔ Principal X」的映射关系。

## SSE 事件流

**Q: SSE 事件流的格式是什么？**

标准 SSE 协议，每条事件含 `id`（递增序号）、`event`（事件类型）、`data`（JSON 负载）三部分。完整事件类型与负载结构详见 [SSE 事件结构](/docs/quickstart/data-model.md#data-sse)。

**Q: 如何判断任务结束？**

当本次运行结束（回答完成/失败/终止）时事件流自动关闭。也可调用 `GET /api/agent/run/getTask` 查询最终状态。

**Q: 连接中断如何重连？**

把已收到的最大事件 id 作为 `lastEventId` 参数重新发起请求，服务端从该序号之后续推，保证不丢失、不重复。

## 附件相关

**Q: 上传附件报错「不属于本会话」怎么办？**

`attachmentIds` 必须是当前用户上传、且属于同一 `sessionId` 的附件。推荐流程：先建会话 → 上传附件 → 带 sessionId 提交对话。

**Q: 附件接口的 Content-Type 应该用什么？**

使用 `multipart/form-data`（-F 方式），不要设 application/json。

### 快速导航

- [环境与部署 — Base URL、超时](#faq-deploy)
- [认证与鉴权 — 身份、Key、Header](#faq-auth)
- [身份与访问模式 — App vs User](#faq-principal)
- [SSE 事件流 — 格式、结束、重连](#faq-sse)
- [附件相关 — 归属、Content-Type](#faq-attachment)