AI Agent Tracing 实战：工具调用、护栏和人工确认怎么追踪

AI Agent 进入业务系统后，最怕的不是“能不能回答”，而是出问题时不知道它经历了什么：模型生成了什么意图，调用了哪个工具，工具返回了什么，护栏有没有拦截，最后为什么让人工确认。

这类问题需要可观测性。OpenAI Agents SDK 的官方文档提供了内置 tracing 能力，可记录模型调用、工具调用、handoff、guardrails 和自定义事件，便于调试、可视化和监控工作流。官方文档可参考 OpenAI Agents SDK Tracing。

适合人群

适合正在做 AI Agent、智能客服、自动化运营、知识库问答或内部助手的开发者。如果你的 Agent 已经开始调用工具、查询数据库、发起审批或进入人工处理，这篇文章会比较实用。

目录

• 为什么 Agent 需要 Tracing
• 把一次任务拆成 trace 和 span
• 给工具调用补关键字段
• 把护栏和人工确认也纳入链路
• 常见坑位和上线建议

为什么 Agent 需要 Tracing

传统接口的日志通常只记录请求参数、状态码和耗时。但 Agent 的一次任务可能包含多轮模型思考、多个工具调用、缓存读取、人工确认和最终回复。只看最终答案，很难复盘中间发生了什么。

一个可追踪的 Agent 至少应该回答四个问题：

• 这次任务的输入和目标是什么？
• 模型做了哪些关键判断？
• 调用了哪些工具，输入输出是否正常？
• 是否触发护栏、重试或人工确认？

下面这张图展示一次客服查询 Agent 的 trace：用户问题进入 Agent，模型判断意图，调用订单查询工具，经过护栏检查，必要时进入人工确认，最后返回结果。

把一次任务拆成 trace 和 span

可以把 trace 理解成一次完整任务，把 span 理解成任务里的一个步骤。比如“查询订单退款状态”是一条 trace，里面可以包含这些 span：

{
  "trace_name": "refund_status_query",
  "trace_id": "trace_20260613_001",
  "spans": [
    {"name": "model_intent", "type": "model"},
    {"name": "search_order", "type": "tool"},
    {"name": "guardrail_check", "type": "guardrail"},
    {"name": "human_confirm", "type": "review"},
    {"name": "final_answer", "type": "response"}
  ]
}

这样拆分后，排查时就不用只看一大段日志，而是能顺着 trace 看到每一步的耗时、输入、输出和状态。

给工具调用补关键字段

Agent 的工具调用最需要留痕。建议记录这些字段：

• 工具名：例如 search_order、query_ticket。
• 业务 key：例如订单号、用户 ID、工单号，敏感内容要脱敏。
• 输入摘要：不要把完整隐私数据直接写入 trace。
• 输出状态：成功、空结果、超时、权限不足。
• 耗时：用于发现慢工具和外部依赖抖动。

一个简化后的工具 span 可以这样设计：

{
  "span_name": "search_order",
  "tool": "order_query",
  "order_id": "A20260613****",
  "status": "success",
  "duration_ms": 236,
  "result_size": 1
}

重点不是把所有原始数据都塞进去，而是让后续排查能知道“调用了什么、用了哪个业务 key、结果是否正常、慢在哪里”。

把护栏和人工确认也纳入链路

Agent 上线后，护栏和人工确认往往比模型回复更重要。比如退款、删除数据、发送消息、修改配置这类动作，最好在 trace 里明确记录是否经过确认。

一个推荐流程是：

1. 模型识别到高风险动作。
2. 护栏 span 标记风险等级和拦截原因。
3. 人工确认 span 记录通过或拒绝。
4. 工具调用 span 只在确认通过后继续。
5. 最终回复 span 说明处理结果。

下面这张图展示高风险操作的可追踪路径：风险识别后先进入护栏，再等待人工确认，通过后才调用工具，拒绝则返回安全提示。

常见坑位和上线建议

第一，不要把 trace 当成聊天记录全文。 trace 应该记录关键事件和脱敏摘要，避免把用户隐私、密钥、完整订单信息写进去。

第二，工具输入输出要可定位。 只记录“工具失败”没有意义。至少要有工具名、业务 key、状态和耗时。

第三，把重试和人工确认单独成 span。 这样才能看出到底是模型判断问题、工具依赖问题，还是人工审批慢。

第四，给 trace 加业务标签。 例如 scene=refund、channel=web、risk=high，后续统计和筛选会方便很多。

总结

AI Agent 的可观测性不是锦上添花，而是上线后的基本能力。只有把模型调用、工具调用、护栏检查、人工确认和最终结果串成一条 trace，团队才能真正调试、复盘和监控 Agent。

落地时可以先从两件事开始：每次任务生成一个 trace，每个工具调用记录一个 span。等链路跑顺后，再逐步补充护栏、人工确认、耗时统计和业务标签。