Managed Deep Agents Beta : Une méthode basée sur des répertoires pour déployer des agents LangChain
Les Managed Deep Agents de LangChain transforment un dossier de projet en un agent hébergé. Ce que fait chaque fichier, le fonctionnement de la déploiement MDA, ainsi que les lacunes de la version bêta à connaître.
Sources: LangChain Just Shipped Managed Deep Agents — And Your Agent Is Now a Directory
Les équipes qui s’appuyaient sur LangGraph continuaient de se heurter au même problème. LangGraph est un environnement d’exécution, une primitive de bas niveau, pourtant de nombreuses personnes le traitaient comme un framework d’application. Deep Agents a été la réponse de LangChain : une fonction de planification, un système de fichiers virtuel, des sous-agents et une compression du contexte regroupés en un ensemble cohérent afin que personne n’ait à réimplémenter ces composants.
Cela a aidé, mais un autre problème est apparu. Un tel ensemble s’arrête à la frontière du processus. Dès qu’un agent doit survivre à une redémarrage, reprendre son travail après qu’un utilisateur ait validé une requête, fonctionner de 8 heures du matin du lundi au vendredi, répondre à une mention sur Slack, ou conserver des informations en dehors du thread actuel, l’équipe doit à nouveau développer des infrastructures. Cela implique des outils de sauvegarde, des tâches planifiées, une vérification des signatures, une gestion des propriétés des threads et un routage des secrets.
Tout ceux qui ont déjà placé un agent dans un conteneur cloud savent à quel point la situation peut devenir déséquilibrée. Pensez à un agent de documents fonctionnant avec MCP sur ECS Fargate : des politiques IAM, une VPC avec des sous-réseaux privés, un état Terraform stocké dans S3 accompagné d’une table de verrouillage DynamoDB, ainsi que des définitions de tâches qui échouent aux vérifications de santé jusqu’à ce que quelqu’un remarque une incohérence dans les ports du conteneur. La logique de l’agent peut nécessiter quelques jours, tandis que l’infrastructure environnante demande plusieurs semaines.
Managed Deep Agents est la réponse de LangChain à cette seconde contrainte. Il est entré en bêta publique le 7 août 2026. Après avoir lu les 21 pages de documentation, ce qui frappe le plus n’est pas le déploiement en une seule commande dont tout le monde parle. C’est plutôt le fait que l’agent cesse d’être un objet Python pour devenir un répertoire.
De quoi le produit est-il réellement fait
Le terme « géré » est vague, donc une définition précise est utile. Managed Deep Agents, désigné sous le nom de mda dans une terminal, est un paquet Python. Il prend un dossier de projet, le compile en une application LangGraph hébergée, puis l’envoie au Agent Server de LangSmith. Le mécanisme des Deep Agents reste inchangé, et LangSmith s’occupe de son exécution, gérant la persistance, les threads durables, le cycle de vie des sandbox, le chargement des compétences et l’allocation de la mémoire.
Le flux de travail se résume à quatre commandes :
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
Cet annonce commence par cela, et c’est exact, mais elle minimise le véritable choix de conception qui existe au niveau inférieur.
Les fonctionnalités sont contrôlées par ls
mda init crée une structure de projet que la documentation considère comme l’ensemble des fonctionnalités disponibles :
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
Seul agent.py est obligatoire. Tout le reste est optionnel, et voici ce sur quoi il faut se concentrer : c’est l’existence d’un fichier qui active ou désactive une fonctionnalité.
Supprimez le répertoire sandbox/ et le sandbox disparaît. Placez un memory.py à la racine et la mémoire persistante s’active. Ajoutez schedules/daily_digest.py et le prochain déploiement crée une tâche cron LangSmith ; supprimez le fichier et la tâche cron est supprimée.
Tout ceux qui ont écrit en Terraform reconnaîtront ce modèle. Il s’agit d’infrastructures déclaratives écrites en syntaxe Python. Vous décrivez l’état souhaité, et mda deploy met la réalité en accord avec celui-ci.
La structure n’a de sens que lorsque vous avez vu ce que contiennent les fichiers, alors voici ceux-ci un par un.
agent.py, le seul fichier requis
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 est le seul argument requis, et il sert à la fois comme identifiant de l’assistant LangGraph et comme nom par défaut du déploiement. En plus de cela, define_deep_agent accepte tools, middleware, subagents, permissions, interrupt_on (pour l’approbation par un humain) ainsi que response_format (sortie structurée).
On constate ce qui manque : pas de prompt système, pas de configuration de mémoire, pas de sandbox, pas de plannings. Tout cela est géré uniquement par des fichiers, et il n’existe aucun moyen de les configurer via du code, même si l’on le souhaitait.
Les outils de recherche côté serveur intégrés n’ont pas besoin de clé de fournisseur, bien que chaque fournisseur exige un dictionnaire d’outils de forme différente, ce qui constitue un point facile où des erreurs peuvent survenir.
tools=[{"type": "web_search"}] # OpenAI
tools=[{"google_search": {}}] # Google
tools=[{"type": "web_search_20260209", "name": "web_search"}] # Anthropic
Lorsque la recherche n’apparaît jamais dans un trace, ce déséquilibre en est presque toujours la cause.
instructions.md et skills/
Le contexte synchronisé avec le cloud se trouve ici. Le fichier des instructions peut indiquer :
# Research assistant
You are a careful research assistant. Use internet search to find sources,
keep notes, and return concise answers with citations.
Ce dernier devient l’invite système, insérée à chaque exécution. Les compétences se comportent différemment. Chacune se trouve dans son propre répertoire, accompagnée de métadonnées :
---
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.
Lorsque l’agent démarre, il ne voit que le nom et la description de chaque compétence. Lorsqu’une tâche correspondante est trouvée, il lit le fichier SKILL.md dans son intégralité, et les fichiers de support sont chargés de manière différée. Il s’agit d’une divulgation progressive, comme dans l’outil open source correspondant.
Détail opérationnel utile : au moment du déploiement, instructions.md ainsi que tout le répertoire skills/ sont envoyés vers LangSmith Context Hub. Ils peuvent ensuite être modifiés via l’interface utilisateur sans nouveau déploiement, de sorte que modifier un prompt n’implique plus de nouvelle compilation. Toute personne ayant dû effectuer un exécution CI uniquement pour corriger une faute d’orthographe dans un prompt système comprendra l’intérêt de cette approche.
memory.py : mémoire persistante, optionnelle
from managed_deepagents import define_memory
memory = define_memory(scope="agent")
Ces deux lignes suffisent, et sans elles l’agent ne dispose d’aucune mémoire durable. Cela peut surprendre ceux qui pensent que la mémoire fait partie des fonctionnalités de base.
Lorsqu’on l’active, un arbre Context Hub est monté à /memories/agent/. Le fichier AGENTS.md présent dans cet arbre constitue la mémoire active, chargée dans le contexte à chaque exécution. Tout le reste est de la mémoire passive que l’agent ne lit que lorsque c’est pertinent. Les lectures et les écritures s’effectuent via les outils habituels read_file, edit_file et write_file ; les écritures vers d’autres emplacements, y compris d’autres chemins sous /memories/, ne sont pas durables. Une conséquence de cette conception est abordée plus loin.
sandbox/ et son étape de capture d’état
from managed_deepagents import define_sandbox
sandbox = define_sandbox(
idle_ttl_seconds=600,
default_timeout=600,
docker_image="python:3.12-slim",
)
Chaque thread durable dispose de son propre environnement isolé, pris en charge par LangSmith Sandboxes. Un fichier sandbox/setup.sh optionnel s’exécute une fois sous bash -e et le résultat est enregistré sous forme de snapshot, que les nouveaux threads clonent afin d’éviter de répéter la configuration :
#!/usr/bin/env bash
set -euo pipefail
apt-get update && apt-get install -y jq
mkdir -p /workspace
Deux pièges méritent d’être connus. Les valeurs provenant de .env sont accessibles pendant l’exécution de setup.sh, ce qui est utile pour cloner un répertoire privé, mais les threads chargés du clonage du snapshot ne les reçoivent jamais. De plus, tout ce qui est enregistré sur le disque finit dans l’image de chaque thread, ce qui rend impossible le stockage de secrets à cet endroit.
schedules/: cron avec une règle de compilation
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.",
)
Il y a un fichier par planification, et le nom du fichier devient le nom du plan. Il faut impérativement spécifier soit prompt, soit input. Seul le format cron à cinq champs est accepté, de sorte qu’une expression basée sur les secondes provoque une erreur de compilation. En l’absence de zone horaire, l’UTC est utilisé.
La contrainte la plus susceptible de causer des problèmes est le fait que les déclarations de planification sont extraites au moment de la compilation et doivent être statiquement serialisables. Aucune variable d’environnement, aucune appel de fonction, aucun **kwargs, aucune valeur calculée n’est autorisée. Les littéraux et les constantes de niveau supérieur sont acceptés. Tout élément dynamique doit être placé dans l’agent, les outils ou le middleware.
Chaque exécution reçoit normalement un thread temporaire qui est supprimé une fois terminée. Les exécutions planifiées qui doivent conserver un état nécessitent plutôt l’option thread={"mode": "persistent", "id": "nightly-memory"}.
channels/ et connectors/
Un canal reçoit les messages qui lancent des exécutions, tandis qu’un connecteur fournit des outils à l’agent. Chacun correspond à un seul fichier :
# 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"],
},
},
)
Le routage suit le nom du fichier. channels/slack.py expose son point de terminaison Events à l’adresse /channels/slack/events, et les outils MCP utilisent le nom du serveur comme préfixe sauf indication contraire, ce qui fait que ce connecteur apparaît sous le nom de langchainDocs__search_docs_by_lang_chain. Les serveurs MCP Stdio ne sont pas une option ; seuls Streamable HTTP et SSE legacy sont disponibles.
identity.py : qui peut appeler l’agent
from managed_deepagents import auth, define_identity
identity = define_identity(auth=auth.langsmith_api_key())
C’est ce que mda init génère en tant que valeur par défaut sécurisée. Les appels sont effectués en envoyant une clé d’espace de travail LangSmith dans l’en-tête x-api-key. Cela détermine si quelqu’un peut appeler l’agent, mais tout le monde partage alors les mêmes threads. Pour assurer la confidentialité par utilisateur, il est nécessaire de passer à Supabase :
identity = define_identity(auth=auth.supabase(project_ref="your-project-ref"))
Les clients envoient ensuite Authorization: Bearer , et MDA vérifie le JWT contre l’endpoint JWKS du projet. La documentation contient un avertissement de migration : l’ajout de cette fonctionnalité à une déploiement existant ne restaure pas les métadonnées du propriétaire sur les threads déjà existants.
Que fait mda deploy
La documentation énumère onze étapes ordonnées. Celes qui sont importantes :
- Vérifie le projet et charge
agent.py. - Recherche la clé LangSmith dans un ordre fixé (
LANGGRAPH_HOST_API_KEY,LANGSMITH_API_KEY,LANGCHAIN_API_KEY) et lit.envavant l’environnement de shell. - Collecte chaque valeur
.envnon réservée et l’envoie en tant que secret de déploiement hébergé. - Le fichier
instructions.mdainsi que le dossierskills/sont téléchargés dans Context Hub. - Le tout est compilé vers
.mda/buildet l’archive générée, dont la taille ne doit pas dépasser 200 MB, est téléchargée. - On attend en vérifiant régulièrement l’état de la révision jusqu’à ce que celui-ci devienne
DEPLOYED. - Les tâches planifiées sont réconciliées en localisant toutes celles créées précédemment, en les supprimant toutes, puis en reconstruisant l’ensemble à partir du répertoire
schedules/actuel.
La septième étape est le moment où comparer cela à Terraform n’est plus une simple métaphore : il s’agit de la correction des écarts, et son fonctionnement est similaire à terraform apply.
Ainsi, tout comme avec Terraform, il existe un paramètre qui permet de l’ignorer discrètement. L’ajout de --no-wait fait en sorte que la ligne de commande lance la compilation à distance et s’arrête avant que l’état ne devienne DEPLOYED, ce qui signifie que l’exécution n’atteint jamais l’étape de réconciliation des plannings. Le nouveau cron n’existe pas, le cron supprimé continue de s’exécuter, et le déploiement indique un succès. Chaque fois qu’un planning change, exécutez mda deploy . sans --no-wait. Une ligne dans le manuel d’utilisation de l’équipe constitue une assurance peu coûteuse.
Sa place dans la pile LangChain
Il y a maintenant quatre couches, et les gens ont tendance à les confondre.
LangChain fournit les éléments de base : modèles, outils, prompts. C’est la fondation.
LangGraph est l’environnement d’exécution qui permet une exécution durable, à état, sous forme de graphe (persistance, streaming, interruptions). Pensez-y comme au moteur.
Deep Agents se situe au-dessus des deux en tant que framework, doté d’un planificateur, d’un système de fichiers, de sous-agents, d’une compression du contexte et de paramètres par défaut prédéfinis.
Managed Deep Agents est l’environnement d’exécution hébergé pour ce framework. Il s’agit du même Agent Server que les clients de LangSmith utilisent déjà en production, mais packagé de manière plus stricte pour les projets Deep Agents.
Une analogie avec une voiture illustre bien cela : LangGraph fournit le moteur et la boîte de vitesses, Deep Agents fournit la voiture, tandis que Managed Deep Agents fournit à la fois la voiture, le garage et quelqu’un pour changer l’huile. Le prix à payer est la perte de la possibilité d’ouvrir le capot. C’est un échange honnête, et la documentation l’indique clairement. Ceux qui ont besoin de chemins personnalisés, de code d’application en complément du graphe, ou d’un contrôle direct de la persistance sont invités à utiliser directement LangSmith Deployment.
Le champ de la mémoire partagée
La version bêta propose un seul espace mémoire, agent : un arbre de lecture/écriture que tous les appels capables d’accéder à la déploiement partagent.
La documentation est inhabituellement directe quant aux conséquences. La mémoire est partagée par tous les appels, et chacun peut y avoir un impact. Il convient donc de ne stocker que des informations que tout le monde peut lire et modifier, et de traiter la mémoire existante comme une entrée non fiable qui ne doit en aucun cas accorder des droits, modifier les permissions des outils ou contourner les validations.
Interprétez cela comme une position en matière de sécurité. AGENTS.md est chargé dans le contexte du système à chaque exécution, de sorte que tout ce que l’appelant A écrit mardi finit par figurer dans le contexte de l’appelant B mercredi, de manière persistante. Cela convient pour un outil interne utilisé par une seule équipe. Mais pour tout système multi-locataires, cela revient à un canal d’injection de commandes accompagné d’une couche de persistance.
Ce qui aggrave encore la situation pour ceux qui se soucient de l’évaluation et de l’observabilité, c’est que la panne ne se manifestera pas dans les évaluations. Les tâches Harbor évaluent l’état de l’espace de travail après une exécution, et elles ne prennent pas en compte un adversaire qui aurait écrit dans la mémoire en temps réel une semaine auparavant.
Le conseil donné dans la documentation est justifié : éviter l’utilisation de la mémoire partagée lorsque les appels ne devraient pas s’influencer mutuellement. Jusqu’à l’arrivée d’un système de gestion de la mémoire par utilisateur, cela représente une véritable limite pour ce qui peut être développé.
Une interface en constante évolution
Avertissement pratique avant de copier tout code : la publication initiale date du 7 août, tandis que la documentation continue de changer. En environ trois semaines, quatre API publiques ont été modifiées, et quiconque développe à partir des exemples fournis dans l’annonce se heurtera à toutes ces modifications.
- Mémoire : l’annonce indique que chaque déploiement commence avec une mémoire dédiée à l’agent, tandis que la documentation décrit la mémoire persistante comme une fonctionnalité optionnelle désactivée par défaut.
- Sandboxes : l’annonce utilise
define_sandbox(provider="langsmith", scope="thread")et suggère un espace de travail partagé au niveau de l’agent; la page de référence mentionneidle_ttl_secondsetdefault_timeoutet précise qu’un sandbox correspond toujours à un thread. - Identité : l’annonce parle de la configuration d’un fournisseur OIDC à l’intérieur de
identity.py, mais la page consacrée à l’identité ne traite que des clés API de LangSmith et de Supabase. - Slack : l’annonce fait appel à
channels.slack(on=[...]), tandis que le guide Slack ne comporte pas d’argumentonet place les abonnements aux événements dans le manifeste de l’application Slack.
La documentation n’est pas non plus toujours cohérente avec elle-même. Une page nomme la commande mda channel init slack tandis qu’une autre indique mda channel add slack . ; le paramètre --configure-slack pour mda deploy . est décrit dans le guide Slack mais fait défaut dans le tableau de référence de la CLI.
Cela ne rend pas le produit médiocre. Cela signifie simplement qu’il s’agit d’une version bêta d’un outil déclaratif, où l’interface est la seule chose que personne ne devrait devoir deviner. Lorsque les documents et les tableaux sont en désaccord, mda --help est la solution.
Quand c’est utile et quand ce n’est pas le cas
Managed Deep Agents est pertinent dans les cas suivants :
- vous développez déjà sur l’infrastructure de Deep Agents et celle-ci constitue un goulot d’étranglement
- l’agent a besoin de threads durables, de tâches planifiées ou d’une interface Slack
- les prompts et les compétences doivent pouvoir être modifiés sans avoir à redéployer
Choisissez LangSmith Deployment lui-même, ou hébergez vous-même l’outil open source, dans les cas suivants :
- Votre propre backend doit appeler l’agent. La version bêta est basée sur la ligne de commande en attendant la finalisation de l’API, et reprendre une exécution interrompue de manière programmée signifie devoir demander l’aide de votre contact chez LangChain, conformément aux documents. Cela bloque complètement ce cas d’usage.
- Les appels doivent être isolés les uns des mémoires des autres.
- Des routes personnalisées ou un contrôle direct de la persistance sont nécessaires.
- Les données doivent rester en dehors des États-Unis.
- Slack fonctionne sur plusieurs réplicas. La déduplication des événements est actuellement locale au processus, ce qui signifie qu’une tentative de réexécution depuis Slack peut déclencher l’agent deux fois ; de plus, les outils accessibles depuis un canal doivent être idempotents s’ils ont des effets secondaires.
Essayer
Installer et créer la structure de base :
uv tool install managed-deepagents
mda init test-agent && cd test-agent
Ensuite, mettez les clés dans .env :
LANGSMITH_API_KEY=<your-key>
OPENAI_API_KEY=<your-key>
Avant d’écrire quoi que ce soit, exécutez ls sur le contenu généré. Cinq minutes passées dans ce répertoire en apprennent davantage sur le modèle du produit que toute annonce ne le pourrait.
Ensuite, uv sync && mda dev . crée le projet, met en place une version locale de Context Hub (gérant les instructions, les compétences et la mémoire) et lance LangSmith Studio dans une nouvelle fenêtre du navigateur. Il ne recharge pas en temps réel les fichiers du projet, il faut donc s’arrêter et relancer après avoir apporté des modifications. Le guide de démarrage officiel se trouve dans la documentation Python de LangSmith, sous la section Gestion des agents profonds.
Les équipes qui utilisent déjà des Deep Agents et qui configurent elles-mêmes leur déploiement devraient y arriver en une après-midi. Le modèle de répertoire est une bonne idée, et les lacunes de la version bêta peuvent être comblées une fois qu’elles sont connues.
Lectures complémentaires
- Pourquoi les agents à long terme ont besoin d’un système de gestion : comment les agents profonds gèrent l’état et le contexte — Une analyse approfondie des agents profonds : dégradation du contexte, les quatre piliers, le middleware, les profils de gestion, les backends de système de fichiers, les sous-agents isolés, les échecs en cas de situations extrêmes et les alternatives.
- Créer un agent de planification dans LangGraph : planifier, exécuter, réplanifier, rapporter — Un agent de planification LangGraph à quatre nœuds pour la recherche financière : plans structurés, un registre d’outils conscient du nom d’espace, des limites de réplanification et un exemple d’exécution traçée.