---

文档: ai.pydantic.dev

---

Pydantic AI 是一个 Python 代理框架，旨在帮助您快速、自信且轻松地使用生成式 AI 构建生产级应用和工作流。

FastAPI 通过创新且人体工学的设计，彻底改变了 Web 开发，其基础是 Pydantic 验证以及现代 Python 特性，如类型提示。

然而，尽管几乎每个 Python 代理框架和 LLM 库都使用了 Pydantic 验证，但当我们开始在 Pydantic Logfire 中使用 LLM 时，却找不到任何能给我们带来同样感觉的东西。

我们构建 Pydantic AI 的目标很简单：将 FastAPI 的那种开发体验带到 GenAI 应用和代理开发中。

为什么选择 Pydantic AI

1. 由 Pydantic 团队打造: Pydantic 验证 是 OpenAI SDK、Google ADK、Anthropic SDK、LangChain、LlamaIndex、AutoGPT、Transformers、CrewAI、Instructor 等众多工具的验证层。既然可以直接使用源头技术，为何还要使用衍生品呢？ :smiley:

2. 模型无关: 支持几乎所有 模型 和提供商：OpenAI、Anthropic、Gemini、DeepSeek、Grok、Cohere、Mistral 和 Perplexity；Azure AI Foundry、Amazon Bedrock、Google Vertex AI、Ollama、LiteLLM、Groq、OpenRouter、Together AI、Fireworks AI、Cerebras、Hugging Face、GitHub、Heroku、Vercel、Nebius、OVHcloud、Alibaba Cloud、SambaNova 和 Outlines。如果您喜欢的模型或提供商未列出，也可以轻松实现 自定义模型。

3. 无缝可观测性: 与我们的通用 OpenTelemetry 可观测平台 Pydantic Logfire 紧密 集成，可实现实时调试、基于评估的性能监控，以及行为、追踪和成本跟踪。如果您已有支持 OTel 的可观测性平台，也可以 使用该平台。

4. 完全类型安全: 设计旨在为您的 IDE 或 AI 编码助手提供尽可能多的上下文信息，以实现自动补全和 类型检查，从而将大量错误从运行时转移到编写时，带来类似 Rust 的“如果能编译，就一定有效”的开发体验。

5. 强大的评估功能: 使您能够系统地测试和 评估 所构建代理系统的性能和准确性，并在 Pydantic Logfire 中持续监控其表现。

6. 设计上高度可扩展: 您可以从可组合的 能力 中构建代理，这些能力将工具、钩子、指令和模型设置打包成可重用单元。使用内置的能力进行 网页搜索、思考 和 MCP，也可以自行构建，或安装 第三方能力包。整个代理的定义都可以用 YAML/JSON 来完成——无需编写代码。

7. MCP、A2A 和 UI: 集成了 模型上下文协议、Agent2Agent 以及多种 UI 事件流 标准，使您的代理能够访问外部工具和数据，与其他代理互操作，并构建基于流式事件通信的交互式应用。

8. 人工介入工具审批: 可以轻松标记某些工具调用需要 审批 后才能继续执行，具体取决于工具调用参数、对话历史或用户偏好。

9. 持久化执行: 使您能够构建 持久化代理，即使在临时性的 API 故障、应用程序错误或重启情况下也能保留进度，并以生产级可靠性处理长时间运行、异步以及涉及人工干预的工作流。

10. 流式输出: 提供持续 流式 输出结构化结果的能力，同时进行即时验证，确保实时访问生成的数据。

11. 图支持: 提供了一种强大的方式，利用类型提示来定义 图，适用于标准控制流程容易演变成“意大利面代码”的复杂应用中。

不过说真的，再长的列表也不如亲自 试一试 来得有说服力！看看它带给您的感受吧！

Hello World 示例

以下是 Pydantic AI 的一个极简示例：

from pydantic_ai import Agent

# 定义一个非常简单的代理，包括要使用的模型；您也可以在运行代理时指定模型。
agent = Agent(
    'anthropic:claude-sonnet-4-6',
    # 使用代理的关键字参数注册静态指令。
    # 对于更复杂的动态生成指令，请参阅下面的示例。
    instructions='言简意赅，只回复一句话。',
)

# 同步运行代理，与大语言模型进行对话。
result = agent.run_sync('“hello world”是从哪里来的？')
print(result.output)
"""
“hello, world”最早见于1974年一本关于C语言的教科书。
"""

(此示例已完整，可在安装了 pydantic_ai 包的情况下直接运行。)

交互过程将非常简短：Pydantic AI 会将指令和用户提示发送给大语言模型，模型则会返回一段文本响应。

目前这还显得不够有趣，但我们可以通过添加工具、动态指令、结构化输出，或可组合的能力，来构建更强大的智能体。

以下是同一个智能体，但增加了思考和网络搜索能力：

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

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    instructions='请简洁回答，只用一句话。',
    capabilities=[Thinking(), WebSearch()],
)

result = agent.run_sync('今年发现的最大陨石质量是多少？')
print(result.output)

工具与依赖注入示例

以下是一个使用 Pydantic AI 构建银行客服代理的简洁示例：

(更详细的文档示例请参见 文档)

from dataclasses import dataclass

from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext

from bank_database import DatabaseConn


# SupportDependencies 用于将运行时所需的数据、连接和逻辑传递给模型，以便在执行指令和工具函数时使用。
# 依赖注入提供了一种类型安全的方式来自定义智能体的行为。
@dataclass
class SupportDependencies:
    customer_id: int
    db: DatabaseConn


# 此 Pydantic 模型定义了智能体返回的输出结构。
class SupportOutput(BaseModel):
    support_advice: str = Field(description='返回给客户的建议')
    block_card: bool = Field(description="是否需要冻结客户的银行卡")
    risk: int = Field(description='查询的风险等级', ge=0, le=10)


# 此智能体将作为银行的一线客服代理。
# 智能体对接受的依赖类型和返回的输出类型都是通用的。
# 在本例中，客服智能体的类型为 `Agent[SupportDependencies, SupportOutput]`。
support_agent = Agent(
    'openai:gpt-5.2',
    deps_type=SupportDependencies,
    # 智能体的响应将被保证为 SupportOutput 类型，
    # 如果验证失败，智能体会被提示重新尝试。
    output_type=SupportOutput，
    instructions=(
        '您是我们银行的客服代表，请为客户提供支持，并评估其咨询的风险等级。'
    ),
)


# 动态指令可以利用依赖注入功能。
# 依赖项通过 `RunContext` 参数传递，该参数以上述 `deps_type` 为泛型。
# 如果这里的类型注解有误，静态类型检查器会捕获它。
@support_agent.instructions
async def add_customer_name(ctx: RunContext[SupportDependencies]) -> str:
    customer_name = await ctx.deps.db.customer_name(id=ctx.deps.customer_id)
    return f"客户的姓名是 {customer_name!r}"


# 使用 `tool` 装饰器可以注册一些函数，这些函数可以在大语言模型响应用户请求时被调用。
# 再次强调，依赖项通过 `RunContext` 传递，其他参数则会成为传递给大语言模型的工具接口。
# Pydantic 用于验证这些参数，如果出现错误，会反馈给大语言模型以便其重试。
@support_agent.tool
async def customer_balance(
        ctx: RunContext[SupportDependencies], include_pending: bool
) -> float:
    """返回客户的当前账户余额。"""
    # 工具的文档字符串也会作为工具描述传递给大语言模型。
    # 参数描述会从文档字符串中提取，并添加到发送给大语言模型的参数模式中。
    balance = await ctx.deps.db.customer_balance(
        id=ctx.deps.customer_id,
        include_pending=include_pending,
    )
    return balance


...  # 在实际应用中，您还可以添加更多工具和更长的系统提示


async def main():
    deps = SupportDependencies(customer_id=123, db=DatabaseConn())
    # 异步运行智能体，与大语言模型进行对话，直到获得最终响应。
    # 即使在这个相对简单的场景中，智能体也会在调用工具获取结果的过程中与大语言模型多次交互。
    result = await support_agent.run('我的余额是多少？', deps=deps)
    # `result.output` 将使用 Pydantic 进行验证，以确保其符合 `SupportOutput` 类型。由于智能体是通用的，
    # 它的类型也将被标注为 `SupportOutput`，从而有助于静态类型检查。
    print(result.output)
    """
    support_advice='您好，约翰，您当前账户的余额（包括未结算交易）为123.45美元。' block_card=False risk=1
    """

    result = await support_agent.run('我刚刚丢了卡！', deps=deps)
    print(result.output)
    """
    support_advice="很抱歉听到这个消息，约翰。我们已暂时冻结您的卡片，以防止未经授权的交易。" block_card=True risk=8
    """

下一步

要亲自体验 Pydantic AI，请先安装，然后按照示例中的说明操作。

阅读文档以了解更多关于使用 Pydantic AI 构建应用程序的信息。

查阅API 参考以理解 Pydantic AI 的接口。

如果您有任何问题，欢迎加入 Slack 或在 GitHub 上提交问题。

Pydantic AI 快速上手指南

Pydantic AI 是一个由 Pydantic 团队打造的 Python Agent 框架，旨在帮助开发者快速、自信地构建生产级的生成式 AI 应用和工作流。它继承了 FastAPI 的优雅设计，提供模型无关、类型安全、可观测性强等特性。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：3.9 及以上
• 前置依赖：
  • 已安装 Python 包管理工具（pip 或 uv）
  • 拥有至少一个 LLM 提供商的 API Key（如 OpenAI, Anthropic, Google Gemini 等）

安装步骤

使用 pip 安装核心包：

pip install pydantic-ai

若需使用特定模型提供商（例如 OpenAI 或 Anthropic），请安装对应的额外依赖：

# 示例：安装 OpenAI 和 Anthropic 支持
pip install "pydantic-ai[openai,anthropic]"

提示：国内开发者若遇到下载速度慢的问题，可使用清华或阿里云镜像源加速安装：

pip install pydantic-ai -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

1. Hello World 示例

以下是最简单的同步运行示例，展示如何定义 Agent 并获取回答：

from pydantic_ai import Agent

# 定义一个简单的 Agent，指定模型和系统指令
agent = Agent(
    'anthropic:claude-sonnet-4-6',
    instructions='Be concise, reply with one sentence.',
)

# 同步运行 Agent
result = agent.run_sync('Where does "hello world" come from?')
print(result.output)

输出示例：

The first known use of "hello, world" was in a 1974 textbook about the C programming language.

2. 添加能力（Capabilities）

你可以轻松为 Agent 添加“思考”或“联网搜索”等内置能力：

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)

3. 使用工具与依赖注入（进阶）

Pydantic AI 支持通过依赖注入传递数据库连接等上下文，并定义结构化输出：

from dataclasses import dataclass
from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext

# 模拟数据库连接
class DatabaseConn:
    async def customer_name(self, id: int) -> str:
        return "John Doe"
    async def customer_balance(self, id: int, include_pending: bool) -> float:
        return 1234.56

@dataclass
class SupportDependencies:
    customer_id: int
    db: DatabaseConn

class SupportOutput(BaseModel):
    support_advice: str = Field(description='Advice returned to the customer')
    block_card: bool = Field(description="Whether to block the customer's card")
    risk: int = Field(description='Risk level of query', ge=0, le=10)

support_agent = Agent(
    'openai:gpt-5.2',
    deps_type=SupportDependencies,
    output_type=SupportOutput,
    instructions='You are a support agent in our bank.',
)

@support_agent.instructions
async def add_customer_name(ctx: RunContext[SupportDependencies]) -> str:
    customer_name = await ctx.deps.db.customer_name(id=ctx.deps.customer_id)
    return f"The customer's name is {customer_name!r}"

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

async def main():
    deps = SupportDependencies(customer_id=123, db=DatabaseConn())
    result = await support_agent.run('What is my balance?', deps=deps)
    print(result.output)

# 运行异步入口
# import asyncio
# asyncio.run(main())

通过以上步骤，你即可开始使用 Pydantic AI 构建类型安全、功能强大的 AI Agent 应用。更多高级功能（如图形工作流、持久化执行、MCP 协议集成等）请参考官方文档。