Tutoriel de prise en main de Deep Agents

Deep Agents est un framework de développement d'agents prêt à l'emploi, officiellement lancé par LangChain, conçu spécifiquement pour les tâches complexes, les processus de longue durée, la planification multi-étapes et les scénarios de collaboration multi-agents.

Comparé aux Agents traditionnels qui obligent les développeurs à assembler manuellement des composants tels que Prompt, Tool, Memory et Workflow, Deep Agents intègre déjà des capacités fondamentales telles que la planification des tâches, le système de fichiers, l'orchestration de sous-agents, la compression du contexte et la gestion de la mémoire, ce qui permet aux développeurs de se concentrer davantage sur la logique métier plutôt que sur la configuration de l'architecture sous-jacente.

Ce tutoriel est conçu pour les développeurs sans expérience préalable. Il vous guide pas à pas, de l'installation et de la configuration jusqu'aux mécanismes de fonctionnement essentiels de Deep Agents, et utilise l'API DeepSeek pour construire un projet d'Agent IA réel et exécutable.

Que sont les Deep Agents ?

Les Deep Agents peuvent être compris comme un framework d'Agent avancé (Agent Harness) conçu pour les environnements de production.

Il est officiellement défini comme : un framework d'exécution d'Agent avec une infrastructure complète, et non comme une simple boucle d'appel LLM + Tool.

Après l'installation, vous pouvez directement obtenir les capacités suivantes sans développement supplémentaire :

Planification automatique des tâches (Planning)
Lecture/écriture du système de fichiers (Filesystem)
Collaboration de sous-agents (Sub Agents)
Compression et gestion du contexte (Context Management)
Exécution de tâches de longue durée (Long Running Tasks)
Approbation humaine (Human-in-the-Loop)
Mémoire persistante (Memory)
Sortie en streaming (Streaming)

Objectifs de conception des Deep Agents

Les Agents traditionnels utilisent généralement le modèle ReAct : entrée utilisateur → raisonnement LLM → appel d'outil → raisonnement LLM → appel d'outil → résultat en sortie.

Lorsque l'échelle de la tâche est petite, ce modèle fonctionne bien. Mais à mesure que la complexité des tâches augmente (par exemple, générer automatiquement des rapports d'étude de marché, analyser les états financiers de plusieurs entreprises ou écrire une base de code de projet complète), les problèmes suivants apparaissent progressivement :

La fenêtre de contexte s'élargit rapidement et dépasse les limites du modèle
] Des chaînes de raisonnement trop longues entraînent une dégradation des performances
L'Agent oublie facilement le travail déjà effectué
Manque d'isolation entre plusieurs tâches, ce qui provoque des interférences mutuelles
La logique d'appel d'outils devient de plus en plus complexe et difficile à maintenir

L’objectif principal de Deep Agents est de résoudre ces problèmes d’ingénierie dans des scénarios de tâches complexes.

Relation avec LangChain et LangGraph

] De nombreux débutants confondent facilement le positionnement de ces trois projets ; ils se situent en réalité à des niveaux d’abstraction différents.

Framework	Positionnement hiérarchique	Responsabilités principales	Scénarios applicables
LangChain	Couche de composants de base.	Fournit des composants de base d’IA tels que Model, Prompt, Tool, Retriever et Output Parser	Capacité fondamentale pour créer des Agents individuels ou des applications d’IA
LangGraph	Couche d’exécution	Fournit la gestion d’état, l’orchestration de workflows, les nœuds et arêtes, ainsi que des capacités de persistance Checkpoint	Pour les scénarios complexes nécessitant des structures de graphe personnalisées et des flux d’exécution
Deep Agents	Couche de framework applicatif.	Encapsule des capacités de niveau production au-dessus de LangGraph, telles que la planification, le système de fichiers, les sous-agents, la mémoire et la compression du contexte	Construisez rapidement des agents complexes à plusieurs étapes sans concevoir l'architecture à partir de zéro

Les trois ne sont pas mutuellement exclusifs mais peuvent être utilisés ensemble : LangChain fournit des blocs de construction, LangGraph est le framework d'ingénierie qui organise les blocs, et Deep Agents est une couche d'application de haut niveau prête à l'emploi par-dessus. N'importe quel LangGraphCompiledStateGraphpeut être passé à Deep Agents comme sous-agent, et les trois couches peuvent être combinées de manière flexible.

Aperçu des compétences essentielles

Deep Agents est livré avec les middlewares intégrés suivants, prêts à l'emploi sans configuration supplémentaire :

Capacité	Description	Composants principaux
Planification des tâches	Utilisez les`write_todos`outils intégrés pour décomposer des tâches complexes en étapes ordonnées	TodoListMiddleware
Système de fichiers virtuel	Lire et écrire des fichiers, décharger les sorties volumineuses d’outils vers le disque, économisant ainsi la fenêtre de contexte	FilesystemMiddleware
Sous-agent	Déléguer des sous-tâches à des sous-agents dédiés disposant de fenêtres de contexte indépendantes	SubAgentMiddleware
Compression du contexte	Résumer automatiquement les messages historiques afin d’éviter de dépasser la limite de contexte du modèle	SummarizationMiddleware
Humain dans la boucle	Mettre en pause avant les appels d’outils critiques pour attendre l’approbation humaine	HumanInTheLoopMiddleware
Mémoire à long terme	Mémoire persistante entre les sessions basée sur LangGraph Store	MemoryMiddleware
Compétences	Charger des connaissances métier réutilisables et des ensembles d'instructions à la demande	SkillsMiddleware

Installer

Deep Agents est publié sur PyPI sous le nom de paquetdeepagents。

Il est recommandé d'utiliseruv pour l'installation, ce qui est plus rapide ; vous pouvez également utiliser le traditionnelpip。

Installer avec uv (recommandé)

uv init
uv add deepagents tavily-python
uv sync

Installer avec pip.

pip install deepagents tavily-python

Installer avec l'API DeepSeek

DeepSeek est compatible avec l'interface OpenAI, vous devez donc aussi installerlangchain-openai。

pip install deepagents langchain-openai

La seule exigence de Deep Agents concernant le modèle est que le modèle prenne en chargel'appel d'outils. Les séries DeepSeek V3 et DeepSeek R1 le prennent toutes les deux en charge, vous pouvez donc l'utiliser en toute confiance.

Instructions de configuration

create_deep_agentC'est la fonction principale pour créer un Agent, qui prend en charge la configuration des paramètres suivants.

Parameters	Type	Requis	Description	Valeur par défaut
`model`	str ou instance de modèle	non	Chaîne de modèle, au format`provider:model-name`, ou transmettez directement un objet modèle initialisé	`anthropic:claude-sonnet-4-6`
`tools`	liste	non	Liste de fonctions d’outil personnalisées ou d’objets Tool de LangChain	Aucune
`system_prompt`	str ou SystemMessage	non	Prompt système personnalisé, utilisé pour définir le rôle et le comportement de l’Agent	Aucune
`backend`	BackendProtocol	non	Backend de système de fichiers virtuel, détermine l’emplacement de stockage des fichiers	StateBackend
`subagents`	liste	non	Liste des définitions de sous-agents, utilisée pour la délégation de tâches	Aucune
`memory`	liste	non	Liste des chemins de fichiers AGENTS.md chargés au démarrage	Aucune
`skills`	liste	non	Liste des chemins de répertoires Skills chargés à la demande	Aucune
`permissions`	liste	non	Règles de contrôle des autorisations d'accès au niveau des chemins du système de fichiers	Aucune
`interrupt_on`	dict	non	Spécifie quels appels d'outils nécessitent une approbation manuelle, doit être utilisé avec checkpointer	Aucune
`checkpointer`	Checkpointer	non	Point de contrôle de persistance de l'état, doit être défini pour les conversations multi-tours ou HITL	Aucune
`store`	BaseStore	non	Backend de stockage à long terme inter-sessions	Aucune
`response_format`	ResponseFormat	non	Définition du schéma pour la sortie structurée	Aucune
`middleware`	liste	non	Middleware personnalisé ajouté à la fin de la pile de middleware par défaut	()
`debug`	bool	non	Activer le mode débogage, produire des journaux détaillés	False

Comparaison des backends de système de fichiers

Deep Agents fournit plusieurs backends pour contrôler la façon dont l'Agent lit et écrit les fichiers.

Backend	Emplacement de stockage	Persistance entre les sessions	Scénario applicable
StateBackend	Dans l'état du graphe LangGraph	Non (valide au sein du même thread)	Par défaut, pour le développement local et les scénarios simples
FilesystemBackend	Disque local	Oui	Nécessite une lecture/écriture réelle de fichiers locaux, à utiliser avec prudence
StoreBackend	LangGraph Store	Oui	Persistance de conversation multi-tours, partage entre Threads
LocalShellBackend	Disque local + Shell	Oui	Nécessite l'exécution de commandes Shell, uniquement dans des environnements de confiance
CompositeBackend	Routes vers plusieurs backends	Dépend du backend enfant	Contrôle granulaire des politiques de stockage pour différents répertoires

Pour les débutants, utiliser simplement leStateBackendpar défaut suffit.FilesystemBackendetLocalShellBackendPermettra à l'Agent d'exploiter directement votre système de fichiers local ; configurez rigoureusement les permissions avant utilisation.

Démarrage rapide

Cette section montre comment créer un Deep Agent exécutable avec un minimum de code.

Configurer la clé API DeepSeek

DeepSeek est compatible avec le format d'API d'OpenAI, et il faut définir à la fois la clé API et l'URL de base.

export OPENAI_API_KEY="sk-your-deepseek-api-key"
export OPENAI_BASE_URL="https://api.deepseek.com"
export TAVILY_API_KEY="your-tavily-api-key"

La clé API de DeepSeek peut être demandée surplatform.deepseek.com. Définissez la variable d'environnementOPENAI_BASE_URLpour pointer vers l'adresse de DeepSeek, et LangChain transmettra automatiquement les requêtes vers celle-ci.

TAVILY_API_KEY doit être demandée sur le site officiel de Tavilyhttps://www.tavily.com/ pour générer une clé au format tvly-xxxxxxxx.

Exemple le plus simple : agent Hello World

Créez un agent avec un outil personnalisé et envoyez le premier message à DeepSeek.

exemple

# Chemin du fichier : hello_agent.py

import os
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

# Utilisez ChatOpenAI et définissez base_url sur DeepSeek ; c'est la façon la plus directe de se connecter
model = ChatOpenAI(
model="deepseek-v4-flash", # Requis : nom du modèle
api_key=os.environ["OPENAI_API_KEY"], # Requis : clé API DeepSeek
base_url="https://api.deepseek.com", # Requis : point de terminaison compatible OpenAI de DeepSeek
)

# Définissez un outil personnalisé simple ; la docstring de la fonction sert de description de l'outil
def get_weather(city: str) -> str:
"""Interroger la météo pour une ville spécifiée."""
# Dans un projet réel, vous appelleriez une véritable API météo ici
return f"{city} est ensoleillé aujourd'hui, 25°C, idéal pour sortir."

# Créer un Agent, en passant l'instance du modèle et la liste des outils
agent = create_deep_agent(
model=model,
tools=[get_weather],
system_prompt="Vous êtes un assistant sympathique qui peut consulter des informations météorologiques.",
)

# Appeler l'Agent ; messages accepte le format de message de style OpenAI
result = agent.invoke({
"messages": [{"role": "user", "content": "Quel temps fait-il à Pékin aujourd'hui ?"}]
})

# Afficher la réponse finale de l'Agent
print(result["messages"][-1].content)

# 运行脚本
python hello_agent.py

Sortie :

Pékin est **ensoleillé** aujourd'hui, avec une température de **25°C**, très approprié pour sortir. ☀️

Remarque : l'Agent renvoie une liste complète de messages (messages), et la réponse finale se trouve à la fin de la liste, c'est-à-dire,result["messages"][-1].content。

Utilisation détaillée

Cette section utilise plusieurs scénarios réels pour démontrer progressivement les capacités principales des Deep Agents.

Utilisez DeepSeek R1 pour les tâches de raisonnement.

DeepSeek R1 est un modèle amélioré pour le raisonnement, adapté aux tâches nécessitant une analyse complexe.

Exemple

# Chemin du fichier : reasoning_agent.py

import os
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

# DeepSeek R1 : conçu pour le raisonnement complexe
model = ChatOpenAI(
model="deepseek-v4-pro", # Modèle de réflexion DeepSeek
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
)

# Exemple d'outil de calcul mathématique
def calculate(expression: str) -> str:
"""Évaluer en toute sécurité une expression mathématique et renvoyer le résultat du calcul."""
try:
# Remarque : Une bibliothèque d'évaluation d'expressions plus sûre devrait être utilisée dans les environnements de production.
result = eval(expression, {"__builtins__": {}}, {})
return f"Résultat du calcul : {expression} = {result}"
except Exception as e:
return f"Erreur de calcul : {str(e)}"

agent = create_deep_agent(
model=model,
tools=[calculate],
system_prompt="Vous êtes un expert en analyse mathématique, compétent pour décomposer des problèmes complexes et les résoudre étape par étape.",
)

result = agent.invoke({
"messages": [{"role": "user", "content": "Calculez la somme de tous les nombres impairs de 1 à 100, et vérifiez le résultat."}]
})

print(result["messages"][-1].content)

Sortie d'exécution :

再换一种方法做交叉验证：

- 1 到 100 所有整数之和：\( \frac{100 \times 101}{2} = 5050 \)
- 1 到 100 的偶数之和：\( 2 + 4 + \cdots + 100 = 2 \times \frac{50 \times 51}{2} = 2550 \)
- 奇数之和：\( 5050 - 2550 = 2500 \)

两种方法结果一致。

---

**结论**：1 到 100 的所有奇数之和为 **2500**。

**推导回顾**：
- 奇数序列首项 1，末项 99，项数 \( \frac{99-1}{2}+1 = 50 \)
- 等差数列求和：\( S = \frac{n(a_1 + a_n)}{2} = \frac{50 \times (1+99)}{2} = 2500 \)

Prompt système personnalisé

Viasystem_promptLes paramètres définissent le rôle de l'agent, les objectifs de la tâche et les normes comportementales.

Exemple

# Chemin du fichier : custom_prompt_agent.py

import os
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
model="deepseek-v4-flash",
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
)

# Prompt système personnalisé : Définir l'identité, les responsabilités et les directives comportementales de l'Agent.
code_review_instructions = """Vous êtes un ingénieur Python senior, spécialisé dans la revue de code.

Vos responsabilités :
- Vérifier la lisibilité, la performance et la sécurité du code
- Signaler les bogues potentiels et les suggestions d'amélioration
- Fournir des exemples de modification spécifiques

Format de réponse :
1. Note globale (1-10)
2. Liste des principaux problèmes
3. Suggestions d'amélioration spécifiques (avec extraits de code modifiés)
"""

agent = create_deep_agent(
model=model,
system_prompt=code_review_instructions,
)

# Soumettre un extrait de code pour revue
code_to_review = """
def find_user(users, name):
for i in range(len(users)):
if users[i]['name'] == name:
return users[i]
return None
"""

result = agent.invoke({
"messages": [{"role": "user", "content": f"Veuillez examiner le code suivant :\n```python{code_to_review}```"}]
})

print(result["messages"][-1].content)

Sortie en streaming

Pour les scénarios nécessitant un affichage de progression en temps réel, vous pouvez utiliserstreamLa méthode reçoit la sortie de l'Agent fragment par fragment.

Exemple

# Chemin du fichier : streaming_agent.py

import os
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
model="deepseek-v4-flash",
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
)

agent = create_deep_agent(
model=model,
system_prompt="Vous êtes un expert en rédaction technique, spécialisé dans la rédaction d'une documentation technique claire et compréhensible.",
)

# La méthode stream renvoie un générateur, produisant un chunk d'événement à la fois.
for chunk in agent.stream({
"messages": [{"role": "user", "content": "Écrivez une brève introduction aux décorateurs Python."}]
}):
# chunk est un dictionnaire contenant des messages incrémentaux
if "messages" in chunk:
for msg in chunk["messages"]:
if hasattr(msg, "content") and msg.content:
print(msg.content, end="", flush=True)

print() # Saut de ligne final

Dialogue multi-tours (avec points de contrôle)

AvecMemorySaverpoints de contrôle, vous pouvez obtenir un dialogue avec état au fil des tours.

exemple

# Chemin du fichier : multi_turn_agent.py

import os
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import MemorySaver # Point de contrôle en mémoire, les données seront perdues après redémarrage.

model = ChatOpenAI(
model="deepseek-v4-flash",
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
)

# MemorySaver enregistre l'état de la conversation en mémoire, lequel est perdu à la fin du processus.
# Il est recommandé d'utiliser SqliteSaver ou PostgresSaver en production
checkpointer = MemorySaver()

agent = create_deep_agent(
model=model,
system_prompt="Vous êtes un assistant de programmation utile.",
checkpointer=checkpointer, # Doit être transmis, sinon les conversations multi-tours ne peuvent pas se souvenir du contexte
)

# thread_id est l'identifiant unique d'un fil de conversation ; le même thread_id partage le même contexte
config = {"configurable": {"thread_id": "example-session-001"}}

# Premier tour
result1 = agent.invoke(
{"messages": [{"role": "user", "content": "Je m'appelle EXAMPLE et j'apprends Python."}]},
config=config,
)
print("Réponse du premier tour :", result1["messages"][-1].content)

# Deuxième tour : L'Agent peut se souvenir des informations du tour précédent
result2 = agent.invoke(
{"messages": [{"role": "user", "content": "Quel est mon nom ? Qu'est-ce que j'apprends ?"}]},
config=config,
)
print("Réponse du deuxième tour :", result2["messages"][-1].content)

First reply:你好，EXAMPLE！很高兴认识你，Python 是一门非常适合初学者的语言...
Second reply:你叫 EXAMPLE，你正在学习 Python！...

Le rôle de thread_id :Le mêmethread_idTous les appels sous celui-ci partagent le même historique de conversation. Différentthread_idsont isolés les uns des autres et n'interfèrent pas. Vous pouvez le considérer comme un "numéro de salle de conversation".

Démo complète : Agent de rapport de recherche

Cette section présente un Agent complet de rapport de recherche, utilisant DeepSeek V3 comme modèle principal, intégrant des outils de recherche personnalisés et démontrant l'utilisation de sous-agents.

Description du scénario

Nous allons créer un Agent qui reçoit le sujet de recherche de l'utilisateur, décompose automatiquement les tâches, appelle des outils de recherche pour collecter des informations, et produit enfin un rapport structuré.

Exemple

# Chemin du fichier : research_agent_demo.py
# Démo : création d'un Agent de rapport de recherche avec l'API DeepSeek + Deep Agents
# Installation des dépendances : pip install deepagents langchain-openai requests

import os
import json
from tavily import TavilyClient
from typing import Literal
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import MemorySaver

# ──────────────────────────────────────────
# 1. Initialiser le modèle DeepSeek
# ──────────────────────────────────────────
main_model = ChatOpenAI(
model="deepseek-v4-flash", # Fortes capacités globales, adaptées à la planification et à la rédaction
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
temperature=0.3, # Facultatif : réduire l'aléatoire pour rendre le rapport plus rigoureux
)
# Initialiser le client Tavily (pour les outils de recherche)
tavily_client = TavilyClient(
api_key=os.environ["TAVILY_API_KEY"]
)
# ──────────────────────────────────────────
# 2. Définir l'outil de recherche Tavily
# ──────────────────────────────────────────
def web_search(
query: str,
max_results: int = 5,
) -> str:
"""Utiliser Tavily pour rechercher des informations sur Internet"""

try:
response = tavily_client.search(
query=query,
max_results=max_results,
search_depth="advanced",
include_answer=True,
include_raw_content=False,
)

lines = []

# Réponse résumée par IA
if response.get("answer"):
lines.append(f"Résumé : {response['answer']}\n")

# Résultats de recherche
for idx, item in enumerate(response.get("results", []), start=1):
lines.append(
f"""
[{idx}] {item.get('title', '')}
URL : {item.get('url', '')}
Contenu : {item.get('content', '')}
""".strip()
)

return "\n\n".join(lines)

def format_report(title: str, sections: str) -> str:
"""Organisez le contenu de recherche dans un rapport au format Markdown.

Arguments :
title : Titre du rapport
sections : Contenu de chaque section, représenté sous forme de chaîne JSON, format : {"Nom du chapitre": "Contenu"}
"""
try:
data = json.loads(sections)
lines = [f"# {title}\n"]
for section_name, content in data.items():
lines.append(f"## {section_name}\n")
lines.append(f"{content}\n")
return "\n".join(lines)
except Exception as e:
return fErreur de formatage : {str(e)}

# ──────────────────────────────────────────
# 3. Définir un sous-agent dédié (expert en intégration d'informations)
# Le sous-agent dispose d'une fenêtre de contexte indépendante, évitant l'engorgement du contexte de l'agent principal
# ──────────────────────────────────────────
report_writer_subagent = {
"name": "report-writer", # Requis : nom unique du sous-agent
"description": Un assistant professionnel de rédaction de rapports, chargé d'intégrer les supports de recherche dans des rapports clairement structurés., # Requis : l'Agent principal utilise cette description pour décider quand déléguer des tâches
"system_prompt": Vous êtes un expert professionnel en rédaction de rapports. Après avoir reçu les supports de recherche, veuillez les organiser en un rapport composé de trois parties : résumé, contenu principal et conclusion, avec un langage clair et concis.,
"tools": [format_report], # Optionnel : outils spécifiques au sous-agent
# Si aucun modèle n'est spécifié, hériter du modèle de l'Agent principal.
}

# ──────────────────────────────────────────
# 4. Configurer et créer un Deep Agent
# ──────────────────────────────────────────
checkpointer = MemorySaver()

research_instructions = Vous êtes un assistant de recherche professionnel, compétent en recherche approfondie et en rédaction de rapports.

Lorsque l'utilisateur fournit un sujet de recherche, vous devez :
1. Utilisez l'outil web_search pour rechercher des informations pertinentes (recherchez au moins 2-3 fois, en couvrant différents angles).
2. Organiser et résumer les données collectées
3. Déléguer au sous-agent rédacteur de rapport la rédaction du rapport final
4. Afficher le rapport complet à l'utilisateur.

Remarque : Utilisez des mots-clés différents pour chaque recherche afin d'obtenir des informations plus complètes.
"""

agent = create_deep_agent(
model=main_model,
tools=[web_search], # Outils disponibles pour l'agent principal
system_prompt=research_instructions,
subagents=[report_writer_subagent], # Enregistrer le sous-agent
checkpointer=checkpointer,
)

# ──────────────────────────────────────────
# 5. Exécuter l'agent
# ──────────────────────────────────────────
print("Recherche en cours, veuillez patienter...\n")

result = agent.invoke(
{
"messages": [{
"role": "user",
"content": Veuillez m'aider à rechercher ce qu'est LangGraph et ses principaux scénarios d'application.
}]
},
config={"configurable": {"thread_id": "example-research-001"}}
)

print("=" * 60)
print("Rapport de recherche")
print("=" * 60)
print(result["messages"][-1].content)

正在研究中，请稍候...

============================================================
研究报告
============================================================
# LangGraph 研究报告

## 摘要
LangGraph 是 LangChain 团队推出的一个用于构建有状态、多角色 LLM 应用的框架...

## 主要内容
### 核心概念
LangGraph 将 Agent 的执行流程建模为一张有向图...

### 主要应用场景
1. 多步骤推理任务
2. 人机协作（Human-in-the-loop）工作流
3. 多 Agent 协作系统
...

## 结论
LangGraph 是构建生产级 Agent 应用的重要工具...

Exemple de human-in-the-loop

Pour les opérations sensibles (par exemple, la suppression de fichiers, l'envoi d'e-mails), l'Agent peut être configuré pour se mettre en pause et attendre une confirmation manuelle avant l'exécution.

Exemple

# Chemin du fichier : hitl_agent.py
# Human-in-the-loop : Permettre à l'Agent de demander une approbation humaine avant d'exécuter des opérations dangereuses

import os
from langchain.tools import tool
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import MemorySaver
from langgraph.types import Command

model = ChatOpenAI(
model="deepseek-v4-flash",
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
)

# Utilisez le décorateur @tool pour définir des outils (nécessite le package langchain)
@tool
def delete_file(path: str) -> str:
"""Supprime le fichier au chemin spécifié."""
# Dans les projets réels, os.remove(path) est appelé ici.
return f"Le fichier {path} a été supprimé."

@tool
def read_file(path: str) -> str:
"""Lit le contenu du fichier au chemin spécifié."""
return fContenu du fichier {path} : (contenu d'exemple)

# interrupt_on configure quels outils nécessitent une approbation manuelle
# True signifie autoriser : approbation, modification des paramètres, rejet, envoi de réponses personnalisées
# False signifie qu'aucune approbation n'est requise
# dict permet un contrôle granulaire des types d'opérations autorisés
checkpointer = MemorySaver() # HITL doit être utilisé avec un checkpointer

agent = create_deep_agent(
model=model,
tools=[delete_file, read_file],
interrupt_on={
"delete_file": True, # Opération de suppression : nécessite un processus d'approbation complet
"read_file": False, # Opération de lecture : aucune approbation requise
},
checkpointer=checkpointer,
)

config = {"configurable": {"thread_id": "example-hitl-001"}}

# Première invocation : l'Agent se met en pause lors de l'exécution de delete_file
print("Démarrage de l'Agent...")
result = agent.invoke(
{"messages": [{"role": "user", "content": "Veuillez supprimer le fichier /tmp/test.txt."}]},
config=config,
)

# Vérifier s'il y a une interruption d'approbation en attente
for msg in result.get("messages", []):
print(fMessage de l'Agent : {msg.content if hasattr(msg, 'content') else msg})

# Reprendre l'exécution : transmettre la décision d'approbation
# "approve" signifie approuver l'exécution de l'outil
# "reject" signifie rejeter ; l'Agent n'exécutera pas l'outil
print("\n"Approbation de l'utilisateur : approuver l'opération de suppression")
final_result = agent.invoke(
Command(resume={"decision": "approve"}),
config=config,
)
print("Résultat final :", final_result["messages"][-1].content)

Comment fonctionne interrupt_on :Lorsque l'Agent est sur le point d'appeler un outil marqué, LangGraph déclenche uneinterrupt, l'exécution de l'Agent se met en pause. Vous pouvezCommand(resume=...)transmettre le résultat d'approbation pour reprendre l'exécution.

Questions fréquentes

Voici les questions et considérations courantes lors de l'utilisation de Deep Agents.

Comment choisir entre utiliser Deep Agents ou utiliser directement LangChain/LangGraph ?

Scénario	Choix recommandé	Raison
Besoin de planification, de lecture/écriture de fichiers, de sous-agents, de compression du contexte	Deep Agents	Ces capacités sont prêtes à l'emploi, pas besoin de les assembler vous-même
Besoin d'un enrobage léger, juste la boucle d'appel d'outil	LangChain create_agent	Plus léger que Deep Agents, sans middleware intégré
Besoin d'une structure de graphe personnalisée, la boucle n'est pas une boucle d'appel d'outil standard	LangGraph	Personnaliser entièrement la logique des nœuds et des arêtes du graphe
LangGraph CompiledStateGraph comme sous-agent	Utilisation mixte	Vous pouvez passer un graphe personnalisé comme sous-agent à Deep Agents

Recommandations pour la sélection du modèle DeepSeek

Modèle	chaîne de modèle	Fonctionnalités	Scénarios applicables
deepseek-v4-flash	`deepseek-v4-flash`	Capacités complètes solides, grande rapidité, prix bas	Tâches générales, conversation quotidienne, rédaction
deepseek-v4-pro	`deepseek-v4-pro`	Forte capacité de raisonnement, chaîne de pensée intégrée	Mathématiques, code, raisonnement logique complexe

Que faire si l'Agent appelle un outil et qu'aucun résultat n'est renvoyé ?

La valeur de retour d'une fonction d'outil doit être une chaîne ou un type pouvant être sérialisé en chaîne.

Si un outil renvoie un objet complexe (tel qu'un dict ou une list), il est recommandé d'utiliserjson.dumps(result, ensure_ascii=False)pour le convertir avant de le renvoyer.

Comment l'Agent peut-il n'accéder qu'à des fichiers spécifiques à la fois ?

Utiliserpermissionsparamètres pour configurer les autorisations d'accès au système de fichiers, qui permettent de contrôler précisément l'Agent afin qu'il ne lise et n'écrive que dans les chemins spécifiés.

exemple

from deepagents import create_deep_agent
from deepagents.permissions import FilesystemPermission
from langchain_openai import ChatOpenAI
import os

model = ChatOpenAI(
model="deepseek-v4-flash",
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
)

agent = create_deep_agent(
model=model,
permissions=[
FilesystemPermission(path="/workspace/", read=True, write=True), # Autoriser la lecture et l'écriture du répertoire de travail
FilesystemPermission(path="/secrets/", read=False, write=False), # Interdire l'accès aux répertoires sensibles
],
)

Comment le prompt système par défaut de l'Agent et mon prompt sont-ils fusionnés ?

Le prompt de Deep Agents est assemblé à partir de quatre parties dans un ordre fixe :

USER(votre system_prompt) →BASE(prompt par défaut du SDK) →SUFFIX(ajustements spécifiques au fournisseur du modèle)

Votre prompt est toujours tout au début et ne sera pas écrasé. Le prompt par défaut du SDK indique au modèle comment utiliser la planification et les outils de fichiers, donc dans la plupart des cas vous n'avez pas besoin de le réécrire vous-même.

Erreurs que les débutants ont tendance à commettre.

Erreur courante 1 :Oublier de passercheckpointer. Lors de l'utilisation de Human-in-the-loop (interrupt_on) ou de conversations multi-tours, vousdevezpasser un checkpointer, sinon l'état ne peut pas être sauvegardé et l'Agent signalera une erreur.

Erreur courante 2 :Les fonctions d'outil n'ont pas de docstrings. Deep Agents utilise la docstring de la fonction comme description de l'outil pour indiquer au modèle quand appeler l'outil. Pour un outil sans docstring, le modèle peut ne pas savoir quand l'appeler, voire refuser de l'utiliser.

Erreur courante 3 :Modifier directementselfles attributs dans le middleware. Les sous-agents et les opérations concurrentes de l'Agent peuvent s'exécuter simultanément, et la modification directe des attributs d'instance de middleware peut entraîner des conditions de concurrence. Lorsque l'état doit être sauvegardé, il doit être transmis via l'état du graphe plutôt que par des variables d'instance de middleware.

Plus d'informations

Pour plus de contenu, consultez la documentation suivante :

Name	Adresse
Documentation officielle de Deep Agents (page d'accueil)	https://docs.langchain.com/deepagents
Dépôt GitHub Deep Agents (code source)	https://github.com/langchain-ai/deepagents
Documentation Python Deep Agents (guide de développement Python)	https://docs.langchain.com/oss/python/deepagents/overview
Documentation JavaScript Deep Agents (guide de développement JS/TS)	https://docs.langchain.com/oss/javascript/deepagents/overview
Manuel de référence de l'API Python Deep Agents	https://reference.langchain.com/python/deepagents/deepagents
Référence de l'API JavaScript Deep Agents	https://reference.langchain.com/javascript/modules/deepagents.html
Documentation officielle LangChain (bibliothèque de composants de base)	https://docs.langchain.com/langchain
Documentation officielle de LangGraph (environnement d'exécution d'agent)	https://docs.langchain.com/langgraph
Dépôt GitHub LangGraph (code source)	https://github.com/langchain-ai/langgraph
Dépôt GitHub LangChain (code source)	https://github.com/langchain-ai/langchain
Site officiel de LangSmith (débogage et surveillance d'agents)	https://www.langchain.com/langsmith
Documentation officielle de LangSmith	https://docs.smith.langchain.com
Site officiel de Tavily (outil de recherche)	https://tavily.com
Documentation de l'API Tavily	https://docs.tavily.com
Plateforme ouverte DeepSeek (services de modèles)	https://platform.deepseek.com
Documentation de l'API DeepSeek	https://api-docs.deepseek.com

Autres extensions

Outils pour agents intelligents

Implémentation d’agents intelligents en Python

Tutoriel de prise en main de Deep Agents

Que sont les Deep Agents ?

Objectifs de conception des Deep Agents

Relation avec LangChain et LangGraph

Aperçu des compétences essentielles

Installer

Installer avec uv (recommandé)

Installer avec pip.

Installer avec l'API DeepSeek

Instructions de configuration

Comparaison des backends de système de fichiers

Démarrage rapide

Configurer la clé API DeepSeek

Exemple le plus simple : agent Hello World

exemple

Utilisation détaillée

Utilisez DeepSeek R1 pour les tâches de raisonnement.

Exemple

Prompt système personnalisé

Exemple

Sortie en streaming

Exemple

Dialogue multi-tours (avec points de contrôle)

exemple

Démo complète : Agent de rapport de recherche

Description du scénario

Exemple

Exemple de human-in-the-loop

Exemple

Questions fréquentes

Comment choisir entre utiliser Deep Agents ou utiliser directement LangChain/LangGraph ?

Recommandations pour la sélection du modèle DeepSeek

Que faire si l'Agent appelle un outil et qu'aucun résultat n'est renvoyé ?

Comment l'Agent peut-il n'accéder qu'à des fichiers spécifiques à la fois ?

exemple

Comment le prompt système par défaut de l'Agent et mon prompt sont-ils fusionnés ?

Erreurs que les débutants ont tendance à commettre.

Plus d'informations