跳到主要内容

工具调用链路追踪

1. 定义与边界​

工具调用链路追踪记录 Agent 从决定调用工具、生成参数、权限检查、执行请求、处理返回到继续推理的完整链路。它关注的是行动路径，而不是单个工具服务的 API 日志。

2. 为什么重要​

生产事故常见于工具层：选错工具、参数错、权限错、工具超时、返回脏数据、Agent 把错误返回当成功。链路追踪能把“Agent 回答错了”拆成可修复原因。

3. 核心机制​

4. 工程实现​

工具调用事件：

{
  "event": "tool_call_requested",
  "trace_id": "tr_001",
  "span_id": "sp_tool_req_1",
  "tool_name": "update_customer_note",
  "tool_schema_version": "2026-05-01",
  "risk_level": "write_low",
  "args_schema_valid": true,
  "args_hash": "sha256:...",
  "policy_decision": "allow",
  "user_confirmed": true
}

工具返回要标准化：

{
  "ok": false,
  "error_code": "RATE_LIMITED",
  "retryable": true,
  "safe_to_show_user": false,
  "message": "rate limit"
}

5. 生产实践​

  • 使用工具网关统一记录、鉴权、限流、脱敏和幂等。
  • 参数记录使用摘要和关键业务字段，避免保存完整敏感载荷。
  • 高风险写工具必须记录用户确认、策略版本和调用者身份。
  • 工具错误码要可机器处理，便于 Agent 正确重试或转人工。

6. 常见反模式​

  • Agent 直接调用多个后端服务，绕过统一审计。
  • 工具返回自然语言错误，Agent 难以区分可重试和不可重试。
  • 只记录工具服务日志，不记录 Agent 为什么调用。
  • 工具 schema 变更未版本化，导致旧评测无法解释。

7. 评测方法​

指标解释
Tool Success Rate工具实际执行成功率
Policy Denial Rate被策略拒绝的调用比例
Argument Validation Failure参数校验失败比例
Retryable Error Recovery可重试错误恢复成功率
Irreversible Action Audit Coverage不可逆动作审计覆盖率

8. 安全与治理​

工具是 Agent 权限边界。应采用最小权限、显式 allowlist、参数校验、用户确认、幂等键、速率限制和审计日志。外部内容不得直接提升工具权限。

9. 权威资料​

15. 主控验收清单​

  • 是否每个工具调用都能关联 Agent run。
  • 是否记录策略决策和审批 ID。
  • 是否记录幂等键或业务事实 ID。
  • 是否记录下游 HTTP 状态和重试次数。
  • 是否对工具参数做 hash 或脱敏。
  • 是否识别 forbidden tool call。
  • 是否能按工具版本比较错误率。
  • 是否有工具超时和下游故障告警。
  • 是否能区分工具失败和模型误用工具。
  • 是否把工具调用失败加入评测集。
  • 是否对外部不可信内容打标。
  • 是否有副作用工具回放替身。
  • 是否检查 tool schema 变更对 trace 字段的影响。
  • 是否限制高危工具 trace 的访问权限。
  • 是否监控重复副作用为 0。
  • 是否把工具调用成本归因到 run。

10. 二次精修：工具链路 trace 示例​

工具调用链路要覆盖模型决策、权限检查、工具入参、下游调用、结果处理和副作用确认。

Span关键字段失败分析用途
tool.policy_checkpolicy.version、decision、reason是否越权
tool.calltool.name、args_hash、idempotency_key是否重复/错参
tool.downstreamhttp.status_code、retry_count下游可靠性
tool.result_normalizeresult_size、schema_valid结果契约
tool.side_effect_confirmbusiness_id、ledger_status副作用确认

11. 工具调用事件结构​

{
  "event_name": "agent.tool_call.completed",
  "tool": {
    "name": "issue_refund",
    "version": "1.4.0",
    "args_hash": "sha256:abc",
    "idempotency_key": "refund:A123:v1"
  },
  "policy": {"version": "refund_policy_v2", "decision": "needs_approval"},
  "downstream": {"status_code": 200, "duration_ms": 480},
  "result": {"schema_valid": true, "business_id": "refund_789"},
  "safety": {"risk_level": "high", "approval_id": "apv_456"}
}

12. 告警与指标​

指标告警建议
Tool Error Rate单工具 5 分钟高于基线
Tool Timeout Rate影响 TSR 时告警
Forbidden Tool Call任意出现即安全告警
Missing Approval Rate高危工具目标为 0
Duplicate Side Effect目标为 0
Tool Cost Spike成本环比异常

13. 安全与治理​

  • 工具参数默认只记录 hash；排障需要明文时走受控调试环境。
  • 外部内容触发的工具调用要标记 untrusted_input=true。
  • 高危工具的 trace 必须记录审批 ID、审批结果和业务事实 ID。
  • tool adapter 要统一注入 traceparent，不能每个工具各自实现。
  • 工具失败回放必须使用 fixture，避免调试时重复产生副作用。

14. 补充权威资料​