Pydantic AI：自信地构建 GenAI 应用

Pydantic AI：GenAI 代理框架

Pydantic AI 是一个 Python 代理框架，旨在促进利用生成式 AI 快速、自信和无缝地构建生产级应用程序和工作流程。它的目标是将 FastAPI 的人体工程学设计带到 GenAI 应用程序和代理开发中。

什么是 Pydantic AI？

Pydantic AI 是一种工具，旨在帮助开发人员快速有效地构建具有生成式 AI 的应用程序。它利用 Pydantic 验证和现代 Python 功能来提供流畅的开发体验。

主要特性：

由 Pydantic 团队构建：直接访问 Pydantic 验证的源代码，该验证在许多流行的 AI SDK 中使用。
模型无关：支持各种模型和提供商，包括 OpenAI、Anthropic、Gemini 等。还可以轻松实现自定义模型。
无缝可观测性：与 Pydantic Logfire 集成，用于实时调试、性能监控和成本跟踪。还支持其他 OpenTelemetry 兼容平台。
完全类型安全：旨在为自动完成和类型检查提供全面的上下文，从而减少运行时错误。
强大的 Evals：支持对代理性能和准确性进行系统测试和评估。
MCP、A2A 和 AG-UI：集成了代理访问外部工具和数据、与其他代理的互操作性以及构建交互式应用程序的标准。
人工参与的工具审批：允许标记在执行前需要批准的工具调用。
持久执行：支持构建可以跨 API 故障和应用程序重启保持进度的代理。
流式输出：提供具有即时验证的结构化输出的连续流。
图形支持：提供了一种使用类型提示为复杂应用程序定义图形的强大方法。

Pydantic AI 如何工作？

Pydantic AI 的工作原理是提供一个简化 AI 代理开发的框架。它使用 Pydantic 模型来定义代理的输入和输出的结构，并提供将代理连接到各种 LLM 和其他服务的工具。

如何使用 Pydantic AI？

安装：安装 pydantic_ai 包。

基本用法：使用指定的模型和指令创建 Agent 实例。

from pydantic_ai import Agent

agent = Agent(
    'anthropic:claude-sonnet-4-0',
    instructions='简洁明了，用一句话回复。',
)

result = agent.run_sync('“hello world” 来自哪里？')
print(result.output)
"""

第一次使用“hello, world”是在 1974 年一本关于 C 编程语言的教科书中。 """ ```

高级用法：添加工具、动态指令和结构化输出，以构建更强大的代理。

Pydantic AI 适合哪些人？

Pydantic AI 非常适合：

希望高效构建 GenAI 应用程序和工作流程的开发人员。
需要强大、类型安全和可观测的 AI 代理的团队。
需要与各种 LLM 和服务集成的项目。

工具和依赖注入示例

Pydantic AI 促进了依赖注入，当您需要将数据或服务注入到您的工具中时，这非常有用。您可以定义您的依赖类并将其传递给代理。下面是使用 Pydantic AI 为银行构建支持代理的示例代码：

from dataclasses import dataclass

from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext

from bank_database import DatabaseConn


@dataclass
class SupportDependencies:
    customer_id: int
    db: DatabaseConn


class SupportOutput(BaseModel):
    support_advice: str = Field(description='返回给客户的建议')
    block_card: bool = Field(description='是否阻止客户的卡')
    risk: int = Field(description='查询的风险等级', ge=0, le=10)


support_agent = Agent(
    'openai:gpt-5',
    deps_type=SupportDependencies,
    output_type=SupportOutput,
    instructions=(
        '您是我们银行的支持代理，请提供客户支持并判断其查询的风险等级。'
    ),
)


@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"客户的姓名是 {customer_name!r}"


@support_agent.tool
async def customer_balance(
    ctx: RunContext[SupportDependencies], include_pending: bool
) -> float:
    """返回客户的当前账户余额。"""
    return await ctx.deps.db.customer_balance(
        id=ctx.deps.customer_id,
        include_pending=include_pending,
    )

使用 Pydantic Logfire 进行检测

为了监控代理的运行情况，Pydantic AI 与 Pydantic Logfire（OpenTelemetry 可观测性平台）无缝集成，该平台支持实时调试、基于评估的性能监控以及行为、跟踪和成本跟踪。示例代码：

...from pydantic_ai import Agent, RunContext
from bank_database import DatabaseConn
import logfire

logfire.configure()
logfire.instrument_pydantic_ai()
logfire.instrument_asyncpg()
...support_agent = Agent(
    'openai:gpt-4o',
    deps_type=SupportDependencies,
    output_type=SupportOutput,
    system_prompt=(
        '您是我们银行的支持代理，请提供客户支持并判断其查询的风险等级。'
    ),
)