Топ-5 Python библиотек для AI-агентов (2026)

Коротко: что выбрать

Если вы пишете AI-агента на Python, между сырым вызовом OpenAI SDK и полновесным фреймворком вроде LangGraph лежит целый слой библиотек, которые за 2025–2026 превратились в самостоятельные экосистемы. Вот пять главных.

• Instructor (13K ⭐ на GitHub) — одна строка кода, и ваш LLM-клиент возвращает Pydantic-модели. 3M+ загрузок в месяц, 15+ провайдеров. Никакого агентного цикла — только структурированный вывод.
• Pydantic AI (18K ⭐) — type-safe агентный фреймворк с dependency injection, tool calling и пятью режимами вывода. Строится командой Pydantic, но всё ещё v0.x.
• Smolagents (28K ⭐) — HuggingFace-агент, который вместо JSON-инструментов пишет и исполняет Python-код напрямую. 44.2% на GAIA benchmark, ~30% меньше LLM-вызовов.
• Outlines (14K ⭐) — библиотека для structured generation: вы задаёте Pydantic-схему, Outlines форсирует логику через logit-маскировку.
• Guidance (21K ⭐) — шаблонный язык управления генерацией. Позволяет делать if/else, циклы, переменные прямо в промпте. Построен Microsoft Research.

Важно: эти библиотеки не конкурируют напрямую. Они работают на разных слоях. Instructor — это «заплатка» на LLM-клиент для структурированного вывода. Pydantic AI — полноценный агентный фреймворк с тулами и DI. Smolagents — генератор кода. Выбор определяется не «какая лучше», а «какая подходит под мою задачу».

Pydantic AI — type-safe агенты от создателей Pydantic

Pydantic AI — это агентный фреймворк от команды, написавшей Pydantic. Вся философия строится вокруг Python type hints: тулы типобезопасны, внешние сервисы подключаются через dependency injection, вывод валидируется Pydantic-моделями.

Ключевая фича, которой нет у конкурентов — dependency injection. Вы прокидываете в агента подключение к БД, HTTP-клиент, API-ключи — и тулы получают к ним доступ через RunContext:

from pydantic_ai import Agent, RunContext
from dataclasses import dataclass

@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):
    return await ctx.deps.db.get_user(user_id)

В тестах вы подставляете mock-объекты в AppDeps — и проверяете логику тулов без единого LLM-вызова. Это та самая структурная дисциплина, которая отличает production-код от прототипа.

Pydantic AI поддерживает пять режимов вывода: text, tool (tool-calling, по умолчанию), native (нативный structured output модели), prompted (через system prompt) и auto (выбирается автоматически по возможностям модели). Multi-agent сценарии пока базовые — для сложной оркестрации лучше комбинировать с LangGraph.

Честные ограничения: библиотека всё ещё v0.x. API может ломаться. Если у вас уже работает production-агент на чём-то другом — не мигрируйте, пока не выйдет v1.0.

Исходники: GitHub pydantic/pydantic-ai (18K ⭐, MIT, Python)

Smolagents — code-execution агенты от HuggingFace

Smolagents — это библиотека от HuggingFace, которая переворачивает подход к инструментам. Обычный агент решает «какой инструмент вызвать с какими аргументами» через JSON. Smolagents вместо этого генерирует и исполняет Python-код напрямую.

Разница радикальная. Вместо {"tool": "search", "query": "..."} агент пишет:

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

По бенчмаркам HuggingFace, это даёт ~30% меньше LLM-вызовов по сравнению с JSON tool-calling: последовательные multi-tool workflow обрабатываются в одном блоке кода вместо одного LLM-вызова за шаг. На GAIA benchmark Smolagents с GPT-4o показал 44.2% — первое место на validation set на момент релиза.

Ядро библиотеки — примерно 1 000 строк кода. Это сделано намеренно: библиотеку можно прочитать и модифицировать под себя. Для исследовательских команд и тех, кому нужно лезть в internals, это серьёзное преимущество.

Честные ограничения. Качество генерации кода резко падает на моделях меньше 7B параметров. GPT-4o или Claude Sonnet — обязательное требование. Исполнение кода — поверхность для атак: CodeAgent использует E2BSandbox или LocalPythonInterpreter, но в production с пользовательским вводом песочница обязательна. Аутентификация, rate limiting, логи — всё пишется руками.

Исходники: GitHub huggingface/smolagents (28K ⭐, Apache 2.0, Python)

Instructor — стопроцентно структурированный вывод

Instructor не заменяет ваш LLM-клиент — он его «патчит». Одна строка instructor.from_openai(client) добавляет параметр response_model, и ваш клиент начинает возвращать Pydantic-модели вместо сырого текста.

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": "John Smith, 30s, Python dev"}]
)
# profile — Pydantic-объект. Валидирован.

Когда валидация падает, Instructor автоматически повторяет запрос с сообщением об ошибке. max_retries контролирует число попыток. 15+ провайдеров: OpenAI, Anthropic, Google Gemini, Mistral, Cohere, Ollama, DeepSeek — меняете строчку, остальное работает.

3 миллиона загрузок в месяц и 100+ контрибьюторов — Instructor самая production-ready библиотека в этой пятёрке. Она не пытается делать агентный цикл, память или оркестрацию. Она делает ровно одну вещь — структурированный вывод — и делает её безупречно.

Честные ограничения: Retry-затраты могут удивлять. Сложные вложенные схемы иногда вызывают 3–5 повторных попыток, и каждая стоит денег. Практическое решение: ограничить max_retries до 1–2 и добавить fallback-логику.

Исходники: GitHub instructor-ai/instructor (13K ⭐, MIT, Python)

Outlines — structured generation без промптов

Outlines — это библиотека от сообщества, которая решает ту же проблему, что и Instructor, но принципиально другим способом. Вместо retry-цикла она использует logit-маскировку: форсирует логику генерации на уровне вероятностей токенов.

Вы задаёте Pydantic-схему или регулярное выражение — и Outlines гарантирует, что модель выдаст только валидные токены. Это значит ноль retry, ноль затрат на повторные вызовы, предсказуемое время ответа.

from outlines import generate
from outlines.models import openai
from pydantic import BaseModel

class Movie(BaseModel):
    title: str
    year: int
    rating: float

model = openai("gpt-4o-mini")
result = generate.json(model, Movie)(
    "Recommend a sci-fi movie from the 80s"
)

Outlines поддерживает генерацию JSON по Pydantic-схеме, Regex-guided генерацию, CFG и Python-интерпретаторы. Работает с OpenAI, Anthropic, Transformers, llama.cpp, vLLM, ExLlamaV2 и другими бэкендами.

Честные ограничения: не все бэкенды поддерживают logit-маскировку. Для OpenAI это работает через logit_bias, но на больших словарях маскировка может замедлять генерацию. Сообщество меньше, чем у Instructor, — 14K звёзд против 3M+ загрузок.

Исходники: GitHub outlines-dev/outlines (14K ⭐, Apache 2.0, Python)

Guidance — контроль над генерацией LLM

Guidance от Microsoft Research — это шаблонный язык для управления генерацией. Если Outlines контролирует вывод на уровне токенов, Guidance делает то же на уровне шаблона — с if/else, циклами, переменными и вызовами инструментов прямо внутри промпта.

Вы пишете {{#system}}, {{#user}}, {{#assistant}} — и Guidance гарантирует, что модель следует структуре. Встроенные функции вроде {{#select}} форсируют выбор из заданного списка, {{#gen}} генерирует текст с ограничениями, {{#each}} делает итерацию.

import guidance

program = guidance("""
{{#system~}}
You are a helpful assistant.
{{~/system}}

{{#user~}}
Extract movie info: {{input}}
{{~/user}}

{{#assistant~}}
Title: "{{#gen 'title'}}"
Year: {{#select 'year' options=[2020,2021,2022,2023,2024,2025,2026]}}
Rating: {{#gen 'rating' pattern="\\d+\\.\\d"}}
{{~/assistant}}
""")

result = program(input="Inception, 2010, 8.8")
print(result["title"], result["year"], result["rating"])

Guidance поддерживает Transformers, llama.cpp, OpenAI, Anthropic, VertexAI. Ключевое преимущество — вы точно знаете, в каком формате модель ответит, потому что формат задан шаблоном, а не промптом.

Честные ограничения: синтаксис Handlebars-подобных шаблонов не всем заходит. Для простых сценариев (просто структурированный вывод) Instructor или Outlines проще. База — 21K ⭐, но библиотека развивается медленнее, чем хотелось бы: последний major-релиз был в 2025.

Исходники: GitHub guidance-ai/guidance (21K ⭐, MIT, Jupyter Notebook / Python)

Сравнительная таблица

Комбинации: как использовать вместе

Самое интересное начинается, когда вы комбинируете эти библиотеки. Они спроектированы для разных слоёв, и вместе покрывают почти любую архитектуру AI-агента.

Instructor + LangGraph. LangGraph управляет состоянием и потоком, Instructor гарантирует структурированный вывод на каждом LLM-узле. Рабочая лошадка для production RAG-пайплайнов.

from langgraph.graph import StateGraph
import instructor

client = instructor.from_anthropic(anthropic_client)

def analyze_node(state):
    result = client.messages.create(
        model="claude-sonnet-4-2025",
        response_model=AnalysisResult,
        messages=[...]
    )
    return {"analysis": result}

Pydantic AI как внутренний слой. В каждом узле LangGraph вы используете Pydantic AI для type-safe тулов и dependency injection. LangGraph — оркестратор, Pydantic AI — исполнитель.

Smolagents standalone. Для research-агентов и code-execution сценариев Smolagents работает сам по себе. Добавьте E2B-песочницу — получите агента, который пишет код, исполняет его, анализирует результат и пишет новый код на основе ошибок.

Guidance для пресетов. Когда нужно гарантировать формат ответа в шаблонных сценариях (генерация отчётов, заполнение форм, структурированные API-ответы), Guidance даёт максимальный контроль без retry-затрат.