多轮会话(Threads)、异步运行(Runs)与可恢复 SSE 事件流
本手册对应 Agentbase v2.10.0(控制台同版本)。
在智能体工作台(Agent Runtime)中,**会话(Thread) 与 运行(Run)** 构成了智能体交互的核心状态骨架:Thread 按业务用户(userId)连续承载多轮对话历史,而每一次用户提问都会触发一条异步执行的 Run。平台将后台持久化的任务状态机与前端有界、可恢复的 AG-UI SSE(Server-Sent Events)实时事件流 解耦设计——即使客户端网络中断或浏览器标签页关闭,后台 ReAct 推理任务依然可靠执行,重连后只需携带 Last-Event-ID 即可无缝续传或通过 message_seq 游标精确补齐最终消息。
功能概述
在企业生产环境中构建多轮排障助手或复杂业务 Agent 时,单次任务往往需要经历多次知识库检索、多次外部工具调用与长文本生成,耗时可能从数秒延伸至数分钟。传统的同步 HTTP 请求-响应模式在面对网关超时、移动端切后台断连或用户连点重复发送时显得极其脆弱。
Agent Runtime 的会话、异步运行与事件流子系统提供以下四大生产级保障:
- 按业务用户严格隔离的多轮会话生命周期(Threads):
- 支持为指定
userId(如user_zhangwei_001、user_lina_002)创建独立会话(POST /threads)、按最近更新时间倒序列出活跃会话(GET /threads?limit=100)、按会话内递增序号message_seq游标分页读取全量消息(GET /threads/{threadId}/messages),以及归档不再使用的会话(DELETE /threads/{threadId})。 - 归档会话与长期记忆解耦:归档会话(状态变为
ARCHIVED)仅结束当前对话窗口的展示,绝不会删除该用户在项目长期记忆(Memory)或 PowerContext 中沉淀的跨会话记忆与用户画像。
- 支持为指定
- 异步运行状态机、单会话并发串行锁与请求幂等重放(Runs):
- 提交任务(
POST /runs)立即返回 HTTP202 Accepted与run_id,任务在后台经历SUBMITTING$\rightarrow$QUEUED$\rightarrow$RUNNING$\leftrightarrow$WAITING_CLIENT_TOOL$\rightarrow$SUCCEEDED/FAILED/CANCELLED的完整状态流转。 - 单会话单活动任务约束:同一个
Thread在同一时刻最多只允许有一条未进入终态的Run(并发提交返回409 THREAD_BUSY),确保多轮上下文顺序严格一致。 - **原生
Idempotency-Key幂等保障**:重试同一条消息提交时携带相同的Idempotency-Key(1~128 字节),服务端直接返回原Run(HTTP200 OK且标记"idempotent_replay": true),杜绝网络抖动导致的重复扣费与重复工具执行。
- 提交任务(
- **标准 AG-UI SSE 实时事件流与
Last-Event-ID断点续传**: - 实时增量流(
GET /runs/{runId}/events)完整输出运行启停、模型思考片段(REASONING_*)、回答文本增量(TEXT_MESSAGE_*)、工具调用参数与结果通知(TOOL_CALL_*)以及平台扩展事件(CUSTOM)。 - 每个运行事件流默认在任务截止后保留 30 分钟(单次运行最多缓存约 8,192 条事件)。客户端断线重连时只需通过请求头
Last-Event-ID传入上次收到的外层帧id即可精准续传;若游标已超出保留窗口(返回409 stream_cursor_expired),客户端可先从持久化消息接口恢复已完成事实,再从earliest_event_id - 1续订剩余流。
- 实时增量流(
- 单步模型调用与 Token 明细审计(Model Invocations):
- 单次
Run可能包含多步模型推理、上下文自动精简与记忆调用。通过GET /runs/{runId}/model-invocations,可按步骤(model_step)与用途(AGENT_RESPONSE、CONTEXT_COMPACTION、MEMORY)逐笔核查输入/输出/缓存/思考 Token 消耗、上游请求 ID(provider_request_id)及单步耗时。
- 单次
核心概念与架构
异步运行(Run)全生命周期状态机
stateDiagram-v2
[*] --> SUBMITTING: POST /runs (202 Accepted)
SUBMITTING --> QUEUED: 任务持久化登记完成
QUEUED --> RUNNING: Worker 领取任务并加载 Config 快照
state RUNNING {
[*] --> PrepareContext: 读取 Thread 历史 + 召回 Memory/PowerContext
PrepareContext --> CompactContext: 逼近窗口预算时触发 Context Compaction
PrepareContext --> ModelStep: 预算充足
CompactContext --> ModelStep: 摘要生成完成
ModelStep --> ServerTool: 模型请求服务端工具 (Knowledge / Gateway MCP)
ServerTool --> ModelStep: 工具结果写回上下文,进入下一 model_step
}
RUNNING --> WAITING_CLIENT_TOOL: 模型请求 CLIENT 工具 (toolCallSource="CLIENT")
WAITING_CLIENT_TOOL --> QUEUED: 客户端 POST /runs/{runId}/tool-messages (202)
RUNNING --> SUCCEEDED: 模型输出最终回答 (发出 RUN_FINISHED)
RUNNING --> FAILED: 触发步骤/时长上限、上游模型错误或上下文超限 (发出 RUN_ERROR)
QUEUED --> CANCELLED: POST /runs/{runId}/cancel
WAITING_CLIENT_TOOL --> CANCELLED: POST /runs/{runId}/cancel
RUNNING --> CANCEL_REQUESTED: POST /runs/{runId}/cancel (202 Accepted)
CANCEL_REQUESTED --> CANCELLED: Worker 确认停止当前步 (发出 appbase.run.cancelled)
SUCCEEDED --> [*]
FAILED --> [*]
CANCELLED --> [*]Run 状态枚举与客户端处理规范表
状态值 (status) | 是否终态 | 状态含义说明 | 客户端与业务后端标准处理方式 |
|---|---|---|---|
**SUBMITTING** | 否(进行中) | 请求已通过鉴权并进入持久化登记阶段。 | 保存 run_id,继续轮询状态或建立 SSE 订阅,切勿重复发起新请求。 |
**QUEUED** | 否(进行中) | 任务已进入调度队列(或刚收到客户端工具结果重新入队),等待 Worker 执行。 | 保持观察;此时该 Thread 已处于占用状态,不可提交第二条 Run。 |
**RUNNING** | 否(进行中) | Worker 正在执行多轮 ReAct 推理、检索或服务端工具调用。 | 通过 SSE 实时渲染推理与回答增量;如需中途终止,必须显式调用 POST /runs/{runId}/cancel。 |
**WAITING_CLIENT_TOOL** | 否(暂停等待) | 模型发出了 toolCallSource: "CLIENT" 的客户端工具调用,正在等待应用回传结果。 | 注意:此时会话仍被该 Run 占用(非空闲)。应用需执行本地工具并调用 POST /runs/{runId}/tool-messages 恢复同一条 Run,或调用 /cancel 取消。 |
**CANCEL_REQUESTED** | 否(取消过渡态) | 已受理取消请求(HTTP 202),正在等待当前执行中的模型或工具步骤安全退出。 | 继续查询或监听事件,直到状态最终变为 CANCELLED(或恰在取消前已完成变为 SUCCEEDED)。 |
**SUCCEEDED** | 是(成功终态) | 本次任务顺利完成,最终 ASSISTANT 消息已持久化落库。 | 调用 GET /runs/{runId}/messages 或 /threads/{threadId}/messages 读取权威持久化消息与引用来源,释放会话输入锁。 |
**FAILED** | 是(失败终态) | 任务因模型限流、上下文超限、超时(RUN_DEADLINE_EXCEEDED)等原因终止。 | 读取 Run.error(含 code 与 message)展示友好提示,并检查已保存的部分消息或 model-invocations 排查根因。 |
**CANCELLED** | 是(取消终态) | 任务已按用户或系统请求确认取消。 | 重要边界:取消仅停止后续推理步骤,无法自动回滚已发生的外部业务副作用(如已调用的外部写接口),需按业务幂等键核对外部状态。 |
角色、入口与关联关系
会话、运行、事件与模型调用接口矩阵
本篇涉及的 11 个接口全部属于用户级数据面资源,使用项目 API Key(Scope:agent-runtime.project)调用时,**每次请求均必须显式传入目标业务用户的 userId**(POST 放 JSON 请求体,GET/DELETE 放 URL Query 参数):
| 接口分类 | HTTP 方法与完整路径 | userId 传参位置 | 成功状态码 | 响应结构与核心用途 |
|---|---|---|---|---|
| 创建会话 | POST /v1/agent-runtime/project/threads | JSON 正文 | 201 Created | 返回 Thread({thread_id, title, status: "ACTIVE"}) |
| 列出会话 | GET /v1/agent-runtime/project/threads | URL Query | 200 OK | 支持 limit(默认 100,范围 1~1000),按最近更新时间倒序返回 Thread[] 数组 |
| 查询单会话 | GET /v1/agent-runtime/project/threads/{threadId} | URL Query | 200 OK | 返回指定 thread_id 的 Thread 元数据 |
| 归档会话 | DELETE /v1/agent-runtime/project/threads/{threadId} | URL Query | 204 No Content | 将会话归档(ARCHIVED);归档前需确保无活动中的 Run |
| 读取会话消息 | GET /v1/agent-runtime/project/threads/{threadId}/messages | URL Query | 200 OK | 支持 after(默认 0,传入 message_seq)与 limit(1~1000),返回整段会话的 Message[] |
| 创建并提交运行 | POST /v1/agent-runtime/project/runs | JSON 正文 | 202 Accepted(幂等重放 200 OK) | 传入 {userId, thread_id, user_message} 及可选 Idempotency-Key 头,返回 Run |
| 查询运行状态 | GET /v1/agent-runtime/project/runs/{runId} | URL Query | 200 OK | 返回 Run({run_id, status, created_at, idempotent_replay?, error?}) |
| 取消运行 | POST /v1/agent-runtime/project/runs/{runId}/cancel | JSON 正文 | 202 Accepted 或 200 OK | 传入 {"userId": "..."} 请求停止当前 Run,返回 CANCEL_REQUESTED 或终态 Run |
| 读取单次运行消息 | GET /v1/agent-runtime/project/runs/{runId}/messages | URL Query | 200 OK | 仅返回本次 run_id 产生的 Message[],分页参数 after / limit 同会话消息 |
| 订阅 SSE 事件流 | GET /v1/agent-runtime/project/runs/{runId}/events | URL Query | 200 OK(游标过期 409) | Header 携带 Accept: text/event-stream 及续传时的 Last-Event-ID,实时推送 AG-UI 事件流 |
| 读取模型调用记录 | GET /v1/agent-runtime/project/runs/{runId}/model-invocations | URL Query | 200 OK | 返回 {items: ModelInvocation[]},审计本次 Run 内每一跳模型调用的 Token 与耗时 |
功能详解与操作指南
1. 多轮会话(Threads)全生命周期管理与 message_seq 游标分页
1. 在 Console 工作台中管理会话与查看执行时间线
- 进入
/console/project-default-enterprise-ai-hub-210/agent-runtime,左侧会话栏列出当前已创建的活跃会话(ACTIVE)。 - 单击左上角 **
+(新建会话)** 即可开启全新的对话上下文;单击已有会话条目可立即切换并从持久化消息库中恢复完整历史。 - 在对话流中,单击任意一轮回答上方的 展开执行过程(Execution Steps) 折叠条,即可逐跳查看模型在本轮 Run 中的思考过程(Reasoning)、调用的工具名称与参数、知识库检索状态以及是否触发了上下文自动精简。
2. 通过 API 创建、列出、游标分页拉取消息与归档会话
export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"
export APPBASE_API_KEY="<APPBASE_API_KEY>"
# 1. 为用户 user_zhangwei_001 创建新会话(POST 请求将 userId 放在 JSON 正文中)
curl -fsSL -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/threads" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"userId": "user_zhangwei_001"
}'
# 2. 列出该用户最近更新的前 50 条活跃会话(GET 请求将 userId 放在 Query 中)
curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/threads?userId=user_zhangwei_001&limit=50" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}"**按 message_seq 游标分页读取会话历史消息(GET /threads/{threadId}/messages)**: 持久化消息按会话内严格递增的整数 message_seq(从 1 开始)排序。首次拉取传 after=0&limit=100;若返回了满页数据,翻下一页时取本页最后一条消息的 message_seq 作为下一次请求的 after 参数(**注意:message_seq 是持久化消息序号,切勿与 SSE 事件流的 id 混用**):
# 读取会话中 message_seq > 0 的前 100 条消息
curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/threads/thd_01j8x9k2m4n6p8q0r2s4t6u8v0/messages?userId=user_zhangwei_001&after=0&limit=100" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}"**持久化 Message 对象四类 message_type 结构详解**:
message_type | payload JSON 值类型 | tool_call_id | 典型 payload 示例与业务解析要点 |
|---|---|---|---|
**USER** | string(纯文本字符串) | null | "OceanBase 报 4013 向量内存不足怎么排查?"(注意:直接是字符串,不是 {"content": "..."} 对象) |
**ASSISTANT** | string(纯文本字符串) | null | "针对错误码 4013 (OB_ALLOCATE_MEMORY_FAILED),请按以下步骤排查..."(含关联的 trace_id) |
**TOOL_CALL** | object(结构化 JSON) | "call_kb_001" | {"call_id": "call_kb_001", "tool_name": "knowledge_retrieve", "arguments": {"query": "OceanBase 4013 OB_ALLOCATE_MEMORY_FAILED"}, "source": "SERVER"} |
**TOOL_RESULT** | object(结构化 JSON) | "call_kb_001" | 包含工具返回的真实结构化结果(如知识库检索命中的文档标题、切片正文与得分),前端展示知识引用来源(Citations)必须从此处读取。 |
**归档会话(DELETE /threads/{threadId})**: 当某段测试或客服工单会话结束后,確認该会话下没有正在运行的 Run,即可调用 DELETE 将其归档(返回 204 No Content):
curl -i -X DELETE "${APPBASE_ENDPOINT}/agent-runtime/project/threads/thd_01j8x9k2m4n6p8q0r2s4t6u8v0?userId=user_zhangwei_001" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}"2. 提交异步运行(Run)、幂等重放与显式取消操作
1. 带 Idempotency-Key 提交任务(POST /v1/agent-runtime/project/runs)
curl -fsSL -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/runs" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Idempotency-Key: zhangwei-thd01-turn02-20261022" \
-d '{
"userId": "user_zhangwei_001",
"thread_id": "thd_01j8x9k2m4n6p8q0r2s4t6u8v0",
"user_message": "请结合知识库进一步说明 ob_vector_memory_limit_percentage 参数的推荐配置比例。"
}'- 首次成功受理:返回 HTTP
202 Accepted及{"run_id": "run_01j8x9p1q2r3s4t5u6v7w8x9y0", "status": "QUEUED", "created_at": "2026-10-22T09:20:00Z"}。 - **相同
Idempotency-Key+ 相同请求体网络重试**:返回 HTTP200 OK及原Run对象,且附带"idempotent_replay": true,不会重复创建任务。 - **相同
Idempotency-Key+ 不同请求体**:返回 HTTP409 IDEMPOTENCY_KEY_CONFLICT。
2. 为什么关闭浏览器或断开 SSE 不会取消正在执行的 Run?
Agent Runtime 是服务端状态驱动的异步引擎。SSE 连接仅是观察任务进度的“只读望远镜”,断开 SSE 连接或关闭网页不会向 Worker 发送中断信号。若业务上确实需要中止一条正在排队(QUEUED)、运行中(RUNNING)或等待客户端工具(WAITING_CLIENT_TOOL)的任务,**必须显式调用取消接口(POST /runs/{runId}/cancel) 或单击控制台输入框旁的 停止(Cancel)** 按钮:
# 显式请求取消正在运行的 Run(POST 请求将 userId 放在 JSON 正文中)
curl -fsSL -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9p1q2r3s4t5u6v7w8x9y0/cancel" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"userId": "user_zhangwei_001"
}'**预期响应(HTTP 202 Accepted)**:
{
"run_id": "run_01j8x9p1q2r3s4t5u6v7w8x9y0",
"status": "CANCEL_REQUESTED",
"created_at": "2026-10-22T09:20:00Z"
}随后 Worker 停止后续步骤,将该 Run 置为终态 "status": "CANCELLED"。
3. AG-UI SSE 事件流全量协议规范与 Last-Event-ID 断点续传
1. AG-UI SSE 事件类型(type)全表
连接 GET /v1/agent-runtime/project/runs/{runId}/events?userId=... 后,服务端以标准 text/event-stream 格式推送事件帧。每帧包含外层可选游标 id: <integer>、event: <TYPE> 与 data: <JSON>:
事件 type | data JSON 核心字段(除 type、timestamp 外) | 事件触发时机与客户端处理规范 | |
|---|---|---|---|
**RUN_STARTED** | runId: string, threadId: string | Run 开始执行;前端初始化加载动画与步骤时间线容器。 | |
**REASONING_START / REASONING_END** | messageId: string | 标记模型思考阶段(Reasoning)的开始与结束。 | |
**REASONING_MESSAGE_START** | messageId: string, role: "reasoning" | 创建深度思考内容折叠块。 | |
**REASONING_MESSAGE_CONTENT** | messageId: string, delta: string | 按 messageId 流式追加模型思考片段文本。 | |
**REASONING_MESSAGE_END** | messageId: string | 当前思考消息片段输出完毕。 | |
**TOOL_CALL_START** | toolCallId: string, toolCallName: string, `toolCallSource: "SERVER" \ | "CLIENT"` | 模型发起工具调用;客户端按 toolCallId 创建工具调用状态卡片(注意同一轮可能并行出现多个不同 toolCallId)。 |
**TOOL_CALL_ARGS** | toolCallId: string, toolCallSource: string, delta: string | 按 toolCallId 拼接工具参数 JSON 字符串片段(服务端内部工具在 SSE 中可能脱敏显示为 {"redacted":true})。 | |
**TOOL_CALL_END** | toolCallId: string, toolCallSource: string | 工具参数传输完毕。若 toolCallSource === "CLIENT",此时应查询 Run 状态确认进入 WAITING_CLIENT_TOOL 并执行本地工具。 | |
**TOOL_CALL_RESULT** | toolCallId: string, messageId: string, role: "tool", content: string | 通知该 toolCallId 的工具结果已提交(SSE 中默认简写为 {"status":"completed"},完整结构化结果通过持久化 messages 接口读取)。 | |
**TEXT_MESSAGE_START** | messageId: string, role: "assistant" | 创建智能体回答正文气泡容器。 | |
**TEXT_MESSAGE_CONTENT** | messageId: string, delta: string | 按 messageId 流式追加 Markdown 回答正文增量。 | |
**TEXT_MESSAGE_END** | messageId: string | 本段回答文本流式输出结束(注意:不代表整次 Run 已结束,等待 RUN_FINISHED)。 | |
**RUN_FINISHED** | runId: string, threadId: string | 整次 Run 执行完毕;客户端拉取 GET /runs/{runId} 与 GET /runs/{runId}/messages 校验终态与知识引用。 | |
**RUN_ERROR** | runId: string, threadId: string, message: string, code?: string | 运行期发生异常或取消;停止流式等待并读取 GET /runs/{runId} 终态详情。 | |
**CUSTOM** | name: string, value: object | 平台扩展事件(详见下方 CUSTOM 事件字典表)。 |
2. CUSTOM 平台扩展事件字典表
CUSTOM 事件 name | value 对象字段结构 | 触发场景与客户端应对动作 | ||
|---|---|---|---|---|
**appbase.context.compaction** | `{runId, threadId, status: "started" \ | "completed" \ | "failed", eventSeq: integer, failureCode?: string}` | 会话历史触发自动上下文精简。前端可在时间线中展示“正在精简早期对话上下文 / 已完成上下文精简”标记。 |
**appbase.run.cancelled** | {runId: string} | 任务取消确认通知(随后可能伴随 code="RUN_CANCELLED" 的 RUN_ERROR 事件)。最终以 Run.status === "CANCELLED" 为准。 | ||
**appbase.stream.attempt_aborted** | {runId, threadId, abandonedInvocationId: string, oldWorkerEpoch: integer, newWorkerEpoch: integer} | 因底层 Worker 故障接管(Failover),上一轮未完成的临时流式输出尝试被放弃。客户端应丢弃该未完成消息的临时流式拼接缓存,并以持久化消息接口为准重新对齐展示。 |
3. 使用 Last-Event-ID 断点续传与处理 409 stream_cursor_expired
客户端在解析 SSE 流时,应实时记录最近收到的非空外层帧 id(例如 id: 24)。当网络闪断重连时,在请求头中携带 Last-Event-ID: 24:
# 从上次收到的事件游标 id=24 之后继续订阅同一条 Run 的事件流
curl -N -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9p1q2r3s4t5u6v7w8x9y0/events?userId=user_zhangwei_001" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
-H "Accept: text/event-stream" \
-H "Last-Event-ID: 24"若客户端断线时间超过 30 分钟,或该 Run 产生的事件数超过了有界缓存窗口(约 8,192 条),致使传入的 Last-Event-ID 已被清理,服务端将返回 **HTTP 409 Conflict**:
{
"code": "stream_cursor_expired",
"earliest_event_id": 120,
"latest_event_id": 385
}标准恢复步骤:
- 先调用
GET /v1/agent-runtime/project/runs/{runId}?userId=...与GET .../runs/{runId}/messages?userId=...恢复所有已持久化的消息和当前运行状态; - 若该 Run 仍在运行(
RUNNING)且需继续监听剩余实时流,将Last-Event-ID更新为earliest_event_id - 1(即119)重新发起 SSE 连接。
4. 审计单次运行的模型调用明细(GET /runs/{runId}/model-invocations)
当一次 Run 涉及多轮工具调用或上下文精简时,可通过 model-invocations 接口精确核算每一跳模型调用的 Token 成本与耗时:
curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9p1q2r3s4t5u6v7w8x9y0/model-invocations?userId=user_zhangwei_001" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}"**预期响应(HTTP 200 OK)**:
{
"items": [
{
"invocation_id": "inv_01j8x9p2a1b2c3d4e5f6g7h8j9",
"model_step": 1,
"purpose": "AGENT_RESPONSE",
"attempt": 1,
"model_id": "qwen-plus",
"input_tokens": 1850,
"output_tokens": 95,
"cached_tokens": 1024,
"reasoning_tokens": null,
"provider_usage_available": true,
"provider_request_id": "req-dashscope-987654321",
"duration_ms": 1120,
"status": "SUCCEEDED",
"started_at": "2026-10-22T09:20:01Z",
"finished_at": "2026-10-22T09:20:02.120Z"
},
{
"invocation_id": "inv_01j8x9p5k9m8n7p6q5r4s3t2u1",
"model_step": 2,
"purpose": "AGENT_RESPONSE",
"attempt": 1,
"model_id": "qwen-plus",
"input_tokens": 3420,
"output_tokens": 410,
"cached_tokens": 1536,
"reasoning_tokens": null,
"provider_usage_available": true,
"provider_request_id": "req-dashscope-987654399",
"duration_ms": 2340,
"status": "SUCCEEDED",
"started_at": "2026-10-22T09:20:03Z",
"finished_at": "2026-10-22T09:20:05.340Z"
}
]
}审计字段解读:
purpose:区分该次调用是主模型推理(AGENT_RESPONSE)、自动上下文精简(CONTEXT_COMPACTION)还是记忆相关处理(MEMORY)。status:支持RUNNING、SUCCEEDED、FAILED、CANCELLED或ABANDONED(Worker 重试或故障切换时被放弃的尝试)。duration_ms:仅代表该单步模型推理耗时,不等同于整次 Run 的端到端总耗时(整次 Run 还包括排队、知识库检索与外部工具等待时间)。
常见问题与排障
Q1:向已有会话提交新消息时返回 HTTP 409 THREAD_BUSY 是什么原因?
原因与排查步骤: Agent Runtime 强制保证单个 Thread 内同时最多只有一条活动中的 Run。当上一条 Run 仍处于 SUBMITTING、QUEUED、RUNNING、WAITING_CLIENT_TOOL 或 CANCEL_REQUESTED 状态时,向同一 thread_id 提交新 Run 即会返回 409 THREAD_BUSY。
- 排查方法:调用
GET /v1/agent-runtime/project/runs/{lastRunId}?userId=...检查上一条任务的状态: - 若处于
WAITING_CLIENT_TOOL:说明上一轮触发了客户端工具调用但应用尚未回传结果,请先调用POST /runs/{runId}/tool-messages回传工具结果,或调用POST /runs/{runId}/cancel取消上一条任务; - 若处于
RUNNING:等待其自然结束或显式调用/cancel后再发送新消息。
- 若处于
Q2:为什么刷新控制台页面或重连后,之前看到的某段“思考过程(Reasoning)”片段消失了,但最终回答和工具结果都在?
原因与排查步骤: 这是由临时流式事件与持久化消息的分层设计决定的:
- 用户输入(
USER)、模型最终回答(ASSISTANT)、工具调用(TOOL_CALL)与工具结果(TOOL_RESULT)作为权威事实写入持久化消息表,永久可查; - 而模型流式输出的中间思考增量(
REASONING_MESSAGE_CONTENT)仅通过有界 SSE 事件流实时广播,不作为独立持久化消息永久存储。因此超出事件流保留窗口或全页刷新重新拉取/messages时,页面仅还原持久化消息与工具步骤。
Q3:为什么 SSE 订阅已经返回了 HTTP 200 OK,但随后任务仍然执行失败了?
原因与排查步骤: SSE 连接建立时返回的 HTTP 200 OK 仅表示事件流订阅通道握手成功,并不代表后台异步 Run 已经执行成功。如果在后续推理步骤中遇到上游模型限流(MODEL_RATE_LIMITED)、模型服务报错(MODEL_UPSTREAM_FAILED)或超过最大运行时长(RUN_DEADLINE_EXCEEDED),HTTP 状态码不会回退为 500,而是通过 SSE 推送一条 event: RUN_ERROR 事件并将 Run.status 更新为 FAILED。客户端必须在收到 RUN_FINISHED 或 RUN_ERROR 后以 GET /runs/{runId} 的终态为准。