LangChain Deep Agents: что это и как запустить на своей модели

LangChain Deep Agents — отдельная библиотека deepagents, которая собирает вокруг цикла «модель вызывает инструменты» то, без чего длинные задачи обычно разваливаются: виртуальную файловую систему, субагентов, управление контекстом и опциональное планирование. Ниже — что входит в Deep Agents, чем он отличается от обычного LangChain-агента и как запустить пример на модели, которую вы выбрали сами, через OpenAI-совместимый шлюз. Опираемся на документацию LangChain (раздел Deep Agents); версии пакетов и названия параметров сверяйте с ней, они развиваются быстро.

LangChain Deep Agents: что внутри и чем он отличается от create_agent

Документация LangChain называет Deep Agents «agent harness»: тот же цикл вызова инструментов, что в других фреймворках, но с готовыми возможностями. Они делятся на четыре группы:

• Среда выполнения: инструменты, виртуальная файловая система (ls, read_file, write_file, edit_file, glob, grep), по желанию песочница.
• Управление контекстом: навыки (skills), память, автоматическая суммаризация истории и вынос больших результатов инструментов в файлы.
• Делегирование: встроенный инструмент task для запуска субагентов в изолированном контексте и опциональный write_todos для плана.
• Управление человеком: остановка на подтверждение чувствительных вызовов (interrupt_on).

Для сравнения: обычный create_agent из LangChain это минимальная обвязка из модели, инструментов, промпта и middleware, где остальное вы собираете сами. Deep Agents построен поверх него и использует среду выполнения LangGraph. Если вам нужен агент «из коробки» для многошаговой работы с файлами, берите Deep Agents. Если нужна полная ручная настройка, берите create_agent (подключение шлюза к LangChain описано в инструкции по LangChain↗).

Установка и запуск на модели через шлюз

В примерах документации модель задаётся строкой вида provider:model. Для своего адреса удобнее передать готовый объект модели: документация прямо допускает «configured model instance». Для Zukko это ChatOpenAI с base_url:

pip install deepagents langchain-openai
export ZUKKO_API_KEY="fetch_ваш_ключ"

import os
from langchain_openai import ChatOpenAI
from deepagents import create_deep_agent

TICKETS = {
    "101": "Не приходит письмо с подтверждением, почта на mail.ru.",
    "102": "Оплата прошла, но баланс не пополнился. Платёж вчера вечером.",
    "103": "Как поменять e-mail в профиле? Старый ящик недоступен.",
}


def read_ticket(ticket_id: str) -> str:
    """Вернуть текст обращения по номеру."""
    return TICKETS.get(ticket_id, "Обращение не найдено")

Это минимальный запуск: create_deep_agent(model=..., tools=[...], system_prompt=...). Документация требует модель с поддержкой вызова инструментов. Если не уверены, подойдёт ли выбранная, проверьте на своей задаче (а список моделей возвращает GET https://api.zukko.pro/v1/models).

Обратите внимание на формат: строка "openai:..." в Deep Agents по документации включает Responses API, поэтому для нестандартного адреса мы передаём объект ChatOpenAI, а не строку. Адрес для OpenAI-клиентов у Zukko заканчивается на /v1.

Субагенты: дешёвая модель на тяжёлую работу

Субагенты в Deep Agents описываются словарями с полями name, description, system_prompt и необязательным model. Субагент работает в своём контексте и возвращает один итоговый отчёт, поэтому длинное чтение файлов не раздувает контекст основного агента. А поле model позволяет поручить рутину дешёвой модели:

cheap_model = ChatOpenAI(
    model="deepseek-v4.1-flash",
    base_url="https://api.zukko.pro/v1",
    api_key=os.environ["ZUKKO_API_KEY"],
)

agent = create_deep_agent(
    model=main_model,
    tools=[read_ticket],
    subagents=[{
        "name": "ticket-reader",
        "description": "Читает одно обращение и возвращает тему и суть в двух предложениях.",
        "system_prompt": "Прочитай обращение через read_ticket и верни тему и суть.",
        "tools": [read_ticket],
        "model": cheap_model,
    }],
    system_prompt="Ты аналитик поддержки. Делегируй чтение обращений субагенту.",
)

Решает ли агент делегировать, зависит от модели и промпта: проверьте по трассе, что субагент действительно вызывается. Остальную схему каскада описывает статья про каскад моделей↗.

Planning и middleware

Планирование в Deep Agents (инструмент write_todos) начиная с версии 0.7 включается явно: вы передаёте TodoListMiddleware в параметр middleware. Документация отмечает, что план особенно полезен на длинных задачах и слабых моделях.

from langchain.agents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model=main_model,
    tools=[read_ticket],
    middleware=[TodoListMiddleware()],
)

Middleware — общий механизм LangChain: это код, который встраивается вокруг вызова модели и инструментов. В Deep Agents на нём построены файловая система, субагенты и память. Свои middleware можно добавлять тем же параметром, а подтверждение действий человеком включается через interrupt_on, например interrupt_on={"edit_file": True}.

Сколько это стоит

Агентный цикл дорог тем, что каждый шаг заново отправляет накопленный контекст. Оценка по формуле: число вызовов модели × средний вход × цена входа + число вызовов × средний выход × цена выхода. Пусть вызовов 30, средний вход 20 000 токенов, выход 1 000. Входных токенов суммарно 600 000, выходных 30 000. Цены на 18 октября 2026, OpenAI-формат (весь вход по цене входа):

Здесь миллионы токенов в формуле: 600 000 токенов это 0.6M. Обратите внимание на ограничение: токены субагентов не попадают в result["messages"] основного агента, поэтому для точного учёта сравнивайте баланс до и после запуска (GET /v1/balance и раздел «Использование» в кабинете) или включите трассировку LangSmith.

Кэш: Anthropic-формат

По документации, для моделей Anthropic Deep Agents автоматически помечает для кэширования статичные части системного промпта. У Claude скидку за кэш Zukko даёт только в Anthropic-формате (/v1/messages), поэтому для длинных сессий можно использовать ChatAnthropic с base_url="https://api.zukko.pro" (без /v1, клиент добавляет путь сам). Расчёт для 15 000 токенов статичного префикса и 30 вызовов на claude-sonnet-5-5 (запись в кэш $0.5, чтение $0.05 за 1M): без кэша 30 × 15 000 × 0.4 / 1M = $0.18, с кэшем 15 000 × 0.5 / 1M + 29 × 15 000 × 0.05 / 1M = 0.0075 + 0.02175 ≈ $0.029. Это верно, только если провайдер реально сообщает чтение кэша: проверьте поля usage в ответе. Подробнее: кэш в Zukko↗.

Не дайте агенту уйти в минус

Автономный агент может зациклиться. Создайте для него отдельный ключ с дневным лимитом в долларах и списком разрешённых моделей, а в коде ограничьте число шагов (recursion_limit в конфиге вызова). Подробнее: агент зациклился↗.

Частые вопросы

Чем Deep Agents отличается от LangGraph?

LangGraph это низкоуровневая среда выполнения для графов, а Deep Agents готовый агент поверх неё и LangChain. Выбор между ними зависит от того, нужна ли вам ручная оркестровка.

Обязательно ли использовать модели из примеров документации?

Нет. Строки вроде anthropic:claude-sonnet-5 в документации лишь примеры; через ChatOpenAI(base_url=...) можно подставить любую модель шлюза с поддержкой инструментов. Контекст у GLM-моделей Zukko 128K, у остальных из примеров 1M, учитывайте это при длинных сессиях.

Субагент не вызывается. Что делать?

Уточните description субагента (по ней основной агент решает, кого звать) и добавьте в системный промпт прямое указание делегировать. Убедитесь по трассе, что инструмент task вызывается.

Нужен ли LangSmith?

Нет, это необязательно, но трассировка помогает увидеть шаги и токены субагентов.

Чтобы попробовать, создайте ключ в кабинете↗, задайте дневной лимит и запустите пример выше.