提交任务后立即返回 requestId，客户端通过 /run/stream 接口读取 SSE 事件流。支持通过urlAttachments传入最多10个HTTPS URL附件，并可与attachmentIds同时使用。任务提交成功不代表URL附件已经导入完成，导入进度和失败结果需通过SSE事件或任务状态获取。可通过 capabilityConfig 限制本次运行可调用的工具和 Skill；不传时沿用智能体配置，传入时只能进一步收窄智能体已有能力。Finx服务传入非空白名单或黑名单时限制本次运行可用范围，白名单优先；空集合或不传时沿用智能体配置；限制会由本次运行派生的定时任务自动继承。可通过 environmentId 指定本次运行使用的沙箱环境（仅在隐式创建新会话时生效，已有会话沿用其原绑定环境），环境必须归属当前租户/应用，否则返回无权访问错误。未传 sessionId 和 bizKey 时可通过 projectId 创建项目会话；projectId 与二者互斥。vaultIds 可在隐式创建新会话时绑定当前应用空间密钥；已有会话沿用原密钥绑定，不传或空列表时不绑定密钥；密钥不归属当前租户/应用时返回无权访问错误。可通过 knowledgeLibraryIds 指定本次运行使用的知识库，非空时覆盖智能体已启用的集合，不传或空数组时回落到智能体已启用的集合；传入的知识库必须全部属于当前应用空间，只要有一个不属于本应用空间则整个请求返回无权访问。

可通过 virtualTools 声明本次运行的客户端展示工具，让模型产出一次结构化的渲染指令，由您的终端渲染图表、卡片等界面元素：服务端不执行您的任何代码，模型发起调用时按 parameters 校验参数，返回预设 mockResponse；省略或null使用默认success回执；调用内容从既有 SSE 事件流的 TOOL_CALL_GENERATING、TOOL_START、TOOL_COMPLETED 事件读取，渲染结果无需回传。该参数请求级生效，不写入会话默认工具也不被后续运行继承，重试失败运行时沿用原请求快照中的定义。工具定义整批由服务端校验，不合法时在运行启动之前整次请求失败并一次性返回全部问题，不会混进 SSE 事件流；不传时行为不变。

通过 requestId 订阅异步运行产生的 SSE 事件流，支持断线重连；事件带序号，保证不丢失、不重复。以下为完整事件手册。

一、SSE 协议约定

响应为标准 Server-Sent Events（Content-Type: text/event-stream），每条消息包含三个字段：

data 的统一结构（AgentEvent）：

{
  "eventType": "TEXT_DELTA",
  "data": { "type": "text", "text": "你好" },
  "timestamp": "2026-07-24T10:00:00",
  "step": 1,
  "totalTokens": 1234
}

回答结束时，MESSAGE_COMPLETED、MESSAGE_FAILED 的 data.usage 可携带回答用量快照： promptTokens、completionTokens、 cachedTokens、reasoningTokens、totalTokens 为当前助手消息累计 Token，不含压缩。 缓存命中率由 cachedTokens / promptTokens 计算，输入为 0 时不计算。 旧事件或无法取得统计时 usage 可为空。顶层 step 与 totalTokens 保持兼容。

二、事件目录（共 19 种）

会话事件

文本事件（最终回答正文）

推理事件（思考过程，非正文）

工具事件

权限确认事件

消息生命周期事件（终态，三选一收尾）

附件事件

补充输入事件

心跳事件

运行期状态事件

三、数据体字段说明（按 data.type）

session：sessionId（会话ID）、userMessageId（本轮用户消息ID）、assistantMessageId（本轮助手消息ID）。

text：text（文本内容，START 为初始文本、DELTA 为增量片段）、synthetic（是否系统合成文本，仅 TEXT_START 有值）。

reasoning：text（推理内容，语义同 text）。

tool：toolCallId（工具调用唯一标识，同一次调用的全部事件共享）、toolName（工具名）、title（进度标题，仅 TOOL_RUNNING）、arguments（调用参数 JSON：GENERATING 为增量片段、START 为完整参数）、output（执行结果，仅 TOOL_COMPLETED）、errorMessage（失败原因，仅 TOOL_FAILED）。

tool_side：toolCallId、toolName、category（事件分类，已知值：auth_required 用户授权缺失、tool_stream_data 工具流式数据；后续可能扩展）、payload（结构化数据，随 category 变化）、userMessage（用户友好提示，可选）。

permission_ask：askId（确认请求唯一标识，resumeTask 时需要）、principalId（身份主体ID）、toolName、toolCallId、arguments（待执行的工具参数 JSON）、ruleDescription（命中的权限规则描述）、rulePattern（规则匹配模式）。

permission_ask_resolved（预留）：askId、approved（是否批准）、reason（结果原因）、resolveType（预留字段）。

message：messageId（助手消息ID）；MESSAGE_COMPLETED 可含 finishReason（STOP 正常完成、MAX_STEPS 达到本次运行轮数上限）和 finishMessage（结束原因文本）。旧事件可能缺少这两个字段；客户端应兼容未来原因值。达到上限的提示也通过既有 synthetic TEXT_START/TEXT_END 展示并保存，完成事件中的 finishMessage 不应重复追加到正文；仅 MESSAGE_FAILED 有值：errorMessage（错误信息）、errorCode（错误码，见第五节）、recoverable（是否可从失败点重试续跑）、networkError（是否网络类瞬态错误）；仅 MESSAGE_SUSPENDED 有值：suspendReason（挂起原因对象，suspendReason.type 可选值：PERMISSION_ASK 权限确认等待、MANUAL_SUSPEND 外部主动挂起、SHUTDOWN_INTERRUPT 系统停机中断、ASYNC_TOOL_PENDING 异步工具等待完成）。

attachment：attachmentId（附件ID）、sessionId、messageId（可为空）、fileName（文件名）、fileExtension（扩展名如 pdf、xlsx）、contentType（MIME 类型）、fileSize（字节数）、virtualPath（虚拟文件路径，用于构造下载URL）、source（来源：USER_UPLOAD 用户上传 / AGENT_GENERATED 智能体生成）、changeType（变更类型：CREATED 新建 / UPDATED 内容覆盖更新）。

supplementary_input：inputId（补充输入ID）、content（文本内容）、userMessageId（注入后生成的用户消息ID）、assistantMessageId、attachmentIds（随补充输入注入的附件ID列表）。

agent_status：code（状态码，见第四节）、level（严重等级：INFO/WARN/ERROR）、message（用户可读文案，可直接展示）、attributes（结构化扩展属性，随 code 变化）。

四、AGENT_STATUS 状态码

处理约定：该事件不写入消息历史、不回灌模型上下文，任务结束后查询消息历史不可见；UI 不应持久化，建议渲染为瞬时提示。服务端未来可能新增状态码，客户端遇到未识别的 code 必须静默忽略（可兜底展示 message 文案）。

五、终态与错误处理

每次运行的事件流必然以 MESSAGE_COMPLETED、MESSAGE_SUSPENDED、MESSAGE_FAILED 三者之一收尾，随后 SSE 连接正常关闭；收到终态事件后客户端应主动断开，不要再重连。

MESSAGE_FAILED 的 errorCode 可选值：

MESSAGE_SUSPENDED 后的恢复方式：调用 /api/agent/run/resumeTask（PERMISSION_ASK 场景需携带 approved 决策），恢复成功后使用相同 requestId 重新连接本接口（携带 lastEventId）继续消费。

控制台兜底错误事件：当流初始化失败（如 requestId 不存在或无权访问）时，本接口会发送一条 event: error 的 SSE 消息，其 data 为空、错误信息位于 SSE 注释行（: 开头的行），随后连接关闭。客户端收到 error 事件应终止重连并提示用户。

六、断线重连

1. 消费过程中持续记录最近一条带 id 事件的 id 值（HEARTBEAT 无 id，跳过）；
2. 连接断开且未收到终态事件时，携带 lastEventId=<最近id> 重新调用本接口；
3. 服务端从 id+1 位置续推历史事件并无缝衔接实时事件，事件按序号连续、不丢不重；
4. 若不传 lastEventId，则从事件流起点（id=0）完整重放。

七、典型事件时序示例

一次包含推理、工具调用与附件产出的完整运行，事件顺序如下：

SESSION_CREATED
REASONING_START → REASONING_DELTA × N → REASONING_END
TOOL_CALL_GENERATING × N → TOOL_START → TOOL_RUNNING → TOOL_COMPLETED
ATTACHMENT_CHANGED
TEXT_START → TEXT_DELTA × N → TEXT_END
MESSAGE_COMPLETED

（期间可能穿插 HEARTBEAT、AGENT_STATUS、SUPPLEMENTARY_INPUT_CONSUMED，位置不固定）

关键事件的完整 SSE 报文示例：

id: 0
event: SESSION_CREATED
data: {"eventType":"SESSION_CREATED","data":{"type":"session","sessionId":9001,"userMessageId":10001,"assistantMessageId":10002},"timestamp":"2026-07-24T10:00:00"}

id: 5
event: TOOL_START
data: {"eventType":"TOOL_START","data":{"type":"tool","toolCallId":"call_abc123","toolName":"web_search","arguments":"{\"query\":\"沪深300走势\"}"},"timestamp":"2026-07-24T10:00:03","step":1,"totalTokens":856}

id: 12
event: TEXT_DELTA
data: {"eventType":"TEXT_DELTA","data":{"type":"text","text":"根据检索结果，"},"timestamp":"2026-07-24T10:00:06","step":2,"totalTokens":1420}

id: 20
event: MESSAGE_COMPLETED
data: {"eventType":"MESSAGE_COMPLETED","data":{"type":"message","messageId":10002,"finishReason":"STOP"},"timestamp":"2026-07-24T10:00:09","step":2,"totalTokens":2310}

八、客户端展示工具（virtualTools）的渲染指令消费

若在 /async 请求中声明了 virtualTools，模型对这些工具的调用不产生新的事件类型，完全复用上文的 TOOL_* 事件：

1. TOOL_CALL_GENERATING：按 toolCallId 拼接 arguments 增量，可用于展示"正在准备图表"之类的过渡态；
2. TOOL_START：arguments 为完整的渲染参数 JSON，是开始渲染的时机；
3. TOOL_COMPLETED：参数校验通过后，output 原样返回工具定义中的 mockResponse 字符串（包括空字符串）；省略或传入 null 时返回默认回执 {"status":"success"}。预设内容是模拟结果，不代表客户端已完成渲染或外部业务实际执行。

消费要点：

• 按 toolName 与自己声明的工具名匹配，即可把渲染指令与平台内置工具的调用区分开；未匹配上的工具名按普通工具处理；
• 服务端不执行调用方代码，渲染完全在客户端完成，渲染结果无需回传，也没有对应的回传接口；
• 渲染失败属于客户端内部问题，不影响运行主流程，事件流仍会照常推进到终态。

九、迁移进来的历史运行没有事件流

通过定时任务「迁移历史运行记录」接口登记的运行（triggerSource 为 imported）只是历史留痕， 没有真实的执行过程，因此不存在可订阅的事件流：用这类运行的 requestId 调用本接口会返回 409 冲突， 而不是返回一个空流。

需要展示这类历史对话时，请改用会话轨迹查询接口读取已落库的消息内容。原生运行的事件流行为不受影响。

十、兼容性约定

• 服务端事件类型、data.type、AGENT_STATUS 状态码均只增不删；
• 客户端遇到未识别的事件类型、data.type、状态码或新增字段时，必须静默忽略，不得报错中断消费；
• 字段可能为 null 或缺省，解析时需做好空值兼容。

按主体维度分页查询智能体运行记录列表，支持按状态和智能体ID过滤。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

根据请求ID查询单次智能体运行的完整信息，包括执行状态、步骤、Token消耗、错误信息等

根据请求ID一次性返回单次运行的用户输入（userInput）、智能体最终回复文本（assistantReply）和执行起止时间，无需再经「查询运行详情取assistantMessageId、查询消息部件、自行过滤拼接」三步流程。startedAt和completedAt为Unix毫秒时间戳；尚未开始时startedAt可能为空，未结束时completedAt可能为空，记录未提供的时间也为空，空时间字段在响应中省略。调用方应以status判断运行是否结束：COMPLETED、FAILED、CANCELLED为终态，CREATED、PROCESSING、SUSPENDED为非终态，不能仅凭completedAt是否有值判断。assistantReply取助手消息最后一个TEXT部件的完整文本，运行未结束时可能为空。若需要工具调用、推理思考等完整执行轨迹，请改用「会话管理」模块的消息部件查询接口（sessionListMessageParts）。

返回当前用户所有未完成的任务以及最近完成的任务，适用于前端定时轮询

按主体维度统计智能体运行记录数量，支持按状态和智能体ID过滤

向正在执行的智能体发送挂起信号，智能体会在下一个安全点优雅挂起

迁移进来的历史运行不支持本操作：通过定时任务「迁移历史运行记录」接口登记的运行（triggerSource 为 imported）只是历史留痕，没有真实的执行过程，对其调用本接口会返回 409 冲突。这类运行仅支持查询和随任务删除。原生运行的行为不受影响。

恢复处于挂起状态的智能体运行，系统根据挂起原因自动路由到对应恢复策略

迁移进来的历史运行不支持本操作：通过定时任务「迁移历史运行记录」接口登记的运行（triggerSource 为 imported）只是历史留痕，没有真实的执行过程，对其调用本接口会返回 409 冲突。这类运行仅支持查询和随任务删除。原生运行的行为不受影响。

立即终止正在执行或挂起的智能体运行，不可恢复

迁移进来的历史运行不支持本操作：通过定时任务「迁移历史运行记录」接口登记的运行（triggerSource 为 imported）只是历史留痕，没有真实的执行过程，对其调用本接口会返回 409 冲突。这类运行仅支持查询和随任务删除。原生运行的行为不受影响。

对已失败的智能体运行发起重试，返回新的 requestId，客户端可通过 /run/stream 接口读取事件流。原请求若声明过 virtualTools，重试时沿用原请求快照中的定义，无需重传。

迁移进来的历史运行不支持本操作：通过定时任务「迁移历史运行记录」接口登记的运行（triggerSource 为 imported）只是历史留痕，没有真实的执行过程，对其调用本接口会返回 409 冲突。这类运行仅支持查询和随任务删除。原生运行的行为不受影响。

在智能体运行过程中提交补充输入，内容会在下一个步骤边界被注入到对话上下文中

迁移进来的历史运行不支持本操作：通过定时任务「迁移历史运行记录」接口登记的运行（triggerSource 为 imported）只是历史留痕，没有真实的执行过程，对其调用本接口会返回 409 冲突。这类运行仅支持查询和随任务删除。原生运行的行为不受影响。

在补充输入被消费之前撤回已提交的补充输入

迁移进来的历史运行不支持本操作：通过定时任务「迁移历史运行记录」接口登记的运行（triggerSource 为 imported）只是历史留痕，没有真实的执行过程，对其调用本接口会返回 409 冲突。这类运行仅支持查询和随任务删除。原生运行的行为不受影响。

查看当前排队中的所有补充输入，不会消费队列内容

迁移进来的历史运行不支持本操作：通过定时任务「迁移历史运行记录」接口登记的运行（triggerSource 为 imported）只是历史留痕，没有真实的执行过程，对其调用本接口会返回 409 冲突。这类运行仅支持查询和随任务删除。原生运行的行为不受影响。