Pydantic AI Harness可观测性实战:Logfire+OpenTelemetry给AI Agent做全链路追踪教程

原创2026-10-22 20:24:201,936 阅读

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:

Pydantic AI Harness AI Agent全链路追踪视图:一次agent run包含多次模型调用与并行工具调用,各自带token数与耗时

阅读这条 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 与成本是一等公民:每个 chat span 自带 usage 统计,天然的“成本视角”。

深入 trace:一个脚本扇出成 N 个工具调用

如果 Agent 使用 Code Mode(模型写一段 Python 在沙箱里批量调工具),trace 会非常耐看:外层 run_code span 扇出成多个并行工具调用 span,每个调用独立成节点:

Pydantic AI Harness Code Mode的OpenTelemetry追踪:沙箱脚本扇出多个并行工具调用,每次调用生成独立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/。

新手观测性三步走清单

  1. 看得见:加 logfire.configure(),即得全链路 trace(模型调用 + 工具调用 + token + 成本);
  2. 问得到:加 LogfireMCP(),Agent 能自查 trace、自诊异常;
  3. 管得住:ManagedPrompt 做 Prompt 版本化与回滚,WarnOnCacheBusts 守住成本底线。

更多能力清单与完整说明见 docs/index.md 和 README.md。

登录后查看全文
pydantic-ai-harness