agent-observability

Agent Observability

只需记录一次 Agent 的大模型调用，即可离线回放，耗时不到 1 ms，零 API 调用，零成本。

---

你的 LangGraph Agent 在第 8 步后失败了。LangSmith 会告诉你哪里出了问题。 要重现问题：还需要调用大模型 8 次，再等 30 秒，并额外花费 $0.15 的 API 费用。 如果故障是由临时的大模型输出导致的，你根本无法重现。

Agent Observability 能解决这个问题。 记录一次。0.93 ms 离线回放。零 API 调用。零成本。

Recording overhead:   0.011%   (0.090 ms added per LLM call)
Replay latency:       0.93 ms  mean (vs ~8,500 ms live on GPT-4o × 10 steps)
Replay fidelity:      100%     (response bytes byte-for-byte identical)
CI cost per replay:   $0

---

安装

pip install agent-observability-trace-cli
# or
uv add agent-observability-trace-cli

LangGraph 支持：

pip install agent-observability-trace-cli[langgraph]

OpenAI Agents SDK 支持：

pip install agent-observability-trace-cli[openai-agents]

30 秒 CLI 快速入门

# Record a live run (your script just needs `import agent_trace` somewhere)
agent-trace run --name my_agent -- python my_agent.py

# List recorded runs
agent-trace list

# Replay offline: zero network, zero cost
agent-trace replay run_<id>

# Show the trace for a run
agent-trace show run_<id>

list、inspect、diff、replay 和 run 都支持 --json，可输出机器可解析的结果，因此编排 Agent 或 CI 作业可以像人一样调用这些命令，并解析结果。（run --json 会将自身状态输出到 stderr，将子进程的输出输出到 stdout，最后以一行 JSON 摘要收尾，因为无法将子进程自身的输出转换为结构化格式。）show 没有自己的 --json 模式，但支持 --errors-only，可将输出筛选为失败的 span。有关各子命令的所有标志，请参阅下方的完整 CLI 参考。

想通过编程方式控制而不是使用 CLI？请使用 Python API：

from agent_trace import tracer
import httpx

@tracer.instrument(record=True)
def fetch_data(query: str) -> dict:
    with tracer.span("http-call") as span:
        resp = httpx.get("https://httpbin.org/get", params={"q": query})
        span.set_attribute("http.status_code", resp.status_code)
        return resp.json()

result = fetch_data("hello")
# Trace and fixture saved to ~/.agent-trace/runs/run_<id>/

离线回放，不调用 API，也不消耗令牌：

from agent_trace import replay

with replay("run_<id>") as ctx:
    result = fetch_data("hello")  # served from fixture, zero network
    print(result)                 # identical to the original run

提示

要存储输入以便稍后在回放时检索，请在录制上下文中调用 ctx.fixture.set_metadata('input', query)。

说明

同步和异步客户端： Agent Observability 会拦截 httpx.Client、httpx.AsyncClient 和 requests.Session，包括 OpenAI Python SDK v1.x 和 Anthropic SDK 默认使用的异步客户端。补丁会在请求分发时安装，因此也适用于录制／回放开始前创建的客户端（例如模块级别的 openai.AsyncOpenAI() 实例）。

---

MCP 服务

agent-observability 提供一个 Model Context Protocol 服务，让 AI Agent（Claude、Cursor 或任何兼容 MCP 的客户端）能够直接列出、检查和回放已录制的运行，无需人工手动调用 CLI。

安装附加组件：

pip install "agent-observability-trace-cli[mcp]"

将其添加到 MCP 客户端的配置中（对于 Claude Desktop，请使用 claude_desktop_config.json）：

{
  "mcpServers": {
    "agent-observability": {
      "command": "uvx",
      "args": ["--from", "agent-observability-trace-cli", "agent-trace-mcp"]
    }
  }
}

该服务提供一个工具 run，它会使用给定的子命令和参数以及 --json 调用 agent-trace CLI，并返回解析后的 JSON 结果：

run(["list"])
run(["replay", "run_abc123def456"])

传输方式为 stdio，因此无需托管任何内容：MCP 客户端会将服务作为本地子进程启动。源码：src/agent_trace/mcp_server.py。

---

支持的框架

LangGraph · OpenAI Agents SDK · CrewAI · AutoGen · LlamaIndex · Haystack · Agno · PydanticAI · Google GenAI
此外：任何 httpx.Client、httpx.AsyncClient 或 requests.Session，无需框架。

---

CLI 参考

agent-trace 有 7 个子命令。每个子命令都支持 -h/--help，可查看与此处相同的详细说明。

agent-trace version

输出已安装的版本并退出。无需参数。

agent-trace list

列出 trace 目录中的所有已录制运行（默认目录为 ~/.agent-trace/runs，也可以通过 $AGENT_TRACE_TRACE_DIR 指定）。

标志	默认值	说明
--json	关闭	输出机器可读的 JSON，而非人类可读的表格。

agent-trace show <run_id>

美化输出某次运行存储的 trace.json。

参数	必填	说明
run_id	是	运行 ID，例如 run_abc123def456。

标志	默认值	说明
--errors-only	关闭	仅输出状态为 ERROR 的 span，每个 span 都附带捕获的异常文本。

show 没有 --json 模式。它输出 trace（安装 rich 时会添加颜色，否则使用普通的 json.dumps），而不是结构化摘要对象。

agent-trace replay <run_id>

进入某次运行的回放模式，并打印生成的 span 树，以及流式时序、HTTP 错误交互和 show 打印的相同跨 span 诊断信息（错误分类、重复节点 span、重试风暴、span 归因错误、检查点持久性、零任务更新）。

参数	必需	描述
run_id	是	运行 ID，例如 run_abc123def456。
--json	否	打印结构化 JSON 摘要（fixture 路径、span/交互计数、原始跟踪），而不是人类可读的 span 树。

agent-trace inspect <run_id>

自动标记某次运行中已知的格式错误的请求/响应结构和跨 span 异常。

参数	必需	描述
run_id	是	运行 ID，例如 run_abc123def456。

标志	默认值	描述
--registered-tools	无	以逗号分隔的已注册工具名称列表。启用工具调用名称模糊匹配、点分复合名称、ReAct 操作名称未注册和工具调用名称未注册检查。
--configured-host	无	框架配置的大模型端点主机。启用端点主机不匹配检查。
--check-kwarg	无	以点分隔的 kwarg 路径（例如 extra_body.chat_template_kwargs.thinking），预期在传输内容中存在。若缺失，则标记请求。
--diff-field	无	要检查传输内容中存在但下游缺失的响应字段：顶层键（例如 usage），或包含数字列表索引段的点分隔/嵌套路径（例如 choices.0.message.reasoning_content，适用于 DeepSeek 的 reasoning_content 等提供方字段）。
--diff-get-post-field	无	用于比较较早的 GET 响应与较晚的、因果相关的 POST 请求正文的点分隔字段路径（例如 instructions）；两者需引用同一资源 ID（参见 issue #2620）。标记过时值不匹配，例如 GPTAssistantAgent 的 POST /runs 仍发送与 GET /assistants/{id} 返回值不一致的 instructions。
--diff-get-post-id-field	id	GET 响应中用于资源 ID 的字段名称。
--diff-get-post-post-id-field	与 --diff-get-post-id-field 相同	POST 请求正文中用于引用同一资源 ID 的字段名称；若不同则填写此项（例如 assistant_id）。
--json	关闭	打印机器可读的 JSON，而不是人类可读的标记列表。

agent-trace diff <run_id_a> <run_id_b>

对比两次已记录运行的交互，按 URL 匹配，并突出显示请求/响应正文中字段级别的差异；此外还会检查共享 LangGraph thread_id 的运行是重启还是恢复（参见 issue #161）。

参数	必需	描述
run_id_a	是	第一次运行的 ID。
run_id_b	是	第二次运行的 ID。

标志	默认值	描述
--json	关闭	打印机器可读的 JSON，而不是人类可读的差异。

agent-trace run -- <command> [args...]

执行子进程，并在整个进程范围内预先启用记录 （AGENT_TRACE_AUTO_RECORD=1），这样该进程内第一次 import agent_trace 时，即使是在 langgraph dev 这类第三方 CLI 所拥有的进程中，也会开始记录，无需对你自己的 Agent 代码进行任何修改。退出时返回子进程自身的退出代码。

标志	默认值	描述
--run-id	随机值（run_<12-hex-chars>），启动时打印	显式指定运行 ID。
--name	auto-record	记录在 trace.json 元数据中的跟踪名称。
--json	关闭	在 stdout 上以一行最终 JSON 输出 agent-trace 自身的状态（状态行改为输出到 stderr）。必须放在子命令之前，例如 agent-trace run --json -- langgraph dev。
child_command（位置参数）	无	-- 后的所有内容都会作为子进程执行，例如 -- langgraph dev。这会捕获命令行的剩余部分，因此必须在它之前指定 --run-id/--name/--json，而不是之后。

---

问题

一次 LangGraph 运行在第 8 步后失败了。你在 LangSmith 或 Langfuse 中的跟踪显示了故障的原因。但要复现它，你必须重新运行整个 Agent：再进行 8 次大模型调用，再等 30 秒，还要多花 0.15 美元的 API 费用。如果故障是由特定工具响应或瞬时模型输出造成的，你根本无法复现它。你只能对着一个不断变化的目标进行调试。

Agent Observability 在 HTTP 传输层解决了这个问题。 它会将每个请求和响应原样记录到本地 SQLite 文件中。回放会按顺序返回这些确切的字节，每次交互耗时不到 1 毫秒：相同的代码路径、相同的 span 树、相同的故障。无需 API 调用。

---

在 CI 中使用：零成本回放

只需记录一次。提交测试固件。在每次 CI 运行中零 API 费用回放：

# tests/test_agent.py
import pytest
from pathlib import Path
from agent_trace import replay

FIXTURE_PATH = Path("fixtures/my_agent_run.db")

@pytest.mark.skipif(
    not FIXTURE_PATH.exists(),
    reason="Run: python scripts/record_fixture.py to generate the fixture"
)
def test_agent_answer():
    with replay(FIXTURE_PATH) as ctx:
        from my_module import my_agent
        result = my_agent("what is 2+2?")
    assert "4" in result

在 CI 中设置 AGENT_TRACE_NETWORK_GUARD=1。任何不在测试固件中的 HTTP 调用都会立即引发 NetworkGuardError，在回归问题进入生产环境之前将其捕获。

AGENT_TRACE_NETWORK_GUARD=1 uv run pytest tests/

这能为你省下什么？

10-step agent × $0.15 per run × 10 debug sessions per week = $15/week in API costs
With Agent Observability CI replay: $0/week

At scale (10 engineers, each debugging 3 failures/week):
Before: ~$45/week, ~5 hours/week waiting for live re-runs
After: $0/week, 0.93 ms per replay

---

为什么不直接使用 LangSmith、Langfuse 或 Helicone？

简而言之：它们能展示发生了什么，却无法离线重现。 LangSmith 的 VCR 磁带仅支持 Python + LangChain，不会捕获完整的线上字节， 而且需要 LangSmith 账号。Agent Observability 适用于任何 Python HTTP 客户端， 无需账号，并且能以 0.93 ms 的速度、100% 的保真度重放。

大多数 LLM Agent 可观测性工具都只能观察：它们会展示发生过什么的跟踪记录，但要重现故障，仍然需要针对实时 API 重新运行整个 Agent。

功能	Agent Observability	LangSmith	Langfuse	Helicone	OpenLLMetry
从本地夹具离线重放	是	部分支持 ¹	否	否	否
适用于任何 HTTP 客户端	是	否	否	否	否
无需 API 密钥即可在 CI 中重放	是	部分支持 ¹	否	否	否
重放时的确定性 Span 计时	是	否	否	否	否
捕获原始 HTTP 请求／响应字节	是	否	否	是	否
Span 级跟踪	是	是	是	是	是
OTLP 导出（Jaeger、Grafana Tempo）	是	否	是	否	是
开源核心	是	否	是	否	是
仅限本地，无需服务	是	否	可自托管	否	可自托管

¹ LangSmith 提供 LANGSMITH_TEST_CACHE / VCR 磁带（langsmith[vcr]），但仅适用于 Python + LangChain。它会捕获发往 api.openai.com 的 HTTP 请求，但不支持任意 HTTP 客户端，也不会记录完整的线上字节，并且需要 LangSmith 账号。

如果团队使用 LangChain，并需要数据集管理、提示词版本管理和人工反馈循环，请选择 LangSmith。

如果你想要一个完全开源、可自托管且采用 Postgres 存储的可观测性技术栈，请选择 Langfuse。

如果团队已经使用 OpenTelemetry，并希望获得标准的 gen_ai.* Span，且不想新增可观测性系统，请选择 OpenLLMetry。

Agent Observability 并不能替代仪表板和评测流水线。它解决的是一个具体的上游问题：无需支付任何 LLM API 费用，即可重现任何基于任意 Python HTTP 客户端构建的 Agent 的某次特定失败运行。

---

使用 Docker 试用

Agent Observability 会生成 OTLP Span。运行本地可观测性技术栈，浏览跟踪树：

git clone https://github.com/RudrenduPaul/agent-observability
cd agent-observability
docker compose up -d

启动三个服务（均为可选）：

• Jaeger（http://localhost:16686）：OTLP Span 接收和跟踪 UI
• Grafana（http://localhost:3000）：仪表板和警报
• Tempo（端口 3200）：长期跟踪存储后端

然后将导出器指向收集器：

from agent_trace.exporters.otlp import OTLPExporter

# 4317 = OTLP gRPC ingestion endpoint
exporter = OTLPExporter(endpoint="http://localhost:4317")
exporter.export(trace)

---

记录／重放能捕获的真实故障

• 第 6 步的模型输出具有瞬时性，导致下游工具失败。重新运行无法重现，重放则轻而易举。
• 第 3 步的限流响应触发了静默回退路径，该路径只能从已记录的夹具字节中看到，无法通过实时重新运行发现。
• HTTP 调度前的工具 Schema 序列化错误，由 LangGraphTracer.on_llm_error 捕获，尽管它从未到达拦截器（参见已知限制）。
• 并行分支中的工具顺序不确定：重放会固定导致故障的确切顺序，因此你调试的是实际运行，而不是一次全新的运行。
• Gemini 的 gRPC 单向流响应仅在特定分块边界处失败：记录一次后按字节原样重放，无需每次都重新触发实时流式调用。

---

已知限制

Agent Observability 的捕获模型基于 HTTP 拦截器（以及针对 src/agent_trace/integrations/ 下集成的插桩框架回调），并且仅限于进程本地。此模型确实存在局限，这里明确列出，方便你提前了解，而不是等遇到问题后才知道：

• 仅限进程本地。 录制和回放发生在导入 agent_trace 的 Python 进程内（httpx.Client(transport= RecordingTransport(...))、session.mount(..., RecordingAdapter(...))，或 ReplayEngine.replay() 的 monkeypatch，参见 src/agent_trace/interceptor/）。它无法观测或回放由你不自行运行或部署的第三方托管服务发出的调用（例如供应商自有的托管聊天助手）。它只能看到你自己的进程发出的出站调用。

• gRPC 覆盖不完整。 src/agent_trace/interceptor/grpc_hook.py 会修补 grpc.secure_channel/grpc.insecure_channel（以及 grpc.aio 中的对应接口），以捕获完全绕过 httpx 的 Gemini/Vertex AI 流量。Unary-unary 调用（例如 GenerateContent）和同步 unary-stream 调用（例如 StreamGenerateContent）都可以完整录制和回放。客户端流式和双向流式 gRPC 调用，以及任何 grpc.aio 流式调用，都不会被捕获。这些调用在录制期间会直接访问实时网络，不受拦截；如果尝试回放，也同样如此。

• 只有请求对象存在后才会开始捕获。 RecordingTransport. handle_request/AsyncRecordingTransport.handle_async_request （httpx_hook.py）和 RecordingAdapter.send （requests_patch.py）只有在完整构造的 httpx.Request/PreparedRequest 到达后才会运行。任何在此之前发生的异常——例如 SDK 正在序列化工具架构、构建请求头或以其他方式组装调用时发生的异常，甚至更早在普通 Python 对象构造期间发生的异常（例如错误实例化抽象类时，abc.ABCMeta 引发的 TypeError）——都发生在拦截器的捕获范围之外，不会生成任何固定数据行。已接入的框架集成自身的错误回调（例如 LangGraphTracer.on_llm_error）仍会捕获这类在 HTTP 请求前发生的异常，前提是异常经由该框架自身的 try/except 传播。因此，“拦截器无法看到”并不等于“任何地方都看不到”。这取决于是否接入了能捕获该异常的框架集成。

• 无法看到框架自身的打印/显示代码。 在本地日志记录/打印/显示机制内部引发的异常（例如由框架自身的 verbose=True 日志触发的 rich Console 输出或 IPython/Jupyter 显示钩子）不会产生任何 HTTP 流量，也不会触发任何框架回调。现有或计划中的捕获机制（HTTP 拦截器、MCP stdio 传输钩子或任何框架集成）都不会观测此类故障。

---

安全

• **供应链：**发布版本通过 GitHub Actions (release.yml) 构建和发布。已验证通过 Sigstore OIDC 签名提供的 SLSA Level 2 来源证明正常工作（每个分发制品都确实生成了 .sigstore.json bundle）；SBOM（CycloneDX JSON + XML）会生成并与签名制品一同附加到 GitHub Release。
• 漏洞扫描：dependabot.yml 每周创建 pip 依赖更新 PR，每月创建 GitHub Actions 版本更新 PR。此仓库已启用 Dependabot 安全公告提醒、密钥扫描和密钥扫描推送保护。
• fixture 安全：~/.agent-trace/runs/ 中的 fixture 文件包含完整的 HTTP 请求和响应正文，包括 API 密钥和提示词内容。请将 .agent-trace/ 和 *.db 添加到你的 .gitignore。
• 漏洞披露：SECURITY.md — 请将漏洞报告发送至 [email protected]，我们承诺在 48 小时内响应。

警告

切勿提交使用生产环境 API 密钥生成的 fixture。fixture 文件会原样记录完整的请求和响应正文，因此提交的 fixture 可能会将真实 API 密钥和提示词内容泄露到你的 git 历史记录中。

已知上游安全公告

• **chromadb（仅限可选的 [crewai] extra）：**GHSA 公告指出存在一个无需身份验证即可利用的代码注入漏洞，影响 chromadb 1.0.0 至当前最新版本（1.5.9）。上游修复（chroma-core/chroma PR #7237）已于 2026-07-07 合并，但此后尚未在任何 PyPI 版本中发布，因此目前没有可指定的修复版本。chromadb 仅由可选的 crewai 集成 extra 引入（pip install agent-observability-trace-cli[crewai]），默认不会安装；本项目也不会运行具有外部可访问 HTTP API 的 Chroma 服务，因此实际利用途径（攻击者可访问的 /api/v2/.../collections 端点）不适用于此软件包的常规用法。如果你安装了 [crewai] extra，并在其他位置运行自己的 Chroma 服务，请关注上游安全公告，并在修复版本发布后立即更新 chromadb。

  **未来规划：**chromadb 发布包含修复的版本后，立即将 chromadb 固定到该版本。如果到下一次计划的安全审查时仍未发布修复版本，且 [crewai] extra 的实际使用量微乎其微，则考虑彻底移除该 extra，作为彻底解决此问题的备用方案。

---

常见问题

什么是 Agent Observability？它与典型的大模型追踪工具有何不同？

它是一个 Python 库和 CLI (agent-trace)，会将你的 Agent 发出的每个 HTTP 请求和响应原样记录到本地 SQLite fixture 中，之后无需网络调用即可重放完全相同的字节。大多数追踪工具，包括 LangSmith、Langfuse、Helicone 和 OpenLLMetry，只会展示一次运行期间发生的情况。Agent Observability 还可以让你离线、确定性地复现完全相同的运行，而无需访问实时 API。上述“为什么不直接使用 LangSmith、Langfuse 或 Helicone？”一节详细比较了它与这四种工具的功能差异。

确定性记录/重放实际上是如何工作的？

记录时，会在传输层修补 httpx.Client、httpx.AsyncClient 和 requests.Session (src/agent_trace/interceptor/)，将每个发出的请求和响应作为原始字节捕获到 fixture.db 中。重放时，会安装 FixtureClock (src/agent_trace/core/clock.py)，并按原始顺序返回相同的字节，因此代码路径、span 树和时间戳都与原始记录一致。上文引用的基准数据（记录开销 0.011%、重放平均延迟 0.93ms、保真度 100%）来自此仓库中的 benchmarks/test_overhead.py、benchmarks/test_replay_vs_live.py 和 benchmarks/test_fidelity.py，你可以运行 uv run pytest benchmarks/ 自行测试。

如何安装？支持哪些平台？ pip install agent-observability-trace-cli，或 uv add agent-observability-trace-cli。它需要 Python 3.10 或更高版本，且仅依赖 httpx 和 rich，没有编译扩展，因此只要有对应的 wheel，就能在任何环境中安装。CI（.github/workflows/ci.yml）已在 Ubuntu、macOS 和 Windows 上通过测试，覆盖 Python 3.10 至 3.13。我们也发布了 npm 封装 agent-observability-trace-cli（本仓库中的源代码位于 npm/），供习惯使用 npx/npm 的团队采用；不过，它在底层仍会调用 Python CLI，因此也必须安装 Python 包。

具体来说，它与 LangSmith 有何不同？

LangSmith 的 LANGSMITH_TEST_CACHE（通过 langsmith[vcr] 使用的 VCR 风格录制）是最接近的内置替代方案。它仅支持 Python 和 LangChain，只捕获对 api.openai.com 的 HTTP 调用，而非任何 HTTP 客户端的调用；不记录完整的线路级字节数据，且需要 LangSmith 账号。Agent Observability 可与任何 Python HTTP 客户端配合使用，还为 gRPC、aiohttp、botocore 和 WebSocket 流量提供专用拦截器，可在本地记录完整的请求和响应字节数据，并且不需要账号或托管服务。如果你已在使用 LangChain，并希望在追踪之外进行数据集管理、提示词版本管理和人工反馈，请选择 LangSmith。如果目标是以零 API 成本复现某一次具体的失败运行，而不受调用所用 SDK 的限制，请选择 Agent Observability。

如果重放时找不到匹配的录制条目，会发生什么？

设置 AGENT_TRACE_NETWORK_GUARD=1 后，任何在录制数据中找不到匹配项的请求都会立即引发 NetworkGuardError，而不是悄悄回退到实时调用。最常见的原因是 HTTP 客户端在进入录制或重放上下文之前就已构建，因为补丁仅适用于在 start_trace/replay 块内创建的客户端。上文的“已知限制”列出了全部边界情况，包括对 gRPC 流式传输的部分覆盖，以及不会到达拦截器的 HTTP 前异常。

它能捕获基于非 Python 框架构建的 Agent 吗？

不能。捕获功能由 Python HTTP 传输拦截器，以及针对 src/agent_trace/integrations/ 下各项集成（LangGraph、CrewAI、AutoGen、LlamaIndex、Haystack、Agno、PydanticAI、Google GenAI 等）的插桩回调组成。它只能看到你自己的 Python 进程发出的流量。使用其他语言构建的 Agent，或由你无法自行运行的第三方托管服务发起的调用，都不在它的捕获范围内。

录制文件可以安全地提交到版本控制中吗？

默认情况下不安全。fixture.db 包含完整的 HTTP 请求和响应正文，因此其中可能包含请求头或负载中的 API 密钥和提示词内容。请将 .agent-trace/ 和 *.db 添加到 .gitignore，并且绝不要提交使用生产 API 密钥录制的文件。如果要将录制文件作为已提交的 CI 测试资源，请先移除或遮盖其中的机密信息。

可以将它免费用于商业用途吗？

可以。本项目采用 Apache 2.0 许可证（见 LICENSE），允许商业使用、修改和再分发，包括在闭源产品中使用，但须遵守许可证中的署名和声明条款。没有单独的付费等级或商业许可证。

---

参与贡献

• 提交 PR 前，请阅读 CONTRIBUTING.md
• GitHub Issues 中标记了适合新手的议题
• 重放引擎（src/agent_trace/_replay/）要求达到 80% 的测试覆盖率（关乎正确性）
• 拦截器（src/agent_trace/interceptor/）要求达到 80% 的测试覆盖率
• 可在 GitHub Discussions 中讨论设计问题和想法

Apache 2.0。欢迎贡献。

---

由 Rudrendu Paul 和 Sourav Nandy 构建