Python AI智能体库比较2026 — Pydantic AI vs Instructor vs Smolagents 实战选择指南

上个月启动一个新项目时，我面临一个选择：用Python构建基于LLM的智能体，该用哪个库？LangGraph、CrewAI这类重量级编排框架我已经熟悉了。但在它们之下还有一个层次——想直接控制LLM调用，但原始OpenAI SDK又太繁琐——填补这一空白的库在2025〜2026年间迎来了爆发式增长。

其中三个库反复出现：Pydantic AI、Instructor和Smolagents。我在真实项目中都用过，以下是我的总结。

首先明确层次——这三者并非竞争关系

最重要的认知是：这三个库处于不同的层次。

• Instructor：通过”打补丁”的方式为现有LLM客户端添加结构化Pydantic输出保证的层。没有智能体循环。
• Pydantic AI：具有工具调用、依赖注入、多智能体支持的类型安全智能体框架。由Pydantic团队开发。
• Smolagents：HuggingFace的代码生成智能体框架。不用JSON调用工具，而是直接生成并执行Python代码。

因此正确的问题不是”哪个最好”，而是”我的情况适合哪个”。这正是本文要回答的问题。

Instructor — 打补丁而非替换LLM客户端

设计理念

Instructor不会将您现有的LLM客户端（OpenAI、Anthropic、Gemini等）替换成新的SDK。而是通过instructor.from_openai(client)这一行代码”打补丁”，添加response_model参数。

import instructor
from openai import OpenAI
from pydantic import BaseModel

client = instructor.from_openai(OpenAI())

class UserProfile(BaseModel):
    name: str
    age: int
    skills: list[str]

profile = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=UserProfile,
    messages=[{"role": "user", "content": "张伟，30多岁，Python和Go开发者"}]
)
# profile是UserProfile实例，已通过Pydantic验证
print(profile.name)  # "张伟"

验证失败时，会自动将错误信息反馈给模型并重试。max_retries参数控制最大重试次数。

优势所在

1. 学习成本几乎为零。 如果已经在使用OpenAI SDK，只需添加一行代码。无需学习新范式。

2. 多提供商支持完善。 OpenAI、Anthropic、Google Gemini、Mistral、Cohere、Ollama、DeepSeek，支持15个以上的提供商。更换提供商时代码结构几乎不变。

3. 结构化提取可靠性高。 月下载量300万次，GitHub星标11k+。经过生产环境验证的库。复杂嵌套模式、列表提取、联合类型均可处理。

4. 流式输出支持。 将类型指定为Iterable[Model]，即可通过流式方式接收结构化对象。

诚实的局限性

Instructor不是智能体框架。没有循环、工具编排或内存管理。它专注于从单次LLM调用中提取结构化数据。如果需要智能体循环，就要考虑其他选择。

验证失败的重试成本由调用方全额承担。模型反复返回错误格式时，成本可能远超预期。我实际遇到过复杂嵌套模式触发3〜5次重试的情况。实际做法是将max_retries限制在1〜2次，并在仍然失败时加入回退逻辑。

Pydantic AI — 追求类型安全的智能体

设计理念

Pydantic AI是Pydantic团队直接开发的智能体框架，将Python类型提示置于智能体设计的核心。工具以类型安全的方式定义，通过依赖注入（Dependency Injection）将外部服务连接到智能体。

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic import BaseModel
import httpx

# 定义智能体返回的类型
class ResearchResult(BaseModel):
    summary: str
    sources: list[str]
    confidence: float

model = OpenAIModel("gpt-4o")
agent = Agent(model, output_type=ResearchResult)

# 以类型安全的方式注册工具
@agent.tool
async def fetch_url(ctx, url: str) -> str:
    """获取指定URL的内容"""
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.text[:2000]

result = await agent.run("调研Python 3.13的新特性")
print(result.output.confidence)  # 0.0〜1.0范围，已验证

依赖注入的魅力

Pydantic AI中我最喜欢的部分是依赖注入模式。数据库连接、HTTP客户端、API密钥等可以在智能体初始化时注入，使测试变得更简单。

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class AppDeps:
    db: Database
    http_client: httpx.AsyncClient

agent = Agent(model, deps_type=AppDeps, output_type=str)

@agent.tool
async def query_user(ctx: RunContext[AppDeps], user_id: int) -> dict:
    # 通过ctx.deps.db、ctx.deps.http_client访问
    return await ctx.deps.db.get_user(user_id)

测试时向AppDeps传入mock对象，无需LLM调用即可验证工具逻辑。这种结构化方式在生产代码库中发挥重要作用。

五种输出模式

Pydantic AI为结构化输出提供五种模式：

模式	说明	使用时机
text	普通文本返回	自由格式回答
tool	工具调用结构化（默认）	大多数情况
native	模型原生结构化输出	OpenAI o1、GPT-4o
prompted	系统提示引导	不支持工具的模型
auto	根据模型能力自动选择	推荐的默认值

诚实的局限性

目前还不是v1.0。快速变化的API是在生产环境中犹豫的主要原因。0.x版本意味着随时可能有破坏性变更。我相信Pydantic团队的质量标准，但静观其变比急于求成更明智。

多智能体场景也存在局限性。如果需要复杂编排，更实际的做法是在LangGraph之上将Pydantic AI仅作为结构化输出层使用。关于上层框架，LangGraph vs CrewAI vs Dapr比较指南提供了详细解析，值得参考。

Smolagents — 让LLM来写代码

设计理念

Smolagents采用最独特的方式。一般智能体通过JSON决定”调用哪个工具，使用什么参数”。而Smolagents的CodeAgent是直接生成并执行Python代码。

from smolagents import CodeAgent, DuckDuckGoSearchTool
from smolagents.models import LiteLLMModel

model = LiteLLMModel(model_id="gpt-4o")
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model
)

result = agent.run(
    "调研2026年Python 3.14的主要变化并进行总结"
)

智能体执行的不是{"tool": "search", "query": "Python 3.14"}这样的JSON，而是：

results = web_search("Python 3.14 changes 2026")
summary = "\n".join([r["snippet"] for r in results[:3]])
final_answer(summary)

真正的Python代码。

代码生成的优势

HuggingFace团队的基准测试表明：

• 与传统JSON工具调用相比，LLM调用减少约30%——多工具顺序调用时，无需每步都请求LLM，用一段代码一次处理
• 使用GPT-4o在GAIA基准测试中达到44.2%（当时验证集第一名）
• 可以直接用代码表达条件分支、循环和错误处理

核心设计——1000行代码

smolagents的核心逻辑约1000行，这是有意为之的设计决策。易于理解和修改，没有不必要的抽象。对于需要深入了解框架内部的研究团队来说，这是重要优势。

诚实的局限性

代码执行存在安全风险。CodeAgent默认使用E2BSandbox或LocalPythonInterpreter，在生产环境中，如果用户输入可能通过智能体影响代码执行，沙箱化是必须考虑的。

使用开源模型时代码质量差异很大。GPT-4o或Claude Sonnet级别的模型表现良好，但在7B以下的模型中，代码中混入bug的情况相当常见。我认为这是Smolagents最大的局限性——对模型质量的依赖程度远高于Instructor或Pydantic AI。

认证、速率限制、日志记录等生产基础设施需要自行构建。Smolagents处于HuggingFace的实验性空间，难以期待企业级支持或长期API稳定性。

关于如何将这些模式整合到更完整的生产智能体架构中，生产级AI智能体设计原则提供了全面的决策框架，值得一读。

三大库综合比较表

项目	Instructor	Pydantic AI	Smolagents
核心目的	结构化提取	类型安全智能体	代码生成智能体
智能体循环	❌	✅	✅
结构化输出	✅ 核心功能	✅ 5种输出模式	⚠️ 部分支持
多提供商	✅ 15个以上	✅ 主要提供商	✅ 通过LiteLLM
类型安全	✅ Pydantic	✅✅ 完全类型化	⚠️ 有限
代码执行	❌	❌	✅ 核心功能
学习曲线	低	中等	中等
生产就绪度	✅ 高	⚠️ v0.x	⚠️ 实验性
多智能体	❌	⚠️ 基本支持	⚠️ 有限
核心复杂度	低	中等	低（1000行）
月下载量	300万+	快速增长中	快速增长中

场景别决策指南

应选择Instructor的情况

• 已在使用OpenAI/Anthropic SDK，只需要结构化输出时
• 不需要智能体循环，只需从单次LLM调用中提取Pydantic对象时
• 生产稳定性是首要考量时（300万下载量背书）
• 团队希望直接延用现有SDK知识时

应选择Pydantic AI的情况

• 希望类型安全地设计智能体逻辑时
• 需要通过依赖注入构建可测试的代码结构时
• 团队已熟悉Pydantic，希望用相同范式开发智能体时

需要接受v0.x带来的破坏性变更风险。我的判断是：新项目值得尝试，但将现有生产代码迁移过来还为时过早。

LLM API定价比较也值得参考。无论选择哪个库，模型选择都会对成本产生巨大影响，特别是在预估Instructor的重试成本或Smolagents代码生成循环成本时大有帮助。

应选择Smolagents的情况

• 需要代码执行智能体，且能处理安全沙箱化问题时
• 实现需要顺序连接多个工具的复杂工作流时
• 需要理解和自定义框架内部时
• 在本地运行开源模型进行智能体实验时

重要前提：使用GPT-4o或Claude Sonnet以上级别的模型。 代码生成质量决定智能体性能。

我的结论 — 视情况三者都用

坦白说，我三个库都在用。因为它们各自擅长的事情不同。

Instructor现在就可以安全地用于生产环境。每当需要从LLM调用中提取结构化数据时，它是我的第一选择。

Pydantic AI方向正确，令人期待。v0.x的风险是真实存在的，但我正在新项目的智能体层上进行实验。等v1.0发布后，计划更积极地作为主力使用。

Smolagents在需要代码执行智能体的特定场景下拿出来用。但要考虑到对模型的高度依赖以及需要自建生产基础设施的成本。

如果有人问”哪个最好”，我的答案是：需要结构化提取用Instructor，需要类型安全的智能体循环用Pydantic AI，需要代码执行智能体用Smolagents。仅此而已。