PydanticAI — 用类型安全方式构建 AI Agent 的 Python 框架

文档: 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 ADK、Anthropic SDK、LangChain、LlamaIndex、AutoGPT、Transformers、CrewAI、Instructor 等众多工具的验证层。既然可以直接使用源头，为何要用衍生品？ :smiley:

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. 无缝可观测性：
   与我们的通用 OpenTelemetry 可观测性平台 Pydantic Logfire 紧密集成，实现实时调试、基于评估的性能监控以及行为、追踪和成本跟踪。如果您已有支持 OTel 的可观测性平台，也可以使用它。

4. 完全类型安全：
   旨在为您的 IDE 或 AI 编码助手提供尽可能多的上下文，以进行自动补全和类型检查，将整类错误从运行时转移到编写时，带来一丝 Rust "编译通过即能运行" 的感觉。

5. 强大的评估功能：
   使您能够系统地测试和评估所构建智能体系统的性能和准确性，并在 Pydantic Logfire 中监控其随时间变化的性能。

6. MCP、A2A 和 UI：
   集成模型上下文协议、Agent2Agent 和各种UI 事件流标准，让您的智能体能够访问外部工具和数据，与其他智能体互操作，并构建基于流式事件通信的交互式应用程序。

7. 人工介入工具调用审批：
   轻松标记某些工具调用在继续之前需要审批，审批可能取决于工具调用参数、对话历史或用户偏好。

8. 持久化执行：
   使您能够构建持久化智能体，这些智能体可以在短暂的 API 故障、应用程序错误或重启中保持进度，并以生产级可靠性处理长时间运行、异步和需要人工介入的工作流。

9. 流式输出：
   提供流式结构化输出的能力，并立即进行验证，确保实时访问生成的数据。

10. 图支持：
    提供了一种强大的方式来使用类型提示定义图，适用于标准控制流可能退化为"意大利面条式代码"的复杂应用场景。

但说实话，任何列表都不如亲自尝试并感受它带给您的体验更有说服力！

Hello World 示例

以下是 Pydantic AI 的一个极简示例：

from pydantic_ai import Agent

# 定义一个非常简单的智能体，包括要使用的模型。您也可以在运行智能体时设置模型。
agent = Agent(
    'anthropic:claude-sonnet-4-6',
    # 使用关键字参数向智能体注册静态指令。
    # 对于更复杂的动态生成指令，请参见下面的示例。
    instructions='Be concise, reply with one sentence.',
)

# 同步运行智能体，与 LLM 进行对话。
result = agent.run_sync('Where does "hello world" come from?')
print(result.output)
"""
The first known use of "hello, world" was in a 1974 textbook about the C programming language.
"""

(此示例是完整的，假设您已安装 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.2',
    deps_type=SupportDependencies,
    # 智能体的响应将被保证是一个 SupportOutput，
    # 如果验证失败，智能体会被提示重试。
    output_type=SupportOutput,
    instructions=(
        'You are a support agent in our bank, give the '
        'customer support and judge the risk level of their query.'
    ),
)


# 动态指令可以利用依赖注入。
# 依赖通过 `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"The customer's name is {customer_name!r}"


# `tool` 装饰器允许您注册函数，LLM 在响应用户时可能会调用这些函数。
# 同样，依赖通过 `RunContext` 传递，其他任何参数都将成为传递给 LLM 的工具模式。
# Pydantic 用于验证这些参数，错误会传回给 LLM 以便其重试。
@support_agent.tool
async def customer_balance(
        ctx: RunContext[SupportDependencies], include_pending: bool
) -> float:
    """Returns the customer's current account balance."""
    # 工具的文档字符串也会作为工具描述传递给 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 进行对话，直到获得最终响应。
    # 即使在这个相当简单的情况下，智能体也会与 LLM 交换多条消息，因为需要调用工具来获取输出。
    result = await support_agent.run('What is my balance?', deps=deps)
    # `result.output` 将使用 Pydantic 进行验证，以保证它是一个 `SupportOutput`。
    # 由于智能体是泛型的，它也会被类型化为 `SupportOutput`，以辅助静态类型检查。
    print(result.output)
    """
    support_advice='Hello John, your current account balance, including pending transactions, is $123.45.' block_card=False risk=1
    """

    result = await support_agent.run('I just lost my card!', deps=deps)
    print(result.output)
    """
    support_advice="I'm sorry to hear that, John. We are temporarily blocking your card to prevent unauthorized transactions." block_card=True risk=8
    """

下一步

要亲自尝试 Pydantic AI，请先安装，然后按照示例中的说明操作。

阅读文档以了解更多关于使用 Pydantic AI 构建应用程序的信息。

阅读API 参考以了解 Pydantic AI 的接口。

如果您有任何问题，请加入 Slack 或在 GitHub 上提交问题。