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 охоплює бекенди, субагентів, пісочниці, моделі з участю людини та CLI. Якщо ви створюєте щось серйозне з використанням агентів, приділіть кілька годин, щоб зрозуміти, яке місце це займає у вашій інфраструктурі, навіть якщо ви не будете використовувати цей підхід відразу.