Pydantic AI Harness可观测性实战:Logfire+OpenTelemetry给AI Agent做全链路追踪教程
Pydantic AI Harness可观测性实战:Logfire+OpenTelemetry给AI Agent做全链路追踪教程
Pydantic AI Harness 是构建于 Pydantic AI 之上的官方能力库,为 AI Agent 提供完整运行“线束”。本文实战讲解如何用 Logfire 搭配 OpenTelemetry 给 AI Agent 做全链路追踪:每一次模型调用、每一次工具调用都会生成可查询、可计费统计的 span,让你一眼看清 Agent 在做什么、花了多少 token、钱花在哪里。
为什么 AI Agent 需要全链路追踪
一次 Agent 运行往往包含多次模型调用和几十次工具调用。当“结果不对”或“成本翻倍”时,没有 trace 你只能靠猜:
- 哪次模型调用最慢?
- 哪个工具返回了异常巨大的输出?
- 提示词缓存是不是失效了、被重复计费?
- 当前行为用的是哪个版本的 Prompt?
官方文档的表述很直接:harness 里的一切都默认可观测——每次 run 都会产生一条完整 trace,覆盖所有模型调用与工具调用,并附带 token 与成本统计。而且基于标准 OpenTelemetry 协议,任何 OTLP 后端(如 Grafana、Jaeger 等自建平台)都能接收;开发期用 Logfire 查看最省事。能力总览参见 docs/index.md。
30秒快速开始:一行命令启用 Logfire 追踪
无需手工埋点,装好包、调用一次 logfire.configure(),追踪自动生效 📊:
uv add 'pydantic-ai-harness[anthropic]'
import logfire
from pydantic_ai import Agent
from pydantic_ai_harness import Coder
logfire.configure() # 追踪相关的唯一一行
agent = Agent('anthropic:claude-sonnet-4', capabilities=[Coder()])
agent.run_sync('找出并修复失败的测试')
运行后打开 Logfire 本地界面,即可看到一次 run 的完整树状 trace:
阅读这条 trace 时关注三层信息:
| 层级 | 是什么 | 能看到什么 |
|---|---|---|
agent run |
一次运行的顶层 span | 总耗时、总输入/输出 token |
chat <模型名> |
一次模型调用 | token 用量、耗时、成本 |
running tool: xxx |
一次工具调用 | 工具名、执行时长、子 span |
幕后机制:Instrumentation 与 OpenTelemetry GenAI spans
你不需要自己写任何 span。Pydantic AI 核心自带 Instrumentation 能力(也可用 logfire.instrument_pydantic_ai()),会为每次模型调用和工具调用自动输出符合 OpenTelemetry GenAI 语义约定的 span。
这意味着两点:
- 不绑定框架:数据是标准 OTLP,开发期在 Logfire 里看,生产期可以直接投递给你自己的追踪后端;
- token 与成本是一等公民:每个
chatspan 自带 usage 统计,天然的“成本视角”。
深入 trace:一个脚本扇出成 N 个工具调用
如果 Agent 使用 Code Mode(模型写一段 Python 在沙箱里批量调工具),trace 会非常耐看:外层 run_code span 扇出成多个并行工具调用 span,每个调用独立成节点:
这种“一个 span 扇出 N 个子 span”的结构,正是理解 Code Mode 实际行为的关键——并行调了哪些工具、各自耗时多少,直接从 trace 上就能核对,详见 docs/code-mode.md。
让 Agent 自查遥测:Logfire MCP 上手
LogfireMCP 能力让 Agent 连接 Logfire 托管 MCP 服务器,直接查询自己的遥测数据——观测的进阶玩法 🔍:
from pydantic_ai_harness.logfire_mcp import LogfireMCP
agent = Agent('openai:gpt-5', capabilities=[LogfireMCP()])
典型场景:
- 自我诊断:让 Agent 查看最近的 traces,总结哪里出了问题;
- 按用户隔离凭证:
auth=传一个函数,每次 run 读取当前用户的 API key,并发运行互不共享账号; - 只读模式:
read_only=True只保留服务器标记为只读的查询类工具。
完整 API 见源码目录 pydantic_ai_harness/logfire_mcp/ 与文档 docs/logfire-mcp.md。
Prompt 版本化与回滚:ManagedPrompt 实战
追踪不止于“看”。Logfire 的托管变量还能管理 Agent 的系统提示词:ManagedPrompt 让 Prompt 的版本化 → 打标签 → A/B 灰度 → 一键回滚全部在 Logfire UI 里完成,无需重新部署。
对可观测性更关键的一点:被选中的标签和版本会作为 baggage 附着到 run 的 span 上,所有子 span 继承。于是看任何一条 trace,都能直接回答“这个行为是哪个版本的 Prompt 产生的”。
from pydantic_ai_harness import ManagedPrompt
agent = Agent(
'openai:gpt-5',
capabilities=[
ManagedPrompt('support_agent', default='You are a helpful agent.', label='production')
],
)
支持 targeting_key 做确定性 A/B 分桶、render_template=True 用 deps 渲染模板。详见 pydantic_ai_harness/logfire/ 与 docs/managed-prompt.md。
进阶观测:用 WarnOnCacheBusts 抓住提示词缓存失效
Prompt 缓存是长时运行 Agent 最大的省钱杠杆,但缓存一旦失效(前缀被移动、TTL 过期),提供商会悄悄重复计费。WarnOnCacheBusts 直接读取提供商返回的 cache_read_tokens,缓存塌陷时立即发出 CacheBustWarning。
由于 Logfire 桥接的是 logging 而非 warnings,把告警送进 trace 只需在启动时加一行:
import logging
logging.captureWarnings(True)
collapse_ratio、cache_ttl_seconds 等参数细节见 docs/warn-on-cache-busts.md,源码位于 pydantic_ai_harness/warn_on_cache_busts/。
新手观测性三步走清单
- 看得见:加
logfire.configure(),即得全链路 trace(模型调用 + 工具调用 + token + 成本); - 问得到:加
LogfireMCP(),Agent 能自查 trace、自诊异常; - 管得住:
ManagedPrompt做 Prompt 版本化与回滚,WarnOnCacheBusts守住成本底线。
更多能力清单与完整说明见 docs/index.md 和 README.md。

