Agent 平台应该区分「工具执行出错，系统自动重试」和「工具执行失败，错误信息给模型判断」，而不是把所有异常都塞进重试循环。

Pydantic AI v2.16.0 新增了 ToolFailed 错误类型，专门用于「模型可见但不触发重试」的失败场景。传统上，工具抛异常 → 框架自动重试 N 次 → 全部失败才回给模型。但有些失败重试也没用：权限不足、文件不存在、API 返回明确错误（400/404）、业务校验不通过。这些失败模型需要知道具体原因来调整策略，但不是「再试一次」。

工程细节：

• ToolFailed 跟普通 Exception 走不同路径：Exception → 框架内部重试计数；ToolFailed → 直接作为 tool output 回给模型，走 finish_reason=tool_calls 的正常路径
• 工具实现方在函数内用 raise ToolFailed("reason") 主动标记「这是终态错误，不需重试」
• 框架层面要保证：ToolFailed 不消耗 retry budget，不触发退避，不回滚 side effect
• 配合「审批被拒也要形成终态」（07-18 分享）看：审批拒绝也是终态，ToolFailed 也是终态——区别在于审批拒绝是外部人决策，ToolFailed 是工具自述「我不行」

这对 OPC 类平台的启示：工具执行结果不应只有「成功/失败」二元状态，而应有至少三级——success、retryable_failure、terminal_failure。terminal_failure 直接回模型，模型据此决定换参数、换工具还是告诉用户。