本文梳理了智能体追踪(Agent Tracing)的 6 大主流实现模式,核心目标是解决分布式智能体任务的可观测性,不再只记录模型 / 工具调用原始日志,而是还原智能体完整决策过程。
- 模型 API 埋点
最简单通用,只能间接推断行为,无法确认工具真实外部影响; - 执行框架埋点
在智能体运行循环内部采集,信息最全,但存在工具调用与外部系统盲区; - 原生会话记录
复用智能体自带持久化会话,事后分析,无需运行时埋点; - OpenTelemetry 分布式追踪
跨进程 / 子智能体链路串联,统一规范,但不同框架输出信息粒度差异大; - 环境证据
把 Git diff、截图、文件快照等外部产物和追踪关联,弥补日志看不到环境变化的缺陷; - 语义增强
用评估模型分析原始追踪,增加业务语义,并且生产追踪沉淀为评估数据集,支撑智能体版本迭代。
长期挑战:模型内部决策黑盒,以及海量碎片化执行数据的人类可解释问题。
10个关键问题Q&A
-
Q:Agent tracing 和普通 LLM 日志最大区别是什么? A:普通日志只记录模型输入输出;Agent tracing 目标还原决策、动作、委派、环境影响完整执行故事,不只看模型调用。 -
Q:模型 API 埋点方案的短板? A:只能拿到模型返回的工具请求,无法确认工具是否真实执行,以及工具对外部系统产生了什么改变。 -
Q:什么是 Harness(智能体执行框架)追踪? A:在驱动 Agent 循环的运行框架内部埋点,直接捕获函数调用、任务转交、生命周期事件,信息比单纯模型 API 埋点丰富。 -
Q:原生执行记录模式的特点? A:智能体本身保存结构化会话,追踪系统事后读取文件分析,不需要运行时部署追踪埋点。 -
Q:OpenTelemetry 在 Agent 场景的价值? A:提供跨框架、跨进程、跨子智能体链路关联能力,统一链路 ID 串联分散的执行事件。 -
Q:环境证据(Environment Evidence)用来解决什么问题? A:弥补工具调用日志看不到真实环境变化的缺陷,例如代码修改、页面截图、数据库变更。 -
Q:语义增强(Semantic Enrichment)是什么? A:使用评估模型对原始 Trace 做分析打分,判断智能体是否合理、是否卡壳,给原始日志增加业务语义。 -
Q:Trace 数据集如何用于智能体迭代? A:生产成功 Trace 作为样例,失败 Trace 作为回归测试用例,用来评估提示词、工具、框架版本变更。 -
Q:为什么智能体追踪很难做到完整观测? A:智能体分布式运行、调用外部系统、创建子智能体;大量决策发生在模型内部,不存在单一埋点拿到全部信息。 -
Q:智能体追踪未来最大挑战? A:模型内部决策黑盒;长任务下海量碎片化执行数据,如何转化为人可以理解的信息。
附录 Agent Trace:捕获智能体执行过程的各类模式
原文:Josh Rosen
记录每一次模型调用、工具调用是一回事;理解智能体过去一小时究竟在做什么,则完全是另一回事。智能体追踪(Agent tracing)本身是一门专门的技术:它要观察智能体做决策、执行动作、委派任务,同时把零散事件拼接成一段连贯的执行过程。
智能体追踪早已不再局限于单一智能体循环。如今它越来越强调跨会话、跨进程,以及追踪智能体正在修改的各类外部系统。
架构层面的难点在于:没有任何一个埋点位置能够掌握全局完整信息。正因如此,业界涌现出多种模式来解决可观测性问题,一大批公司与开源项目也各自提出了智能体追踪方案。
但这些系统观测的对象并不相同。下面拆解智能体追踪背后的不同架构,看看它们各自观测什么、如何实现。
观测模型层(Watching the Model)
模型 API 是最容易接入追踪数据的位置,也是最早出现、至今仍最常用的智能体追踪方案。你只需要对模型 API 埋点,不需要深入了解应用其余部分。
-
Weave(W&B)可自动对支持的模型库做埋点;Langfuse、Braintrust、AgentOps 也提供同类集成方案。 -
另一种方案是在应用与模型服务商之间架设网关,例如 LiteLLM、Helicone。
这种方式可以拿到对话消息、模型返回内容、模型参数配置、延迟、Token 消耗、费用与报错信息。工具调用请求通常也会体现在模型返回结果里。对于简单智能体,我们可以通过连续多轮模型调用,还原出大部分执行轨迹。
但这种方式本质上是通过智能体和大模型的对话来间接观测智能体。即便模型输出指令要求运行命令,模型 API 本身并不知道:命令是否真的执行成功,以及这条命令修改了 1 个文件还是 50 个文件。
带埋点的执行框架(The Instrumented Harness)
智能体执行框架(harness)能看到更多信息,因为它本身就是驱动智能体循环运行的载体。它可以直接记录操作,而不是事后依靠模型调用日志反向还原。
-
OpenAI 的 openai-agents-python 追踪模块:记录智能体运行记录、生成结果、函数调用、任务转交、防护规则与自定义操作。 -
LangSmith 依托 LangChain / LangGraph 获取同类信息;Google ADK、微软智能体框架也在运行时内部暴露追踪能力。
几乎主流代码智能体框架都提供生命周期钩子(Lifecycle hooks),不需要接管整个框架,就能接入智能体循环事件。例如 Anthropic Claude Code 的钩子,可以把工具调用与智能体生命周期事件对外暴露。OpenAI 托管智能体 API、Claude 托管智能体平台也在托管运行时内提供钩子与追踪能力,由平台管控智能体运行环境与模型。
即便采用框架埋点追踪,依然存在盲区:工具调用内部经常无法观测,尤其是当工具修改外部系统时。有些工具调用本质是调用另一个子智能体,会进一步增加执行过程的黑盒程度。
原生执行记录(Native Execution Records)
Claude Code、OpenAI Codex、pi-mono、LangChain DeepAgents 等代码智能体,本身就会持久化结构化会话历史。这些状态原本用于会话持久化、任务续跑、上下文压缩、上下文管理,支撑长时间任务稳定运行;而这些记录同样可以用于追踪。
消息、工具请求与返回结果、会话事件,可以在智能体任务结束之后读取,而不是在运行时实时推送到可观测平台。Hugging Face Agent Traces 就是典型:读取智能体原生会话文件(包括代码智能体输出的 JSONL 历史),并转换成可供查看、分享的追踪链路。
简单来说:这套追踪系统完全可以事后分析,直接读取智能体已经落地保存的执行历史,不需要在智能体运行阶段额外部署追踪集成。
分布式追踪(Distributed Tracing)
智能体执行越来越多地分布在多个进程、服务、远程工具中。单次智能体任务可能横跨多个独立系统,每个系统都有自己的埋点。当智能体创建子智能体、工具调用外部服务时,这个问题尤为突出。
OpenTelemetry 提供了串联这些操作的标准。Arize 的 OpenInference 在 OpenTelemetry 之上增加 AI 专属规范与埋点;Traceloop OpenLLMetry 基于 OpenTelemetry,自动为 LLM 与智能体应用埋点。Langfuse、Braintrust、微软智能体框架、Datadog、HoneyHive 等产品也在各自技术栈中支持 OpenTelemetry。
正在完善的 OpenTelemetry GenAI 语义约定(SemConv),为模型调用、智能体、工具等执行环节定义统一概念。
执行框架层与 MCP 层可能同时观测同一次工具调用;而另一些操作完全没有埋点。两个框架都可以输出合法的 OpenTelemetry 追踪链路,但二者提供的智能体行为细节差异巨大。OpenTelemetry 的价值,就是能够跨框架、跨进程、跨工具、跨可观测后端,把分散链路关联起来,哪怕各个系统输出的信息详略程度不一样。
环境证据(Environment Evidence)
单靠工具调用日志,信息仍然有限。代码智能体执行 shell 命令返回退出码 0,但追踪记录可能完全不知道这条命令改动了 10 个文件。浏览器智能体点击按钮后,追踪链路无法保留页面后续变化。
追踪链路可以搭配智能体所处环境的证据一起使用:
-
代码智能体:Git 变更 diff、文件系统改动、测试结果、编译器输出、代码仓库快照; -
浏览器智能体:页面截图、页面状态; -
数据库智能体:变更的数据行与数据库状态。
这类数据并不适合直接塞进传统追踪链路。Git diff、截图、测试报告、环境快照更适合作为产物(artifact)存储;追踪链路只需要记录:哪一步操作生成了这份产物,以及它在整个执行流程中的位置。
语义增强(Semantic Enrichment)
前面所有方案都有一个共性短板:采集大量原始数据,但容易 “只见树木不见森林”。追踪记录可能显示智能体连续调用 6 次工具、浏览 15 个文件之后才做出修改,但日志无法告诉你:智能体是陷入了卡壳,还是这段探索本身是合理必要的。
追踪平台越来越多地使用模型来分析追踪链路,做这类判断:
-
LangSmith 可以对生产链路运行评估器; -
Langfuse 支持给观测项、追踪链路、会话附加评分; -
Braintrust、Arize Phoenix 同样把追踪和评估系统打通。
评估器可以判断智能体是否遵守指令、工具选择是否合适、任务完成效率、是否出现特定故障模式。轻量决策 / 分类模型(例如 typesafe.ai 等)成本更低,可以大规模分析海量追踪数据。
这一步为智能体追踪增加语义信息,形成迭代优化闭环。团队可以基于大量追踪链路体现出来的语义行为,调整提示词、能力集、工具,而不是只优化底层指标。
追踪数据集(Trace Datasets)
生产环境的追踪数据也正在直接喂入评估数据集。LangSmith、Langfuse、Braintrust、Arize Phoenix、W&B Weave 都把追踪链路和评估、实验工作流打通。失败的执行记录可以作为回归测试用例;成功案例则用来测试提示词、模型、工具、执行框架的版本改动。
追踪链路不一定支持回放复现:环境会变化,模型输出本身具备不确定性。但它不需要完整复现原始执行细节,就可以成为有效的测试用例。生产环境智能体产生的追踪,正逐步成为评估新版智能体的测试集。
智能体追踪未来走向
随着模型能力持续变强,智能体追踪也需要持续演进。越来越多关键决策发生在模型内部,很难甚至无法直接观测。仅靠对执行框架埋点会遇到天花板;我们不能让智能体能力演进速度超过人类理解其行为的能力。
与此同时,当前这套追踪技术的落地普及率还处在早期阶段。现有工具带来的可观测能力,依然有大量价值待挖掘。
智能体开始承接更长、更复杂的任务。我们还需要持续解决一个难题:如何把海量、碎片化的执行数据,整理成人可以看懂的信息。

