pydantic-ai

Pydantic 团队的类型安全 Agent 框架，工具参数与输出都由 schema 校验。

补充说明

Pydantic AI 用 Agent 组织模型、工具和输出类型。工具参数来自 Python 类型注解，最终输出由 output_type 指定的 Pydantic 模型校验；校验失败会把错误回传给模型重试。deps_type 配合 RunContext[Deps] 做依赖注入，把数据库连接、配置或用户身份传进工具，而不是塞进全局变量。

它适合需要强类型 I/O、可测试性和多模型切换的单 Agent 或工具型工作流。LangGraph 更偏图编排、持久化和人工中断；CrewAI 更偏角色团队；OpenAI Agents SDK 与 OpenAI 生态结合更紧。Pydantic AI 的优势是 provider 无关、Pydantic 原生，并且 TestModel/FunctionModel 让离线测试比较容易。

版本注意：system_prompt 在新版本中逐步由 instructions 取代，模型类名（如 OpenAIModel 与 OpenAIChatModel）也发生过变化；升级前锁定版本并跑测试，具体以当前版本文档为准。

常用示例

安装并配置模型提供方：

pip install -U pydantic-ai
export OPENAI_API_KEY="sk-..."

最小 Agent，模型字符串使用 提供方:模型 格式：

from pydantic_ai import Agent
agent = Agent("openai:gpt-4o-mini", instructions="用一句话回答。")
print(agent.run_sync("什么是 OOMKilled？").output)

用 Pydantic 模型约束最终输出，避免解析自由文本：

from pydantic import BaseModel
from pydantic_ai import Agent
class Ticket(BaseModel):
    category: str; priority: int
agent = Agent("openai:gpt-4o-mini", output_type=Ticket)
print(agent.run_sync("Pod 反复 OOMKilled").output)

用 deps_type 和 RunContext 注入依赖，工具参数会生成 schema：

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
@dataclass
class Deps:
    docs: dict[str, str]
agent = Agent("openai:gpt-4o-mini", deps_type=Deps)
@agent.tool
def lookup(ctx: RunContext[Deps], key: str) -> str:
    """按 key 查询内部文档。"""
    return ctx.deps.docs.get(key, "not found")
print(agent.run_sync("查 oom", deps=Deps(docs={"oom": "提高 limit"})).output)

用 TestModel 离线测试 Agent 装配，不发起真实模型请求：

from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
agent = Agent("openai:gpt-4o-mini")
with agent.override(model=TestModel()):
    print(agent.run_sync("测试").output)

用 capture_run_messages() 检查实际发送的消息和工具调用：

from pydantic_ai import Agent, capture_run_messages
agent = Agent("openai:gpt-4o-mini")
with capture_run_messages() as messages:
    agent.run_sync("你好")
print([type(m).__name__ for m in messages])

测试环境用全局开关阻止真实请求：

from pydantic_ai import models
models.ALLOW_MODEL_REQUESTS = False

易错点与排错

工具函数缺少类型注解或 docstring，生成的 schema 不清晰，模型会传错参数；参数、返回值和说明都要写全。
用了 RunContext[Deps] 却没设 deps_type，或调用时没传 deps，会直接报错；Agent 定义和 run 调用要成对配置。
output_type 校验失败会触发重试并消耗 token；重试次数过多时检查模型是否支持结构化输出，必要时换更强模型。
TestModel 会生成 schema 合法但内容无意义的数据，只适合测试装配和类型，不代表回答质量。
models.ALLOW_MODEL_REQUESTS = False 会拦截真实请求；测试环境用它防止误调用，出现“模型请求被禁止”不是 bug。
模型字符串分隔符是 openai:gpt-4o-mini，不是 openai/gpt-4o-mini；写错会找不到 provider。
本地模型不支持 tool calling 或 JSON schema 时，工具调用和结构化输出会失败；先确认推理服务的能力。
在异步服务里调用 run_sync 会阻塞事件循环；改用 await agent.run(...)，工具内部也尽量使用异步客户端。
system_prompt 与 instructions、OpenAIModel 与 OpenAIChatModel 存在版本差异；照抄旧教程可能 ImportError 或行为不同。

读完自测

deps_type 与 RunContext 如何配合？
output_type 校验失败会发生什么？
如何离线测试 Pydantic AI Agent？

答案

Agent(..., deps_type=Deps) 声明依赖类型，工具第一个参数写 RunContext[Deps]；调用时传 deps=...，工具通过 ctx.deps 访问。
Pydantic 校验失败会把错误信息回传给模型并要求重试，重试次数受配置限制；持续失败会抛异常，同时消耗额外 token。
用 agent.override(model=TestModel()) 或 FunctionModel 替换真实模型，配合 capture_run_messages() 检查消息，并用 ALLOW_MODEL_REQUESTS=False 防止误发请求。

pydantic-ai

补充说明

常用示例

易错点与排错

相关命令

读完自测