PydanticAI：Pydantic 官方出品的结构化 AI 应用开发框架

1. 开篇

这篇教程带你从零跑通 PydanticAI 的完整链路，最终成果是一个能回答用户提问并返回强类型结构化结果的天气查询 Agent——你问"上海今天冷吗"，它返回一个带 temperature 和 clothing_advice 字段的 Python 对象，而不是一段裸字符串。

2. 前置条件

• Python 3.9+：PydanticAI 依赖 Pydantic v2，低于 3.9 无法安装
• OpenAI API Key：默认使用 OpenAI 模型，需要 OPENAI_API_KEY 环境变量
• 网络能够访问 API 端点：如果你所在网络需要代理，请提前配置
• pip 22+：确保能正常安装依赖和解析版本

3. 安装部署

3.1 创建虚拟环境并安装

mkdir pydantic-ai-demo && cd pydantic-ai-demo
python -m venv .venv
source .venv/bin/activate  # Windows 下使用 .venvScriptsactivate
pip install pydantic-ai

3.2 准备环境变量

把 API Key 写入环境变量，避免在代码里硬编码。

export OPENAI_API_KEY="sk-你的key"

3.3 验证安装

python -c "import pydantic_ai; print(pydantic_ai.__version__)"

正常会输出版本号，比如 0.0.10。

4. 第一个 Demo：天气查询 Agent

4.1 定义输出模型

这一步要做什么：声明一个 Pydantic 模型，规定 LLM 的输出结构。这样后续拿到的一定是 WeatherResponse 实例，而不是自由文本。

from pydantic import BaseModel, Field

class WeatherResponse(BaseModel):
    temperature: float = Field(description="摄氏度")
    clothing_advice: str = Field(description="适合当前温度的穿衣建议")

4.2 创建 Agent 并绑定模型

这一步要做什么：初始化一个 Agent，指定使用的 LLM 和输出类型。PydanticAI 会在内部完成工具调用与结果校验的流程。

from pydantic_ai import Agent

agent = Agent(
    'openai:gpt-4o-mini',
    result_type=WeatherResponse,
    system_prompt='你是一个贴心的天气助手。根据用户问题提取温度信息并给出建议。',
)

4.3 运行并获取结构化结果

这一步要做什么：直接调用 agent.run_sync() 传入用户问题，然后在结果中取出 output 字段，这就是校验后的类型化对象。

if __name__ == "__main__":
    result = agent.run_sync("上海今天多少度？穿什么合适？")
    weather = result.output
    print(type(weather))
    print(f"温度: {weather.temperature}")
    print(f"建议: {weather.clothing_advice}")

预期输出

<class '__main__.WeatherResponse'>
温度: 18.0
建议: 建议穿薄外套，早晚温差较大，注意保暖

可以看到 result.output 是一个 WeatherResponse 对象，字段可以直接点取。这和普通 LLM 返回字符串有本质区别——下游代码再也无需做脆弱的正则解析。

5. 配置与调优

5.1 使用更快的模型

将模型名从 openai:gpt-4o-mini 换成 openai:gpt-4o-mini 只是基础操作。更关键的是通过 model_settings 调低温度，让输出更稳定。

agent = Agent(
    'openai:gpt-4o-mini',
    result_type=WeatherResponse,
    model_settings={'temperature': 0.2},
)

5.2 启用结果校验重试

当 LLM 输出的 JSON 不合法时，PydanticAI 默认会报错。你可以开启自动重试，让模型自己修正格式问题。

agent = Agent(
    'openai:gpt-4o-mini',
    result_type=WeatherResponse,
    retries=3,
)

这样即使模型第一次拿到非法 JSON，也能自动带着错误信息重新请求，最多 3 次。

5.3 使用日志输出隐藏内部细节

PydanticAI 默认会输出详细的内部日志，对调试有用，但对线上服务噪音太大。用标准 logging 控制级别。

import logging
logging.getLogger('pydantic_ai').setLevel(logging.WARNING)

6. 常见坑与排错

7. 下一步

• 接入工具调用：Read pydantic_ai.tools 文档，给 Agent 挂一个真实的天气 API，让模型在需要时动态查询数据，而不是依赖裁剪过的训练知识
• 依赖注入：使用 RunContext 将数据库连接、用户会话等资源传入 Agent 内部，支持更复杂的业务状态管理
• 多 Agent 协作：用 AgentGroup 或消息传递机制构建一套"路由 + 任务执行"的架构，模拟真实业务中的多角色协同