文档中心: ai.pydantic.dev

Pydantic AI是一个Python智能体框架，旨在帮助您快速、可靠且轻松地构建生产级生成式AI应用和工作流。

FastAPI通过基于Pydantic数据验证的创新人体工学设计，结合类型提示等现代Python特性，彻底改变了Web开发。

然而尽管几乎所有Python智能体框架和LLM库都使用Pydantic验证，当我们在Pydantic Logfire中使用LLM时，却找不到能带来相同体验的工具。

我们开发Pydantic AI只有一个简单目标：将FastAPI的卓越体验带入GenAI应用和智能体开发领域。

选择Pydantic AI的十大理由

1. Pydantic团队原厂打造： Pydantic验证是OpenAI SDK、Google SDK、Anthropic SDK、LangChain、LlamaIndex、AutoGPT、Transformers、CrewAI、Instructor等众多框架的验证层。与其使用衍生品，何不直接选择源头？ 😊

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、阿里云、SambaNova和Outlines。如果未列出您喜爱的模型，可轻松实现自定义模型。

3. 无缝可观测性： 深度集成Pydantic Logfire——我们的通用OpenTelemetry可观测性平台，实现实时调试、基于评估的性能监控，以及行为追踪和成本分析。若您已有支持OTel的可观测平台，也可直接使用。

4. 完全类型安全： 设计上为IDE和AI编程助手提供最大上下文支持，通过类型检查实现自动补全，将整类错误从运行时转移到编写时，带来类似Rust"编译通过即能运行"的安心体验。

5. 强大的评估系统： 支持系统化测试和评估所构建智能体系统的性能与准确性，并通过Pydantic Logfire持续监控表现。

6. MCP/A2A/UI三位一体： 集成模型上下文协议、智能体间通信及多种UI事件流标准，让您的智能体能访问外部工具数据、与其他智能体交互，并通过流式事件通信构建交互应用。

7. 人工审核工具调用： 轻松标记特定工具调用需经审批方可执行，审批条件可基于工具参数、对话历史或用户偏好。

8. 持久化执行： 支持构建持久化智能体，在API临时故障和应用重启时保持进度，以生产级可靠性处理长时间运行、异步及需人工介入的工作流。

9. 流式结构化输出： 提供流式输出能力，持续生成经过即时验证的结构化数据，确保实时访问生成内容。

10. 图结构支持： 通过类型提示提供强大的图结构定义方式，适用于标准控制流易退化为"面条代码"的复杂应用场景。

不过说真的，任何列表都不如亲身体验来得有说服力！

Hello World示例

以下是Pydantic AI的极简示例：

from pydantic_ai import Agent

# 定义包含所用模型的简单智能体，也可在运行时设置模型
agent = Agent(
    'anthropic:claude-sonnet-4-0',
    # 通过关键字参数注册静态指令
    # 更复杂的动态指令生成参见下方示例
    instructions='回答请简明扼要，用一句话回复。',
)

# 同步运行智能体，与LLM进行对话
result = agent.run_sync('"hello world"这个说法最早出自哪里？')
print(result.output)
"""
"hello, world"的首次使用记录出现在1974年关于C语言的教材中。
"""

(此示例完整可运行，前提是您已安装pydantic_ai包)

这个交互非常简单：Pydantic AI会将指令和用户提示发送给LLM，模型返回文本响应。

虽然还不够有趣，但我们可以轻松添加工具、动态指令和结构化输出来构建更强大的智能体。

工具与依赖注入示例

以下是使用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',
    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`装饰器用于注册LLM在响应时可能调用的函数
# 依赖项同样通过`RunContext`传递，其他参数将转为传递给LLM的工具模式
# Pydantic会验证这些参数，错误将反馈给LLM以便重试
@support_agent.tool
async def customer_balance(
        ctx: RunContext[SupportDependencies], include_pending: bool
) -> float:
    """返回客户当前账户余额"""
    # 工具函数的文档字符串也会作为描述传递给LLM
    # 参数描述将从文档字符串提取并添加到发送给LLM的参数模式中
    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()) # 异步运行智能代理，与LLM进行多轮对话直至获得最终响应 # 即使在这个简单案例中，代理也会通过多次消息交互调用工具来获取输出结果 result = await support_agent.run('查询我的余额', deps=deps) # 结果输出将通过Pydantic验证确保符合SupportOutput类型。由于代理是泛型的， # 静态类型检查时也会明确标注为SupportOutput类型 print(result.output) """ support_advice='您好John，您当前账户余额（含待处理交易）为123.45美元。' block_card=False risk=1 """

result = await support_agent.run('我的卡片丢失了！', deps=deps)
print(result.output)
"""
support_advice="很遗憾听到这个消息，John。我们将临时冻结您的卡片以防止未授权交易。" block_card=True risk=8
"""

后续步骤

立即体验Pydantic AI：

• 安装指南
• 按照示例教程操作

深入学习：

• 阅读开发文档了解应用构建
• 查看API参考掌握接口规范

获取支持：

• 加入Slack社区
• 提交GitHub工单

（注：保留所有技术术语和链接原貌，仅对自然语言部分进行本地化转换）