ecosystem-primer

<overview> LangChain Inc. maintient trois outils open-source structurés en couches pour construire des agents, plus LangSmith pour l'observabilité. La pile, de haut en bas :

• Deep Agents (couche supérieure, harnais) — toolkit tout-en-un construit sur LangChain + LangGraph. Inclut nativement la planification, la gestion de fichiers, la création de sous-agents et la mémoire.
• LangGraph (couche intermédiaire, runtime) — orchestration bas-niveau pour l'exécution durable, les flux de contrôle personnalisés et les workflows avec état. Les agents LangChain s'exécutent sur LangGraph.
• LangChain (couche inférieure, framework) — abstractions pour les modèles, les outils et la boucle agent. Agnostique des fournisseurs, le plus facile pour commencer.
• LangSmith (transversal) — plateforme d'observabilité et d'évaluation. Agnostique du framework ; toujours recommandé avec l'un quelconque des outils ci-dessus.

Les couches supérieures dépendent des inférieures, mais tu n'as pas besoin d'utiliser directement les couches inférieures. Deep Agents te donne l'exécution durable de LangGraph sans écrire de code graphe. LangChain te donne les modèles et les outils sans gérer les arêtes du graphe. </overview>

Étape 1 — Choisis ton outil

<decision-table>

Évalue ces conditions dans l'ordre et arrête-toi au premier match :

1. Si la tâche nécessite de la planification, la gestion de fichiers sur une longue session, une mémoire persistante, la délégation de sous-agents ou des compétences à la demande → Deep Agents
2. Sinon, si la tâche nécessite un flux de contrôle personnalisé (boucles déterministes, logique de branchement) → LangGraph
3. Sinon, si c'est un agent à usage unique avec un ensemble fixe d'outils → LangChain (fonction create_agent)
4. Sinon, si c'est un appel de modèle pur, un pipeline de retrieval ou une simple chaîne de prompts sans boucle agent → LangChain (modèle direct / chaîne)

C'est ta couche. MAIS tu n'as pas terminé : plus tard à l'Étape 4, tu DOIS charger la compétence spécifique à la couche avant d'écrire du code agent.

</decision-table>

Profils des outils

<langchain-profile>

LangChain — framework agent

Idéal pour :

• Les agents à usage unique avec un ensemble d'outils fixe
• Les pipelines RAG et les Q&A sur documents
• Les appels de modèles, les templates de prompts, les sorties structurées

Pas idéal quand :

• L'agent doit planifier sur plusieurs étapes ou gérer un grand contexte
• Le flux de contrôle est conditionnel, itératif ou parallèle
• L'état doit persister entre les sessions

Tous les agents LangChain utilisent create_agent(model, tools=[...]).

</langchain-profile>

<langgraph-profile>

LangGraph — runtime agent

Idéal pour :

• Le flux de contrôle personnalisé — boucles déterministes, cycles de réflexion, parallélisation
• Les workflows complexes combinant étapes déterministes et agentic
• Le human-in-the-loop avec des points d'interruption et de reprise précis
• L'état qui doit survivre aux défaillances ou s'étendre sur de longues sessions

Pas idéal quand :

• Tu veux la planification, la gestion de fichiers et la délégation de sous-agents out-of-the-box (utilise Deep Agents à la place)
• Le workflow est assez simple pour une boucle d'outil directe

Tous les graphes LangGraph utilisent StateGraph(State) avec des nœuds, des arêtes et des arêtes conditionnelles explicites.

</langgraph-profile>

<deep-agents-profile>

Deep Agents — agent harness

Idéal pour :

• Les tâches longue durée qui nécessitent planification et décomposition
• Les agents qui lisent, écrivent et gèrent des fichiers au cours d'une session
• La délégation de sous-tâches à des sous-agents spécialisés
• La mémoire persistante entre les sessions
• Le chargement de compétences spécifiques à un domaine à la demande

Pas idéal quand :

• La tâche est assez simple pour un agent à usage unique
• Tu as besoin d'un contrôle précis et fait à la main sur chaque arête du graphe (utilise LangGraph directement)

Tous les Deep Agents utilisent create_deep_agent(model, tools=[...]).

</deep-agents-profile>

Mélanger les couches

<mixing-layers>

Les outils sont structurés en couches, ils peuvent donc être combinés dans le même projet. Motifs courants :

• Orchestrateur Deep Agents → sous-agent LangGraph — quand l'agent principal a besoin de planification et mémoire mais une sous-tâche nécessite un graphe déterministe.
• Graphe LangGraph enveloppé comme outil ou sous-agent — quand un pipeline spécialisé (p. ex. RAG, boucle de réflexion) est appelé par un agent plus large.

Un graphe LangGraph compilé peut être enregistré comme un sous-agent nommé à l'intérieur de Deep Agents — l'orchestrateur le délègue via l'outil task sans connaître sa structure interne. Les outils LangChain et les retrievers fonctionnent librement à l'intérieur des nœuds LangGraph et des outils Deep Agents.

</mixing-layers>

Étape 2 — Définis les variables d'environnement

Définis toujours celles-ci pour l'observabilité. Ce sont les noms actuels des variables d'environnement LangSmith. Copie-les tel-quel. LES ANCIENS NOMS NE FONCTIONNENT PLUS.

<environment-variables> LANGSMITH_API_KEY=<your-key> LANGSMITH_TRACING=true LANGSMITH_PROJECT=<project-name> </environment-variables>

Les clés spécifiques au fournisseur de modèles et aux outils (ANTHROPIC_API_KEY, OPENAI_API_KEY, TAVILY_API_KEY, etc.) dépendent de ta pile — définis-les au besoin.

Étape 3 — Comment fonctionnent les docs

<docs>

Toute la documentation se trouve sur docs.langchain.com, organisée en deux sections au niveau supérieur :

• OSS — LangChain, LangGraph, Deep Agents. Arbres Python (/oss/python/) et TypeScript (/oss/javascript/) en parallèle.
• LangSmith — observabilité, évaluation, déploiement, prompt engineering.

Chaque produit a son propre arborescence : overview → quickstart → how-to guides → reference.

Pages d'atterrissage canoniques

Commence par là plutôt que de chercher depuis la racine (remplace python → javascript pour TypeScript) :

• LangChain — /oss/python/langchain/overview
• LangGraph — /oss/python/langgraph/overview
• Deep Agents — /oss/python/deepagents/overview
• LangSmith — /langsmith/home (pas de division par langage)

Accès aux docs dans un contexte agent

Si le serveur MCP LangChain Docs est connecté (les outils mcp__docs-langchain__* sont disponibles), interroge-le directement :

tree /oss/python -L 2                        # explore la structure Python
tree /oss/javascript -L 2                    # structure TypeScript parallèle
cat /oss/python/langchain/quickstart.mdx     # lis une page spécifique
rg -il "checkpointer" /oss/python/langgraph/ # recherche par mot-clé

Si le serveur MCP n'est pas disponible, utilise l'index llms.txt :

1. Récupère https://docs.langchain.com/llms.txt — liste structurée de toutes les pages avec descriptions
2. Identifie les 2–4 pages les plus pertinentes pour la question
3. Récupère ces pages directement pour un contenu précis et à jour

Privilégie toujours la récupération des docs live plutôt que de te fier aux connaissances de l'entraînement — ces bibliothèques évoluent rapidement et les APIs changent souvent.

</docs>

Étape 4 — Charge la bonne compétence ensuite

Maintenant charge la compétence ci-dessous qui correspond à ta couche de l'Étape 1. C'est obligatoire — la compétence spécifique à la couche porte l'API actuelle ; l'introduction seule ne suffit pas.

<next-skills>

LangChain

• langchain-fundamentals — construire n'importe quel agent LangChain
• langchain-rag — ajouter RAG / retrieval de vector store
• langchain-middleware — sortie structurée avec Pydantic
• langchain-dependencies — versions de packages, installations ou questions de gestion des dépendances

LangGraph

• langgraph-fundamentals — n'importe quel graphe LangGraph
• langgraph-human-in-the-loop — workflows human-in-the-loop ou d'approbation
• langgraph-persistence — état qui doit survivre aux redémarrages ou mémoire cross-thread

Deep Agents

Charge toujours d'abord deep-agents-core. Puis, au besoin :

• deep-agents-orchestration — délégation ou orchestration de sous-agents
• deep-agents-memory — mémoire persistante cross-session

</next-skills>