常见问题

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

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

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

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

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

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

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

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

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

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

标准 SSE 协议，每条事件含 id（递增序号）、event（事件类型）、data（JSON 负载）三部分。完整事件类型与负载结构详见 SSE 事件结构。

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

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

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

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