waiting_for_human)和停止条件(stopped)都不是错误:两者都会返回正常结果。哪些失败还会发送 run.failed 事件因语言而异,所以不要只依靠这个事件来检测失败。
失败的运行如何表现
出错时会触发哪些事件
生命周期钩子列出了所有事件。
找出错误的原因
TypeScript 错误类型
AgentGatewayError 包含 status、statusText、headers、body、requestId、generationId、reason、errorType、errorOrigin、failedProviders、failedStatuses 以及路由诊断信息。失败的运行和步骤会在 errorDetails 中保留相同的详情。流式响应中途发生的失败是 AgentStreamError,它是一个带有 code 和 retryable 的子类。
AgentSchemaValidationError 的 target 为 tool_input、tool_output、tool_event 或 agent_output,details 中是校验器的错误。请把它们视为契约失败,而不是暂时性的模型失败。
如果要对任何错误分类(例如在 modelRetry.retryOn 中),请使用 agentErrorIsRetryable(error)、agentRetryAfterMs(error) 和 agentErrorIsContextOverflow(error)。
Rust 错误类型
每个运行时失败都是AgentError;用 message() 读取它。网关的 PhaseoError 值会被转换为 AgentError,所以如果你需要原始的网关状态码和响应体,请直接调用 phaseo 客户端,或实现一个保留这些信息的自定义 ModelClient。
从工具错误中恢复
默认情况下,工具错误会让运行失败。当模型可以合理地尝试别的办法时,把工具的错误策略设为return-to-model:错误会变成工具结果 {"error": "..."},运行继续。对于不安全或无法恢复的失败,请保留默认的 fail-run。
处理取消和超时
工具超时或取消并不总能停止工具本身的工作。请为工具内部的 HTTP、数据库和进程调用设置各自的截止时间,并把已取消或已超时的运行视为已结束,除非你的应用重新启动一个运行。从中断的 TypeScript 运行中恢复
如果运行在某个步骤中途崩溃或被取消,它的历史中可能包含没有结果的工具调用,而提供商会拒绝这样的历史。TypeScript 的continueRun() 会把它们回复为未运行,并发送 history.repaired。如果你在其他地方复用这些消息,请自己调用 repairToolHistory(messages)。
先检查这些
PHASEO_API_KEY能传到进程中,并且已传给网关客户端。- 每个工具都有唯一且稳定的 ID。
- 批准、拒绝和工具输出都使用精确的工具调用 ID,并且人工输入的消息绝不能代替工具输出。
- 在展示审批界面或把控制权交给另一个请求或 worker 之前,先保存整个运行结果。
- 校验器是确定性的且没有副作用,这样检查失败后可以安全地重试。
- 模型重试有上限;校验失败和审批失败不应盲目重试。
step.started、model.requested 和 tool.failed;把步骤与网关日志关联起来的 ID 见可观测性。