用 Pydantic AI 从零搭建一个能干活的 AI Agent

引言

在人工智能应用日益深入的今天，单纯的聊天机器人已无法满足复杂业务需求。AI Agent（智能体）的概念应运而生，它不仅能理解自然语言，还能自主调用工具、执行任务并管理状态，成为真正“能干活的”助手。对于具备后端或运维基础的工程师而言，如何高效、可靠地搭建这样一个 Agent 是关键。

Pydantic AI 是一个新兴的 Python 框架，它巧妙地将 Pydantic 强大的数据验证与序列化能力，与 LLM（大语言模型）的交互能力结合。其核心优势在于通过类型提示和声明式编程，极大地简化了 Agent 的开发流程，降低了工具调用、状态管理和错误处理的复杂度。本文将带你从零开始，构建一个具备实用能力的 AI Agent。

原理要点

理解 Pydantic AI 的核心机制，是成功搭建 Agent 的基础。其工作原理主要围绕以下三点：

1. 模型集成与调用：Pydantic AI 抽象了与不同 LLM 提供商（如 OpenAI、Anthropic 等）的交互细节。你只需定义一个 Agent 实例，并指定使用的模型，框架会自动处理提示词构建、API 调用和响应解析。
2. 工具定义与调用：Agent 的能力通过“工具”（Tools）扩展。工具本质上是带有类型注解的 Python 函数。Pydantic AI 能自动将这些函数注册为 Agent 可识别和调用的接口，并在模型需要时执行它们，将结果返回给模型。
3. 状态管理：Agent 可以维护对话历史或内部状态。通过 Session 或类似机制，Agent 能够记住之前的交互上下文，实现多轮对话和复杂任务处理。

实战步骤

我们将搭建一个名为 TaskAssistant 的 Agent，它能查询天气信息和执行简单的数学计算。

步骤一：环境准备与安装

首先，确保你的 Python 环境（建议 3.9+）已准备好。安装 Pydantic AI 及其依赖。

pip install pydantic-ai
# 同时，你需要安装对应 LLM 提供商的 SDK，例如：
pip install openai

步骤二：定义工具函数

工具函数是 Agent 能力的基石。使用 Pydantic 的类型注解来明确输入和输出。

from pydantic_ai import Tool
import httpx  # 用于模拟外部 API 调用

# 定义一个查询天气的工具
async def get_weather(city: str) -> str:
    """
    获取指定城市的天气信息。
    这是一个模拟函数，实际项目中可替换为真实 API 调用。
    """
    # 模拟 API 调用逻辑
    weather_data = {
        "北京": "晴朗，25°C",
        "上海": "多云，22°C",
        "广州": "小雨，28°C"
    }
    return weather_data.get(city, "未知城市")

# 定义一个执行计算的工具
async def calculate(expression: str) -> str:
    """
    执行简单的数学表达式计算。
    """
    # 注意：生产环境中需严格限制计算范围，避免安全风险
    try:
        result = eval(expression, {"__builtins__": {}}, {})
        return f"计算结果: {result}"
    except Exception as e:
        return f"计算错误: {e}"

步骤三：创建 Agent 实例

将定义的工具注册到 Agent 中，并配置模型。

from pydantic_ai import Agent

# 创建 Agent，指定使用的模型（例如 OpenAI 的 gpt-4o-mini）
# 模型配置通常通过环境变量或配置文件管理，此处为示例
agent = Agent(
    model="openai:gpt-4o-mini",
    tools=[get_weather, calculate],  # 注册工具
    system_prompt="你是一个乐于助人的任务助手，可以查询天气和进行简单计算。"
)

步骤四：运行 Agent 并交互

使用 Agent 实例与用户进行对话。

async def main():
    # 启动一个对话会话
    async with agent.run_session() as session:
        # 用户提问
        user_message = "北京今天天气怎么样？另外，请计算 123 * 456。"
        result = await session.run(user_message)
        print(result.data)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

运行上述代码，Agent 将自动调用 get_weather 和 calculate 工具，并将结果整合后返回给用户。

常见坑与排查清单

1. 模型 API 密钥配置错误：
   • 现象：Agent 初始化或运行时抛出认证错误。
   • 排查：检查环境变量（如 OPENAI_API_KEY）是否正确设置，或模型配置中的凭据是否有效。
2. 工具函数签名不符合要求：
   • 现象：工具未被 Agent 正确识别或调用失败。
   • 排查：确保工具函数是 async 函数，且参数和返回值类型有明确的 Pydantic 类型注解。函数名和文档字符串应清晰描述其功能。
3. LLM 响应解析失败：
   • 现象：Agent 返回错误或空结果。
   • 排查：检查模型返回的原始响应。有时 LLM 可能未按预期格式输出。可尝试调整 system_prompt 或增加示例来引导模型行为。
4. 状态管理不当导致上下文混乱：
   • 现象：多轮对话中，Agent 忘记之前的信息或行为异常。
   • 排查：确保正确使用 run_session 来维护会话状态。对于复杂任务，考虑在工具中显式管理状态，或使用 Agent 的 state 功能。
5. 外部工具调用超时或失败：
   • 现象：Agent 在调用外部 API（如天气服务）时卡住或报错。
   • 排查：为外部工具调用设置合理的超时时间，并添加异常处理逻辑，确保 Agent 能优雅地处理失败情况。

小结

使用 Pydantic AI 框架搭建 AI Agent，为工程师提供了一个结构化、类型安全且易于维护的开发路径。通过定义清晰的工具函数和配置 Agent，你可以快速构建出能够自主执行复杂任务的智能体。掌握其核心原理并避开常见陷阱，将使你在构建企业级 AI 应用时更加得心应手。