PydanticAI：类型安全的 Agent

你将学会什么

• 用 Pydantic 模型声明 Agent 的「输出结构」
• 用新命名 instructions / output_type 创建 Agent
• 从 result.output 拿到验证过的结构化对象

正文

PydanticAI 是 Pydantic 团队出品的 Agent 框架，主打「类型安全」：你声明 Agent 的答案必须长成什么形状，框架就会强制校验，不达标就自动让 LLM 重试——这种「像写 FastAPI 一样写 Agent」的手感，让它成为 Python 工程化路线的代表。官方文档在 pydantic.dev/docs/ai。

先记住版本红线：2026 年的新命名是 instructions（旧名 system_prompt）、output_type（旧名 result_type）、result.output（旧名 result.data）。网上大量老教程还在用旧名，照抄会直接报错。下面这个例子用内置的 test 模型，不需要任何 API key 就能跑：

# 安装: pip install "pydantic-ai-slim[openai]"
from pydantic import BaseModel
from pydantic_ai import Agent
# ① 用 Pydantic 模型声明输出结构:答案必须长成这个形状
class CityLocation(BaseModel):
    city: str
    country: str

# ② 创建 Agent:模型名 + 指令 + 输出类型。
#    'test' 是内置的免 key 模拟模型,适合先跑通再换真实模型。
agent = Agent(
    'test',
    instructions='用一句话简洁回答。',
    output_type=CityLocation,
)

# ③ 运行:result.output 是验证过的 CityLocation 对象,不是字符串
result = agent.run_sync('2012 年奥运会在哪个城市举办?')
print(result.output.city)      # 点号访问字段,IDE 有补全提示
print(result.output.country)

为什么类型安全值得学？没有它，你拿到的是自由文本，想取字段只能靠正则和祈祷；有了它，result.output 的类型、字段、校验逻辑都由你声明，写错了当场报错而不是上线后才发现。进阶玩法还有 output_validator（旧名 result_validator）——校验不通过就抛 ModelRetry，让 LLM 带着错误信息重试，以及 deps_type 依赖注入，把数据库连接等依赖类型安全地传进工具和验证器。

动手练

练习

把输出模型改成 Movie（字段：title: str、score: float、comment: str），问 Agent「推荐一部你喜欢的电影」。完成标准：result.output 是 Movie 实例，能通过点号访问三个字段，且 score 的类型是 float。

知识检查

先自己回答，再看答案：

1. output_type 的作用是什么？
2. 新版应该用 result.output 还是 result.data？
3. 校验失败时 PydanticAI 默认会怎么做？

参考答案

1. 声明 Agent 返回值的结构（可以是 int、bool、BaseModel 或联合类型），框架会强制校验。
2. 新版是 result.output，result.data 是旧版命名。
3. 校验失败时框架会让 LLM 带着错误信息自动重试（配合 output_validator 抛 ModelRetry）。

本节小结

• 用 Pydantic 模型声明输出，output_type=... 让 Agent 返回验证过的对象
• 新命名：instructions / output_type / result.output，照旧教程会报错
• 类型安全 = 字段可访问、类型可检查、失败自动重试

PydanticAI 小测

x

1 / 3

PydanticAI 2026 年新版创建 Agent 时，指令参数叫什么？

system_promptinstructionspromptsystem

下一题