> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误与故障排查

> 处理 Ruby Agent 中的模型、工具、验证、超时和续接失败。

Agent 失败通常源于模型请求、本地工具、架构验证、超时或缺少人工决策。

## 从工具错误中恢复

如果模型可以从工具错误中恢复，请设置 `on_error: "return-to-model"`。错误会变成工具结果，Agent 可选择其他操作。对于不安全或无法恢复的操作，请保留 fail-run 行为。

## 了解 Ruby 执行方式

Ruby 通过常规同步迭代消费模型流。请为网络和进程工具设置明确的超时，避免慢速持久化操作阻塞生命周期回调。

## 排查续接错误

每个待处理调用都需要审批、拒绝或由外部提供的输出，并按工具调用 ID 标识。显示审批界面前，请持久化返回的完整运行状态。

## 记录有用字段

记录运行 ID、步骤索引、请求 ID、供应商、模型、结束原因、工具调用 ID 和停止原因。优先使用生命周期钩子或 DevTools，而非直接记录提示。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.