Managed Deep Agents Beta: способ развертывания агентов LangChain на основе каталогов
Управляемые глубокие агенты 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 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, при следующей развертке будет создана задача cron LangSmith; если файл удалить, задача 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 — единственный обязательный аргумент, который служит одновременно идентификатором помощника 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 или разместите open-source инструментарий самостоятельно в следующих случаях:
- Ваш собственный бэкенд должен вызывать агента. В бета-версии в первую очередь используется 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 для финансовых исследований: структурированные планы, реестр инструментов с учетом пространства имён, ограничения на перепланирование и пример работы с отслеживанием этапов.