pydantic-ai

Pydantic AI

用于构建生产级 GenAI 应用的 Python Agent 框架，带来「FastAPI 般的体验」。

快速导航

主题	参考文档
Agents	agents.md
能力	agents.md
工具	tools.md
模型	models.md
嵌入	embeddings.md
评估	evals.md
集成	integrations.md
图	graphs.md
UI 流	ui.md
安装	installation.md

适用场景

• 构建具有结构化输出的 AI Agent
• 需要类型安全且适合 IDE 的 Agent 开发体验
• 需要为工具注入依赖
• 支持多种模型（OpenAI、Anthropic、Gemini 等）
• 使用 Logfire 实现生产环境可观测性
• 使用图构建复杂工作流

安装

完整安装、精简安装选项及可选依赖组请参阅 references/installation.md。需要 Python 3.10+。

版本亮点（2.40.0 → 2.48.0）

• 安全性（升级）（2.44.0，回移植至 1.107.6）：通过 web_fetch_tool 或 OTel 插桩触发的四项修复——允许本地 URL 时，IPv6 区域标识符可绕过私有 IP 屏蔽列表；web_fetch 的 HTML／字符集处理复杂度呈超线性增长，可能导致事件循环停滞；域名屏蔽列表比较时未进行解析器规范化；include_content=False 时 span 内容泄露（GHSA-vmxc-h2x2-jmf3、GHSA-fpf4-vwcp-v4hp、GHSA-22h6-qm39-v87j、GHSA-4x9p-g9wm-8q7f）。
• 实时会话控制（2.40.0／2.46.0）：支持 handle_barge_in=True 和 interrupt(played_bytes=...)、用于带外提示词的 RealtimeSession.enqueue()、send() 上的 respond=、wait_for_playback() 以及 @agent.on_event 监听器。
• 图像生成（2.41.0）：除内置工具外，新增直接使用的 ImageGenerator API；ImageGeneration／XSearch 上的 fallback_model 已弃用，改用 fallback_subagent_model。
• 提供方与模型（2.41.0／2.42.0／2.48.0）：新增用于 ChatGPT／Codex 订阅身份验证的 openai-codex 提供方、GitHubCopilotProvider；新增 OpenAI gpt-6-sol／gpt-6-luna 和 Claude Opus 5.5（claude-opus-5-5）。
• 定价（2.40.0）：pydantic_ai.prices.update_in_background() 在后台刷新 genai-prices 数据。
• Temporal（2.46.0）：TemporalDurability 新增 event_stream_topic，可通过 Workflow Streams 流式传输 Agent 事件。

版本亮点（2.23.0 -> 2.39.0）

• 实时语音到语音（2.28.0）：Agent.realtime() 支持浏览器 WebRTC 和服务器侧带支持；通过 azure_voice_live 设置使用 Azure AI Voice Live（2.29.0）；RealtimeSession.send_audio() 接受异步可迭代对象（2.36.0）。
• 运行取消（2.26.0）：AgentRun.cancel()、RunContext.cancel() 和 RunCancelled；stream_run_events() 返回公开的 AgentRunEvents 句柄，支持 cancel() 和运行状态访问。
• 延迟公开工具（2.23.0/2.26.0/2.30.0）：ToolAvailabilityDeltaPart 支持原生的 tool_addition/additional_tools；工具可以在通过工具搜索、load_capability 或 ToolReturn.tools 公开之前保持隐藏，并使用各提供方原生的延迟公开/添加通道；延迟公开的工具必须先公开，才能调用。
• 成本跟踪（2.23.0）：RunUsage 中的 cost 和 UsageLimits 中的 cost_limit。上下文窗口（2.38.0）：ModelProfile 中的 context_window 和 RunContext 中的 context_window_used。
• 类型化事件（2.38.0）：应用代码和能力可以向运行事件流发送类型化的 CustomEvent/CapabilityEvent，并通过 @on_event 订阅。持久化执行（2.36.0）：为能力提供 @durable_operation，并为第三方持久化执行引擎提供公开的后端 API。
• 提供方和模型：Crusoe（2.28.0）、Snowflake Cortex（2.27.0）和 vLLM（2.38.0）提供方；gemini-3.7-flash（2.30.0）、gemini-3.8-flash（2.38.0）、Claude Fable 5.1 / Mythos 5.1（2.38.0）、OpenAI gpt-6-astra（2.39.0）、ZaiModel 上的 GLM-5.3（2.34.0）、DeepSeek V4 Flash（2.26.0）。
• MCP 和 HTTP 客户端：MCPToolset 在支持 FastMCP 3 的同时，也支持 FastMCP 4 和 MCP SDK v2（2.29.0）。构建流程改用 httpx2 客户端；pydantic-ai[anthropic] 要求 anthropic>=1.0.0，自定义 AnthropicProvider 的 http_client 必须是 httpx2.AsyncClient（2.32.0/2.33.0）。
• clai CLI（2.36.0）：支持 --mcp-config 和工具调用流式传输。OpenRouter（2.30.0/2.32.0）：提供用于网页搜索的 openrouter:web_search，并在 provider_details["annotations"] 中提供网页搜索来源。
• 安全（升级）：2.24.0 修复了本地 web_fetch 工具 / FileUrl 媒体下载中的内存无界增长问题（GHSA-v2xh-2vp8-57h8）；2.27.1 修复了 include_content=False 时低严重性重试提示词脱敏信息泄露问题（GHSA-3gh4-cghq-f8v4）；2.28.0 修复了开发用网页聊天 UI 缺少内容类型检查的高严重性问题，因此任意跨源请求不再会运行 Agent（GHSA-h4xc-3qfq-jf93）；2.30.0 修复了开发用网页聊天 UI 中通过 Host 标头验证防止 DNS 重绑定的问题，并为非回环部署提供可选的 allowed_hosts（GHSA-q2xc-rrxj-58x9）。

发布亮点（2.13.0 -> 2.22.0）

• 持久化能力取代包装器 Agent：TemporalDurability、DBOSDurability 和 PrefectDurability（2.14.0）可通过 capabilities=[...] 附加到常规 Agent，取代已弃用的 TemporalAgent / DBOSAgent / PrefectAgent 包装类（已在 v3 中移除）。切换后，现有基于包装器的工作流仍可正确重放。更新后的 Temporal/DBOS/Prefect 示例请参阅 integrations.md。
• 新增模型/提供商：Claude Opus 5（2.20.0）、gemini-3.6-flash/gemini-3.5-flash-lite（2.16.0）、Mistral reasoning_effort（2.14.0）和 mistral_prompt_cache_key（2.16.0）、针对 gpt-5.6 的 OpenAI 显式提示词缓存（2.15.0）、BedrockMantleProvider（2.18.0），以及适用于 Anthropic/OpenRouter 的内置工具 AdvisorTool（2.18.0）。
• 用量与限制：RequestUsage/RunUsage 中的 cache_hit_ratio（2.13.0）、不会消耗重试次数且模型可见的失败类型 ToolFailed（2.16.0）、运行时可选的 run_id=（2.16.0）、可在 run/iter/override 时覆盖工具重试预算（2.15.0），以及 UsageLimits 中的 per_request_input_tokens_limit（2.21.0）。
• 错误处理与插桩：ModelHTTPError 现在会携带 headers，并提供从每个提供商 SDK 解析出的 retry_after（2.19.0）；RaiseContentFilterError 能力和 include_model_request_parameters 插桩设置（2.13.0）；缓存每条消息的 OTel 序列化结果，以避免 O(n^2) 开销（2.17.0）。
• 依赖项：fastmcp 可选分组现在限制 fastmcp<4（2.19.0）。

发布亮点（2.0.0 -> 2.12.0）

• V2 稳定版（2.0.0）：采用以 harness 为先的设计，以能力作为核心原语，将 Agent 的工具、钩子、指令和模型设置封装为一个可组合单元。从 V1 迁移需要使用官方升级指南。1.9x 系列中已弃用的能力式路径现在成为默认方式。
• 消息历史与处理：message_history 符合提供商要求，并修复了工具调用配对问题；HistoryProcessor 已导出；此外还可使用延迟工具调用事件和 EnqueuedMessagesEvent（2.10.0 至 2.12.0）。
• 新增模型/提供商：支持 Moonshot AI kimi-k3、OpenAI 后台模式，以及 Anthropic stop_reason=pause_turn；在 Groq、DeepSeek 和 Cerebras 之间统一处理推理力度。
• 嵌入与令牌：Gemini 2 嵌入的文本前缀条件控制，以及使用量跟踪中的输出音频令牌累积。
• 修复：ToolReturnPart 序列化使用字段别名；处理 Anthropic/Bedrock 原生输出架构；为用量限制和工具重试错误提供可操作的提示。

发布亮点（1.96.1）

• V2 准备工作：Agent(..., prepare_tools=..., prepare_output_tools=..., event_stream_handler=...) 现在属于已弃用路径；新的方向是迁移到基于能力的方式。
• 能力迁移：使用 PrepareTools、PrepareOutputTools 和 ProcessEventStream 能力，而不是通过构造函数语法糖配置这些行为。
• OpenAI 修复：最新补丁系列还改进了 OpenAIResponsesModel 对系统提示词角色的处理，并优化了图像生成请求的构造。

版本亮点（1.97.0 → 1.102.0）

• MCP 迁移：新集成 MCP 时优先使用 MCPToolset。FastMCPToolset 和较早的 MCPServer* 客户端接口现已进入弃用流程。
• Google 提供商拆分：GoogleProvider 和 GoogleCloudProvider 现已区分开来，模型 ID 从 google-gla: / google-vertex: 变更为 google: / google-cloud:。
• 流式传输迁移：从 stream_responses() 迁移到 stream_response()；新 API 会直接生成 ModelResponse 对象。
• 重试配置：优先使用 Agent(retries=...) 或 AgentRetries(...)，而不是较早的构造函数级重试参数。
• 新增运行时工具：ctx.enqueue() 和 MCP 后台任务让你更轻松地排队安排后续工作，而不必强行将其纳入当前响应轮次。

版本亮点（1.105.0 → 1.107.0）

• 新模型：支持 Claude Fable 5 和 Claude Mythos 5（1.107.0），并支持 Grok 4.3 的 reasoning_effort 和更新后的 xAI 模型名称（1.105.0）。
• 延迟加载：现在可以按需加载指令、工具、模型设置和钩子，而不必在构造 Agent 时立即加载（1.105.0）。
• 模型自检：known_model_names() 可枚举 KnownModelName 成员（1.107.0）。
• OpenRouter 缓存：OpenRouter 已实现 CachePoint 和提示词缓存（1.107.0）。
• xAI 配置：XaiProvider 新增 api_host 和 timeout，并支持映射 seed 参数（1.106.0）。
• 安全性：加固了 VercelAIAdapter 对 UploadedFile 的处理，以防范混淆代理导致的文件读取漏洞（GHSA-h7p7-w5gc-xj3w，1.106.0）。
• 修复：修复了 event_stream_handler 未消费流时流式响应不完整、非 base64 数据 URI 的 from_data_uri、Temporal gateway/ 模型构造、GoogleModelSettings.google_cached_content 请求格式、Anthropic Bedrock message=None 起始事件，以及搭配原生工具使用时的 AnthropicModel.count_tokens。

版本亮点（1.103.0 → 1.104.0）

• MCP 提示词：维护中的 McpServer 集成现可通过 list_prompts 和 get_prompt 列出并获取提示词；除非必须使用旧版封装器，否则新客户端代码仍应优先使用 MCPToolset。
• UI 适配器：VercelAIAdapter 通过 UIMessage.metadata 往返传递消息时间戳，UIAdapter.sanitize_messages 则会从 FileUrl 部分中移除客户端提交的 force_download。
• 提供商／模型更新：支持 Claude Opus 4.8，OpenRouterModel 可使用 anthropic_eager_input_streaming，混合 OpenRouter/xAI/Bedrock 路由现在会一致地传递 thinking=False。
• Bedrock／工具集修复：Bedrock 会将格式错误的模型／工具输出映射为 FinishReason.error，识别自适应思考，保留单工具 tool_choice 缓存行为；工具集准备回调意外返回 None 时会发出警告。

版本亮点（1.75.0 → 1.84.1）

• 能力：CapabilityOrdering 为复杂的能力堆栈新增显式包装／排序控制（innermost、outermost、wraps、wrapped_by、requires）。
• 压缩：为 OpenAI 和 Anthropic 新增服务端压缩能力；OpenAI 新增有状态压缩模式。
• 模型：支持 Claude Opus 4.7，并新增原生 OllamaModel 路径，修正了 Ollama 的结构化输出能力标志。
• 工具：对于单个 BaseModel 工具，工具钩子现在会始终接收字典形式的已验证参数；内部输出工具会跳过钩子执行。
• 加固：在 1.83/1.84 版本线中，通过加固正则表达式提升了 Google FileSearchTool 的解析安全性。

版本亮点（1.71.0 → 1.74.0）

• Capabilities：可组合、可复用的 Agent 行为单元，可将工具、生命周期钩子、指令和模型设置打包到一个类中。可接入任意 Agent，实现最大程度的复用。
• AgentSpec：通过 Agent.from_file 从 YAML/JSON 文件加载 Agent。支持 TemplateStr，用于引用 deps 的模板化指令。
• Hooks capability：使用装饰器（@hooks.on_model_request 等）定义钩子。
• Thinking capability：跨提供商的 thinking 模型设置，用于推理。
• 自适应提供商的工具：WebSearch、WebFetch、MCP、ImageGeneration——可自动从内置（提供商）工具回退到本地工具。
• 在线评估：pydantic-evals 中的评估基础设施。
• TextContent：带有 metadata 的用户提示词不会发送给模型。
• CaseLifecycle 钩子：用于 Dataset.evaluate 生命周期的钩子。
• 在钩子中切换模型：before_model_request / wrap 钩子可通过 ModelRequestContext 切换模型。
• 钩子中的 ModelRetry：钩子可抛出 ModelRetry 来控制重试流程。
• 支持同步工具准备函数。MCP capability 不再需要显式指定 url=。

版本亮点（1.69.0 → 1.70.0）

• Agent：启用插桩后，Agent(description=...) 会将人类可读的描述添加到运行 span 中，作为 gen_ai.agent.description。
• 模型：FallbackModel 现在支持基于响应的回退处理器，用于处理非流式运行中的语义失败。
• 工具：多模态工具结果会直接传递给提供商 API，而不再总是拆分成额外的用户消息部分。
• Bedrock：模型和嵌入设置中提供了 bedrock_inference_profile，可通过推理配置文件 ARN 路由请求。
• 稳定性：修复了 OpenRouter Anthropic 模型匹配、Cohere 嵌入、Google 图像尺寸、Bedrock 工具名称清理，以及格式错误的工具调用重试处理等提供商问题。

快速开始

基本 Agent

from pydantic_ai import Agent

agent = Agent(
    'openai:gpt-4o',
    instructions='Be concise, reply with one sentence.'
)

result = agent.run_sync('Where does "hello world" come from?')
print(result.output)

使用结构化输出

from pydantic import BaseModel
from pydantic_ai import Agent

class CityInfo(BaseModel):
    name: str
    country: str
    population: int

agent = Agent('openai:gpt-4o', output_type=CityInfo)
result = agent.run_sync('Tell me about Paris')
print(result.output)  # CityInfo(name='Paris', country='France', population=2161000)

使用工具和依赖项

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class Deps:
    user_id: int

agent = Agent('openai:gpt-4o', deps_type=Deps)

@agent.tool
async def get_user_name(ctx: RunContext[Deps]) -> str:
    """Get the current user's name."""
    return f"User #{ctx.deps.user_id}"

result = agent.run_sync('What is my name?', deps=Deps(user_id=123))

主要功能

功能	描述
类型安全	完整的 IDE 支持和类型检查
与模型无关	支持 30 多个提供商
依赖注入	向工具传递上下文
结构化输出	Pydantic 模型验证
嵌入	支持多提供商向量
Logfire 集成	内置可观测性
MCP 支持	外部工具和数据
评估	系统化测试
图	支持复杂工作流

支持的模型

提供商	模型
OpenAI	GPT-4o、GPT-4、o1、o3
Anthropic	Claude Opus 5、Claude Opus 4.8、Claude 4、Claude 3.5
Google	Gemini 2.0、Gemini 1.5
xAI	Grok-4（原生 SDK）
Groq	Llama、Mixtral
Mistral	Mistral Large、Codestral
Azure	Azure OpenAI
Bedrock	AWS Bedrock + Nova 2.0
SambaNova	SambaNova 模型
Ollama	本地模型

最佳实践

1. 使用类型提示 — 启用 IDE 支持和验证
2. 定义输出类型 — 确保响应结构化
3. 使用依赖项 — 向工具注入上下文
4. 添加工具文档字符串 — 大模型会将其用作描述
5. 启用 Logfire — 实现生产环境可观测性
6. 简单场景使用 run_sync — 异步场景使用 run
7. 为测试覆盖 deps — agent.override(deps=...)
8. 设置用量限制 — 使用 UsageLimits 防止无限循环

禁止事项

• 不要在代码中暴露 API 密钥
• 不要在生产环境中跳过输出验证
• 不要忽略工具错误
• 使用 run_stream 时，必须处理部分输出
• 不要忘记关闭 MCP 连接（async with agent）
• 涉及多个包装器／钩子时，不要假设能力顺序无关紧要；组合顺序影响结果时，应明确指定。

常见模式

流式响应

async with agent.run_stream('Query') as response:
    async for text in response.stream_text():
        print(text, end='')

备用模型

from pydantic_ai.models.fallback import FallbackModel

fallback = FallbackModel(openai_model, anthropic_model)
agent = Agent(fallback)

MCP 集成

from pydantic_ai.mcp import MCPToolset

toolset = MCPToolset(command='python', args=['mcp_server.py'])
agent = Agent('openai:gpt-4o', toolsets=[toolset])

使用 TestModel 进行测试

from pydantic_ai.models.test import TestModel

agent = Agent(model=TestModel())
result = agent.run_sync('test')  # Deterministic output

嵌入

from pydantic_ai import Embedder

embedder = Embedder('openai:text-embedding-3-small')

# Embed search query
result = await embedder.embed_query('What is ML?')

# Embed documents for indexing
docs = ['Doc 1', 'Doc 2', 'Doc 3']
result = await embedder.embed_documents(docs)

有关提供商和设置，请参阅 embeddings.md。

xAI 提供商

from pydantic_ai import Agent

agent = Agent('xai:grok-4-1-fast-non-reasoning')

有关配置详情，请参阅 models.md。

Exa 神经搜索

import os
from pydantic_ai import Agent
from pydantic_ai.common_tools.exa import ExaToolset

api_key = os.getenv('EXA_API_KEY')
toolset = ExaToolset(api_key, num_results=5, include_search=True)
agent = Agent('openai:gpt-4o', toolsets=[toolset])

如需了解所有 Exa 工具，请参阅 tools.md。

链接

• 文档
• 发行版本
• GitHub
• PyPI