Managed Deep Agents Beta: Спосіб розгортання агентів LangChain на основі каталогів
Managed Deep Agents від LangChain перетворює папку проекту на хостованого агента. Що робить кожен файл, як працює процес розгортання mda, та недоліки бета-версії, про які варто знати.
Джерела: LangChain Just Shipped Managed Deep Agents — And Your Agent Is Now a Directory
Команди, які розвивалися на основі LangGraph, постійно стикалися з тією самою обмеженістю. LangGraph — це середовище виконання, примітив низького рівня, проте багато хто ставився до нього як до фреймворку додатків. Deep Agents став відповіддю LangChain: планування, віртуальна файлова система, підагенти та стиснення контексту об’єднані в єдину структуру, щоб нікому не доводилося заново будувати всю цю інфраструктуру.
Це допомогло, але з’явилася ще одна обмеженість. Така структура діє лише в межах процесу. Як тільки агенту потрібно вижити після перезапуску, продовжити роботу після того, як людина схвалить використання інструменту, працювати з 8 ранку з понеділка по п’ятницю, відповідати на повідомлення в Slack чи зберігати будь-яку інформацію поза поточним потоком, команда знову змушена будувати інфраструктуру. Це означає необхідність використання механізмів перевірки стану, завдань типу cron, верифікації підписів, визначення власника потоку та маршрутизації секретних даних.
Кожен, хто коли-небудь використовував агента в хмарному контейнері, знає, наскільки це може стати нерівноваженим. Уявіть собі документний агент, який працює за допомогою MCP на ECS Fargate: політики IAM, VPC із приватними підмережами, стан Terraform у S3 із таблицею блокування DynamoDB, а також визначення завдань, які провалюють перевірки стану, поки хтось не помітить неузгодженість портів контейнера. Логіка агента може розроблятися кілька днів, тоді як супутня інфраструктура вимагає кількох тижнів.
Managed Deep Agents — це рішення LangChain для подолання цього другого обмеження. Воно вийшло у публічну бета-версію 7 серпня 2026 року. Прочитавши 21 сторінку документації, найбільш вражаючим є не можливість розгортання за одну команду, про яку всі згадують. Найважливіше те, що агент перестає бути об’єктом Python — він стає каталогом.
Що насправді є цим продуктом
Слово „managed“ є розпливчастим, тому корисно мати точне визначення. Managed Deep Agents, який у терміналі позначається як mda, — це пакет Python. Він бере папку проекту, компілює її у хостовану додаток LangGraph та надсилає його на сервер Agent Server LangSmith. Сам механізм Deep Agents залишається незмінним, а LangSmith бере на себе його запуск, керування стабільністю, роботою потоків, життєвим циклом сандбоксів, завантаженням навичок та управлінням пам’яттю.
Робочий процес можна виконати за допомогою чотирьох команд:
uv tool install managed-deepagents
mda init research-assistant
cd research-assistant
uv sync
mda dev . # run locally in LangSmith Studio
mda deploy . # deploy to LangSmith
У оголошенні йдеться саме про це, і це точно, але воно не відображає справжній вибір дизайну на наступному рівні.
Функціонал контролюється за допомогою ls
mda init створює структуру проекту, яку документація вважає повною поверхнею для роботи:
my-agent/
├── agent.py # required — the model and core config
├── instructions.md # system prompt, synced to Context Hub
├── skills/
│ └── research/
│ └── SKILL.md # task-specific playbooks
├── tools/ # your LangChain tools
├── middleware/ # logic around model and tool calls
├── connectors/
│ └── mcp.py # remote MCP servers
├── channels/
│ └── slack.py # Slack, GitHub, other entry points
├── schedules/
│ └── daily_digest.py # managed cron jobs
├── sandbox/
│ └── __init__.py # isolated filesystem and shell
├── identity.py # auth and thread scoping
├── memory.py # durable cross-thread memory
├── pyproject.toml
├── .env
└── evals/ # Harbor tasks
Лише agent.py є обов’язковим. Усе інше є необов’язковим, і ось на що варто звернути увагу: наявність файлу визначає, чи буде функція увімкнена чи вимкнена.
Якщо видалити каталог sandbox/, сандбокс зникне. Якщо покласти memory.py у кореневу директорію, буде увімкнена постійна пам’ять. Якщо додати schedules/daily_digest.py, під час наступного розгортання буде створено завдання LangSmith cron; якщо видалити файл, завдання cron буде знищене.
Кожен, хто працював з Terraform, впізнає цю модель. Це декларативна інфраструктура у синтаксисі Python. Ви описуєте бажаний стан, а mda deploy узгоджує реальність із ним.
Структура має сенс лише після того, як ви побачите, що містять файли, тож ось вони по одному.
agent.py – єдиний обов’язковий файл
from managed_deepagents import define_deep_agent
from middleware.audit import log_tool_calls
from tools.search import internet_search
agent = define_deep_agent(
name="research-assistant",
model="openai:gpt-5.5",
tools=[internet_search],
middleware=[log_tool_calls],
interrupt_on={"internet_search": True},
)
name — це єдиний обов’язковий аргумент, який виконує функцію ID асистента LangGraph та стандартної назви розгортання. Крім того, функція define_deep_agent приймає параметри tools, middleware, subagents, permissions, interrupt_on (для схвалення людиною) та response_format (структурований вихід).
Подивіться, чого бракує: немає системного запиту, немає налаштувань пам’яті, немає сандбоксу, немає графіків. Усе це контролюється лише файлами, і немає можливості налаштувати їх у коді, навіть якщо це було б бажано.
Вбудовані інструменти пошуку з боку сервера не потребують ключа постачальника, хоча кожен постачальник очікує словник інструментів у іншій формі, і саме тут легко виникнути проблеми:
tools=[{"type": "web_search"}] # OpenAI
tools=[{"google_search": {}}] # Google
tools=[{"type": "web_search_20260209", "name": "web_search"}] # Anthropic
Коли пошук ніколи не з’являється у записі, майже завжди причиною є саме ця невідповідність.
instructions.md та skills/
Тут знаходиться контекст, який синхронізується з хмарою. Файл інструкцій може містити такий текст:
# Research assistant
You are a careful research assistant. Use internet search to find sources,
keep notes, and return concise answers with citations.
Це стає системним запитом, який додається до кожного запуску. Навички поводяться по-різному. Кожна з них знаходиться у власній директорії разом із метаданими:
---
name: research
description: Gather and synthesize context before answering complex questions.
---
# Research
Use this skill when a task needs more than a direct answer.
1. Identify what information is missing.
2. Use `query_db` to look up relevant records.
3. Summarize findings before responding to the user.
Коли агент запускається, він бачить лише назву та опис кожної навички. Якщо знаходить відповідне завдання, він читає весь файл SKILL.md, а всі додаткові файли завантажуються за потреби. Це є принципом поступового розкриття інформації, як у інструментах з відкритим кодом.
Корисна оперативна деталь: під час розгортання файл instructions.md та вся структура директорії skills/ передаються до LangSmith Context Hub. Після цього їх можна змінювати в інтерфейсі користувача без нового розгортання, тож редагування запиту більше не означає необхідності побудови проекту. Кожен, хто коли-небудь проходив процес CI лише для виправлення опечатки в системному запиті, розуміє суть цього підходу.
memory.py: стійка пам’ять, за бажанням
from managed_deepagents import define_memory
memory = define_memory(scope="agent")
Цих двох рядків достатньо, і без них агент зовсім не має стійкої пам’яті. Це може здивувати тих, хто вважає, що пам’ять є стандартною функцією.
Її увімкнення призводить до створення одного дерева Context Hub у каталозі /memories/agent/. Файл AGENTS.md у цьому дереві є «гарячою» пам’яттю, яка завантажується в контекст при кожному запуску. Усе інше є «холодною» пам’яттю, яку агент читає лише тоді, коли це необхідно. Зчитування та записування відбуваються за допомогою звичайних інструментів read_file, edit_file та write_file, а записи в інші місця, включаючи інші шляхи під каталогом /memories/, не є стійкими. Це має наслідки для проектування, про які йтиметься далі.
sandbox/ та крок створення знімка
from managed_deepagents import define_sandbox
sandbox = define_sandbox(
idle_ttl_seconds=600,
default_timeout=600,
docker_image="python:3.12-slim",
)
Кожен стійкий потік отримує власну пісочницю, підтримувану LangSmith Sandboxes. Опційний файл sandbox/setup.sh виконується один раз за допомогою bash -e, а результат зберігається у вигляді знімка, який нові потоки клонують замість повторної налаштування:
#!/usr/bin/env bash
set -euo pipefail
apt-get update && apt-get install -y jq
mkdir -p /workspace
Варто знати про дві проблеми. Значення з .env доступні під час виконання setup.sh, що допомагає під час клонування приватного репозиторію, але потоки, які клонують знімок, ніколи їх не отримують. Крім того, все, що залишається на диску під час налаштувань, потрапляє до образу кожного потоку, що унеможливлює зберігання там конфіденційної інформації.
schedules/: cron із правилом часу компіляції
from managed_deepagents import define_schedule
schedule = define_schedule(
cron="0 8 * * 1-5",
timezone="America/Los_Angeles",
prompt="Review durable memory for reusable research rules. List open questions for today.",
)
Для кожного графіка існує один файл, а назва цього файлу стає назвою графіка. Має бути вказано рівно один з параметрів prompt або input. Приймається лише формат cron із п’ятьма полями, тому вирази, засновані на секундах, призводять до невдачі компіляції. У разі відсутності часової зони використовується UTC.
Обмеження, яке найчастіше створює проблеми, полягає у тому, що оголошення графіків вилучаються під час компіляції та мають бути статично серіалізованими. Не дозволяються змінні середовища, виклики функцій, параметри **kwargs чи обчислені значення. Літерали та константи верхнього рівня допускаються. Усе динамічне має знаходитися в агенті, інструментах чи проміжковому програмному забезпеченні.
Зазвичай кожен запуск використовує тимчасову нитку, яка видаляється після завершення. Для запланованих запусків, які мають формувати стан, потрібно використовувати параметр thread={"mode": "persistent", "id": "nightly-memory"}.
channels/ та connectors/
Канал отримує повідомлення, які запускають процеси, тоді як конектор надає агенту інструменти. Кожен з них — це окремий файл:
# channels/slack.py
from managed_deepagents import channels
channel = channels.slack(
auto_reply=True,
mention_behavior="strip",
conversation={"app_mention": "thread", "direct_message": "conversation"},
)
# connectors/mcp.py
from managed_deepagents import connectors
connector = connectors.mcp(
mcp_servers={
"langchainDocs": {
"transport": "http",
"url": "https://docs.langchain.com/mcp",
"include_tools": ["search_docs_by_lang_chain"],
},
},
)
Маршрутизація відбувається за назвою файлу. channels/slack.py відкриває свій кінцевий пункт Events за адресою /channels/slack/events, а інструменти MCP передають назву сервера як префікс, якщо не вказано інше, тому цей конектор відображається як langchainDocs__search_docs_by_lang_chain. Сервери Stdio MCP не є варіантом — доступні лише Streamable HTTP та старіші формати SSE.
identity.py: хто може викликати агента
from managed_deepagents import auth, define_identity
identity = define_identity(auth=auth.langsmith_api_key())
Ось що генерує mda init як безпечний стандарт. Користувачі надсилають ключ робочого простору LangSmith у заголовку x-api-key. Це визначає, чи може хтось викликати агента, але всі потім користуються однаковими потоками. Для забезпечення приватності на рівні кожного користувача необхідно перейти на Supabase:
identity = define_identity(auth=auth.supabase(project_ref="your-project-ref"))
Клієнти потім надсилають Authorization: Bearer , і MDA перевіряє JWT проти кінцевої точки JWKS проєкту. У документації є одне попередження щодо міграції: додавання цього елемента до існуючої розгортки не відновлює метадані власника для вже існуючих потоків.
Що робить mda deploy
У документації перелічено одинадцять послідовних кроків. Найважливіші з них:
- Перевіряє проєкт та завантажує
agent.py. - Знаходить ключі LangSmith у фіксованому порядку (
LANGGRAPH_HOST_API_KEY,LANGSMITH_API_KEY,LANGCHAIN_API_KEY) та читає файл.envдо налаштувань середовища оболонки. - Збирає кожне значення з файлу
.env, яке не є зарезервованим, та надсилає його як таємницю розгортки.
instructions.md та папку skills/ до Context Hub..mda/build та завантажує архів, розмір якого не повинен перевищувати 200 МБ.DEPLOYED.schedules/.Сьомий крок — це момент, коли порівняння з Terraform вже не є просто метафорою. Це корекція відхилень, і цей процес функціонує так само, як terraform apply.
Отже, як і у Terraform, існує прапорець, який тихо ігнорує цей процес. Додавання --no-wait змушує CLI розпочати віддалену обробку та завершити її ще до того, як статус стане DEPLOYED, що означає, що крок узгодження графіка виконання так і не досягається. Новий cron не існує, видалений cron все одно запускається, а процес розгортання повідомляє про успіх. Кожного разу, коли змінюється графік, виконайте mda deploy . без параметра --no-wait. Рядок у посібнику команди — це недороге страхування.
Яке місце це займає у стеку LangChain
Зараз існує чотири шари, і люди часто змішують їх між собою.
LangChain забезпечує базові елементи: моделі, інструменти, запити. Це основа.
LangGraph — це середовище виконання, яке забезпечує стабільну, зберігаючу стан виконання у вигляді графа (перезапис, стрімінг, переривання). Можна уявити його як двигун.
Deep Agents знаходиться на вищому рівні та є основою для цих рішень, маючи планувальник, файлову систему, підагентів, функції стиснення контексту та жорсткі стандартні налаштування.
Managed Deep Agents — це середовище виконання для цієї основи. Це той самий Agent Server, який клієнти LangSmith вже використовують у промислових умовах, але у більш строгій формі під проекти Deep Agents.
Аналогія з автомобілем допомагає це пояснити: LangGraph забезпечує двигун та коробку передач, Deep Agents — сам автомобіль, а Managed Deep Agents — автомобіль, гараж та когось, хто змінює мастило. Ціною є втрата можливості відкрити капот. Це чесна угода, і документація чесно про це повідомляє. Тим, хто потребує індивідуальних шляхів обробки даних, коду додатку окремо від графу чи прямого контролю над зберіганням даних, рекомендується використовувати LangSmith Deployment безпосередньо.
Область спільної пам’яті
Бета-версія пропонує один діапазон пам’яті — agent: одну ієрархію для читання/запису, якою користуються всі користувачі, що мають доступ до цього розгортання.
У документації дуже прямолінійно описано наслідки цього підходу. Пам’ять є спільною для всіх користувачів, і кожен з них може її змінювати. Тому зберігайте лише ту інформацію, яку всі можуть читати та модифікувати, а існуючу пам’ять розглядайте як ненадійний вхідний даний, який ніколи не повинен надавати прав, змінювати дозволи інструментів чи обходити процедури схвалення.
Це є проявом певної позиції щодо безпеки. Файл AGENTS.md завантажується в системний контекст при кожному запуску, тож все, що користувач A запише у вівторок, залишиться в контексті користувача B у середу та буде зберігатися постійно. Для внутрішнього інструменту, що використовується лише однією командою, це нормально. Однак для будь-якого інструменту з кількома користувачами це створює канал для введення команд із механізмом постійного зберігання даних.
Що ще гірше для тих, хто піклується про оцінку та спостережуваність, так це те, що ця проблема не буде відображатися у результатах оцінки. Завдання Harbor оцінюють стан робочого простору після виконання, і вони не враховують ситуацію, коли хтось написав дані у «гарячу» пам’ять тиждень раніше.
Власні рекомендації документації є правильними: уникайте використання спільної пам’яті, коли викликаючі програми не повинні впливати одна на одну. До того часу, поки не з’явиться механізм обмеження пам’яті за користувачем, це справжня перешкода для розробки.
Інтерфейс, який все ще змінюється
Практичне попередження перед копіюванням будь-якого коду. Дата публікації поста становить 7 серпня, тоді як документація постійно змінюється. Протягом приблизно трьох тижнів змінилися чотири публічні API, і будь-хто, хто розробляє на основі прикладів з цього оголошення, стикатиметься з усіма ними.
- Пам’ять: у оголошенні зазначено, що кожне розгортання починається з пам’яті, обмеженої межами агента, тоді як у документації стійка пам’ять описується як опція, яка за замовчуванням вимкнена.
- Сандбокси: у оголошенні використовується
define_sandbox(provider="langsmith", scope="thread"), і натякається на спільний діапазонagent; на сторінці з посиланнями переліченіidle_ttl_secondsтаdefault_timeout, і зазначено, що один сандбокс завжди відповідає одному потоку. - Ідентичність: у оголошенні йдеться про налаштування постачальника OIDC у файлі
identity.py, але на сторінці, присвятованій ідентичності, розглядаються лише API-ключі LangSmith та Supabase. - Slack: у оголошенні використовується
channels.slack(on=[...]), тоді як у посібнику з Slack немає параметраon, і підписки на події розміщуються у маніфесті додатку Slack.
Документація також не завжди є послідовною сама з собою. На одній сторінці команда називається mda channel init slack, а на іншій — mda channel add slack .; параметр --configure-slack для mda deploy . описаний у посібнику Slack, проте відсутній у таблиці посилань CLI.
Це не робить продукт поганим. Це просто означає, що мова йде про бета-версію декларативного інструменту, де саме інтерфейс — це те, що ніхто не повинен вгадувати. Коли документація та таблиці суперечать одна одній, перемагає mda --help.
Коли це підходить, а коли — ні
Managed Deep Agents має сенс у таких випадках:
- якщо ви вже працюєте з інфраструктурою Deep Agents та інфраструктура є вузьким місцем
- якщо агенту потрібні стійкі потоки, заплановані завдання чи інтерфейс у Slack
- якщо запити та навички потрібно можливо змінювати без повторної розгортки
Виберіть сам LangSmith Deployment або самостійно розмістіть відкритий код цього інструменту, коли:
- Ваш власний бекенд має викликати агента. У бета-версії використовується CLI, поки розробляється API, а програмне відновлення перерваного запуску, згідно з документацією, означає звернення до вашого контакту в LangChain. Це повністю унеможливлює використання цього сценарію.
- Абоненти мають бути ізольовані один від пам’яті іншого.
- Необхідні коригування маршрутів або прямий контроль над зберіганням даних.
- Дані мають залишатися поза межами США.
- Slack працює на кількох репліках. Наразі усунення дублікатів подій відбувається локально, тому повторна спроба з боку Slack може двічі запустити агента, а інструменти, доступні з каналу, мають бути ідемпотентними, якщо у них є побічні ефекти.
Спробувати самостійно
Встановіть та створіть схему:
uv tool install managed-deepagents
mda init test-agent && cd test-agent
Потім додайте ключі до .env:
LANGSMITH_API_KEY=<your-key>
OPENAI_API_KEY=<your-key>
Перш ніж щось писати, виконайте команду ls у створеному каркасі. П’ять хвилин роботи з каталогом дають більше інформації про модель продукту, ніж сам оголошення.
Далі команда uv sync && mda dev . створює проект, формує локальну аналогію Context Hub (що включає інструкції, навички та пам’ять) та запускає LangSmith Studio у вкладці браузера. Він не здійснює гаряче завантаження файлів проекту, тому після змін потрібно зупинитися та запустити процес знову. Офіційний посібник з швидкого старту знаходиться у документації LangSmith для Python у розділі Managed Deep Agents.
Командам, які вже використовують Deep Agents та самостійно налаштовують їх розгортання, має вистачити одного дня. Модель каталогу — це гарна ідея, а проблеми бета-версії можна усунути, як тільки вони стануть відомими.
Пов’язана література
- Чому агенти довгострокового планування потребують спеціальних інструментів: як глибокі агенти керують станом та контекстом — Детальний аналіз глибоких агентів: проблема зміни контексту, чотири основні елементи архітектури, проміжне програмне забезпечення, профілі інструментів, бекенди файлової системи, ізольовані підагенти, ситуації виникнення помилок та альтернативні рішення.
- Створення агента планування в LangGraph: планування, виконання, перепланування, звітування — Агент планування з чотирма вузлами в LangGraph для фінансових досліджень: структуровані плани, реєстр інструментів із урахуванням імен просторів, обмеження щодо перепланування та приклад виконання зі збереженням логів.