AI 代理怎样记录工具调用链路和失败原因

AI 代理出了问题，单看“模型调用失败”通常不够。真正需要回答的是：代理先做了哪次判断、调用了哪个工具、工具参数是否被拒绝、下游接口是否超时，以及失败有没有被重试或改走备用路径。一个实用的做法，是把代理请求建成一棵 Trace 树，用 Span 表示有持续时间的操作，用事件表示操作中的瞬时状态变化，再用统一的调用 ID 串起模型、工具和下游服务。

OpenTelemetry 的 GenAI 语义约定已经把代理调用、工具执行、工具名称、工具调用 ID 等概念放进同一套观测模型。官方资料入口可以直接复制：https://opentelemetry.io/docs/。本文只聚焦工具调用链路和失败原因，不讨论某个模型厂商的 SDK 封装。

先把代理请求建成一棵 Trace 树

建议把一次用户请求当作根操作 invoke_agent，每轮模型交互建立一个 chat 子 Span，每次真正执行工具建立一个 execute_tool 子 Span。如果工具又访问 HTTP 服务或数据库，就让对应客户端 Span 继续挂在工具 Span 下面。这样在追踪页面里可以直接看到“代理决定调用工具”与“工具调用下游失败”之间的父子关系。

不要为每一条普通日志都创建 Span。Span 适合表达有开始和结束的操作；同一工具执行中的“开始重试”“参数被拒绝”“回退备用服务”等瞬时变化，用事件更合适。

给每次工具调用补齐可检索字段

工具 Span 至少应能回答四件事：调用了什么、属于哪次会话、传入的调用是哪一个、结果大致是什么。可以优先记录 gen_ai.operation.name=execute_tool、gen_ai.tool.name、gen_ai.tool.call.id、gen_ai.conversation.id，再按需要补充模型名、代理版本、重试次数和结果类型。

参数和结果很容易携带个人信息、访问令牌或业务数据。不要默认把完整 JSON 塞进 Span。更稳妥的默认值是记录字段名、参数摘要、长度、脱敏后的枚举值或不可逆关联标识；只有在受控环境中，才对指定字段开启内容采集，并设置大小上限。

# 这些字段用于定位调用，不把用户原始问题和令牌写入遥测
span.set_attribute("gen_ai.operation.name", "execute_tool")
span.set_attribute("gen_ai.tool.name", tool_name)
span.set_attribute("gen_ai.tool.call.id", call_id)
span.set_attribute("gen_ai.conversation.id", conversation_id)
span.set_attribute("agent.retry_count", retry_count)
span.set_attribute("agent.input_keys", ",".join(sorted(safe_input_keys)))

如果你的 SDK 版本对 GenAI 语义约定的支持还不完整，也可以先使用同样稳定的自定义字段，但要把字段名、类型、脱敏规则写成团队约定，后续再映射到官方语义字段。

用事件记录重试、拒绝和失败原因

一个工具调用可能经历多次重试，但它仍然是同一个有明确开始和结束的操作。因此，工具本身用一个 Span 表示，重试过程用带时间戳的事件表示。例如 tool.retry 记录第几次重试和退避毫秒数，tool.rejected 记录业务校验拒绝，tool.completed 记录结果类型。

如果异常在 Span 结束时仍未处理，OpenTelemetry 的异常约定建议记录名为 exception 的事件，并补充 exception.message、exception.stacktrace、exception.type；同时把 Span 状态设为 ERROR。这样既能按错误类型聚合，也能在 Trace 中看到失败发生的时间点。

业务拒绝与系统异常不要混为一谈。例如参数缺少必填字段，是工具可以预期处理的业务分支；下游服务连接超时，则更像依赖异常。前者可以记录 tool.rejected 和拒绝原因，是否标记为 ERROR 取决于它在你的业务中是否代表操作失败；后者通常应记录异常并将工具 Span 设为 ERROR。

在工具封装层统一落地

把埋点放在每个工具函数内部，会很快出现字段不一致、异常漏记和重试逻辑各写一套的问题。更容易维护的方式，是在工具注册表外包一层统一执行器：进入时创建 Span，执行前写入安全字段，失败时记录异常，退出时结束 Span。

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

# 统一的执行器让所有工具共享同一套字段和错误处理规则
tracer = trace.get_tracer("agent-runtime")

def execute_tool(tool_name, call_id, conversation_id, arguments, registry):
    # 只保留允许进入遥测的键名，避免原始参数泄露
    safe_keys = sorted(k for k in arguments if k in {"city", "query", "limit"})
    with tracer.start_as_current_span("execute_tool") as span:
        span.set_attribute("gen_ai.operation.name", "execute_tool")
        span.set_attribute("gen_ai.tool.name", tool_name)
        span.set_attribute("gen_ai.tool.call.id", call_id)
        span.set_attribute("gen_ai.conversation.id", conversation_id)
        span.set_attribute("agent.input_keys", ",".join(safe_keys))
        try:
            # 工具实现只负责业务，父 Span 自动承接当前上下文
            result = registry[tool_name](**arguments)
            span.add_event("tool.completed", {"result.type": type(result).__name__})
            return result
        except Exception as exc:
            # 异常事件保留类型、消息和堆栈，便于在链路中定位失败点
            span.record_exception(exc)
            span.set_attribute("error.type", type(exc).__name__)
            span.add_event("tool.failed", {"retryable": False})
            span.set_status(Status(StatusCode.ERROR, str(exc)))
            raise

示例故意没有记录 arguments 和 result 原文。若确实需要调试某个字段，应先定义允许采集的字段清单、脱敏策略、最大长度和保存期限，再通过配置开关启用。

按调用链排查而不是只搜错误日志

出现“代理回答失败”时，可以按下面顺序排查：

1. 先从 invoke_agent 根 Span 确认会话 ID、总耗时和最终状态。
2. 沿子 Span 找到产生工具调用的 chat，核对模型是否选择了预期工具。
3. 用 gen_ai.tool.call.id 定位对应的 execute_tool，查看工具名、重试事件和错误类型。
4. 如果工具 Span 下面还有 HTTP 或数据库 Span，继续看超时、返回码或连接错误，判断故障属于工具逻辑还是下游依赖。
5. 最后对照 tool.rejected、tool.failed 和 exception 事件，确认是业务规则拒绝、可重试失败，还是未处理异常。

这套链路比“在每个函数里打印一行 error”多了一个关键能力：它能把模型的决定、工具执行和依赖故障放在同一个上下文里比较。日志仍然有用，但应通过 Span 上下文关联，而不是让排障者手工拼接时间戳。

常见问题与采用边界

工具参数要不要全部记录？

默认不要。工具参数可能包含个人信息、业务机密或令牌。先记录键名、长度、枚举值和调用 ID，只有经过数据治理批准的字段才采集内容。

一次重试要不要创建一个新 Span？

如果重试仍属于同一次工具操作，通常保留一个工具 Span，并为每次尝试增加事件；只有重试本身跨越独立的远程操作边界时，才考虑创建子 Span。

业务拒绝也一定要标记 ERROR 吗？

不一定。是否是错误取决于调用方的业务语义：预期的参数校验分支可以保持正常状态并记录拒绝事件；如果它导致本次代理任务无法完成，则应把失败状态向上反映。

应该先接入哪一层？

先接入代理入口和工具统一执行器，再接入工具内部的 HTTP、RPC 或数据库客户端。先让链路完整，再逐步增加内容采集，比较容易控制成本和敏感数据风险。

小结

AI 代理的可观测性重点不是多打印几行日志，而是让一次工具调用具备清晰的父子关系、稳定的调用标识和结构化的失败事件。用 invoke_agent 统领请求，用 chat 和 execute_tool 拆出模型与工具边界，用 exception 事件记录未处理异常，再通过脱敏和采样控制数据风险，就能更快回答“哪一步失败、为什么失败、是否可以重试”。

官方资料：

• https://opentelemetry.io/docs/
• https://opentelemetry.io/docs/specs/otel/trace/exceptions/
• https://opentelemetry.io/docs/specs/semconv/general/events/
• https://opentelemetry.io/blog/2026/genai-observability/