LangChain : premiers pas avec les chaînes et les modèles

Votre client tape un message à 22 h sur la page Facebook de la coopérative : « Bonjour, le panier en osier de taille moyenne, il est dispo et il coûte combien ? ». Personne ne répond avant le lendemain matin. Pendant ce temps, il a commandé ailleurs. C’est exactement ce trou que nous allons combler dans cette série : un assistant qui lit la question, va chercher la bonne information et répond en français, tout seul.

Dans ce premier tutoriel, on pose les fondations avec LangChain, la bibliothèque Python la plus utilisée pour brancher un modèle de langage (LLM) dans une vraie application. À la fin, vous aurez un embryon d’« Assistant Teranga » : un programme qui appelle un modèle, suit des consignes précises, et sait déjà déclencher un premier outil pour donner un prix exact plutôt que d’inventer.

🎯 Ce que vous allez apprendre

• Installer LangChain 1.x et appeler un modèle de langage depuis Python en quelques lignes.
• Construire une chaîne (prompt → modèle → analyseur) avec la syntaxe LCEL et le caractère |.
• Écrire un outil avec le décorateur @tool et le donner à un agent via create_agent.
• Faire la différence entre une simple chaîne et un agent qui décide quand utiliser un outil.

🛠️ Ce que vous allez construire

Une brique minimale de l’Assistant Teranga : un agent qui répond aux questions des clients sur les produits de la coopérative. Pour ce premier jet, il connaît un petit catalogue codé en dur et sait répondre « le panier en osier moyen coûte 8 500 FCFA, il est en stock » au lieu de répondre n’importe quoi. Les vrais catalogues et la base de connaissances viendront dans les tutoriels suivants.

Prérequis

• Python 3.10 ou plus récent (LangChain 1.x exige au minimum la 3.10). Vérifiez avec python --version.
• Savoir créer un environnement virtuel et lancer un script Python. Test express : si python -m venv .venv puis l’activation ne vous fait pas peur, vous êtes prêt ; sinon, révisez les bases de Python d’abord.
• Une clé d’API chez un fournisseur de modèle (OpenAI, Anthropic…) ou Ollama installé en local pour travailler gratuitement et hors-ligne.
• ⏱️ Temps estimé : ~35 minutes.

Étape 1 — Installer LangChain et isoler le projet

On commence toujours par un environnement virtuel : il enferme les dépendances du projet dans un dossier à part, sans polluer le Python du système. C’est une habitude qui évite des heures de conflits de versions, surtout quand on jongle entre plusieurs projets IA sur la même machine.

python -m venv .venv
source .venv/bin/activate        # sous Windows : .venv\Scripts\activate

pip install -U langchain langchain-openai

Au moment d’écrire ces lignes, pip installe langchain 1.3.x. Le paquet langchain-openai fournit la connexion vers les modèles OpenAI ; si vous préférez Anthropic, installez langchain-anthropic, et pour le local, langchain-ollama. Vérifiez que tout est en place :

python -c "import langchain; print(langchain.__version__)"

Vous devriez voir un numéro de version commençant par 1. s’afficher. Si Python se plaint d’un module introuvable, c’est presque toujours que l’environnement virtuel n’est pas activé — le préfixe (.venv) doit apparaître dans votre terminal.

✅ Point d’étape — LangChain est installé dans un environnement isolé et le numéro de version s’affiche. Si la commande échoue, réactivez le venv avant d’aller plus loin.

Étape 2 — Le premier appel à un modèle

Avant de construire quoi que ce soit, il faut une poignée vers le modèle. LangChain offre une fonction unique, init_chat_model, qui sait parler à des dizaines de fournisseurs : on précise le modèle sous la forme "fournisseur:nom-du-modèle" et la bibliothèque charge le bon connecteur. Cette abstraction est précieuse : changer de fournisseur revient à changer une chaîne de caractères, pas à réécrire le code.

import os
from langchain.chat_models import init_chat_model

os.environ["OPENAI_API_KEY"] = "votre-cle-api"   # en prod, passez par une variable d'environnement

# Choisissez votre modèle. Les noms évoluent vite : vérifiez la doc de votre fournisseur.
modele = init_chat_model("openai:gpt-4o-mini")

reponse = modele.invoke("Réponds en une phrase : qu'est-ce qu'un panier en osier ?")
print(reponse.content)

La méthode invoke envoie le message et renvoie un objet AIMessage ; son attribut .content contient le texte. Vous devriez voir une phrase cohérente s’afficher. Pour travailler gratuitement en local, remplacez la ligne du modèle par init_chat_model("ollama:llama3.1") après avoir lancé ollama pull llama3.1 — utile quand la connexion est chère ou instable, à la nuance près que les petits modèles locaux suivent moins bien des consignes complexes.

✅ Point d’étape — un appel direct au modèle renvoie une réponse. Si vous obtenez une erreur d’authentification, c’est la clé d’API qui est absente ou erronée.

Étape 3 — Composer une chaîne avec LCEL

Appeler le modèle à la main, c’est bien pour tester. Mais une application a besoin de répéter la même opération avec des consignes fixes et une variable qui change. C’est le rôle d’une chaîne : on assemble un gabarit de prompt, le modèle et un analyseur de sortie. LangChain les relie avec le caractère |, comme un tuyau Unix : la sortie de l’un devient l’entrée du suivant. Cette écriture s’appelle LCEL (LangChain Expression Language).

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

gabarit = ChatPromptTemplate.from_messages([
    ("system", "Tu es l'assistant de la coopérative d'artisans Teranga. "
               "Réponds en français, poliment et en une à trois phrases."),
    ("human", "{question}"),
])

chaine = gabarit | modele | StrOutputParser()

print(chaine.invoke({"question": "Faites-vous des paniers sur mesure ?"}))

Trois objets, un seul tuyau. Le gabarit transforme {"question": "..."} en messages, le modèle répond, et StrOutputParser extrait directement la chaîne de texte — plus besoin de toucher à .content. Vous obtenez une réponse propre, dans le ton imposé par le message system. Changez la question : la consigne reste, seule la réponse varie. C’est la base réutilisable de tout ce qui suit.

✅ Point d’étape — votre chaîne répond dans le rôle de l’assistant Teranga, quelle que soit la question passée. Si le ton n’est pas respecté, relisez le message system.

Étape 4 — Donner un premier outil à un agent

Une chaîne suit toujours le même chemin. Mais notre assistant doit parfois aller chercher une information : un prix, un stock. Un modèle seul inventerait un chiffre — c’est le fameux problème d’« hallucination ». La solution est un agent : un modèle à qui l’on donne des outils, et qui décide lui-même quand les appeler. On déclare un outil avec le décorateur @tool ; sa docstring sert de mode d’emploi que le modèle lit pour savoir quand s’en servir.

from langchain.tools import tool
from langchain.agents import create_agent

CATALOGUE = {
    "panier osier moyen": {"prix_fcfa": 8500, "stock": 12},
    "tabouret bois": {"prix_fcfa": 15000, "stock": 3},
}

@tool
def consulter_produit(nom: str) -> str:
    """Donne le prix en FCFA et le stock d'un produit de la coopérative à partir de son nom."""
    p = CATALOGUE.get(nom.lower().strip())
    if not p:
        return f"Produit '{nom}' introuvable dans le catalogue."
    return f"{nom} : {p['prix_fcfa']} FCFA, {p['stock']} en stock."

assistant = create_agent(
    model=modele,
    tools=[consulter_produit],
    system_prompt="Tu es l'assistant de la coopérative Teranga. "
                  "Pour tout prix ou stock, utilise l'outil consulter_produit. N'invente jamais de chiffre.",
)

La fonction create_agent (du paquet langchain) assemble le modèle, les outils et la consigne en un agent prêt à l’emploi. On l’interroge avec une liste de messages, exactement comme une conversation :

resultat = assistant.invoke({
    "messages": [{"role": "user", "content": "Le panier en osier moyen, c'est combien ?"}]
})
print(resultat["messages"][-1].content)

Sous le capot, le modèle lit la question, repère qu’il lui faut un prix, appelle consulter_produit("panier osier moyen"), lit le résultat (8 500 FCFA, 12 en stock) et formule une réponse en français appuyée sur ce chiffre réel. Le dernier message de la liste contient la réponse finale. Vous venez de franchir la frontière entre « un modèle qui bavarde » et « un agent qui agit ».

✅ Point d’étape — l’assistant donne un prix exact tiré du catalogue. Si la réponse contient un chiffre inventé, renforcez la consigne « n’invente jamais de chiffre » et vérifiez que l’outil est bien dans la liste tools.

Étape 5 — Vérification de bout en bout

Posons une question dont la réponse n’est pas dans le catalogue, pour vérifier que l’agent ne se contente pas de deviner.

r = assistant.invoke({
    "messages": [{"role": "user", "content": "Vous avez des nappes brodées ? À quel prix ?"}]
})
print(r["messages"][-1].content)

L’outil renvoie « introuvable », et un agent bien réglé l’annonce honnêtement (« je n’ai pas ce produit au catalogue ») plutôt que d’inventer un prix. C’est le comportement qu’on veut en production : mieux vaut un « je ne sais pas » qu’une fausse promesse au client. Si votre agent invente quand même, c’est le signal qu’il faut durcir la consigne — un thème que l’on creusera avec les outils et LangGraph.

Chaîne ou agent : lequel choisir ?

La tentation, après ce tutoriel, est de tout transformer en agent. Ce serait une erreur. Un agent coûte plus cher (le modèle réfléchit à plusieurs reprises, appelle des outils, puis rédige) et il est moins prévisible : on ne sait pas à l’avance combien d’appels il fera. Une chaîne, elle, est rapide, bon marché et déterministe.

La règle simple : si la tâche suit toujours le même chemin — résumer un texte, traduire un message, classer un avis client en « positif/négatif » — une chaîne LCEL suffit et coûte dix fois moins. Réservez l’agent aux situations où il faut décider : aller chercher une donnée à un endroit qui dépend de la question, enchaîner plusieurs outils selon le contexte, ou s’arrêter dès qu’on a la réponse. Pour l’Assistant Teranga, le choix est clair : répondre à des questions variées sur des produits réels exige d’aller chercher la bonne information au bon moment, donc un agent. Mais sa future fonction « résumer la conversation pour le gérant » restera, elle, une simple chaîne.

🐞 Pièges fréquents

🌍 Adaptation au contexte ouest-africain

Le poste de coût d’un agent IA, ce sont les appels au modèle hébergé, facturés au volume de texte. Trois leviers concrets : d’abord, pendant tout le développement, travaillez avec Ollama en local — zéro facture, et vos tests ne consomment pas votre forfait data. Ensuite, choisissez un petit modèle (les variantes « mini ») pour les tâches simples : la différence de prix est d’un facteur dix sans perte notable sur des réponses courtes. Enfin, gardez vos consignes system brèves et précises : chaque mot envoyé à un modèle hébergé est payé, et un prompt concis répond aussi plus vite sur une connexion à faible débit. Pour la mise en production, un VPS à 5 000–6 000 FCFA par mois suffit largement à héberger ce type d’assistant.

✅ Récapitulatif

Vous êtes parti d’une page vide et vous avez maintenant un assistant qui appelle un modèle, suit un rôle, et déclenche un outil pour donner des informations exactes au lieu de les inventer. Les notions clés acquises : l’environnement isolé, init_chat_model pour parler à n’importe quel fournisseur, la chaîne LCEL avec |, le décorateur @tool, et create_agent — la fonction centrale de LangChain 1.x. C’est le socle sur lequel reposent tous les tutoriels suivants.

🧾 Aide-mémoire

💪 À vous de jouer

Ajoutez un second outil verifier_delai(produit: str) qui renvoie un délai de fabrication (par exemple « 3 jours » pour un panier, « 7 jours » pour un tabouret), et posez à l’assistant : « Je veux deux tabourets, c’est dispo et c’est prêt quand ? ». Observez l’agent enchaîner deux outils dans une même réponse.

DELAIS = {"panier osier moyen": "3 jours", "tabouret bois": "7 jours"}

@tool
def verifier_delai(produit: str) -> str:
    """Donne le délai de fabrication d'un produit de la coopérative."""
    return DELAIS.get(produit.lower().strip(), "délai inconnu")

assistant = create_agent(
    model=modele,
    tools=[consulter_produit, verifier_delai],
    system_prompt="Tu es l'assistant Teranga. Utilise les outils pour les prix, "
                  "stocks et délais. N'invente jamais.",
)
print(assistant.invoke({"messages": [
    {"role": "user", "content": "Je veux deux tabourets, dispo et prêts quand ?"}
]})["messages"][-1].content)

Tutoriels frères

• Donner des outils à un agent LangChain (tool calling) — connecter votre agent à de vraies fonctions et API.
• RAG : brancher une base de connaissances sur votre agent — répondre à partir de vos propres documents.

Pour aller plus loin

• 🔝 Retour au guide principal : LangChain, LangGraph et CrewAI : le guide des frameworks d’agents IA
• Documentation officielle LangChain : docs.langchain.com
• Tutoriel suivant conseillé : donner des outils à votre agent.

FAQ

Q : Faut-il forcément payer un fournisseur comme OpenAI ?
R : Non. Avec Ollama, vous faites tourner un modèle gratuitement sur votre machine. C’est plus lent et un peu moins fiable sur les tâches complexes, mais parfait pour apprendre et développer sans facture.

Q : Quelle différence entre une chaîne et un agent ?
R : Une chaîne suit toujours le même chemin (prompt → modèle → sortie). Un agent reçoit des outils et décide lui-même, à chaque question, lesquels appeler et dans quel ordre. La chaîne est prévisible, l’agent est autonome.

Q : Pourquoi mon ancien code avec create_react_agent ne marche plus ?
R : LangChain 1.x a unifié la création d’agents autour de create_agent. L’ancienne fonction de langgraph.prebuilt est dépréciée. Migrez vers create_agent du paquet langchain.

Q : LangChain et LangGraph, c’est la même chose ?
R : LangChain fournit les briques (modèles, outils, agents prêts à l’emploi) ; LangGraph sert à orchestrer des agents plus complexes avec des états et des cycles. On y vient dans le tutoriel LangGraph de la série.