LlamaIndex agents : guide complet

LlamaIndex est le framework Python de référence pour connecter des LLMs à vos données. Là où d'autres outils orchestrent des chaînes de traitement génériques, LlamaIndex se concentre sur un problème précis : ingérer, indexer et interroger n'importe quelle source de données avec un LLM. Ce guide couvre l'architecture, les types d'agents disponibles, le RAG agentique et les exemples de code pour démarrer immédiatement.

---

Résumé rapide

• Philosophie : framework "data-first" — l'accès aux données est au centre de tout
• Point fort : RAG agentique, indexation multi-sources, QueryEngine avancé
• Langages : Python principal, TypeScript via LlamaIndex.TS
• Agents : ReAct Agent, OpenAI Agent, Function Calling, multi-agents
• Licence : MIT
• Ancien nom : GPT Index (renommé LlamaIndex en 2023)

---

Qu'est-ce que LlamaIndex

LlamaIndex est né en 2022 sous le nom GPT Index. Son créateur, Jerry Liu, cherchait une solution simple pour connecter GPT-3 à des documents personnels. L'idée : structurer les données de façon à ce qu'un LLM puisse les exploiter efficacement, quelle que soit leur taille ou leur format.

En 2023, le projet est renommé LlamaIndex et lève 8,5 millions de dollars. La v0.10, sortie début 2024, marque une refonte majeure de l'architecture avec une séparation claire entre les packages (llama-index-core, llama-index-llms-openai, etc.), ce qui facilite les mises à jour sans casser les dépendances.

Une philosophie data-centric

Là où LangChain est un framework d'orchestration généraliste, LlamaIndex part d'une hypothèse différente : la qualité d'un agent ou d'une application LLM dépend avant tout de la qualité de l'accès aux données. Le framework propose donc une stack complète pour :

• Ingérer : connecteurs pour PDF, Notion, Slack, bases SQL, APIs REST, GitHub, et plus de 160 sources via llama-hub
• Indexer : structures de données optimisées pour la recherche sémantique (VectorIndex, SummaryIndex, KnowledgeGraph)
• Interroger : QueryEngine avec reranking, filtres de métadonnées, fusion de résultats
• Agir : agents ReAct et Function Calling qui utilisent les QueryEngines comme outils

Cette architecture positionne LlamaIndex comme le choix naturel dès que votre agent doit raisonner sur un corpus de documents, une base de code, ou des données structurées privées. Pour une vue d'ensemble de l'écosystème, voir notre guide sur les frameworks agents IA.

---

Développement principal

Composants clés de LlamaIndex

Documents et Nodes

Tout commence par le chargement des données. LlamaIndex découpe les documents en Node — des unités de texte avec métadonnées, identifiant unique et relations parent/enfant. Ce découpage intelligent (chunking) est configurable : taille des chunks, overlap, stratégie de découpage par phrase ou par token.

from llama_index.core import SimpleDirectoryReader

documents = SimpleDirectoryReader("./data").load_data()
# Chaque fichier PDF, TXT, DOCX devient une liste de Document

Index et VectorStore

Un VectorStoreIndex transforme les documents en embeddings et les stocke dans une base vectorielle. Par défaut, LlamaIndex utilise un store en mémoire, mais s'intègre avec Chroma, Pinecone, Weaviate, pgvector et bien d'autres.

from llama_index.core import VectorStoreIndex

index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()

response = query_engine.query("Quels sont les points clés du rapport Q3 ?")
print(response)

QueryEngine

Le QueryEngine est l'interface principale pour interroger un index. Il gère la récupération des passages pertinents (retrieval), la construction du prompt et la génération de la réponse. LlamaIndex propose plusieurs variantes :

• RetrieverQueryEngine : retrieval + synthèse classique
• SubQuestionQueryEngine : décompose une question complexe en sous-questions
• RouterQueryEngine : route vers le bon index selon la question
• SQLJoinQueryEngine : combine SQL et recherche vectorielle

ReAct Agent et Tools

Les agents LlamaIndex suivent le paradigme ReAct (Reasoning + Acting) : le LLM raisonne à voix haute, choisit un outil, observe le résultat, puis continue jusqu'à avoir une réponse finale.

Un Tool dans LlamaIndex est simplement une fonction Python décorée avec une description. L'agent utilise cette description pour décider quand appeler l'outil.

from llama_index.core.tools import FunctionTool
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI

def calculer_tva(montant_ht: float, taux: float = 0.20) -> str:
    """Calcule la TVA et le montant TTC à partir d'un montant HT."""
    tva = montant_ht * taux
    ttc = montant_ht + tva
    return f"TVA : {tva:.2f}€ — TTC : {ttc:.2f}€"

outil_tva = FunctionTool.from_defaults(fn=calculer_tva)

llm = OpenAI(model="gpt-4o", temperature=0)
agent = ReActAgent.from_tools([outil_tva], llm=llm, verbose=True)

response = agent.chat("Si mon devis est de 1500€ HT, quel est le montant TTC ?")
print(response)

RAG agentique vs RAG classique

Le RAG classique est un pipeline fixe : on récupère des passages, on les injecte dans le prompt, on génère. Simple et efficace pour des questions directes.

Le RAG agentique (Agentic RAG) est différent : l'agent décide dynamiquement comment interroger les données. Il peut :

• Reformuler la question avant de chercher
• Lancer plusieurs requêtes en parallèle sur des sources différentes
• Demander des précisions si le résultat est insuffisant
• Croiser des informations entre plusieurs index

LlamaIndex est particulièrement fort sur ce point. Un QueryEngine peut devenir un outil de l'agent, ce qui donne accès à toute la puissance du pipeline RAG depuis le raisonnement de l'agent. C'est l'avantage clé sur d'autres outils pour agents IA plus généralistes.

from llama_index.core.tools import QueryEngineTool

# Le QueryEngine devient un outil de l'agent
outil_docs = QueryEngineTool.from_defaults(
    query_engine=query_engine,
    name="recherche_documents",
    description="Interroge la base documentaire interne. Utile pour répondre à des questions sur les politiques, procédures et rapports de l'entreprise."
)

agent = ReActAgent.from_tools([outil_docs, outil_tva], llm=llm, verbose=True)

Types d'agents LlamaIndex

Type	Description	Quand l'utiliser
ReActAgent	Raisonnement chain-of-thought + outils	Usage général, transparence du raisonnement
OpenAIAgent	Function calling natif OpenAI	Modèles GPT-4, latence plus faible
FunctionCallingAgent	Générique, compatible Anthropic/Mistral	Multi-LLM
StructuredPlannerAgent	Planification + exécution séparées	Tâches longues et complexes

Cas d'usage typiques

Assistant documentaire d'entreprise : ingestion de PDFs internes (politiques RH, fiches produit, contrats), index vectoriel, agent qui répond aux questions des employés avec citation des sources.

Agent Q&A sur données privées : connexion à une base SQL + documents non structurés, RouterQueryEngine qui choisit entre SQL et RAG selon la question.

Pipeline d'analyse financière : agent qui lit des rapports PDF, extrait des chiffres, les compare sur plusieurs périodes et génère un résumé structuré.

Quand choisir LlamaIndex vs LangChain

Choisissez LlamaIndex si :

• Votre agent doit raisonner sur un corpus de documents (RAG agentique)
• Vous avez des besoins avancés d'indexation (multi-index, knowledge graph)
• La précision de la récupération est critique

Choisissez LangChain si :

• Vous construisez des workflows complexes avec état (plutôt LangGraph)
• Vous avez besoin d'un écosystème très large d'intégrations
• Votre cas d'usage est davantage orienté orchestration que données

Les deux frameworks sont complémentaires et s'intègrent ensemble : LlamaIndex peut être utilisé comme outil de récupération dans un agent LangChain. Pour comparer tous les frameworks, consultez notre comparatif des meilleurs frameworks agents IA.

---

Exemple concret : agent Q&A sur un corpus PDF

Voici un agent LlamaIndex complet qui répond à des questions sur un dossier de PDFs. L'agent peut interroger les documents ET effectuer des calculs.

import os
from llama_index.core import (
    VectorStoreIndex,
    SimpleDirectoryReader,
    StorageContext,
    load_index_from_storage,
)
from llama_index.core.tools import QueryEngineTool, FunctionTool
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

# Configuration
os.environ["OPENAI_API_KEY"] = "votre-cle-api"
PERSIST_DIR = "./storage"

# 1. Chargement et indexation des PDFs
if not os.path.exists(PERSIST_DIR):
    documents = SimpleDirectoryReader("./pdfs").load_data()
    index = VectorStoreIndex.from_documents(
        documents,
        embed_model=OpenAIEmbedding(model="text-embedding-3-small"),
    )
    index.storage_context.persist(persist_dir=PERSIST_DIR)
    print(f"{len(documents)} documents indexés.")
else:
    storage_context = StorageContext.from_defaults(persist_dir=PERSIST_DIR)
    index = load_index_from_storage(storage_context)
    print("Index chargé depuis le cache.")

# 2. QueryEngine avec paramètres optimisés
query_engine = index.as_query_engine(
    similarity_top_k=5,         # Récupère les 5 passages les plus pertinents
    response_mode="compact",    # Synthèse concise
)

# 3. Définition des outils
outil_recherche = QueryEngineTool.from_defaults(
    query_engine=query_engine,
    name="recherche_pdfs",
    description=(
        "Recherche dans la base documentaire PDF. "
        "Utilise cet outil pour toute question factuelle sur le contenu des documents."
    ),
)

def compter_mots(texte: str) -> str:
    """Compte le nombre de mots dans un texte donné."""
    n = len(texte.split())
    return f"Le texte contient {n} mots."

outil_compteur = FunctionTool.from_defaults(fn=compter_mots)

# 4. Création de l'agent
llm = OpenAI(model="gpt-4o", temperature=0)
agent = ReActAgent.from_tools(
    [outil_recherche, outil_compteur],
    llm=llm,
    verbose=True,
    max_iterations=10,
)

# 5. Utilisation
questions = [
    "Quelles sont les principales conclusions du rapport annuel ?",
    "Combien de fois le mot 'risque' apparaît-il dans le résumé exécutif ?",
    "Quels sont les objectifs fixés pour 2027 ?",
]

for question in questions:
    print(f"\nQuestion : {question}")
    reponse = agent.chat(question)
    print(f"Réponse : {reponse}\n{'—'*60}")

Ce code est autonome et directement exécutable. L'index est persisté sur disque pour éviter de recalculer les embeddings à chaque exécution — point essentiel en production pour maîtriser les coûts API.

---

Bonnes pratiques

Optimiser le chunking : la taille des chunks (par défaut 1024 tokens) a un impact direct sur la qualité du RAG. Pour des documents techniques denses, réduire à 512 tokens avec un overlap de 50 tokens améliore souvent la précision. Testez avec SentenceSplitter(chunk_size=512, chunk_overlap=50).

Persister l'index : ne reconstruisez jamais l'index à chaque démarrage. Utilisez storage_context.persist() et load_index_from_storage() pour mettre en cache les embeddings.

Utiliser un reranker : après la récupération vectorielle, un reranker (Cohere, BGE) réordonne les passages par pertinence réelle. Cela améliore significativement la qualité des réponses sans modifier l'index.

from llama_index.postprocessor.cohere_rerank import CohereRerank
reranker = CohereRerank(top_n=3)
query_engine = index.as_query_engine(node_postprocessors=[reranker])

Limiter max_iterations : fixez toujours une limite d'itérations pour l'agent (paramètre max_iterations) afin d'éviter les boucles infinies en cas d'hallucination sur les outils disponibles.

Logger les traces : LlamaIndex s'intègre avec LangFuse et Arize Phoenix pour tracer les appels LLM, les retrievals et les décisions de l'agent en production. Indispensable pour debugger et optimiser.

---

Questions fréquentes

LlamaIndex est-il difficile à apprendre ?

Non. L'API de haut niveau (VectorStoreIndex, ReActAgent) permet de créer un agent fonctionnel en moins de 20 lignes. La courbe monte quand on personnalise le pipeline RAG (custom retrievers, rerankers, query transformations), mais la documentation est très bien fournie.

LlamaIndex supporte-t-il d'autres LLMs qu'OpenAI ?

Oui. Anthropic Claude, Mistral, Cohere, Ollama (modèles locaux), Hugging Face, et bien d'autres sont supportés via des packages séparés (llama-index-llms-anthropic, etc.). L'interface est identique quel que soit le LLM.

Quelle est la différence entre LlamaIndex et un simple appel RAG direct ?

Un appel RAG direct (embeddings + recherche vectorielle + prompt) fonctionne pour des cas simples. LlamaIndex ajoute : gestion de multiples sources, pipelines de retrieval avancés, agents capables d'itérer, gestion des métadonnées, et une architecture modulaire testable. Pour les agents IA en production, la différence est significative.

Peut-on utiliser LlamaIndex avec une base vectorielle existante ?

Oui. LlamaIndex s'intègre avec Chroma, Pinecone, Weaviate, Qdrant, pgvector (PostgreSQL), Milvus et d'autres. Il suffit de configurer un VectorStore et de le passer au StorageContext.

LlamaIndex est-il adapté à la production ?

Oui, à partir de la v0.10. Des entreprises comme Uber, Dropbox et Airbnb l'utilisent. LlamaCloud, la version managée, propose des fonctionnalités supplémentaires (pipelines d'ingestion managés, parsing de documents avancé avec LlamaParse).

---

Articles liés

LlamaIndex s'inscrit dans un écosystème plus large de frameworks et d'outils pour agents IA. Pour choisir le bon framework selon votre cas d'usage, notre comparatif des meilleurs frameworks agents IA met en regard LlamaIndex, LangChain, LangGraph, CrewAI et AutoGen sur des critères concrets. Si vous démarrez avec les agents IA, le guide agent IA : comprendre et construire pose les bases conceptuelles indispensables.

Pour aller plus loin :

• Frameworks agents IA : panorama complet
• LangChain : guide complet
• Comparatif des meilleurs frameworks agents IA
• Agent IA : définition et guide de démarrage
• Outils pour agents IA