Doramagic.ai
English

Doramagic 项目包 · 项目说明书

pydantic-ai 项目

以 Pydantic 方式构建的 AI Agent 框架

项目概览

Pydantic AI 是由 Pydantic 团队推出的 GenAI Agent Framework，其核心理念源自 FastAPI 的开发体验，目标是把"如果能编译通过就能运行"的工程感受带入到 LLM 应用的开发中。资料来源：[README.md:1-40]()

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 4.1 Hello World

继续阅读本节完整说明和来源证据。

章节 4.2 使用 Capabilities 与工具注入

继续阅读本节完整说明和来源证据。

章节 4.3 工具与依赖注入

继续阅读本节完整说明和来源证据。

1. 项目定位与设计目标

Pydantic AI 是由 Pydantic 团队推出的 GenAI Agent Framework，其核心理念源自 FastAPI 的开发体验，目标是把"如果能编译通过就能运行"的工程感受带入到 LLM 应用的开发中。资料来源：README.md:1-40

仓库根目录的 README.md 明确写道：「我们开发 Pydantic AI 的初衷很简单：把 FastAPI 的感觉带到 GenAI 应用与 Agent 的开发中」。该框架建立在 Pydantic Validation 之上，而 Pydantic Validation 本身已经是 OpenAI SDK、Google ADK、Anthropic SDK、LangChain、LlamaIndex 等众多项目的底层验证层。资料来源：README.md:24-32

Pydantic AI 强调 "model-agnostic（模型无关）" 设计，原生支持 OpenAI、Anthropic、Gemini、DeepSeek、Grok、Cohere、Mistral、Perplexity 等模型厂商，以及 Azure AI Foundry、Amazon Bedrock、Google Cloud、Ollama、LiteLLM、Groq、OpenRouter 等托管与自托管平台，未列出的厂商也可以通过 custom model 接口扩展。资料来源：README.md:36-40

2. 仓库结构与子包

Pydantic AI 采用 monorepo 形式组织，多个子包各司其职。下表总结了顶层目录所对应的子包及其职责。

目录 / 包名角色主要内容
pydantic_ai_slim/核心运行时最小依赖集合下的 Pydantic AI 主体逻辑
pydantic_evals/评估库对"非确定性函数"进行系统性测试与评估的库
pydantic_graph/图与状态机库基于类型注解定义图节点与边的有限状态机库
clai/命令行工具与 LLM 交互的命令行客户端（含 Web Chat UI）
examples/示例集合演示各类用法的可运行示例
docs-site/文档站点源码基于 Cloudflare Workers Static Assets 的文档站

资料来源：pydantic_ai_slim/README.md:1-8、pydantic_evals/README.md:1-18、pydantic_graph/README.md:1-12、clai/README.md:1-16、examples/README.md:1-12、docs-site/README.md:1-6。

其中：

  • pydantic_ai_slim 提供"最少依赖"的核心，便于按需安装；详见 pydantic_ai_slim/README.md。资料来源：pydantic_ai_slim/README.md:1-8
  • pydantic_evals 独立于 Pydantic AI 主体，可与任意"stochastic function"实现一起使用；详见 pydantic_evals/README.md。资料来源：pydantic_evals/README.md:9-18
  • pydantic_graph 是"无 Pydantic AI 依赖"的纯图状态机库，可单独用于非 GenAI 场景；详见 pydantic_graph/README.md。资料来源：pydantic_graph/README.md:5-12
  • clai 提供 clai 命令行入口和 clai web 的 Web 聊天界面，默认端口 7932。资料来源：clai/README.md:42-58
graph TD
  A[pydantic-ai 仓库] --> B[pydantic_ai_slim]
  A --> C[pydantic_evals]
  A --> D[pydantic_graph]
  A --> E[clai CLI]
  A --> F[examples]
  A --> G[docs-site]
  B --> H[Agent / 模型适配 / 工具]
  C --> I[评估数据集与判定器]
  D --> J[图节点与状态机]
  E --> K[终端 / Web Chat UI]
  G --> L[Cloudflare Workers 文档站]

3. 核心特性

README 总结了 11 项关键能力，从工程化、协议互通到可观测性一应俱全：

  1. 由 Pydantic 团队构建 — 复用 Pydantic Validation 生态。资料来源：README.md:24-32
  2. 模型无关 — 支持多达数十家厂商，可自定义。资料来源：README.md:36-40
  3. 无缝可观测性 — 深度集成 Pydantic Logfire（同时兼容任何支持 OTel 的后端）。资料来源：README.md:42-46
  4. 完全类型安全 — IDE 与静态类型检查器友好。资料来源：README.md:48-50
  5. 强大的 Evals — 系统化测试与监控 agent 表现。资料来源：README.md:52-54
  6. 可组合能力（Capabilities） — 将工具、hooks、指令、模型设置打包为可复用单元；内置 Thinking、WebSearch、MCP 等。资料来源：README.md:56-60
  7. MCP / A2A / UI 事件流 — 集成 Model Context Protocol、Agent2Agent 以及各类 UI 事件流标准。资料来源：README.md:62-64
  8. Human-in-the-Loop 工具审批 — 通过 deferred tools 机制对工具调用进行人工审核。资料来源：README.md:66-68
  9. Durable Execution（持久化执行） — 在瞬时故障、重启与长时 / 异步工作流中保持进度。资料来源：README.md:70-72
  10. 流式结构化输出 — 在流式生成时立即进行 Pydantic 校验。资料来源：README.md:74-76
  11. Graph 支持 — 使用类型注解定义图节点。资料来源：README.md:78-80

社区中关于 issue #110 讨论的"toolsets / MCP"以及 issue #1978 提到的"handoffs / sub-agent delegation"在主线发展中均被纳入 Agent 抽象、Capabilities 与 Graph 之中。

4. 快速上手

4.1 Hello World

from pydantic_ai import Agent

agent = Agent(
    'openai:gpt-5.2',
    instructions='Be concise, reply with one sentence.',
)

result = agent.run_sync('What is the capital of France?')
print(result.output)

资料来源：README.md:90-100。

4.2 使用 Capabilities 与工具注入

README 展示了如何用 Thinking 与 WebSearch 这两个内置能力快速启用思考与联网搜索。资料来源：README.md:108-118

from pydantic_ai import Agent
from pydantic_ai.capabilities import Thinking, WebSearch

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    instructions='Be concise, reply with one sentence.',
    capabilities=[Thinking(), WebSearch()],
)
result = agent.run_sync('What was the mass of the largest meteorite found this year?')
print(result.output)

4.3 工具与依赖注入

银行客服示例演示了 RunContext[DepsType] 风格的依赖注入与结构化输出。@agent.tool 装饰器把函数注册为 LLM 可调用的工具，参数 schema 来自 Pydantic 校验；校验失败时错误会回传给 LLM 让其重试。资料来源：README.md:128-182

@support_agent.tool
async def customer_balance(
    ctx: RunContext[SupportDependencies], include_pending: bool
) -> float:
    """Returns the customer's current account balance."""
    balance = await ctx.deps.db.customer_balance(
        id=ctx.deps.customer_id,
        include_pending=include_pending,
    )
    return balance

4.4 使用 `clai` CLI

通过 uvx clai ... 即可在终端直接与 LLM 交互；clai web -m openai:gpt-5.2 启动 Web Chat UI（默认 7932 端口），也可通过 --agent my_agent:my_agent 启动已存在的 Agent。资料来源：clai/README.md:22-58

5. 文档与版本

  • 文档站基于 Cloudflare Workers Static Assets 构建，并使用 marked 渲染 Release Notes；通过 KV 缓存 Release HTML 以减轻 GitHub API 压力。资料来源：docs-site/README.md:1-6、docs-site/src/index.ts:1-40、docs-site/package.json:1-22
  • 最新发布包含 v1 主线（如 v1.103.0、v1.104.0、v1.105.0）与 v2 Beta（v2.0.0b4、v2.0.0b5），其中 v1.105.0 引入了"按需（deferred loading）"能力，包括指令、工具、模型设置和 hooks。资料来源：v1.105.0 Release Notes

See Also

资料来源：pydantic_ai_slim/README.md:1-8、pydantic_evals/README.md:1-18、pydantic_graph/README.md:1-12、clai/README.md:1-16、examples/README.md:1-12、docs-site/README.md:1-6。

Agent 模块

Agent 是 Pydantic AI 框架的核心抽象，承担"用户意图 → 模型推理 → 结构化输出"全链路编排职责。模块位于 pydanticai/agent/init.py，其设计目标是让开发者以类型安全、Pythonic 的方式构建可观测、可组合的智能体应用。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 Capability 与 Deferred Loading

继续阅读本节完整说明和来源证据。

章节 工具执行治理

继续阅读本节完整说明和来源证据。

章节 已知边界

继续阅读本节完整说明和来源证据。

概述与设计目标

Agent 是 Pydantic AI 框架的核心抽象，承担"用户意图 → 模型推理 → 结构化输出"全链路编排职责。模块位于 pydantic_ai/agent/__init__.py，其设计目标是让开发者以类型安全、Pythonic 的方式构建可观测、可组合的智能体应用。

Agent 类是泛型化的：Agent[SupportDependencies, SupportOutput] 表示该代理在运行时依赖 SupportDependencies，并以 SupportOutput 模型作为输出契约。构造时需要指定模型（形如 'openai:gpt-5.2' 或 'anthropic:claude-sonnet-4-6'）、deps_type、output_type 以及 instructions 等关键参数，参见 pydantic_ai/agent/__init__.py 与 README 中的示例片段。

模块同时提供三个扩展点：

扩展点作用所在文件
abstract.Agent抽象基类，便于类型化引用agent/abstract.py
spec.AgentSpecYAML/JSON 形式的声明式代理定义agent/spec.py
wrapper.WrapperAgent在不修改原代理的情况下包裹额外行为agent/wrapper.py

抽象基类与 WrapperAgent 的拆分，使得依赖注入、工具注册、嵌套代理等横切关注点可以被一致地复用。

核心组件与架构

Agent 在内部按职责划分为若干子系统：模型调用、消息历史管理、工具注册与执行、指令系统、输出校验。其典型运行流程如下：

flowchart LR
    A[用户输入] --> B[RunContext 注入 deps]
    B --> C[动态指令拼接]
    C --> D[模型推理 ModelRequest]
    D --> E{需要调用工具?}
    E -- 是 --> F[工具执行 ToolCall]
    F --> D
    E -- 否 --> G[输出校验 output_type]
    G --> H[RunResult 返回]
  • 运行上下文 RunContext：通过泛型 Agent[DepsType, OutputType] 携带 deps，是访问数据库连接、用户信息等运行时依赖的唯一通道（来源：README.md）。
  • 动态指令：使用 @agent.instructions 装饰器注册协程函数，函数签名接收 RunContext，使其能够根据依赖动态拼装系统提示（来源：README.md 中的 add_customer_name 示例）。
  • 结构化输出：output_type 既支持 BaseModel 子类，也支持流式输出；校验失败时框架自动回灌错误并要求模型重试（来源：pydantic_ai/agent/__init__.py）。

工具系统与依赖注入

工具通过 @agent.tool 装饰器注册，其签名同样以 RunContext[DepsType] 开头，其余参数将作为 JSON Schema 提交给模型；文档字符串则作为工具描述（来源：README.md 中的 customer_balance 工具示例）。这种"声明式签名 + Pydantic 校验"的设计意味着：错误的参数类型在静态类型检查阶段即可被 IDE 拦截，运行时模型返回的非法参数也会被自动转换为可重试的校验错误。

pydantic_evals 子包对代理行为进行系统化评估，其 Dataset.evaluate_sync 接口与 Agent 紧密耦合，使代理可被当作"可重放的非确定性函数"批量测试（来源：pydantic_evals/README.md）。

pydantic_graph 子包则提供了图与有限状态机能力，允许把多个 Agent 实例编排为有向无环图，通过 BaseNode.run 的返回类型注解来声明边（来源：pydantic_graph/README.md）。这与社区长期关注的"子代理委派 / Handoffs"诉求（Issue #1978）形成对应：组合多个 Agent 既可通过 WrapperAgent，也可借助图结构实现更显式的控制流。

高级特性与社区关注点

Capability 与 Deferred Loading

V2 Beta 引入了"按需（deferred loading）能力"，可把指令、工具、模型设置和钩子打包为可在运行时按需加载的 Capability（来源：v2.0.0b5 发布说明）。README 中展示的 capabilities=[Thinking(), WebSearch()] 即是该机制的典型用法。

工具执行治理

社区提案（Issue #5730）建议在工具执行层引入策略/审计网关。Agent 模块的"deferred tools"机制（人类审批后才能继续）已经提供了类似的钩子位点，可在 WrapperAgent 中进一步封装。

已知边界

  • model_request_parameters 跨度属性会序列化整个 ModelRequestParameters 数据类，可能引入未发送给模型的大字段（Issue #5760），调用方在敏感场景下应显式裁剪。
  • Vercel AI / AG-UI 适配器在往返过程中会静默丢弃 FileUrl.vendor_metadata 与 BinaryContent.vendor_metadata，而这些字段对部分模型提供方是"承重"的（Issue #5764）。

See Also

  • pydantic_evals/README.md — 代理系统化评估
  • pydantic_graph/README.md — 图与状态机，代理组合
  • clai/README.md — 命令行 clai 入口，可加载 Agent 变量
  • Issue #1978 Handoffs — 子代理委派讨论
  • Issue #582 Structured outputs — 结构化输出替代 Tool Calling 的讨论

来源：https://github.com/pydantic/pydantic-ai / 项目说明书

Toolsets 模块

Toolsets 模块是 Pydantic AI 中负责将一组「工具」以及与之关联的指令、模型设置、钩子等打包为可复用、可动态加载单元的核心机制。该模块位于 pydanticaislim/pydanticai/toolsets/ 目录中，是 Pydantic AI 将 Model Context Protocol（MCP）、OpenAPI、以及自定义工具进行统一抽象的关键基...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 延迟加载（Deferred Loading）

继续阅读本节完整说明和来源证据。

章节 工具搜索（Tool Search）

继续阅读本节完整说明和来源证据。

章节 动态工具集（Dynamic Toolsets）

继续阅读本节完整说明和来源证据。

概述

Toolsets 模块是 Pydantic AI 中负责将一组「工具」以及与之关联的指令、模型设置、钩子等打包为可复用、可动态加载单元的核心机制。该模块位于 pydantic_ai_slim/pydantic_ai/toolsets/ 目录中，是 Pydantic AI 将 Model Context Protocol（MCP）、OpenAPI、以及自定义工具进行统一抽象的关键基础设施。资料来源：pydantic_ai_slim/pydantic_ai/toolsets/AGENTS.md、pydantic_ai_slim/pydantic_ai/toolsets/__init__.py。

从社区演进的角度看，Toolsets 的概念最早在 issue #110「Toolsets, OpenAPI and Model Context Protocol」中被正式提出，目的是为 Pydantic AI 提供一种以「工具集」为单位的资源封装方式，使代理（agent）能够按需获取外部能力。资料来源：Issue #110。在 v1.105.0 发布说明中也明确提到：「feat: On-demand (deferred loading) capabilities, including instructions, tools, model settings, and hooks」，这表明 Toolsets 已经支持在调用时按需延迟加载能力。资料来源：Release v1.105.0。

模块组成

Toolsets 目录下的文件按职责进行了清晰拆分。下表对各核心组件进行了汇总说明：

文件角色主要职责
AGENTS.md文档入口为代理（agent）提供面向工具集行为的说明
__init__.py模块导出暴露 Toolsets 公共 API
_capability_owned.py能力所有权抽象表示「被某个 capability 所拥有」的工具集合，用于在 capability 体系下定位工具来源
_deferred_capability_loader.py延迟加载器提供在运行期按需加载 instructions、tools、model settings、hooks 等能力的机制
_dynamic.py动态工具集允许工具集在运行期根据上下文或状态动态变化
_tool_search.py工具搜索在大量工具存在时支持按需检索，避免一次性下发过多工具定义

资料来源：pydantic_ai_slim/pydantic_ai/toolsets/AGENTS.md、pydantic_ai_slim/pydantic_ai/toolsets/__init__.py、pydantic_ai_slim/pydantic_ai/toolsets/_capability_owned.py、pydantic_ai_slim/pydantic_ai/toolsets/_deferred_capability_loader.py、pydantic_ai_slim/pydantic_ai/toolsets/_dynamic.py、pydantic_ai_slim/pydantic_ai/toolsets/_tool_search.py。

架构与数据流

下图展示了 Toolsets 模块在 Pydantic AI 代理运行流程中的位置以及各子模块之间的协作关系：

flowchart LR
    A[Agent 启动] --> B[Capability 解析]
    B --> C{是否需要延迟加载?}
    C -- 是 --> D[_deferred_capability_loader<br/>按需拉取 instructions/tools/hooks]
    C -- 否 --> E[直接装配 Toolsets]
    D --> F[_capability_owned<br/>标识工具归属]
    E --> F
    F --> G[模型调用]
    G --> H{工具集较大?}
    H -- 是 --> I[_tool_search<br/>按需检索工具]
    H -- 否 --> J[下发全部工具]
    I --> J
    J --> K[模型返回 / 工具调用]
    K --> L{是否动态变更?}
    L -- 是 --> M[_dynamic<br/>运行期调整工具集]
    L -- 否 --> N[结果返回 Agent]
    M --> N

在上述流程中，能力（capability）解析阶段会根据代理配置决定哪些工具集是同步激活、哪些需要延迟加载。_deferred_capability_loader.py 负责把那些声明为按需加载的工具集在第一次实际被调用时才进行实例化。_capability_owned.py 用于记录某个具体工具是归属于哪个 capability 的，从而在多 capability 场景下追踪工具来源。资料来源：pydantic_ai_slim/pydantic_ai/toolsets/_deferred_capability_loader.py、pydantic_ai_slim/pydantic_ai/toolsets/_capability_owned.py。

关键能力解析

延迟加载（Deferred Loading）

延迟加载是 Toolsets 在 v1.105.0 中引入的关键能力之一。它允许把 instructions、tools、model settings、hooks 等原本随代理启动就立即初始化的资源，延后到真正需要时再进行加载。资料来源：Release v1.105.0。对应的实现位于 _deferred_capability_loader.py，它在能力注册阶段仅记录「可被延迟加载」的事实，直到运行期第一次被引用时才执行实际的构建工作。资料来源：pydantic_ai_slim/pydantic_ai/toolsets/_deferred_capability_loader.py。

工具搜索（Tool Search）

当一个工具集包含大量工具（例如通过 MCP 接入的上百个工具）时，一次性把工具定义全部发送给模型既不经济，也可能超出上下文窗口。_tool_search.py 引入了按需检索的能力，使代理能够根据当前任务在运行期发现并加载合适的工具子集。资料来源：pydantic_ai_slim/pydantic_ai/toolsets/_tool_search.py。

动态工具集（Dynamic Toolsets）

_dynamic.py 提供了在运行期根据上下文（如 RunContext、用户偏好或外部状态）改变工具集内容的能力。社区提案 #5730「Gating tool execution with a policy/audit layer」即基于此扩展点讨论如何为工具执行增加策略与审计层。资料来源：Issue #5730、pydantic_ai_slim/pydantic_ai/toolsets/_dynamic.py。

常见使用场景

  • MCP 集成：通过 Toolsets 将 MCP Server 提供的工具进行封装，使代理能够按工具集粒度启用或停用 MCP 能力。资料来源：Issue #110。
  • 大型工具集裁剪：借助 _tool_search 在面对上百个工具时减少 prompt 体积。资料来源：pydantic_ai_slim/pydantic_ai/toolsets/_tool_search.py。
  • 按需能力加载：将昂贵的初始化逻辑放入延迟加载器，以缩短代理冷启动时间。资料来源：pydantic_ai_slim/pydantic_ai/toolsets/_deferred_capability_loader.py。
  • 策略与审计网关：在动态工具集中插入策略检查点，实现人类审批或权限控制。资料来源：Issue #5730。

已知问题与边界

社区中关于 Toolsets 的若干讨论点值得关注：

  • 模型调用跨度（span）中的 model_request_parameters 属性会序列化整个 ModelRequestParameters 数据类，其中可能包含未实际发送给模型的较大字段（如完整工具集），从而产生额外开销。资料来源：Issue #5760。
  • 第三方项目（如 Agent_Sudo）建议在 Toolsets 之上引入策略/审计网关层，以便对工具调用进行权限控制。资料来源：Issue #5730。
  • V2 路线图中提到了将 Toolsets 与 capabilities、harness 体系进一步整合的方向。资料来源：Release v2.0.0b5。

See Also

资料来源：pydantic_ai_slim/pydantic_ai/toolsets/AGENTS.md、pydantic_ai_slim/pydantic_ai/toolsets/__init__.py、pydantic_ai_slim/pydantic_ai/toolsets/_capability_owned.py、pydantic_ai_slim/pydantic_ai/toolsets/_deferred_capability_loader.py、pydantic_ai_slim/pydantic_ai/toolsets/_dynamic.py、pydantic_ai_slim/pydantic_ai/toolsets/_tool_search.py。

Providers 模块

Providers 模块位于 Pydantic AI 的核心包 pydanticaislim 之下，是框架面向多模型厂商的适配器层（adapter layer）。其唯一职责是把上层与厂商无关的 Agent、ModelRequestParameters、ModelResponse 等抽象，翻译成各个 LLM 厂商 SDK 所要求的请求/响应形态。Pydantic AI 在 R...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述与设计目标

Providers 模块位于 Pydantic AI 的核心包 pydantic_ai_slim 之下，是框架面向多模型厂商的适配器层（adapter layer）。其唯一职责是把上层与厂商无关的 Agent、ModelRequestParameters、ModelResponse 等抽象，翻译成各个 LLM 厂商 SDK 所要求的请求/响应形态。Pydantic AI 在 README 中将 "Model-agnostic" 列为第二大卖点，并明确列出了 OpenAI、Anthropic、Gemini、DeepSeek、Grok、Cohere、Mistral、Perplexity、Azure AI Foundry、Amazon Bedrock、Google Cloud、Ollama、LiteLLM、Groq、OpenRouter、Together AI、Fireworks AI、Cerebras、Hugging Face、GitHub、Heroku、Vercel、Nebius、OVHcloud、Alibaba Cloud、SambaNova 等多家厂商。资料来源：README.md

Providers 子包目录中针对每家厂商各设独立模块，例如 pydantic_ai_slim/pydantic_ai/providers/anthropic.py、pydantic_ai_slim/pydantic_ai/providers/azure.py、pydantic_ai_slim/pydantic_ai/providers/alibaba.py 等；并由 pydantic_ai_slim/pydantic_ai/providers/__init__.py 统一导出。这一组织方式让上层 models 子包只依赖抽象接口，新增厂商时只需在 providers/ 中追加一个文件，符合 "open-closed" 的扩展原则。资料来源：pydantic_ai_slim/pydantic_ai/providers/__init__.py

slim 包的设计哲学是 "core logic with minimal required dependencies"，因此每个 provider 文件按需引入对应厂商 SDK，避免把 OpenAI、Anthropic、Bedrock 等重型客户端同时拖入依赖图。资料来源：pydantic_ai_slim/README.md

目录结构与扩展规范

providers/ 目录被进一步细分为两类资源：

  1. 厂商适配器模块：以厂商名命名（如 anthropic.py、azure.py、alibaba.py、google.py），每个文件实现统一的 Provider 协议，负责构造厂商特定的 HTTP 客户端、鉴权头、region/endpoint 设置以及消息与工具的格式转换。
  2. 厂商元数据：例如 pydantic_ai_slim/pydantic_ai/providers/_bedrock_model_names.py 维护了 Bedrock 平台支持的全部 model id 静态列表；类似机制用于其它模型数量庞大的平台。

下表汇总了 README 中明确支持的厂商类别，便于读者快速对照：

类别典型厂商Provider 字符串示例
一线闭源OpenAI、Anthropic、Google Geminiopenai:gpt-5.2、anthropic:claude-sonnet-4-6
国产/亚洲DeepSeek、Alibaba Cloud由 alibaba.py 等模块提供
云托管代理Azure AI Foundry、Amazon Bedrock、Google Cloudazure:、bedrock:、google-vertex:
开源自托管Ollama、LiteLLM、Groq、OpenRouterollama:、litellm:、groq:
聚合/转发Together AI、Fireworks AI、Cerebras、Hugging Face、GitHub、Heroku、Vercel、Nebius、OVHcloud、SambaNova统一以 <provider>:<model> 形式引用

新增厂商时请遵循 pydantic_ai_slim/pydantic_ai/providers/AGENTS.md 中的贡献规范，确保与 Model 抽象保持一致。

通用调用模式与配置约定

调用 Pydantic AI 时使用 <provider>:<model> 字符串即可隐式选择对应 Provider。CLI 工具 clai 同样遵循此约定，默认模型为 openai-chat:gpt-5。资料来源：clai/README.md

环境变量约定与上游 SDK 一致，例如 OpenAI 使用 OPENAI_API_KEY，其它厂商以 <VENDOR>_API_KEY 形式提供。pydantic_ai_slim 包刻意保持最少必需依赖，因此安装基础包时不会带入任何厂商 SDK；用户需自行安装对应 provider 的可选依赖。资料来源：pydantic_ai_slim/README.md

下面是 README 中给出的多厂商典型用法：

from pydantic_ai import Agent
from pydantic_ai.capabilities import Thinking, WebSearch

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    instructions='Be concise, reply with one sentence.',
    capabilities=[Thinking(), WebSearch()],
)

Capability（如 Thinking、WebSearch）以声明式方式接入，由各 provider 在自身模块内翻译为厂商原生字段，例如 thinking 开关、搜索工具启用等；v1.104.0 还修复了在 OpenRouter/xAI/Bedrock 等混合路由上 thinking=False 静默丢失的 bug。资料来源：README.md、v1.104.0 release

社区关注的问题与演进方向

Providers 是社区讨论最密集的子系统之一。代表性议题包括：

  • Vertex AI 服务等级扩展：Issue #5095 提出在 google_service_tier 中新增 "Priority PayGo"，与已有的 Flex PayGo 共享 X-Vertex-AI-LLM-Shared-Request-Type 请求头模式。资料来源：Issue #5095
  • xAI 新 SDK 字段覆盖不足：Issue #5662 指出 xai-sdk 已暴露 conversation_id、seed 等参数，但当前 adapter 尚未透传。资料来源：Issue #5662
  • vendor_metadata 跨适配器丢失：Issue #5764 报告 Vercel AI / AG-UI adapter 在 round-trip 时丢弃 FileUrl.vendor_metadata 与 BinaryContent.vendor_metadata，而这些字段是若干上游 provider 的负载字段，需要在 provider 层统一处理。资料来源：Issue #5764
  • 可观测性属性过大：Issue #5760 反映 model_request_parameters 在 OTel span 中序列化整个 dataclass，对未发送字段造成不必要的开销。资料来源：Issue #5760

这些讨论共同表明，Providers 层既要做"协议翻译"，也要承担"语义守门人"的职责——任何在请求路径上被静默丢弃的字段，都可能破坏下游 provider 的可追溯性与审计能力。

See Also

来源：https://github.com/pydantic/pydantic-ai / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Ability to Persist Messages in External Stores

可能增加新用户试用和生产接入成本。

high 来源证据：Feature request: Structured inter-agent message passing for multi-agent workflows

可能阻塞安装或首次运行。

high 来源证据：RFC: Pluggable cross-run memory layer (AbstractMemoryStore)

可能增加新用户试用和生产接入成本。

high 来源证据：[roundtrip-sweep] Vercel AI & AG-UI adapters: FileUrl.vendor_metadata and BinaryContent.vendor_metadata silently droppe…

可能增加新用户试用和生产接入成本。

Pitfall Log / 踩坑日志

项目：pydantic/pydantic-ai

摘要：发现 38 个潜在踩坑项，其中 14 个为 high/blocking；最高优先级：安装坑 - 来源证据：Ability to Persist Messages in External Stores。

1. 安装坑 · 来源证据：Ability to Persist Messages in External Stores

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ability to Persist Messages in External Stores
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/530 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Feature request: Structured inter-agent message passing for multi-agent workflows

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: Structured inter-agent message passing for multi-agent workflows
  • 对用户的影响：可能阻塞安装或首次运行。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/4580 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：RFC: Pluggable cross-run memory layer (AbstractMemoryStore)

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：RFC: Pluggable cross-run memory layer (AbstractMemoryStore)
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/4773 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：[roundtrip-sweep] Vercel AI & AG-UI adapters: FileUrl.vendor_metadata and BinaryContent.vendor_metadata silently droppe…

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[roundtrip-sweep] Vercel AI & AG-UI adapters: FileUrl.vendor_metadata and BinaryContent.vendor_metadata silently dropped on round-trip (UploadedFi [Content tru…
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/5764 | 来源类型 github_issue 暴露的待验证使用条件。

5. 配置坑 · 来源证据：[aw] Pydantic AI Round-Trip Sweep failed

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[aw] Pydantic AI Round-Trip Sweep failed
  • 对用户的影响：可能阻塞安装或首次运行。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/5755 | 来源类型 github_issue 暴露的待验证使用条件。

6. 配置坑 · 来源证据：model_request_parameters span attribute serializes the entire ModelRequestParameters dataclass on every model-invoke sp…

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：model_request_parameters span attribute serializes the entire ModelRequestParameters dataclass on every model-invoke span, including large fields that aren't s…
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/5760 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 运行坑 · 来源证据：Gateway: Adaptive routing — latency-aware provider selection

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Gateway: Adaptive routing — latency-aware provider selection
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/5160 | 来源类型 github_issue 暴露的待验证使用条件。

8. 维护坑 · 来源证据：ToolReturn return_value Annotation not working as documented

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：ToolReturn return_value Annotation not working as documented
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/5765 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

9. 安全/权限坑 · 失败模式：security_permissions: Proposal: Gating tool execution with a policy/audit layer

  • 严重度：high
  • 证据强度：source_linked
  • 发现：Developers should check this security_permissions risk before relying on the project: Proposal: Gating tool execution with a policy/audit layer
  • 对用户的影响：Developers may expose sensitive permissions or credentials: Proposal: Gating tool execution with a policy/audit layer
  • 证据：failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/5730 | Proposal: Gating tool execution with a policy/audit layer

10. 安全/权限坑 · 来源证据：GoogleModel returns empty responses (0 tokens) after v1.92.0 streaming cleanup changes (PR #5313)

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：GoogleModel returns empty responses (0 tokens) after v1.92.0 streaming cleanup changes (PR #5313)
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/5769 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 安全/权限坑 · 来源证据：[Feature] Add `/usage` slash command to `clai` CLI to display cumulative token usage

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature] Add /usage slash command to clai CLI to display cumulative token usage
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/5770 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

12. 安全/权限坑 · 来源证据：[aw] No-Op Runs

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[aw] No-Op Runs
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/5685 | 来源类型 github_issue 暴露的待验证使用条件。

13. 安全/权限坑 · 来源证据：[aw] Pydantic AI Regression Detector failed

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[aw] Pydantic AI Regression Detector failed
  • 对用户的影响：可能阻塞安装或首次运行。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/5766 | 来源类型 github_issue 暴露的待验证使用条件。

14. 安全/权限坑 · 来源证据：xAI: review support for newer SDK request and provider options

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：xAI: review support for newer SDK request and provider options
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/5662 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

15. 安装坑 · 失败模式：installation: Ability to Persist Messages in External Stores

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: Ability to Persist Messages in External Stores
  • 对用户的影响：Developers may fail before the first successful local run: Ability to Persist Messages in External Stores
  • 证据：failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/530 | Ability to Persist Messages in External Stores, failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/530 | Ability to Persist Messages in External Stores

16. 配置坑 · 失败模式：configuration: Feature request: Structured inter-agent message passing for multi-agent workflows

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: Feature request: Structured inter-agent message passing for multi-agent workflows
  • 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Feature request: Structured inter-agent message passing for multi-agent workflows
  • 证据：failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/4580 | Feature request: Structured inter-agent message passing for multi-agent workflows

17. 配置坑 · 失败模式：configuration: GoogleModel returns empty responses (0 tokens) after v1.92.0 streaming cleanup changes (PR #5...

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: GoogleModel returns empty responses (0 tokens) after v1.92.0 streaming cleanup changes (PR #5313)
  • 对用户的影响：Developers may misconfigure credentials, environment, or host setup: GoogleModel returns empty responses (0 tokens) after v1.92.0 streaming cleanup changes (PR #5313)
  • 证据：failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/5769 | GoogleModel returns empty responses (0 tokens) after v1.92.0 streaming cleanup changes (PR #5313)

18. 配置坑 · 失败模式：configuration: [aw] No-Op Runs

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: [aw] No-Op Runs
  • 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [aw] No-Op Runs
  • 证据：failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/5685 | [aw] No-Op Runs

19. 配置坑 · 失败模式：configuration: [aw] Pydantic AI Regression Detector failed

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: [aw] Pydantic AI Regression Detector failed
  • 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [aw] Pydantic AI Regression Detector failed
  • 证据：failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/5766 | [aw] Pydantic AI Regression Detector failed

20. 配置坑 · 失败模式：configuration: [roundtrip-sweep] Vercel AI & AG-UI adapters: FileUrl.vendor_metadata and BinaryContent.vendo...

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: [roundtrip-sweep] Vercel AI & AG-UI adapters: FileUrl.vendor_metadata and BinaryContent.vendor_metadata silently dropped on round-trip (UploadedFi [Content truncated due to length]
  • 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [roundtrip-sweep] Vercel AI & AG-UI adapters: FileUrl.vendor_metadata and BinaryContent.vendor_metadata silently dropped on round-trip (UploadedFi [Content truncated due to length]
  • 证据：failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/5764 | [roundtrip-sweep] Vercel AI & AG-UI adapters: FileUrl.vendor_metadata and BinaryContent.vendor_metadata silently dropped on round-trip (UploadedFi [Content truncated due to length]

21. 配置坑 · 失败模式：configuration: v1.105.0 (2026-06-02)

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: v1.105.0 (2026-06-02)
  • 对用户的影响：Upgrade or migration may change expected behavior: v1.105.0 (2026-06-02)
  • 证据：failure_mode_cluster:github_release | https://github.com/pydantic/pydantic-ai/releases/tag/v1.105.0 | v1.105.0 (2026-06-02)

22. 配置坑 · 失败模式：configuration: v2.0.0b4 (2026-05-28)

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: v2.0.0b4 (2026-05-28)
  • 对用户的影响：Upgrade or migration may change expected behavior: v2.0.0b4 (2026-05-28)
  • 证据：failure_mode_cluster:github_release | https://github.com/pydantic/pydantic-ai/releases/tag/v2.0.0b4 | v2.0.0b4 (2026-05-28)

23. 配置坑 · 失败模式：configuration: v2.0.0b5 (2026-06-02)

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: v2.0.0b5 (2026-06-02)
  • 对用户的影响：Upgrade or migration may change expected behavior: v2.0.0b5 (2026-06-02)
  • 证据：failure_mode_cluster:github_release | https://github.com/pydantic/pydantic-ai/releases/tag/v2.0.0b5 | v2.0.0b5 (2026-06-02)

24. 配置坑 · 失败模式：configuration: xAI: review support for newer SDK request and provider options

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: xAI: review support for newer SDK request and provider options
  • 对用户的影响：Developers may misconfigure credentials, environment, or host setup: xAI: review support for newer SDK request and provider options
  • 证据：failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/5662 | xAI: review support for newer SDK request and provider options

25. 配置坑 · 来源证据：RFC: Pluggable cross-run memory layer (AbstractMemoryStore)

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RFC: Pluggable cross-run memory layer (AbstractMemoryStore)
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/4773 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

26. 配置坑 · 来源证据：[aw] Pydantic AI Stale Issues Finder failed

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[aw] Pydantic AI Stale Issues Finder failed
  • 对用户的影响：可能影响升级、迁移或版本选择。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/5676 | 来源类型 github_issue 暴露的待验证使用条件。

27. 能力坑 · 能力判断依赖假设

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：README/documentation is current enough for a first validation pass.
  • 对用户的影响：假设不成立时，用户拿不到承诺的能力。
  • 证据：capability.assumptions | github_repo:818331198 | https://github.com/pydantic/pydantic-ai | README/documentation is current enough for a first validation pass.

28. 维护坑 · 失败模式：migration: [aw] Pydantic AI Stale Issues Finder failed

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this migration risk before relying on the project: [aw] Pydantic AI Stale Issues Finder failed
  • 对用户的影响：Developers may hit a documented source-backed failure mode: [aw] Pydantic AI Stale Issues Finder failed
  • 证据：failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/5676 | [aw] Pydantic AI Stale Issues Finder failed

29. 维护坑 · 维护活跃度未知

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：未记录 last_activity_observed。
  • 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
  • 证据：evidence.maintainer_signals | github_repo:818331198 | https://github.com/pydantic/pydantic-ai | last_activity_observed missing
  • 严重度：medium
  • 证据强度：source_linked
  • 发现：no_demo
  • 证据：downstream_validation.risk_items | github_repo:818331198 | https://github.com/pydantic/pydantic-ai | no_demo; severity=medium

31. 安全/权限坑 · 存在评分风险

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：no_demo
  • 对用户的影响：风险会影响是否适合普通用户安装。
  • 证据：risks.scoring_risks | github_repo:818331198 | https://github.com/pydantic/pydantic-ai | no_demo; severity=medium

32. 安全/权限坑 · 来源证据：Proposal: Gating tool execution with a policy/audit layer

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Proposal: Gating tool execution with a policy/audit layer
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 证据：community_evidence:github | https://github.com/pydantic/pydantic-ai/issues/5730 | 来源类型 github_issue 暴露的待验证使用条件。

33. 能力坑 · 失败模式：capability: Feature request: Structured inter-agent message passing for multi-agent workflows

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this capability risk before relying on the project: Feature request: Structured inter-agent message passing for multi-agent workflows
  • 对用户的影响：Developers may hit a documented source-backed failure mode: Feature request: Structured inter-agent message passing for multi-agent workflows
  • 证据：failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/4580 | Feature request: Structured inter-agent message passing for multi-agent workflows

34. 能力坑 · 失败模式：capability: [aw] Pydantic AI Round-Trip Sweep failed

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this capability risk before relying on the project: [aw] Pydantic AI Round-Trip Sweep failed
  • 对用户的影响：Developers may hit a documented source-backed failure mode: [aw] Pydantic AI Round-Trip Sweep failed
  • 证据：failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/5755 | [aw] Pydantic AI Round-Trip Sweep failed, failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/5755 | [aw] Pydantic AI Round-Trip Sweep failed

35. 运行坑 · 失败模式：performance: Gateway: Adaptive routing — latency-aware provider selection

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this performance risk before relying on the project: Gateway: Adaptive routing — latency-aware provider selection
  • 对用户的影响：Developers may hit a documented source-backed failure mode: Gateway: Adaptive routing — latency-aware provider selection
  • 证据：failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/5160 | Gateway: Adaptive routing — latency-aware provider selection

36. 运行坑 · 失败模式：performance: RFC: Pluggable cross-run memory layer (AbstractMemoryStore)

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this performance risk before relying on the project: RFC: Pluggable cross-run memory layer (AbstractMemoryStore)
  • 对用户的影响：Developers may hit a documented source-backed failure mode: RFC: Pluggable cross-run memory layer (AbstractMemoryStore)
  • 证据：failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/4773 | RFC: Pluggable cross-run memory layer (AbstractMemoryStore), failure_mode_cluster:github_issue | https://github.com/pydantic/pydantic-ai/issues/4773 | RFC: Pluggable cross-run memory layer (AbstractMemoryStore)

37. 维护坑 · issue/PR 响应质量未知

  • 严重度：low
  • 证据强度：source_linked
  • 发现：issue_or_pr_quality=unknown。
  • 对用户的影响：用户无法判断遇到问题后是否有人维护。
  • 证据：evidence.maintainer_signals | github_repo:818331198 | https://github.com/pydantic/pydantic-ai | issue_or_pr_quality=unknown

38. 维护坑 · 发布节奏不明确

  • 严重度：low
  • 证据强度：source_linked
  • 发现：release_recency=unknown。
  • 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
  • 证据：evidence.maintainer_signals | github_repo:818331198 | https://github.com/pydantic/pydantic-ai | release_recency=unknown

来源：Doramagic 发现、验证与编译记录