Pydantic AI

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？

1. 安装： 安装 pydantic_ai 包。

2. 基本用法： 使用指定的模型和指令创建 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 编程语言的教科书中。 """ ```

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

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=(
        '您是我们银行的支持代理，请提供客户支持并判断其查询的风险等级。'
    ),
)

为什么选择 Pydantic AI？

Pydantic AI 提供了一种简化的 GenAI 应用程序构建方法。 它基于 Pydantic 验证、模型无关设计、无缝可观测性和类型安全环境，使其成为旨在提高效率和可靠性的开发人员的引人注目的选择。

下一步

要进一步探索 Pydantic AI：

• 安装 Pydantic AI 并按照示例进行操作。
• 请参阅文档以获得更深入的了解。
• 查看 API 参考以了解 Pydantic AI 的接口。
• 加入 Slack 频道或在 GitHub 上提交问题以获取任何问题。