Comment Construire des Agents IA avec LangChain : Tutoriel Complet 2026

Ce Que Vous Allez Construire

À la fin de ce tutoriel, vous aurez un agent IA fonctionnel capable de :

• Rechercher sur le web pour des informations en temps réel
• Interroger une base de données pour des données structurées
• Maintenir une mémoire de conversation entre les sessions
• Gérer les erreurs gracieusement avec logique de retry
• Se déployer en production avec monitoring approprié

Ce n'est pas une démo "hello world". C'est un pattern d'agent prêt pour la production que vous pouvez adapter pour des applications réelles.

"La meilleure façon d'apprendre les agents IA est d'en construire un qui résout un vrai problème."

Prérequis :

• Python 3.10+
• Compréhension basique des LLMs et prompts
• Clé API OpenAI (ou Anthropic/autres providers)
• 30 minutes de temps concentré

Étape 1 : Configuration du Projet

D'abord, créez la structure de votre projet et installez les dépendances.

# Créer le répertoire du projet
mkdir langchain-agent && cd langchain-agent

# Créer l'environnement virtuel
python -m venv venv
source venv/bin/activate  # Sur Windows: venv\Scripts\activate

# Installer les dépendances
pip install langchain langchain-openai langchain-community
pip install python-dotenv tavily-python chromadb

Créez votre fichier .env pour les clés API :

# .env
OPENAI_API_KEY=votre-cle-openai
TAVILY_API_KEY=votre-cle-tavily  # Pour la recherche web

Créez la structure principale du projet :

langchain-agent/
├── .env
├── agent.py           # Logique principale de l'agent
├── tools.py           # Outils personnalisés
├── memory.py          # Configuration de la mémoire
├── evaluation.py      # Tests et évaluation
└── requirements.txt

Étape 2 : Votre Premier Agent

Construisons un agent simple qui peut répondre aux questions en utilisant la recherche web.

# agent.py
import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_react_agent
from langchain_community.tools.tavily_search import TavilySearchResults
from langchain_core.prompts import PromptTemplate

load_dotenv()

# Initialiser le LLM
llm = ChatOpenAI(
    model="gpt-4o",
    temperature=0,
    max_tokens=1000
)

# Initialiser les outils
search_tool = TavilySearchResults(
    max_results=3,
    search_depth="advanced"
)
tools = [search_tool]

# Définir le prompt de l'agent
template = """Tu es un assistant IA utile avec accès à la recherche web.

Réponds à la question de l'utilisateur en utilisant les outils disponibles. Cite toujours tes sources.

Tu as accès aux outils suivants :
{tools}

Utilise le format suivant :
Question: la question à laquelle tu dois répondre
Thought: tu dois toujours réfléchir à ce qu'il faut faire
Action: l'action à effectuer, doit être l'un de [{tool_names}]
Action Input: l'entrée de l'action
Observation: le résultat de l'action
... (ce cycle Thought/Action/Action Input/Observation peut se répéter N fois)
Thought: Je connais maintenant la réponse finale
Final Answer: la réponse finale à la question originale

Commence !

Question: {input}
{agent_scratchpad}
"""

prompt = PromptTemplate.from_template(template)

# Créer l'agent
agent = create_react_agent(llm, tools, prompt)

# Créer l'exécuteur avec gestion d'erreurs
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,
    handle_parsing_errors=True,
    max_iterations=5
)

# Tester l'agent
if __name__ == "__main__":
    result = agent_executor.invoke({
        "input": "Quels sont les derniers développements en agents IA en janvier 2026 ?"
    })
    print(result["output"])

Exécutez votre agent :

python agent.py

Vous devriez voir l'agent raisonner sur le problème, rechercher sur le web et fournir une réponse sourcée.

Étape 3 : Ajouter des Outils Personnalisés

Les vrais agents ont besoin d'outils personnalisés pour des tâches spécifiques. Ajoutons un outil de requête de base de données.

# tools.py
from langchain.tools import tool
from typing import Optional
import json

# Base de données simulée (remplacer par une vraie connexion)
MOCK_DATABASE = {
    "users": [
        {"id": 1, "name": "Alice", "role": "engineer", "projects": 5},
        {"id": 2, "name": "Bob", "role": "designer", "projects": 3},
        {"id": 3, "name": "Charlie", "role": "manager", "projects": 8},
    ],
    "projects": [
        {"id": 1, "name": "AI Dashboard", "status": "active", "team_size": 4},
        {"id": 2, "name": "Data Pipeline", "status": "completed", "team_size": 3},
        {"id": 3, "name": "Mobile App", "status": "planning", "team_size": 2},
    ]
}

@tool
def query_database(query: str) -> str:
    """
    Interroge la base de données interne pour des informations utilisateurs et projets.

    Args:
        query: Requête en langage naturel comme "liste tous les ingénieurs" ou "projets actifs"

    Returns:
        Chaîne JSON avec les résultats de la requête
    """
    query_lower = query.lower()

    if "user" in query_lower or "engineer" in query_lower or "designer" in query_lower:
        if "engineer" in query_lower:
            results = [u for u in MOCK_DATABASE["users"] if u["role"] == "engineer"]
        elif "designer" in query_lower:
            results = [u for u in MOCK_DATABASE["users"] if u["role"] == "designer"]
        else:
            results = MOCK_DATABASE["users"]
        return json.dumps({"type": "users", "count": len(results), "data": results})

    if "project" in query_lower:
        if "active" in query_lower:
            results = [p for p in MOCK_DATABASE["projects"] if p["status"] == "active"]
        elif "completed" in query_lower:
            results = [p for p in MOCK_DATABASE["projects"] if p["status"] == "completed"]
        else:
            results = MOCK_DATABASE["projects"]
        return json.dumps({"type": "projects", "count": len(results), "data": results})

    return json.dumps({"error": "Requête non comprise. Essayez de demander des informations sur les utilisateurs ou projets."})

Étape 4 : Implémenter la Mémoire

Les agents sans mémoire oublient tout entre les conversations. Ajoutons une mémoire persistante.

# memory.py
from langchain.memory import ConversationBufferWindowMemory
from langchain_community.chat_message_histories import SQLChatMessageHistory

def create_memory(session_id: str, window_size: int = 10):
    """
    Crée une instance de mémoire avec historique de conversation.

    Args:
        session_id: Identifiant unique pour la conversation
        window_size: Nombre de messages récents à garder en contexte

    Returns:
        Instance de mémoire configurée
    """
    message_history = SQLChatMessageHistory(
        session_id=session_id,
        connection_string="sqlite:///chat_history.db"
    )

    memory = ConversationBufferWindowMemory(
        chat_memory=message_history,
        k=window_size,
        return_messages=True,
        memory_key="chat_history"
    )

    return memory

Étape 5 : Ajouter RAG (Retrieval-Augmented Generation)

Pour les agents qui doivent répondre à des questions à partir de documents, ajoutez des capacités RAG.

# rag.py
from langchain_community.document_loaders import TextLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import Chroma
from langchain.tools import tool

embeddings = OpenAIEmbeddings()
vectorstore = None

def initialize_vectorstore(documents_path: str):
    """Charge les documents et crée le vector store."""
    global vectorstore

    loader = TextLoader(documents_path)
    documents = loader.load()

    text_splitter = RecursiveCharacterTextSplitter(
        chunk_size=1000,
        chunk_overlap=200
    )
    splits = text_splitter.split_documents(documents)

    vectorstore = Chroma.from_documents(
        documents=splits,
        embedding=embeddings,
        persist_directory="./chroma_db"
    )
    return vectorstore

@tool
def search_documents(query: str) -> str:
    """
    Recherche dans les documents internes pour des informations pertinentes.

    Args:
        query: La requête de recherche

    Returns:
        Extraits de documents pertinents
    """
    if vectorstore is None:
        return "Document store non initialisé."

    results = vectorstore.similarity_search(query, k=3)

    if not results:
        return "Aucun document pertinent trouvé."

    formatted_results = []
    for i, doc in enumerate(results, 1):
        formatted_results.append(f"[{i}] {doc.page_content[:500]}...")

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

Étape 6 : Gestion d'Erreurs et Logique de Retry

Les agents en production nécessitent une gestion d'erreurs robuste.

# error_handling.py
import time
from functools import wraps

def retry_with_backoff(max_retries: int = 3, base_delay: float = 1.0):
    """Décorateur pour logique de retry avec backoff exponentiel."""
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            retries = 0
            while retries < max_retries:
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    retries += 1
                    if retries == max_retries:
                        raise e
                    delay = base_delay * (2 ** retries)
                    print(f"Tentative {retries} échouée : {e}. Retry dans {delay}s...")
                    time.sleep(delay)
            return None
        return wrapper
    return decorator

Étape 7 : Évaluation et Tests

Ne déployez jamais un agent sans tests. Voici comment évaluer votre agent.

# evaluation.py
from dataclasses import dataclass
from typing import List

@dataclass
class TestCase:
    input: str
    expected_action: str
    expected_keywords: List[str]
    min_confidence: float = 0.7

TEST_CASES = [
    TestCase(
        input="Combien d'ingénieurs avons-nous ?",
        expected_action="query_database",
        expected_keywords=["engineer", "user"]
    ),
    TestCase(
        input="Quelles sont les dernières nouvelles sur LangChain ?",
        expected_action="tavily_search",
        expected_keywords=["LangChain"]
    ),
]

def run_evaluation(agent_executor, test_cases: List[TestCase]) -> dict:
    """Exécute la suite d'évaluation sur l'agent."""
    results = {"total": len(test_cases), "passed": 0, "failed": 0, "details": []}

    for test in test_cases:
        try:
            response = agent_executor.invoke({"input": test.input})
            output = response.get("output", "").lower()

            keywords_found = sum(1 for kw in test.expected_keywords if kw.lower() in output)
            keyword_score = keywords_found / len(test.expected_keywords)
            passed = keyword_score >= test.min_confidence

            results["details"].append({"test": test.input, "passed": passed})
            results["passed" if passed else "failed"] += 1

        except Exception as e:
            results["failed"] += 1
            results["details"].append({"test": test.input, "passed": False, "error": str(e)})

    results["pass_rate"] = results["passed"] / results["total"]
    return results

Étape 8 : Déployer en Production

Voici un déploiement simple avec FastAPI.

# api.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import uvicorn

from agent import agent_executor

app = FastAPI(title="API Agent IA")

class QueryRequest(BaseModel):
    query: str
    session_id: str = "default"

@app.post("/query")
async def query_agent(request: QueryRequest):
    """Envoie une requête à l'agent IA."""
    try:
        result = agent_executor.invoke({"input": request.query})
        return {"response": result["output"], "session_id": request.session_id}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.get("/health")
async def health_check():
    return {"status": "healthy"}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

Erreurs Courantes et Solutions

Erreur : "Agent stopped due to max iterations"

Cause : L'agent est bloqué dans une boucle ou prend trop d'étapes.

Solution : Augmentez max_iterations ou améliorez votre prompt.

Erreur : "Could not parse LLM output"

Cause : La réponse du LLM ne correspond pas au format attendu.

Solution : Activez la gestion d'erreurs :

agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    handle_parsing_errors=True
)

Erreur : "Rate limit exceeded"

Cause : Trop d'appels API en peu de temps.

Solution : Ajoutez du caching :

from langchain.cache import SQLiteCache
from langchain.globals import set_llm_cache
set_llm_cache(SQLiteCache(database_path=".langchain.db"))

FAQ

Q : Quel LLM utiliser ?

Pour les agents, utilisez des modèles avec un raisonnement fort : GPT-4o, Claude 3.5 Sonnet, ou Gemini 1.5 Pro.

Q : Comment réduire les coûts ?

1. Cachez les réponses avec set_llm_cache()
2. Limitez la taille de la fenêtre mémoire
3. Définissez max_iterations correctement

Q : Puis-je utiliser des modèles locaux ?

Oui ! Utilisez Ollama :

from langchain_community.llms import Ollama
llm = Ollama(model="llama3.1:70b")

Quelle Suite ?

Vous avez maintenant un agent IA prêt pour la production. Voici les prochaines étapes :

1. Ajoutez plus d'outils - Connectez-vous à vos APIs et bases de données
2. Implémentez des garde-fous - Ajoutez des vérifications de sécurité
3. Configurez le monitoring - Suivez l'utilisation, les erreurs et les coûts
4. Construisez une UI - Connectez à un frontend ou Slack/Discord

Guides connexes

Continuez votre parcours agents IA :

• Pourquoi les agents IA échouent (et comment les corriger) — Déboguez les échecs d'agents en production.
• Guide de Bataille de l'Orchestrateur IA 2026 — Passez des agents simples aux systèmes multi-agents.
• Workflows développeurs avec IA — Comparez les outils pour construire avec l'IA.

Si ce tutoriel vous a aidé à construire votre premier agent, partagez-le avec un autre développeur. La meilleure façon d'apprendre est de construire.

Construire avec l IA et livrer proprement

Besoin d un developpeur capable de transformer une idee en livrable ?

J aide les equipes a livrer du React, Next.js, Node.js, de l IA et de l automatisation avec un cadrage clair, des garde-fous utiles et une execution rapide.

Voir le profilVoir l offre freelanceMe contacter