Docs
文档目录

多轮会话(Threads)、异步运行(Runs)与可恢复 SSE 事件流

在智能体工作台(Agent Runtime)中,会话(Thread) 与 运行(Run) 构成了智能体交互的核心状态骨架:Thread 按业务用户(userId)连续承载多轮对话历史,而每一次用户提问都会触发一条异步执行的 Run。运行状态与 AG-UI SSE(Server-Sent Events)实时事件流 分别管理。客户端断线后,可在事件仍处于保留窗口内时使用 Last-Event-ID 续订;窗口过期或事件未保留时,查询运行状态及已保存消息。message_seq 是消息游标,与事件游标不同。


功能概述

在企业生产环境中构建多轮排障助手或复杂业务 Agent 时,单次任务往往需要经历多次知识库检索、多次外部工具调用与长文本生成,耗时可能从数秒延伸至数分钟。传统的同步 HTTP 请求-响应模式在面对网关超时、移动端切后台断连或用户连点重复发送时显得极其脆弱。

Agent Runtime 的会话、异步运行与事件流子系统提供以下四大生产级保障:

  1. 按业务用户严格隔离的多轮会话生命周期(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 中沉淀的跨会话记忆与用户画像。

  2. 异步运行状态机、单会话并发串行锁与请求幂等重放(Runs):

    • 提交任务(POST /runs)立即返回 HTTP 202 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(HTTP 200 OK 且标记 "idempotent_replay": true),避免重复创建运行。外部工具可能产生业务副作用;结果不确定时应先核对外部状态,不能把请求幂等视为对外部执行或计费的绝对保证。

  3. 标准 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 决定是否续订剩余流。缓存整个不存在时,服务可能依据运行状态返回回退事件,不一定返回 409。

  4. 单步模型调用与 Token 明细审计(Model Invocations):

    • 单次 Run 可能包含多步模型推理、上下文自动精简与记忆调用。通过 GET /runs/{runId}/model-invocations,可按步骤(model_step)与用途(AGENT_RESPONSE、CONTEXT_COMPACTION、MEMORY)逐笔核查输入/输出/缓存/思考 Token 消耗、上游请求 ID(provider_request_id)及单步耗时。


核心概念与架构

异步运行(Run)全生命周期状态机

多轮会话(Threads)、异步运行(Runs)与可恢复 SSE 事件流:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

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/threadsJSON 正文201 Created返回 Thread({thread_id, title, status: "ACTIVE"})
列出会话GET /v1/agent-runtime/project/threadsURL Query200 OK支持 limit(默认 100,范围 1~1000),按最近更新时间倒序返回 Thread[] 数组
查询单会话GET /v1/agent-runtime/project/threads/{threadId}URL Query200 OK返回指定 thread_id 的 Thread 元数据
归档会话DELETE /v1/agent-runtime/project/threads/{threadId}URL Query204 No Content将会话归档(ARCHIVED);归档前需确保无活动中的 Run
读取会话消息GET /v1/agent-runtime/project/threads/{threadId}/messagesURL Query200 OK支持 after(默认 0,传入 message_seq)与 limit(1~1000),返回整段会话的 Message[]
创建并提交运行POST /v1/agent-runtime/project/runsJSON 正文202 Accepted(幂等重放 200 OK)传入 {userId, thread_id, user_message} 及可选 Idempotency-Key 头,返回 Run
查询运行状态GET /v1/agent-runtime/project/runs/{runId}URL Query200 OK返回 Run({run_id, status, created_at, idempotent_replay?, error?})
取消运行POST /v1/agent-runtime/project/runs/{runId}/cancelJSON 正文202 Accepted 或 200 OK传入 {"userId": "..."} 请求停止当前 Run,返回 CANCEL_REQUESTED 或终态 Run
读取单次运行消息GET /v1/agent-runtime/project/runs/{runId}/messagesURL Query200 OK仅返回本次 run_id 产生的 Message[],分页参数 after / limit 同会话消息
订阅 SSE 事件流GET /v1/agent-runtime/project/runs/{runId}/eventsURL Query200 OK(游标过期 409)Header 携带 Accept: text/event-stream 及续传时的 Last-Event-ID,实时推送 AG-UI 事件流
读取模型调用记录GET /v1/agent-runtime/project/runs/{runId}/model-invocationsURL Query200 OK返回 {items: ModelInvocation[]},审计本次 Run 内每一跳模型调用的 Token 与耗时

功能详解与操作指南

1. 多轮会话(Threads)全生命周期管理与 message_seq 游标分页

1. 在 Console 工作台中管理会话与查看执行时间线

  1. 进入 /console/project-default-enterprise-ai-hub-210/agent-runtime,左侧会话栏列出当前已创建的活跃会话(ACTIVE)。

  2. 单击 创建会话 开始新的对话;单击 会话 可选择已有会话并读取已保存消息。

  3. 单击回答上方的 运行过程 查看运行状态及可用步骤;如逐步事件未保留,页面会提示事件不可用,但仍可查看已保存回复。需要进一步排查时,可单击 查看运行 Trace。

运行过程面板示例

图:测试项目中一次已完成的运行;运行 ID 已遮挡。本例未保留逐步事件,实际展示内容取决于事件是否可用。

2. 通过 API 创建、列出、游标分页拉取消息与归档会话

步骤 1: 创建会话;确认 HTTP 2xx 和返回内容。

(
  set +x
  set -e -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/threads" -i \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "Content-Type: application/json" \
    -d '{
      "userId": "user_zhangwei_001"
    }'
)

步骤 2: 查询会话;仅在创建成功后单独执行。

(
  set +x
  set -e -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/threads?userId=user_zhangwei_001&limit=50" -i \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}"
)

按 message_seq 游标分页读取会话历史消息(GET /threads/{threadId}/messages): 持久化消息按会话内严格递增的整数 message_seq(从 1 开始)排序。首次拉取传 after=0&limit=100;若返回了满页数据,翻下一页时取本页最后一条消息的 message_seq 作为下一次请求的 after 参数(注意:message_seq 是持久化消息序号,切勿与 SSE 事件流的 id 混用):

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 读取会话中 message_seq > 0 的前 100 条消息
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -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}" \
  --header @-
)

持久化 Message 对象四类 message_type 结构详解:

message_typepayload JSON 值类型tool_call_id典型 payload 示例与业务解析要点
USERstring(纯文本字符串)null"OceanBase 报 4013 向量内存不足怎么排查?"(注意:直接是字符串,不是 {"content": "..."} 对象)
ASSISTANTstring(纯文本字符串)null"针对错误码 4013 (OB_ALLOCATE_MEMORY_FAILED),请按以下步骤排查..."(含关联的 trace_id)
TOOL_CALLobject(结构化 JSON)"call_kb_001"{"call_id": "call_kb_001", "tool_name": "knowledge_retrieve", "arguments": {"query": "OceanBase 4013 OB_ALLOCATE_MEMORY_FAILED"}, "side_effect_free": true}
TOOL_RESULTobject(结构化 JSON)"call_kb_001"包含工具返回的结构化结果。知识库检索结果可能包含切片、得分和来源信息;应按实际返回字段展示引用,空结果或缺少来源时不应虚构。

归档会话(DELETE /threads/{threadId}): 当某段测试或客服工单会话结束后,確認该会话下没有正在运行的 Run,即可调用 DELETE 将其归档(返回 204 No Content):

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -i -X DELETE "${APPBASE_ENDPOINT}/agent-runtime/project/threads/thd_01j8x9k2m4n6p8q0r2s4t6u8v0?userId=user_zhangwei_001" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @-
)

2. 提交异步运行(Run)、幂等重放与显式取消操作

1. 带 Idempotency-Key 提交任务(POST /v1/agent-runtime/project/runs)

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/runs" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -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": "请结合知识库说明如何根据数据库版本和日志定位内存分配错误。"
    }'
)

2. 为什么关闭浏览器或断开 SSE 不会取消正在执行的 Run?

Agent Runtime 是服务端状态驱动的异步引擎。SSE 连接仅是观察任务进度的“只读望远镜”,断开 SSE 连接或关闭网页不会向 Worker 发送中断信号。若业务上确实需要中止一条正在排队(QUEUED)、运行中(RUNNING)或等待客户端工具(WAITING_CLIENT_TOOL)的任务,必须显式调用取消接口(POST /runs/{runId}/cancel) 或单击控制台输入框旁的 停止(Cancel) 按钮:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 显式请求取消正在运行的 Run(POST 请求将 userId 放在 JSON 正文中)
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9p1q2r3s4t5u6v7w8x9y0/cancel" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -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>:

事件 typedata JSON 核心字段(除 type、timestamp 外)事件触发时机与客户端处理规范
RUN_STARTEDrunId: string, threadId: stringRun 开始执行;前端初始化加载动画与步骤时间线容器。
REASONING_START / REASONING_ENDmessageId: string标记模型思考阶段(Reasoning)的开始与结束。
REASONING_MESSAGE_STARTmessageId: string, role: "reasoning"创建深度思考内容折叠块。
REASONING_MESSAGE_CONTENTmessageId: string, delta: string按 messageId 流式追加模型思考片段文本。
REASONING_MESSAGE_ENDmessageId: string当前思考消息片段输出完毕。
TOOL_CALL_STARTtoolCallId: string, toolCallName: string, toolCallSource: "SERVER" | "CLIENT"模型发起工具调用;客户端按 toolCallId 创建工具调用状态卡片(注意同一轮可能并行出现多个不同 toolCallId)。
TOOL_CALL_ARGStoolCallId: string, toolCallSource: string, delta: string按 toolCallId 拼接工具参数 JSON 字符串片段(服务端内部工具在 SSE 中可能脱敏显示为 {"redacted":true})。
TOOL_CALL_ENDtoolCallId: string, toolCallSource: string工具参数传输完毕。若 toolCallSource === "CLIENT",此时应查询 Run 状态确认进入 WAITING_CLIENT_TOOL 并执行本地工具。
TOOL_CALL_RESULTtoolCallId: string, messageId: string, role: "tool", content: string通知该 toolCallId 的工具结果已提交(SSE 中默认简写为 {"status":"completed"},完整结构化结果通过持久化 messages 接口读取)。
TEXT_MESSAGE_STARTmessageId: string, role: "assistant"创建智能体回答正文气泡容器。
TEXT_MESSAGE_CONTENTmessageId: string, delta: string按 messageId 流式追加 Markdown 回答正文增量。
TEXT_MESSAGE_ENDmessageId: string本段回答文本流式输出结束(注意:不代表整次 Run 已结束,等待 RUN_FINISHED)。
RUN_FINISHEDrunId: string, threadId: string整次 Run 执行完毕;客户端拉取 GET /runs/{runId} 与 GET /runs/{runId}/messages 校验终态与知识引用。
RUN_ERRORrunId: string, threadId: string, message: string, code?: string运行期发生异常或取消;停止流式等待并读取 GET /runs/{runId} 终态详情。
CUSTOMname: string, value: object平台扩展事件(详见下方 CUSTOM 事件字典表)。

2. CUSTOM 平台扩展事件字典表

CUSTOM 事件 namevalue 对象字段结构触发场景与客户端应对动作
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:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 从上次收到的事件游标 id=24 之后继续订阅同一条 Run 的事件流
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -N -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9p1q2r3s4t5u6v7w8x9y0/events?userId=user_zhangwei_001" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -H "Accept: text/event-stream" \
  -H "Last-Event-ID: 24"
)

当事件缓存仍有记录,但传入的 Last-Event-ID 落后于最早可续传事件时,服务端可能返回 HTTP 409 Conflict。保留期限不以客户端断线时刻计算;如整个事件缓存已不存在,终态或等待客户端工具的运行可返回相应回退事件,需要结合运行状态和持久化消息判断:

{
  "code": "stream_cursor_expired",
  "earliest_event_id": 120,
  "latest_event_id": 385
}

标准恢复步骤:

  1. 先调用 GET /v1/agent-runtime/project/runs/{runId}?userId=... 与 GET .../runs/{runId}/messages?userId=... 恢复所有已持久化的消息和当前运行状态;

  2. 若该 Run 仍在运行(RUNNING)且需继续监听剩余实时流,将 Last-Event-ID 更新为 earliest_event_id - 1(即 119)重新发起 SSE 连接。


4. 审计单次运行的模型调用明细(GET /runs/{runId}/model-invocations)

当一次 Run 涉及多轮工具调用或上下文精简时,可通过 model-invocations 接口精确核算每一跳模型调用的 Token 成本与耗时:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9p1q2r3s4t5u6v7w8x9y0/model-invocations?userId=user_zhangwei_001" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @-
)

预期响应(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。

Q2:为什么刷新控制台页面或重连后,之前看到的某段“思考过程(Reasoning)”片段消失了,但最终回答和工具结果都在?

原因与排查步骤: 这是由临时流式事件与持久化消息的分层设计决定的:

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} 的终态为准。


相关文档