Skip to main content

安装

支持版本:pydantic-ai-slim 2.0 至 3.0。2.0 移除了 Agent(instrument=...) 并引入了本适配器所依赖的 capability 协议,因此 1.x 无法以此方式进行追踪。

追踪配置

instrument() 必须在构建任何 Agent 之前运行。Capability 在构建时附加,因此提前创建的 Agent 不会携带任何 capability,也不会记录任何内容,且不会报错——因为并没有出错。这是使用本适配器时出现空追踪记录最常见的原因。
模块级别的 Agent 最容易踩这个坑:
确认配置是否生效:
Pydantic AI 会将传入的列表合并为一个 root_capability,因此没有 agent.capabilities 属性可供读取。 在追踪配置生效期间构建的 Agent 会保留该 capability,因此可以先调用 uninstrument(),再重新配置追踪,无需重新构建 Agent。

记录内容

此处没有钩子对和人机交互对。Pydantic AI 没有可供标记的节点或步骤边界,也没有内置的人工暂停机制,因此无从映射。如果你自行构建了上述功能,请手动发出对应事件——参见自定义 Agent output_type 不影响追踪记录。类型化运行与字符串运行产生相同的事件。

示例

在追踪记录中,restock_eta 以携带错误信息的 tool_result 形式出现,紧随其后的是另一次模型调用——Agent 在其中绕过了该错误,整个运行最终仍以 success 结束。两个事实均被完整保留。

错误、重试与控制流

Pydantic AI 会为三种不同情况抛出异常,适配器对其进行了区分: ModelRetry 被刻意划入第一组。它意味着某次尝试确实失败了,并要求模型重试,这正是工具 span 的错误字段所要记录的内容。若将其归类为控制流,则会将真实的工具失败隐藏在绿色运行结果之后。

为 Span 命名

Pydantic AI 自身的运行 span 命名为 agent。在调用时包裹一层,即可赋予自定义标签:
框架的 span 随即嵌套在 inventory 之下,模型和工具事件也挂载在此处。 保持 agent_id 低基数。它是所有仪表盘视图的主要分面,应使用角色名称,而非 UUID 或每次运行生成的字符串。

控制 Session

按以下顺序解析,首次匹配生效:
  1. instrument("pydantic_ai", session_id=...)
  2. 外层的 failproofai_sdk.session() 作用域
  3. 运行的 conversation_id,其次是 run_id
  4. 生成的 uuid4().hex

选项

常见问题

Agentinstrument() 运行之前就已构建。请参阅上方警告,并检查 agent.root_capability.capabilities
raise 会向上传播——这是 Pydantic AI 的设计。若希望模型能绕过该错误,请改为抛出带有可操作提示信息的 ModelRetry。无论哪种方式,失败都会被记录。
该子 span 是 Pydantic AI 自己的运行 span,模型和工具事件挂载于此。若希望只有一个 span,可以去掉自定义作用域,但代价是失去自定义名称。
Pydantic AI 的异步图调用栈超出了负载字段的长度限制,而回溯的最后一行正是异常本身。该字段从头部而非尾部进行截断,因此你所需的那一行会被保留。

下一步

工作原理

事件对、ID、Session 生命周期与数据传递。

读取追踪记录

在刚捕获的 Session 中追踪因果关系。

其他框架

LangGraph、CrewAI、LlamaIndex 及自定义 Agent。