AI Agent 出错后只能看日志？AgentTrace 用运行时自愈把工具调用接着跑下去
多步骤 AI Agent 最难排查的故障，往往不是模型完全失控，而是某一步工具调用的参数“差一点正确”：把数字写成带单位的字符串、把 user_id 写成 user_identifier，或者漏掉一个必填字段。传统做法通常是让整个工作流失败，再回头翻日志。
AgentTrace 是一个刚发布的 MIT 项目，尝试把这件事前移到运行时：用 Pydantic 校验工具参数，记录每一步的输入、输出、状态和耗时；如果参数格式不符合工具 Schema，则通过 Groq 推理修复 payload，并把原始参数与修复后的参数同时留在追踪记录中。它的重点不是替代 Agent 框架，而是给现有的多步骤流程加一层可观察、可回放的保护层。
它到底解决什么问题
AgentTrace 的 README 给出的典型错误很有代表性：1200.0 可能被模型写成 "1200 INR"，正确的 user_id 可能变成模型自造的 user_identifier。如果这些参数直接传给 Pydantic 模型或业务函数，调用会立刻抛错。
项目把一次 Agent 运行拆成几个可观察的维度：
- Session：把一次完整任务的多个步骤串起来；
- Step：记录工具名、工具类型、输入和输出；
- Latency：保存每一步耗时，便于定位慢调用；
- Healing：记录是否发生过修复，以及修复说明；
- Payload Diff：在界面中对比原始参数和最终参数。
后端是 FastAPI 加 SQLite，前端使用 Next.js 和 Tailwind CSS。这个组合并不复杂，反而适合先在本地或内部环境验证 Agent 的失败模式。
先把观测后端跑起来
仓库提供的后端入口是 main:app，README 给出的启动方式如下：
python -m uvicorn main:app --reload --port 8000
启动时会初始化 traces.db，并创建 traces 表。表中保存 session_id、步骤编号、步骤名称、步骤类型、输入、原始输入、输出、延迟、状态、是否修复以及修复说明等字段。
后端有两个关键接口。POST /api/v1/trace 接收一条步骤记录，核心数据结构包括：
class TraceItem(BaseModel):
session_id: str
step_number: int
step_name: str
step_type: str
inputs: Dict[str, Any]
original_inputs: Optional[Dict[str, Any]] = None
output: Any
latency_ms: float
status: str
was_healed: Optional[bool] = False
heal_notes: Optional[str] = "None"
GET /api/v1/sessions 则会按 session_id 聚合步骤，返回完整的运行记录。也就是说，即使前端暂时不可用，后端 API 和 SQLite 数据库仍足够支持基础排查。
一个更真实的三步支付流程
仓库里的模拟脚本把 Agent 流程拆成三个工具：先查余额，再做风控检查，最后执行付款。正常情况下，三个工具的参数都由 Pydantic Schema 约束：
class PaymentSchema(BaseModel):
user_id: str
amount: float
note: str = Field(default="Transfer")
问题出现在最后一步。模拟代码故意构造了一组错误参数：
malformed_args = {
"user_identifier": target_user,
"amount": f"{transfer_amount} INR",
}
payout_res = execute_payout(**malformed_args)
这里同时包含两个常见幻觉：键名错误，以及类型错误。没有自愈层时，调用会因为缺少 user_id 或 amount 不是浮点数而失败。有了 AgentTrace，理想的处理路径是保留原始 payload，识别 Schema 差异，再生成修复后的参数，随后继续执行工具，并把 was_healed 标记为真。
这个设计有一个重要边界：自愈只应该发生在参数校验和格式转换层，不能绕过业务授权、支付审批或风控规则。对于转账、删除数据、发布代码等不可逆操作，修复参数之后仍应保留人工确认或独立的策略门禁。
适合什么场景
AgentTrace 当前最适合三类工作：
- 调试多工具 Agent：按 session 查看究竟是哪一步改变了参数；
- 观察延迟瓶颈：比较模型调用、工具调用和后端处理的耗时；
- 评估自愈收益：统计哪些错误被修复、修复后是否完成，以及修复后的 payload 是否需要人工复核。
它暂时不是完整的生产级遥测标准，也没有替代 OpenTelemetry 的意图。项目更像一个轻量实验台：用很少的组件把“Agent 为什么失败”从一条异常堆栈，变成可查询的步骤时间线。
使用时的三个注意点
第一，修复结果必须可追溯。不要只把修复后的参数传给工具而丢弃原始输入，否则后续无法判断是模型输出错误，还是修复器改错了。
第二，修复器的输出仍要重新通过严格 Schema 校验。模型说“已经修好”不是安全证明，尤其不能把自然语言解释当成结构化参数。
第三，SQLite 适合本地试验和低并发内部工具。若要承载大量 Agent 会话，应在保留字段语义的前提下迁移到合适的数据库，并补上认证、限流、敏感字段脱敏和数据保留策略。
AgentTrace 的价值不在于提出一个复杂的新 Agent 框架，而在于把运行时失败变成可观察事件：哪一步出错、原始参数是什么、修复做了什么、最后是否继续完成。对于正在搭建工具调用链的开发者，这种“先记录，再修复，最后复盘”的路径，往往比单纯增加模型提示词更容易验证效果。