Managed Deep Agents Beta: Un método basado en directorios para desplegar agentes de LangChain
Los Agentes Profundos Gestionados de LangChain convierten una carpeta de proyecto en un agente alojado. Qué hace cada archivo, cómo funciona el despliegue de MDA y las limitaciones de la versión beta que es importante conocer.
Fuentes: LangChain Just Shipped Managed Deep Agents — And Your Agent Is Now a Directory
Los equipos que desarrollaban sobre LangGraph seguían topándose con el mismo límite. LangGraph es un entorno de ejecución, una primitiva de bajo nivel, pero muchas personas lo trataban como un framework de aplicaciones. Deep Agents fue la respuesta de LangChain: planificación, un sistema de archivos virtual, subagentes y compresión de contexto integrados en una estructura que evitaba que nadie tuviera que volver a construir esa infraestructura desde cero.
Eso ayudó, pero luego apareció un segundo límite. Una estructura de este tipo termina en los límites del proceso. Tan pronto como un agente debe sobrevivir a un reinicio, reanudar su trabajo después de que una persona apruebe una llamada a una herramienta, ejecutarse a las 8 a.m. de lunes a viernes, responder a una mención en Slack o conservar cualquier memoria más allá del hilo actual, el equipo vuelve a tener que desarrollar infraestructura. Eso implica el uso de mecanismos de punto de control, tareas programadas con cron, verificación de firmas, definición de propietarios de hilos y enrutamiento de credenciales confidenciales.
Cualquiera que haya integrado un agente en un contenedor en la nube sabe cuán desequilibrado puede volverse todo esto. Piense en un agente de documentos impulsado por MCP en ECS Fargate: políticas IAM, una VPC con subredes privadas, el estado de Terraform en S3 junto con una tabla de bloqueo de DynamoDB, y definiciones de tareas que fallan en las verificaciones de estado hasta que alguien detecta una discrepancia en los puertos del contenedor. La lógica del agente puede tardar un par de días, mientras que la infraestructura circundante requiere unas cuantas semanas.
Managed Deep Agents es la solución de LangChain para ese segundo límite. Entró en beta pública el 7 de agosto de 2026. Después de leer las 21 páginas de documentación, lo más llamativo no es el despliegue con un solo comando del que todos hablan, sino el hecho de que el agente deja de ser un objeto de Python para convertirse en un directorio.
Qué es realmente el producto
La palabra “managed” es vaga, por lo que una definición precisa es útil. Managed Deep Agents, a la que se hace referencia como mda en una terminal, es un paquete de Python. Toma una carpeta de proyecto, la compila en una aplicación LangGraph alojada y la envía al Agent Server de LangSmith. El mecanismo de Deep Agents en sí no cambia, y LangSmith se encarga de ejecutarlo, gestionando la persistencia, los hilos duraderos, el ciclo de vida de los entornos de pruebas, la carga de habilidades y la gestión de la memoria.
El flujo de trabajo se resume en cuatro comandos:
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
El anuncio comienza con eso, y es preciso, pero subestima la verdadera elección de diseño que existe en un nivel inferior.
Las capacidades están controladas por ls
mda init crea una estructura de proyecto que la documentación considera como toda la superficie de trabajo:
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
Solo agent.py es obligatorio. Todo lo demás es opcional, y aquí está lo importante: el hecho de que exista un archivo es lo que activa o desactiva una funcionalidad.
Si elimina el directorio sandbox/, este desaparece. Si coloca un memory.py en la raíz, se activa la memoria persistente. Si agrega schedules/daily_digest.py, la próxima implementación crea un trabajo cron de LangSmith; si elimina el archivo, dicho trabajo cron se elimina también.
Cualquiera que haya escrito con Terraform reconocerá este modelo. Se trata de infraestructura declarativa en sintaxis de Python: usted describe el estado deseado y mda deploy armoniza la realidad con él.
El esquema solo tiene sentido una vez que ha visto qué contiene cada archivo, así que aquí los presentamos uno por uno.
agent.py, el único archivo requerido
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 es el único argumento requerido, y sirve tanto como ID del asistente de LangGraph como como nombre predeterminado de la implementación. Además, define_deep_agent acepta tools, middleware, subagents, permissions, interrupt_on (para aprobación con intervención humana) y response_format (salida estructurada).
Observe qué falta: no hay prompt del sistema, ni configuración de memoria, ni entorno aislado, ni programaciones. Todo eso se gestiona únicamente mediante archivos, y no existe forma de configurarlo en código aunque se desee.
Las herramientas de búsqueda integradas del lado del servidor no necesitan clave de proveedor, aunque cada proveedor espera un diccionario de herramientas con una estructura diferente, y ese es un punto fácil de cometer errores.
tools=[{"type": "web_search"}] # OpenAI
tools=[{"google_search": {}}] # Google
tools=[{"type": "web_search_20260209", "name": "web_search"}] # Anthropic
Cuando la búsqueda nunca aparece en un registro, este desfase es casi siempre la causa.
instructions.md y skills/
El contexto que se sincroniza con la nube se encuentra aquí. El archivo de instrucciones podría decir:
# Research assistant
You are a careful research assistant. Use internet search to find sources,
keep notes, and return concise answers with citations.
Se convierte en el prompt del sistema, que se inserta en cada ejecución. Las habilidades se comportan de manera diferente. Cada una se encuentra en su propio directorio, con información preliminar:
---
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.
Cuando el agente se inicia, solo ve el nombre y la descripción de cada habilidad. Cuando hay una tarea que coincide, lee todo el archivo SKILL.md, y los archivos de soporte se cargan de forma perezosa. Esto constituye una divulgación progresiva, al igual que en el framework de código abierto.
El detalle operativo útil es que, en el momento del despliegue, instructions.md y todo el árbol skills/ se envían al LangSmith Context Hub. A partir de entonces se pueden modificar en la interfaz sin necesidad de un nuevo despliegue, por lo que editar un prompt ya no implica realizar una compilación. Cualquiera que haya tenido que esperar a que finalice un proceso CI solo para corregir un error tipográfico en un prompt del sistema entenderá a qué me refiero.
memory.py: memoria duradera, opcional
from managed_deepagents import define_memory
memory = define_memory(scope="agent")
Esas dos líneas son todo lo que se necesita; sin ellas, el agente no cuenta con ninguna memoria duradera. Esto puede sorprender a quienes piensan que la memoria viene incluida de forma estándar.
Al activarla, se monta un árbol de Context Hub en /memories/agent/. El archivo AGENTS.md dentro de ese árbol es memoria activa, que se carga en el contexto en cada ejecución. Todo lo demás es memoria pasiva que el agente solo lee cuando es relevante. Las lecturas y escrituras se realizan mediante las herramientas habituales read_file, edit_file y write_file, y las escrituras en otras ubicaciones, incluidas otras rutas bajo /memories/, no son duraderas. De esto se deriva una consecuencia de diseño que se explica más adelante.
sandbox/ y su paso de captura de estado
from managed_deepagents import define_sandbox
sandbox = define_sandbox(
idle_ttl_seconds=600,
default_timeout=600,
docker_image="python:3.12-slim",
)
Cada hilo duradero recibe su propia caja de pruebas, respaldada por LangSmith Sandboxes. Un archivo opcional sandbox/setup.sh se ejecuta una vez bajo bash -e y el resultado se guarda como una instantánea, que los nuevos hilos clonan en lugar de repetir la configuración:
#!/usr/bin/env bash
set -euo pipefail
apt-get update && apt-get install -y jq
mkdir -p /workspace
Hay dos trampas que es importante conocer. Los valores de .env están disponibles mientras se ejecuta setup.sh, lo cual es útil para clonar un repositorio privado, pero los hilos que realizan la clonación del snapshot nunca los reciben. Además, todo lo que se deja en el disco termina en la imagen de cada hilo, lo que impide guardar secretos allí.
schedules/: cron con una regla en tiempo de compilación
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.",
)
Hay un archivo por programa, y el nombre del archivo se convierte en el nombre del programa. Debe especificarse exactamente uno de prompt o input. Solo se acepta el formato cron de cinco campos, por lo que una expresión basada en segundos hace que la compilación falle. Si no se indica una zona horaria, se aplica UTC.
La restricción que más probablemente cause problemas es que las declaraciones de los programas se extraen en tiempo de compilación y deben ser serializables de forma estática. No se permiten variables de entorno, llamadas a funciones, **kwargs ni valores calculados. Los literales y las constantes de nivel superior están bien. Todo lo dinámico debe ir en el agente, las herramientas o el middleware.
Cada ejecución normalmente utiliza un hilo temporal que se elimina al finalizar. Las ejecuciones programadas que necesitan mantener estado deben utilizar thread={"mode": "persistent", "id": "nightly-memory"} en su lugar.
canales/ y conectores/
Un canal recibe los mensajes que inician las ejecuciones, mientras que un conector proporciona herramientas al agente. Cada uno es un archivo único:
# 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"],
},
},
)
El enrutamiento sigue el nombre del archivo. channels/slack.py expone su endpoint Events en /channels/slack/events, y las herramientas MCP incluyen el nombre del servidor como prefijo a menos que se indique lo contrario, por lo que este conector aparece como langchainDocs__search_docs_by_lang_chain. Los servidores MCP de Stdio no son una opción; solo están disponibles Streamable HTTP y SSE heredado.
identity.py: quién puede llamar al agente
from managed_deepagents import auth, define_identity
identity = define_identity(auth=auth.langsmith_api_key())
Esto es lo que mda init genera como valor predeterminado seguro. Los usuarios que realizan la llamada envían una clave de espacio de trabajo de LangSmith en el encabezado x-api-key. Eso determina si alguien puede llamar al agente, pero todos comparten los mismos hilos de conversación. Para garantizar privacidad por usuario, es necesario realizar un cambio a Supabase:
identity = define_identity(auth=auth.supabase(project_ref="your-project-ref"))
Los clientes envían entonces Authorization: Bearer , y MDA verifica el JWT contra el endpoint JWKS del proyecto. La documentación incluye una advertencia sobre migración: agregar esto a una implementación existente no rellena automáticamente los metadatos del propietario en los hilos que ya existen.
Qué hace mda deploy
La documentación enumera once pasos en orden. Los que son importantes son:
- Verifica el proyecto y carga
agent.py. - Encuentra la clave de LangSmith en un orden fijo (
LANGGRAPH_HOST_API_KEY,LANGSMITH_API_KEY,LANGCHAIN_API_KEY) y lee.envantes que el entorno de la shell. - Recopila cada valor de
.envque no esté reservado y lo envía como un secreto de implementación alojada. - Sube
instructions.mdy la carpetaskills/a Context Hub. - Compila el contenido en
.mda/buildy sube el archivo resultante, cuyo tamaño no debe superar los 200 MB. - Espera, verificando periódicamente el estado, hasta que este sea
DEPLOYED. - Reconcilia las tareas programadas localizando todas las que había creado anteriormente, eliminándolas todas y reconstruyendo el conjunto a partir de la carpeta
schedules/actual.
El séptimo paso es el momento en el que comparar esto con Terraform deja de ser solo una metáfora: se trata de la corrección de desviaciones, y funciona de manera similar a terraform apply.
Así como en Terraform, existe una opción que permite omitir este proceso de forma silenciosa. Al añadir --no-wait, la CLI inicia la compilación remota y se cierra antes de que el estado cambie a DEPLOYED, lo que significa que el paso de reconciliación de horarios nunca se ejecuta. El nuevo cron no existe, el cron eliminado sigue activándose, y la implementación indica éxito. Cada vez que cambie el horario, ejecute mda deploy . sin --no-wait. Tener una línea al respecto en el manual de operaciones del equipo es una forma económica de garantizar seguridad.
Ubicación dentro de la pila de LangChain
Actualmente hay cuatro capas, y la gente tiende a confundirlas entre sí.
LangChain proporciona los componentes básicos: modelos, herramientas y prompts. Es la base.
LangGraph es el entorno de ejecución que ofrece un funcionamiento duradero, con estado y en forma de grafo (persistencia, transmisión en tiempo real, interrupciones). Pensemos en él como el motor.
Deep Agents se sitúa por encima de ambos como el marco de trabajo, e incluye un planificador, un sistema de archivos, subagentes, compresión de contexto y valores predeterminados definidos por el sistema.
Managed Deep Agents es el entorno de ejecución alojado para dicho marco de trabajo. Se trata del mismo Agent Server que los clientes de LangSmith ya utilizan en producción, pero empacado de manera más estructurada para proyectos de Deep Agents.
Una analogía con los automóviles lo ilustra bien: LangGraph proporciona el motor y la transmisión, Deep Agents proporciona el coche, y Managed Deep Agents proporciona el coche, el taller y a alguien más que cambia el aceite. El precio a pagar es perder la posibilidad de abrir el capó. Es un intercambio honesto, y la documentación lo explica claramente. A quienes necesiten rutas personalizadas, código de aplicación adicional al grafo o control directo sobre la persistencia se les indica que utilicen directamente LangSmith Deployment.
El ámbito de la memoria compartida
La versión beta ofrece un único ámbito de memoria, agent: un árbol de lectura/escritura que comparten todos los usuarios que pueden acceder a la implementación.
La documentación es excepcionalmente explícita al respecto. La memoria es compartida por todos los usuarios, y cada uno puede influir en ella. Por lo tanto, almacene solo conocimientos que todos puedan leer y modificar, y trate la memoria existente como entrada no fiable que nunca debe otorgar autoridad, cambiar permisos de herramientas ni eludir aprobaciones.
Considérelo como una postura de seguridad. AGENTS.md se carga en el contexto del sistema en cada ejecución, de modo que lo que el usuario A escriba el martes terminará en el contexto del usuario B el miércoles, de forma persistente. Para una herramienta interna de un único equipo está bien. Pero para cualquier sistema multiinquilino, esto equivale a un canal de inyección de comandos con una capa de persistencia adjunta.
Lo que empeora aún más la situación para quienes se preocupan por la evaluación y la observabilidad es que el fallo no se reflejará en las pruebas de evaluación. Las tareas de Harbor califican el estado del espacio de trabajo después de una ejecución, y no tienen en cuenta la posibilidad de que un atacante haya escrito en la memoria activa una semana antes.
El propio consejo de la documentación es acertado: se debe evitar el uso de memoria compartida cuando los llamantes no deberían influirse mutuamente. Hasta que llegue la posibilidad de delimitar la memoria por usuario, eso representa un verdadero límite para lo que se puede desarrollar.
Una superficie que sigue cambiando
Un aviso práctico antes de copiar cualquier código. La publicación inicial data del 7 de agosto, mientras que la documentación sigue cambiando constantemente. En aproximadamente tres semanas, cuatro APIs públicas se modificaron, y cualquiera que desarrolle basándose en los ejemplos del anuncio se encontrará con todas ellas.
- Memoria: el anuncio indica que cada despliegue comienza con memoria limitada al agente, mientras que la documentación describe la memoria duradera como algo opcional que está desactivado por defecto.
- Sandboxes: el anuncio utiliza
define_sandbox(provider="langsmith", scope="thread")y sugiere un ámbitoagentcompartido; la página de referencia mencionaidle_ttl_secondsydefault_timeouty afirma que un sandbox siempre se asocia a un hilo de ejecución. - Identidad: el anuncio habla de configurar un proveedor OIDC dentro de
identity.py, pero la página dedicada a la identidad solo trata las claves API de LangSmith y Supabase. - Slack: el anuncio hace referencia a
channels.slack(on=[...]), mientras que la guía de Slack no incluye el parámetroony coloca las suscripciones a eventos en el manifiesto de la aplicación de Slack.
Tampoco la documentación siempre es coherente consigo misma. Una página denomina al comando mda channel init slack y otra indica mda channel add slack .; la opción --configure-slack para mda deploy . se describe en la guía de Slack, pero no aparece en la tabla de referencia de la CLI.
Eso no significa que el producto sea deficiente. Simplemente indica que se trata de una versión beta de una herramienta declarativa, donde la interfaz es algo que nadie debería tener que adivinar. Cuando la documentación y las tablas difieren, mda --help es la solución.
Cuándo funciona y cuándo no
Managed Deep Agents tiene sentido cuando:
- ya estás trabajando con la plataforma y la infraestructura representa un cuello de botella
- el agente necesita hilos duraderos, tareas programadas o una interfaz en Slack
- las preguntas y habilidades deben poder modificarse sin necesidad de volver a desplegar
Elige LangSmith Deployment directamente o aloja tú mismo el framework de código abierto cuando:
- tu propio backend debe llamar al agente. La versión beta está orientada a la CLI mientras se finaliza la API, y reanudar una ejecución interrumpida de forma programática implica consultar a tu contacto en LangChain, según la documentación. Esto impide completamente el uso de este caso de aplicación.
- es necesario mantener a los llamantes alejados de la memoria de los demás.
- se requieren rutas personalizadas o control directo de la persistencia.
- los datos deben permanecer fuera de EE. UU.
- Slack funciona en varias réplicas. La deduplicación de eventos es, por el momento, local al proceso, por lo que un intento de reintentar desde Slack puede activar al agente dos veces, y las herramientas accesibles desde un canal deben ser idempotentes si tienen efectos secundarios.
Probándolo
Instalar y estructurar:
uv tool install managed-deepagents
mda init test-agent && cd test-agent
Luego coloque las claves en .env:
LANGSMITH_API_KEY=<your-key>
OPENAI_API_KEY=<your-key>
Antes de escribir algo, ejecute ls en lo que se ha generado como estructura inicial. Cinco minutos trabajando con el directorio enseñan más sobre el modelo del producto que el anuncio mismo.
A continuación, uv sync && mda dev . construye el proyecto, crea una versión local de Context Hub (que incluye instrucciones, habilidades y memoria) y abre LangSmith Studio en una pestaña del navegador. No realiza recargas en tiempo real de los archivos del proyecto, por lo que debe detenerse y volver a ejecutarlo después de realizar cambios. La guía de inicio rápido oficial se encuentra en la documentación de Python de LangSmith, en la sección de Managed Deep Agents.
Los equipos que ya están utilizando Deep Agents y que están configurando manualmente su infraestructura de despliegue deberían poder completarlo en una tarde. El modelo basado en directorios es una buena idea, y los problemas de la versión beta pueden solucionarse una vez se conozcan.
Leer más
- ¿Por qué los agentes a largo plazo necesitan un marco de control? Cómo gestionan los agentes profundos el estado y el contexto — Un análisis detallado de los agentes profundos: deterioro del contexto, los cuatro pilares fundamentales, middleware, perfiles de control, backends de sistema de archivos, subagentes aislados, fallos en casos extremos y alternativas.
- Construir un agente de planificación en LangGraph: planificar, ejecutar, replanificar e informar — Un agente de planificación de cuatro nodos en LangGraph para investigación financiera: planes estructurados, un registro de herramientas consciente del espacio de nombres, límites de replanificación y un ejemplo de ejecución con seguimiento.