介绍 Motus Tracing：面向 AI 代理的开源可观测性工具。没有追踪，代理就是一个烧 token 的黑盒。然而，如今大多数代理可观测性和追踪栈都隐藏在账户和订阅层级之后。Motus Tracing 完全开源。捕获每一次模型调用、工具调用、沙箱交互、子代理动作、重试和错误，适用于任何代理框架。从开发到生产，一个统一界面。相同的 span 可用于调试、评估和学习型代理。博客：https://lithosai.com/blog/motus-agent-tracing… 代码：http://github.com/lithos-ai/motus @lithos_ai

AI 代理的开源可观测性 | LithosAI

来源：https://www.lithosai.com/blog/motus-agent-tracing ← 返回博客 (https://www.lithosai.com/blog)2026年5月15日·阅读5分钟

对于任何规模或形态的 AI 代理而言，可观测性是必不可少的。没有可观测性，代理就是一个烧 token 的黑盒。它选择工具、分支、重试、重写自己的计划，却无法被调试、评估或改进。

Motus 代理追踪是我们的可观测性层。它详细记录运行的每一步：模型调用、工具调用、沙箱交互、子代理动作、重试、错误和任务转换。这些步骤通过一个 span 模型暴露出来，该模型在本地开发和云部署之间共享相同的核心。它适用于任何框架，无论是 Motus 原生代理，还是基于 OpenAI Agents SDK、Anthropic SDK、Google ADK 或纯 Python 构建的代理。整个追踪栈完全开源 (https://github.com/lithos-ai/motus)，免费使用。

这个设计基于三个约束条件。首先，检测必须零成本设置：任何构建代理的人，当问题出现时，无需修改代理代码就能检查一次运行。其次，本地产生的追踪与已部署代理发出的追踪必须共享相同的模式，这样分析工具、调试工作流以及下游评估管道都能基于同一种表示来操作。第三，遥测不仅用于调试，还用于改进。揭示故障的同一个 span，既能为迭代代理时的偏好编码代理提供输入，也能为更高级的技术（如学习型代理 (https://www.lithosai.com/blog/learning-agents)）提供支持。

本地追踪

本地追踪作为开源 motus Python 包的一部分提供。通过一个环境变量即可启用：

MOTUS_TRACING=1 uv run python agent.py

运行时会在磁盘上写入一个自包含的 trace_viewer.html 文件。打开它即可显示该运行的完整 span 树，包括模型调用、工具调用、持续时间、token 计数和载荷内容。无需服务器、网络连接或账户。

本地 Motus 追踪查看器会渲染单次运行的完整 span 树，包括模型调用、工具调用、计时、token 使用情况和载荷详情。对于需要随着代理执行即时查看 span 的交互式会话，运行时还提供了一个流式变体：

MOTUS_TRACING_ONLINE=1 uv run python agent.py

这会启动一个由服务器推送事件支持的本地查看器。Span 在关闭时会被推送到浏览器，使开发者能够检查部分状态、识别挂起、观察错误，而无需等待运行结束。

云遥测

相同的代理源码在本地通过 motus serve 运行，在 Motus 云中通过 motus deploy 运行：

motus deploy --name support-agent agent:agent

在部署环境中，运行时连续发出追踪，并为每个追踪打上项目、构建和会话标识符。无需集成第二个 SDK，也无需为生产环境设置条件代码路径。本地产生 trace_viewer.html 的同一 span 发射也会产生云追踪流，确保工程师在比较本地重现与生产故障时，看到的是结构上相同的记录。

在 Motus 云追踪查看器中检查已部署的代理运行。本地和云边界严格分离。即使在用户已认证的情况下，由 motus serve 或直接调用生成的追踪仍然保留在开发者机器上；云上传仅在已部署的云运行时内部发生。这种分离是有意为之：开发阶段的追踪经常包含未经编辑的提示、合成测试数据和不完整的实验，这些内容不应传输到主机之外。

Span 模型

追踪查看器围绕一个分层 span 树组织。每个 span 属于以下三类之一：

• Model spans 记录输入消息、生成的输出、可用的工具、token 使用情况和推理成本。
• Tool spans 记录参数、返回值、引发的异常和执行时间。
• Task spans 将模型和工具 spans 分组为逻辑工作单元，保留代理的推理结构。

查看器将这些 span 作为时间线以及树状显示，因此延迟异常值和错误位置无需检查单个载荷即可显现。同一视图回答了代理调试中常见的问题：模型收到什么、选择了哪个工具、传入了什么参数、返回了什么、时间花在哪里、哪一步失败。

Motus 云追踪 UI 显示会话追踪时间线和模型调用详情。Motus 云追踪查看器在单一视图中呈现时间线、span 树和每个 span 的细节。

框架无关性

检测是在运行时层面实现的，而非嵌入到任何单一代理框架内部。使用 Motus 原生 ReActAgent 和 @tool 装饰器编写的代理，以及基于 OpenAI Agents SDK、Anthropic SDK、Google ADK 或纯 Python 构建的代理都得到支持。一旦代理由 Motus 提供服务，操作层面——会话、追踪、span、部署和云 UI——无论上游框架如何都是相同的。

追踪作为学习型代理的基底

对于学习型代理 (https://www.lithosai.com/blog/learning-agents)，追踪提供了主要的反馈信号。优化器依靠生产追踪来识别故障模式、归因成本、采样代表性输入，并量化候选版本之间的行为差异。

由于追踪模式在不同环境间不变，工程师在查看器中检查的同一 span 会成为回归集、错误驱动数据集、流量采样数据集和成本关注数据集的输入。调试一次运行和改进下一个部署版本都源自同一个证据源。

开源，人人可用

Motus 追踪在宽松许可证下开源。Python 运行时检测、span 模式和本地追踪查看器全部位于 lithos-ai/motus (https://github.com/lithos-ai/motus) 仓库中。安装该包足以捕获、渲染和流式传输任何代理的追踪，在任何机器上，无需账户，不依赖网络。在 motus serve 下运行的自托管部署保留与管理云相同的追踪表面；云增加了托管留存、多会话索引以及与学习型代理的集成，但底层可观测性对每个运行开源运行时开发者都是可用的。