Pydantic AI

一、Pydantic AI 的核心定位和设计理念是什么？

1. 类型安全优先

Pydantic AI 的核心理念是将整类错误从运行时前移到编写时。通过 Pydantic 模型定义 Agent 的输入、输出和工具参数，开发者的 IDE 和类型检查器能够在编码阶段发现类型不匹配问题，获得类似 Rust 的"if it compiles, it works"的安全感。

2. 模型无关设计

框架支持几乎所有主流模型提供商，包括 OpenAI、Anthropic、Google Gemini、DeepSeek、Grok、Cohere、Mistral、Perplexity，以及 Azure AI Foundry、Amazon Bedrock、Ollama 等 30 余个。切换模型只需修改一个字符串，无需改动业务代码。

3. 生产级可靠性

Pydantic AI 内置结构化输出验证、自动重试、持久化执行、可观测性集成等生产级特性。v1 版本于 2025 年 9 月发布并承诺 API 稳定，v2 版本于 2026 年 6 月发布，引入 Capabilities 机制重构扩展体系。

二、Pydantic AI 的核心组成部分有哪些？

1. Agent

Agent 是 Pydantic AI 与 LLM 交互的主要接口，可视为以下组件的容器：

• Instructions：开发者编写的 LLM 指令集
• Tools：LLM 可调用的函数工具集
• Output Type：LLM 必须返回的结构化数据类型
• Dependencies：依赖注入类型约束
• Model：可选的默认 LLM 模型
• Capabilities：可复用的工具、钩子、指令和模型设置捆绑包

2. Capabilities

v2 版本引入的核心原语，将 Agent 的指令、工具、生命周期钩子和模型设置捆绑为单一可组合单元。一个 Capability 可以是一个记忆系统、一个护栏、一个编码工具包，通过一个概念触及 Agent 的每一层。

3. Pydantic AI Harness

官方提供的即用型 Capabilities 库，包含代码执行、文件访问、护栏、子 Agent 编排等功能，开发者可按需选择构建编码 Agent、研究助手等应用。

三、Pydantic AI 的 Agent 循环（Agentic Loop）是如何运行的？

1. 基本执行流程

Agent 循环的核心逻辑已趋于稳定：调用模型、执行工具、将结果反馈给模型。Pydantic AI 提供五种运行方式：

• agent.run()：异步函数，返回包含完成响应的 RunResult
• agent.run_sync()：同步函数，内部调用 run()
• agent.run_stream()：异步上下文管理器，支持流式输出
• agent.run_stream_sync()：同步版本的流式运行
• agent.iter()：返回 AgentRun，可遍历底层 Graph 的节点

2. 工具调用机制

当模型决定调用工具时，Pydantic AI 自动执行工具函数、验证参数、将结果追加到消息历史，并继续循环。整个过程对开发者透明，只需通过 @agent.tool 装饰器注册工具函数。

3. 结构化输出验证

每次运行结束时，Pydantic AI 根据 Agent 定义的 output_type 验证模型输出。验证失败时，框架将错误信息反馈给模型并要求重试，重试次数可通过 retries 参数配置。

四、Pydantic AI 的 Capabilities 机制是如何工作的？

1. 可组合的行为单元

一个 Capability 捆绑 Agent 的指令、工具、生命周期钩子和模型设置，使整个扩展（如记忆系统、护栏、编码工具包）能够通过一个概念触及 Agent 的每一层。

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

agent = Agent(
    'anthropic:claude-opus-4-7',
    instructions='Research thoroughly and cite your sources.',
    capabilities=[
        Thinking(effort='high'),
        WebSearch(),
        ToolSearch(),
        Capability(
            id='github',
            description='Look up GitHub issues, pull requests, and code.',
            instructions='Use the GitHub tools when a question is about a repository.',
            toolset=MCPToolset('https://mcp.example.com/github'),
            defer_loading=True,
        ),
    ],
)

2. 延迟加载

标记 defer_loading=True 的 Capability 在模型需要之前不会出现在提示中。模型只在紧凑目录中看到一行描述，然后在决定使用时才一次性加载整个捆绑包（包括指令和工具）。

3. 钩子机制

Capabilities 通过钩子读取和重写模型在每一步看到的内容，包括其工具、指令和消息历史。代码模式和工具搜索都基于相同的公共钩子构建。

五、Pydantic AI 如何保证类型安全和结构化输出？

1. 输出类型定义

开发者通过 output_type 参数指定 Pydantic 模型作为 Agent 的输出类型。框架会根据该模型生成 JSON Schema，并将其嵌入 LLM 请求中，利用各提供商的原生结构化输出机制（如 OpenAI 的 response_format、Anthropic 的工具调用接口）。

2. 运行时验证

LLM 返回原始响应后，Pydantic AI 根据 JSON Schema 对其进行验证，包括类型检查、字段约束和枚举成员资格验证。验证失败时，框架将错误信息反馈给模型并要求重新生成。

3. 自动重试机制

验证失败触发自动重试，重试次数可通过 Agent(retries={'output': N}) 配置。每次重试消耗一个输出重试预算单位，直到达到上限或验证成功。

六、Pydantic AI 的 Graph API 是如何定义工作流的？

1. 基于类型提示的图定义

Pydantic Graph 使用类型提示定义节点和边，每个节点的 run 方法显式声明返回类型（即下一个可能的节点），使图结构在定义时即可验证。

from pydantic_graph import Graph, BaseNode, End
from dataclasses import dataclass

@dataclass
class ConversationState:
    user_name: str | None = None
    interests: list[str] = field(default_factory=list)

@dataclass
class GreetUser(BaseNode[ConversationState]):
    async def run(self, ctx: GraphRunContext[ConversationState]) -> 'AskName':
        print("Hello! Welcome to our recommendation system.")
        return AskName()

@dataclass
class AskName(BaseNode[ConversationState]):
    async def run(self, ctx: GraphRunContext[ConversationState]) -> 'AskInterests':
        name = input("What's your name? ")
        ctx.state.user_name = name
        return AskInterests()

# 定义图
conversation_graph = Graph(
    nodes=[GreetUser, AskName, AskInterests, GenerateRecommendations, SayGoodbye],
    state_type=ConversationState,
)

2. 状态持久化

Graph 支持状态持久化，允许工作流在任意节点暂停并从断点恢复。这对于长时间运行的工作流和人机交互场景尤为重要。

3. 与 Agent 集成

Graph 节点内部可以嵌入 Pydantic AI Agent，实现 AI 驱动的工作流节点。每个步骤都可以调用 Agent 进行结构化输出处理。

七、Pydantic AI 的 Web Search 能力是如何工作的？

1. 原生工具支持

Web Search 通过 WebSearchTool 实现，作为 NativeTool 传递给模型的 Capabilities 列表。与常见的自定义工具不同，原生工具由模型提供商的基础设施直接执行。

2. 提供商支持情况

• OpenAI Responses：完整功能支持
• Anthropic：完整功能支持，支持域名过滤和最大使用次数限制
• Google Gemini：支持，但无参数支持
• xAI：支持 blocked_domains、allowed_domains 和 user_location 参数
• OpenRouter：通过插件支持网页搜索

3. 动态配置

可以通过包装函数根据运行上下文动态配置 WebSearchTool，例如根据用户位置设置搜索参数，或在无位置信息时禁用该工具。

八、Pydantic AI 的 Tool Search 能力是如何工作的？

1. 按需发现工具

Tool Search 允许 Agent 按需发现工具，而不是在提示中列出数百个工具。当工具数量庞大时，这能显著减少 Token 消耗并提高模型选择工具的准确性。

2. 延迟加载机制

与 defer_loading 的 Capability 类似，Tool Search 只在模型决定需要时才加载工具定义。模型首先看到紧凑的工具目录，然后在需要时加载完整工具信息。

3. 与 Capabilities 集成

Tool Search 作为内置 Capability 提供，可与其他 Capabilities 组合使用。它基于与用户自定义 Capabilities 相同的公共钩子构建。

九、Pydantic AI 的上下文管理机制如何控制 Token 消耗？

1. 提供商原生压缩

部分提供商暴露内置压缩 API，Pydantic AI 将其封装为 Capabilities：

• OpenAICompaction：使用 OpenAI Responses API 的压缩功能
• AnthropicCompaction：使用 Anthropic 的自动上下文压缩，可配置 token_threshold 触发阈值

2. 模型无关的历史处理

通过 history processor 包装为 ProcessHistory capability，可在任何模型上实现上下文管理：

• 滑动窗口：仅保留最近的消息，零成本
• 摘要压缩：使用更便宜的模型将旧消息压缩为摘要

3. Pydantic AI Harness 的分层压缩

Harness 提供一系列即用型模型无关压缩策略，包括零 LLM 历史编辑（滑动窗口修剪、清除旧工具结果、去重重复文件读取、钳制过大的消息部分）和 LLM 摘要，以及 TieredCompaction 编排器，仅在需要时从廉价策略升级到昂贵策略。

十、Pydantic AI 的持久化执行（Durable Execution）是如何实现的？

1. 基本原理

持久化执行使 Agent 运行能够在进程崩溃、机器重启或长时间等待后从上一个完成的步骤恢复，而不是从头开始。通过检查点记录每个步骤，在恢复时重放或重新加载状态。

2. 支持的运行时

Pydantic AI 原生支持四种持久化执行解决方案：

• Temporal：成熟的集群编排，适合长期、跨服务的工作流
• DBOS：库形式，使用现有 Postgres 连接，无需单独编排进程
• Prefect：Python 原生工作流编排，提供 UI 和缓存功能
• Restate：单一自包含二进制文件，内置复制日志和嵌入式存储

3. 使用方式

通过附加对应的 Durability capability 即可启用持久化执行：

from pydantic_ai import Agent
from pydantic_ai.durable_exec.temporal import TemporalDurability

agent = Agent(
    'openai:gpt-5.6-sol',
    instructions='Research the topic and write a structured brief.',
    capabilities=[WebSearch(), WebFetch(), TemporalDurability()],
)

十一、Pydantic AI 与 Pydantic Logfire 如何配合实现可观测性？

1. 一键集成

Pydantic AI 内置对 Logfire 的支持，只需两行代码即可启用：

import logfire
logfire.configure()
logfire.instrument_pydantic_ai()

2. 捕获内容

每次 Agent 运行生成一个 trace，包含：

• 使用的模型和运行时长
• 与模型的完整对话（可读的转录形式）
• 每次工具调用（作为子 span，包含参数和结果）
• 重试记录（包括触发每次重试的失败尝试）
• 每次模型调用的 Token 使用量和错误信息

3. OpenTelemetry 兼容

Pydantic AI 的检测功能使用 OpenTelemetry，可发送到任何 OTel 后端。Logfire 是基于 OTel 构建的商业平台，提供慷慨的免费套餐。

十二、Pydantic AI 的测试支持有哪些？

1. TestModel

最简单快速的测试方式，不调用真实 LLM，而是根据工具 schema 生成有效的结构化数据。默认会调用 Agent 中的所有工具，然后返回纯文本或结构化响应。

from pydantic_ai.models.test import TestModel

with agent.override(model=TestModel()):
    result = agent.run_sync('Hello')
    assert isinstance(result.output, str)

2. FunctionModel

用于更复杂的测试场景，允许定义自定义响应逻辑：

from pydantic_ai.models.function import FunctionModel, ModelContext
from pydantic_ai.messages import ModelResponse, TextPart

def custom_model_function(messages: list, info: ModelContext) -> ModelResponse:
    return ModelResponse(parts=[TextPart(content='Custom response')])

with agent.override(model=FunctionModel(custom_model_function)):
    result = agent.run_sync('Any query')

3. 阻止真实 API 调用

设置 ALLOW_MODEL_REQUESTS=False 全局阻止对非测试模型的请求，防止测试中意外产生 API 费用。

十三、Pydantic AI 在开发体验和调试方面有哪些优势？

1. IDE 友好

由于完全基于 Python 类型提示，IDE 能够提供自动补全、类型检查和重构支持。工具名称拼写错误会在运行前被编辑器标红。

2. 最小抽象

Pydantic AI 只有约二十个公共概念，无全局状态，无回调注册表，工具调用在各提供商间统一抽象。开发者可以在一个下午读完源代码并预测每行代码的行为。

3. 调试体验

通过 Logfire 可以可视化 Agent 运行的完整流程，包括模型调用、工具调用、重试记录。SQL 查询方式比自定义查询语言更易于调试生产问题。

十四、Pydantic AI 适合什么样的应用场景？

1. 适合的场景

• 需要结构化输出的生产级 Agent：类型安全保证输出可靠性
• 已使用 Pydantic 或 FastAPI 的团队：心智模型直接迁移
• 需要模型切换灵活性：模型无关设计支持随时切换提供商
• 对可观测性有要求：内置 OpenTelemetry 集成

2. 不太适合的场景

• 需要大量预构建集成：生态系统较新，集成数量少于 LangChain
• 复杂多 Agent 编排：Graph API 较年轻，持久化状态支持不如 LangGraph 成熟
• 非 Python 技术栈：框架仅支持 Python

十五、Pydantic AI 与 LangChain 框架的主要区别是什么？

1. 设计哲学

• Pydantic AI：类型安全优先，最小抽象，Python 原生模式
• LangChain：生态系统优先，声明式链式 DSL，丰富的预构建组件

2. 类型安全

Pydantic AI 将类型安全作为一等公民，输出验证内置且默认启用。LangChain 的输出解析器存在但可选，且经常被绕过。

3. 生态系统

LangChain 拥有 700+ 预构建集成，覆盖向量库、文档加载器、记忆系统等。Pydantic AI 覆盖主流提供商，集成数量较少但增长迅速。

4. 学习曲线

熟悉 Pydantic 或 FastAPI 的开发者可以几乎零学习成本上手 Pydantic AI。LangChain 入门简单但深度陡峭，需要理解 LCEL、runnable 协议和大量 API 表面。

5. 生产就绪性

Pydantic AI 专为生产可靠性设计，通过强制类型安全和验证输出来减少运行时错误。LangChain 通过 LangGraph 在大规模部署中得到验证，在 Klarna、Uber、Elastic 等公司有实际应用。