安装
pydantic-ai-slim 2.0 至 3.0。2.0 移除了 Agent(instrument=...) 并引入了本适配器所依赖的 capability 协议,因此 1.x 无法以此方式进行追踪。
追踪配置
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。在调用时包裹一层,即可赋予自定义标签:
inventory 之下,模型和工具事件也挂载在此处。
保持 agent_id 低基数。它是所有仪表盘视图的主要分面,应使用角色名称,而非 UUID 或每次运行生成的字符串。
控制 Session
按以下顺序解析,首次匹配生效:instrument("pydantic_ai", session_id=...)- 外层的
failproofai_sdk.session()作用域 - 运行的
conversation_id,其次是run_id - 生成的
uuid4().hex
选项
常见问题
运行正常,但没有任何事件出现
运行正常,但没有任何事件出现
Agent 在 instrument() 运行之前就已构建。请参阅上方警告,并检查 agent.root_capability.capabilities。工具中的普通异常导致运行终止
工具中的普通异常导致运行终止
裸
raise 会向上传播——这是 Pydantic AI 的设计。若希望模型能绕过该错误,请改为抛出带有可操作提示信息的 ModelRetry。无论哪种方式,失败都会被记录。出现了一个我没有创建的嵌套 Agent Span
出现了一个我没有创建的嵌套 Agent Span
该子 span 是 Pydantic AI 自己的运行 span,模型和工具事件挂载于此。若希望只有一个 span,可以去掉自定义作用域,但代价是失去自定义名称。
回溯信息以截断标记开头
回溯信息以截断标记开头
Pydantic AI 的异步图调用栈超出了负载字段的长度限制,而回溯的最后一行正是异常本身。该字段从头部而非尾部进行截断,因此你所需的那一行会被保留。
下一步
工作原理
事件对、ID、Session 生命周期与数据传递。
读取追踪记录
在刚捕获的 Session 中追踪因果关系。
其他框架
LangGraph、CrewAI、LlamaIndex 及自定义 Agent。

