LangChain Deep Agents: встроенные функции планирования, работы с файлами и подагентами.

Команды, которые серьезно подходят к работе с агентами, как правило, идут по одному и тому же пути. Они начинают с цепочек LangChain, которые хорошо справляются с простыми пайплайнами. Затем задачи становятся сложнее: требуются вызовы инструментов, циклы, выводы непредсказуемой длины. Цепочек уже недостаточно, поэтому они переходят к LangGraph, где начинают писать схемы состояний, условные ребра и код для компиляции графа еще до того, как займутся самой проблемой.

Проблема не в LangGraph — он мощный инструмент. Но это среда выполнения, низкоуровневый примитив, и люди часто относятся к нему как к фреймворку приложений. deepagents — это ответ LangChain на это несоответствие.

Что это такое

«Глубокие агенты» могут означать практически что угодно, поэтому для точности: deepagents — это отдельный пакет на Python, устанавливаемый командой pip install deepagents; он работает поверх LangChain и LangGraph. В документации LangChain его называют инструментом для управления агентами. Он использует тот же цикл вызова инструментов, что и другие фреймворки, но включает в себя дополнительные встроенные возможности, поэтому их не нужно создавать заново каждый раз.

Точка входа — функция create_deep_agent(). Сначала её необходимо импортировать:

from deepagents import create_deep_agent

Затем передайте инструмент и промпт:

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"
agent = create_deep_agent(
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)
agent.invoke(
    {"messages": [{"role": "user", "content": "What is the weather in Mumbai?"}]}
)

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

Пять встроенных возможностей

Планирование с помощью write_todos

Каждый глубокий агент автоматически получает инструмент write_todos. При решении сложной задачи он разделяет её на шаги, отмечает каждый из них как ожидающий выполнения, в процессе или завершённый, а также корректирует план по мере изменения обстоятельств. Это не трюк с промптами — список хранится в состоянии агента, поэтому агент может вернуться к нему, обновить его и использовать его в течение всей сессии. Никому не нужно просить модель думать пошагово, поскольку такая структура является частью инфраструктуры.

Виртуальная файловая система

Это, возможно, будет самым большим сюрпризом. По умолчанию у агента есть функции ls, read_file, write_file, edit_file, glob и grep. Зачем агенту нужны файлы? Для управления контекстом.

Окна контекста имеют ограниченный объем, и длительные исследования, выполнение кода или результаты работы крупных инструментов быстро увеличивают объем истории. Глубокие агенты сохраняют объемный контент в виртуальную файловую систему вместо того, чтобы хранить всё в промпте. Когда результат работы инструмента превышает 20 000 токенов, библиотека сохраняет его в настроенном хранилище и оставляет в контексте путь к файлу вместе с 10-строчным превью. Когда агенту нужен полный контент, он вызывает функции read_file или grep. Это не фрагментация и не обрезка — это целенаправленная передача данных с извлечением по запросу.

Бэкенд файловой системы является модульным: по умолчанию используется состояние в памяти, локальный диск, LangGraph Store для сохранения данных между потоками или среды вроде Modal и Daytona.

Подагенты

Встроенный инструмент task позволяет основному агенту создавать специализированных подагентов для выполнения изолированных подзадач. Это важнее, чем кажется. При длительных исследовательских задачах агент, обрабатывающий всё сам, заполняет свой контекст промежуточными шагами, результатами поиска и частичными выводами. С помощью подагентов основной агент передаёт подзадачу новой инстанции с чистым контекстом. Эта инстанция работает самостоятельно, завершает работу и возвращает один краткий отчёт, благодаря чему контекст основного агента остаётся организованным.

Вы можете определить собственных подагентов с их собственными инструментами и системными промптами. Начните с импорта:

from deepagents import create_deep_agent, Subagent

Затем определите рецензента и привяжите его:

code_reviewer = Subagent(
    name="code-reviewer",
    system_prompt="You are an expert code reviewer. Analyze code for bugs, style, and performance.",
    tools=[read_file_tool],
)
agent = create_deep_agent(
    tools=[internet_search],
    subagents=[code_reviewer],
    system_prompt="You are a research and engineering assistant.",
)

Универсальный вспомогательный агент с инструментами файловой системы всегда доступен без какой-либо настройки.

Автоматическое краткое изложение

Для длительных задач именно здесь библиотека проявляет свою ценность. Как только объем контекста достигает 85% от максимального лимита модели и больше ничего нельзя сохранить в файлах, система запускает процесс краткого изложения. Языковая модель генерирует структурированный отчет, охватывающий цель сессии, созданные результаты и следующие шаги, и этот отчет заменяет полную историю в рабочей памяти. Оригинальные сообщения сохраняются в файловой системе в качестве официальной записи, чтобы позже можно было восстановить детали. По сути, сложные агенты могут продолжать работу над задачами без нарушения лимитов контекста, что обычно требует ручной настройки в базовой версии LangGraph.

Память между разговорами

Обычно состояние остаётся внутри одной нити. Однако при настройке CompositeBackend с LangGraph Store агент может сохранять память между сессиями и нитями. Файлы, хранящиеся по пути /memories/ или по любому другому выбранному вами пути, сохраняются после перезагрузки и могут быть прочитаны в любом диалоге. Используйте это для того, чтобы агент мог вспоминать ваши предпочтения, стиль программирования в вашем репозитории или то, на чём остановилась исследовательская работа, занимавшая несколько дней. Сначала импортируйте:

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

Затем проводка:

store = InMemoryStore()
backend = CompositeBackend(
    routes={"/memories/": StoreBackend(store=store)},
    default=StateBackend(),
)
agent = create_deep_agent(
    tools=[...],
    backend=backend,
    memory=["path/to/AGENTS.md"],  # persistent context file
)

Как связаны эти компоненты

Люди часто путают их, поэтому стоит разъяснить всё подробно.

• LangChain предоставляет базовые элементы: модели, инструменты, промпты и цепочки операций. Это фундамент.
• LangGraph — это среда выполнения для надёжной, имеющей состояние работы на основе графов, обеспечивающая сохранение данных, потоковую обработку, обработку прерываний и сложные условные алгоритмы. Это двигатель.
• Deep Agents — это инструмент, объединяющий оба компонента. Он не заменяет LangGraph; он использует LangGraph для всех операций и добавляет API высокого уровня с предустановленными параметрами, что позволяет избежать необходимости самостоятельной разработки механизмов планирования, слоя файловой системы, сжатия контекста и инфраструктуры подагентов.

Можно сказать так: LangGraph предоставляет двигатель и трансмиссию, а Deep Agents — готовую машину.

Для простых агентов функция create_agent из LangChain, вероятно, вполне достаточна. Когда задачи становятся сложными, длительными и требуют большого объема контекста, именно тогда deepagents оправдывает затраты на свою абстракцию.

Реалистичный быстрый старт: исследовательский агент

Вот пример исследовательского агента, который ищет информацию в Интернете и составляет структурированный отчет. Сначала необходимо настроить среду:

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent

Затем инструмент, инструкции и сам агент:

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search and return results."""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )
research_instructions = """You are an expert researcher.
Your job is to conduct thorough research and then write a polished report.
Use internet_search to gather information.
Write your findings to files as you go to avoid losing context.
Use write_todos to plan your research steps before starting.
"""
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",  # default model
    tools=[internet_search],
    system_prompt=research_instructions,
)
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Research the current state of agentic AI frameworks in 2025 and write a structured report."
    }]
})
print(result["messages"][-1].content)

Его запуск инициирует определённую последовательность действий. Агент вызывает функцию write_todos для планирования исследования. Он выполняет поиски и автоматически переносит большие объёмы результатов в виртуальную файловую систему. Если объём работы велик, он запускает дочерний агент для обработки отдельного раздела. По мере необходимости он снова считывает файлы и собирает всё в итоговый отчёт. Всё это время механизм управления контекстом обеспечивает, чтобы модель никогда не превысила установленный лимит. Вы сами не писали эту инфраструктуру — она поставлялась вместе с механизмом управления.

Агент командной строки

В пакет также входит терминальный агент, созданный на основе того же SDK:

pip install deepagents
deepagents  # launches the interactive CLI agent

Это агент для программирования, похожий на Claude Code или Aider, но работающий с использованием SDK Deep Agents. Он предоставляет интерактивный режим, неинтерактивный режим в виде «трубки» для написания скриптов (флаг -n), пользовательские навыки и постоянную память. Научите его правилам вашего проекта, и он будет помнить их между сессиями. Таким образом, SDK, используемое для управления агентом в производственных исследованиях, сразу же предоставляет вам готовый инструмент для разработчиков.

Когда использовать его

deepagents подойдет вам, когда:

• Задача требует планирования и множества шагов.
• Результаты работы инструментов объемны и должны обрабатываться в течение длительной сессии.
• Вам нужно делегирование задач подагентам без необходимости создания сложной инфраструктуры.
• Вам требуется память, сохраняющаяся между различными потоками общения.
• Вы разрабатываете агента для программирования или автономную исследовательскую систему.

Используйте create_agent или обычный LangGraph в следующих случаях:

• Агент простой, с одним или двумя вызовами инструментов и краткими ответами.
• Вам нужен тонкий контроль над топологией графа.
• Вы уже далеко продвинулись в разработке собственного рабочего процесса с LangGraph и не хотите использовать предустановленные параметры.

Сами документы это подтверждают: простые агенты требуют простых инструментов.

Почему это важно

Времена меняют подходы. Основные шаблоны агентов, вызовы инструментов, циклы ReAct и простые решения типа RAG сейчас уже хорошо поняты. Однако в области все еще остаются проблемы надежности при работе в долгосрочной перспективе, при выполнении задач, требующих планирования, большого объема контекста, сохранения данных и делегирования задач. Каждая команда, создающая производственные агенты, вынуждена решать эти же проблемы с нуля, причем стратегии работы с контекстом, шаблоны подагентов и конструкции памяти постоянно переосмысляются в незначительно измененных формах.

deepagents — это стратегия LangChain, заключающаяся в том, что подобные решения настолько распространены, что их можно стандартизировать. Инструмент с заранее заданными настройками, встроенной инфраструктурой и возможностью подключения внешних бэкендов пытается сместить акцент с вопроса «как нам создать необходимую инфраструктуру?» на вопрос «что именно должен делать агент?». Успех этого подхода зависит от того, смогут ли заранее заданные настройки функционировать в реальных условиях. Однако как направление развития он имеет смысл.

Начало работы

Установите пакет и клиент для поиска:

pip install deepagents tavily-python

Затем установите свои ключи:

export ANTHROPIC_API_KEY="your-key"
export TAVILY_API_KEY="your-key"
export LANGSMITH_TRACING=true  # optional, for debugging
export LANGSMITH_API_KEY="your-key"

В разделе обзора Deep Agents в документации LangChain рассматриваются бэкенды, сабагенты, песочницы, механизм участия человека и командная строка. Если вы планируете создавать что-то серьезное с использованием агентов, уделите полдня тому, чтобы понять, как это вписывается в вашу технологическую стек, даже если вы не будете использовать этот инструмент сразу.