Les services IA de DnC

RAG : Compression contextuelle

Bertrand Degoy — 2026-02-12T08:19:12Z

La contextual compression est un sujet qui est devenu central dans les RAG modernes.

C'est une technique qui permet de réduire dynamiquement - c'est à dire en fonction du contexte - la quantité de texte envoyée au LLM en ne gardant que ce qui est pertinent pour la requête.

On ne renvoit pas les documents bruts, mais une version compressée, filtrée, ou résumée, adaptée à la question.

C'est un pré‑processing intelligent du contexte.

C'est devenu indispensable

Parce que :

les fenêtres de contexte sont grandes mais pas infinies,
les chunks bruts sont souvent trop verbeux,
les embeddings récupèrent parfois trop de documents,
les modèles hallucinent moins quand le contexte est précis.

La contextual compression permet :

d'augmenter la précision,
de réduire le bruit,
d'améliorer la factualité,
de diminuer le coût.

Les 3 grandes familles de contextual compression

1. Compression par résumé (LLM summarization)

On récupère les documents pertinents, puis on demandes au LLM :

« Résume uniquement les parties utiles pour répondre à la requête X. »

C'est la version la plus simple et la plus efficace.

Exemple

Document : 3 pages
Requête : « Quels sont les effets secondaires du médicament ? »
Résumé compressé : 4 lignes ciblées

2. Compression par extraction (LLM extraction)

Le LLM ne résume pas : il extrait les passages pertinents.

« Extrait uniquement les phrases qui répondent à la question X. »

C'est plus précis et moins risqué que le résumé.

3. Compression par filtrage sémantique (embedding‑based filtering)

On fait un re‑ranking interne :

récupérer les chunks via embeddings.
re‑embed de chaque chunk par rapport à la requête.
élimination des chunks peu pertinents.

C'est du semantic pruning.

Comment ça s'intègre dans un pipeline RAG ?

Voici le pipeline classique :

User query
→ embedding de la requête
→ retrieval (top‑k documents)
→ contextual compression (résumé / extraction / filtrage)
→ Prompt final = system + historique + requête + contexte compressé
→ LLM

La compression intervient entre le retrieval et le prompt final.

Pourquoi c'est supérieur au RAG naïf ?

Sans compression :

envoit trop de texte,
dépasse la fenêtre,
ajoute du bruit,
augmente les hallucinations.

Avec compression :

n'envoie que l'essentiel,
reste dans la fenêtre,
augmente la précision,
réduit le coût.

Le point clé : la compression est contextuelle
Ce n'est pas un résumé générique.
C'est un résumé conditionné par la requête.

Exemple :

Requête A : « Quels sont les risques ? »
Requête B : « Quels sont les bénéfices ? »

Le même document donnera deux compressions différentes pour des requêtes différentes.

Notons que, par requête, on peut entendre historique + question. Ainsi, la même question de l'utilisateur, après avoir posé différentes questions et obtenu différentes réponses, une nouvelle question sera traitée en tenant compte des précédentes.

C'est ce qui rend la technique si puissante.

Les erreurs fréquentes

-résumer les documents avant le retrieval
→ tu perds de l'information utile

-compresser sans conditionner sur la requête
→ tu obtiens un résumé générique, inutile

-compresser trop tôt dans le pipeline
→ tu risques de biaiser la recherche

-compresser avec un modèle trop faible
→ tu introduis des erreurs dans le contexte

Comment faire une contextual compression robuste ?

Étape 1 — Retrieval large (top‑20 ou top‑50)

On récupère large pour ne rien rater.

Étape 2 — Re‑ranking (embedding ou cross‑encoder)

On réduit à top‑5 ou top‑10.

Étape 3 — Compression LLM (résumé/extraction)

On produit un contexte propre, court, précis.

Étape 4 — Prompt final

On injecte uniquement la version compressée.

Ce pipeline est beaucoup plus stable que le RAG naïf.

ReAct : le nommage des outils.

Bertrand Degoy — 2026-01-28T10:00:52Z

Dans la sélection d'un outil par le LLM, il apparaît que le nom de l'outil est prioritaire, et que la description est secondaire. De toute évidence, la description ne peut compléter un nom de fonction ambigu et ne servira au LLM qu'en deuxième intention.
Quelles sont les règles à appliquer pour le nommage des outils ?

Dans le choix de l'outil par le LLM, il apparait que le nom de la fonction (= le nom de l'outil) est totalement prioritaire, que la la Docstring vient ensuite, elle-même prioritaire sur la métadonnée 'description' [1] . De toute évidence, ni la Docstring ni la description ne peuvent corriger un nom de fonction ambigu, elle ne serviront qu'en cas de deuxième intention du LLM, après avoir constaté une erreur.

Exemple d'ambiguïté

Considérons un outil qui convertit une date lisible par un humain (human-readable date) en timestamp. Initialement nommé 'convert_date_to_timestamp'. On peut constater que l'usage de l'outil est mal compris par le LLM qui, notamment, peut tenter de l'utiliser à l'envers.

Le mot "date" est trop générique, et dans un contexte LLM, il peut désigner aussi bien une date lisible qu'un timestamp.

Pour éviter toute ambiguïté, il faut que le nom de l'outil encode clairement :

le type d'entrée attendu (ex. : texte lisible par un humain),
le type de sortie produit (ex. : timestamp numérique),
et idéalement, la direction de la conversion : l'entrée en tête, la sortie en queue.

Un meilleur choix serait : readable_date_to_timestamp

readable_date désambiguïse immédiatement : ce n'est pas un timestamp.
to_timestamp indique clairement la direction.
C'est court, typiquement LLM-friendly, et sans ambiguïté.

Ce qu'il faut éviter :

Des noms ambigus comme convert_dates ou parse_date (trop flous)
Des noms au singulier pour des fonctions vectorisées (ex. date_to_timestamp qui prend une liste)
Des noms inverses (timestamp_to_date) qui risquent d'être utilisés à contresens si mal nommés

Distinction entre fonction unitaire et vectorisée

L'outil readable_date_to_timestamp est 'unitaire' dans le sens où il n'effectue qu'une seule conversion.

Prenons le cas d'un outil qui transformerait une liste de dates humainement lisibles en la liste des timestamps correspondants. Comment nommer un tel outil ? Un nom comme readable_dates_to_timestamps sera bien interprété par un LLM comme une opération vectorisée (liste → liste), surtout si :

le nom est au pluriel (dates, timestamps),
il suit une convention claire et régulière dans l'ensemble des outils,
la Docstring ou l'intension associé confirme ce comportement,
on évite (faut-il le préciser ?) de créer des outils d'intention différente avec un nom similaire.

Pourquoi ce nom est bien compris :

readable_dates → explicite que l'entrée est une liste de dates lisibles.
to_timestamps → suggère une transformation vers une liste de timestamps.
Le pluriel des deux côtés induit une correspondance élément par élément.

Mais il y a quelques subtilités à garder en tête pour éviter toute confusion. C'est une convention que les LLM comprennent bien, surtout si :

on l'applique systématiquement (ex. : texts_to_embeddings, urls_to_titles, etc.),
il existe (comme dans notre exemple) la version unitaire.

l'outil expose une Docstring explicite et non contradictoire :

"""
Converts a list of human-readable date strings into a list of UNIX timestamps in milliseconds.
"""

on expose aussi une version unitaire : readable_date_to_timestamp → pour une seule date readable_dates_to_timestamps → pour une liste
on évite les inversions en exposant les outils inverses : timestamp_to_readable_date → pour une seule date timestamp_to_readable_date → pour une liste

Encore un défaut !

Cependant, notre exemple présente encore un défaut : la Docstring fait apparaître le timestamp comme étant un 'UNIX timestamps in milliseconds'. Or, fin 1990-début 2000 sont apparus les timestamp en microsecondes puis, dans les années 2010, en nanosecondes.

Le LLM risque de découvrir trop tard (en reprenant le raisonnement après avoir constaté l'erreur, si elle est détectée) que l'outil ne fonctionne qu'avec des timestamps en millisecondes !

Prenant modèle sur Python, il faut renommer nos fonctions avec timestamp_ms ou timestamp_ns [2] . Voici donc le jeu complet (pour un format millisecondes) : readable_date_to_timestamp_ms readable_dates_to_timestamps_ms timestamp_ms_to_readable_date timestamp_ms_to_readable_date

Sur ce sujet, voir également : ReAct : la carte des intentions : Intent Map

[1] La distinction entre Docstring et métadonnée 'description' existe dans l'objet FunctionTool mais pas dans le modèle de données MCP dans lequel il n'existe que la description de l'outil.

[2] Cependant, Python n'a pas de fonction pour traiter les microsecondes ; on adoptera timestamp_us ?

ReAct : la carte des intentions : Intent Map

Bertrand Degoy — 2025-12-15T12:31:00Z

Dans la sélection d'un outil par le LLM, le nom de l'outil est prioritaire, la description est secondaire. Il va falloir opérer une pré-sélection des outils sur une meilleure base, avant de les passer au LLM.
C'est ici qu'apparaît la carte des intentions (Intent Map).

Dans la sélection d'un outil par le LLM, il apparaît que le nom de l'outil est prioritaire, et que la description est secondaire [1]. De toute évidence, la description ne sert au LLM qu'en deuxième intention, le plus souvent sur une reprise après erreur. La première sélection de l'outil est fondée sur une base trop sommaire.

La carte des intentions (Intent Map)

Puisque le LLM ne fait pas le travail avec suffisamment de discernement, il va falloir opérer une pré-sélection des outils au niveau de l'orchestrateur, avant de les passer au LLM. Il convient également de limiter le nombre d'outils passés avec le prompt afin de maîtriser le nombre de tokens envoyés au LLM.

C'est ici qu'apparaît la carte des intentions (Intent Map).

L'Intent Map fait le lien entre les noms techniques des outils et leur intention métier explicite. C'est un dictionnaire de la forme :

```
intent_map = {
"readable_dates_to_timestamps_ms": "Convert a list of human-readable dates into a list of UNIX timestamp expressed in milliseconds."
"extract_dates": "Extraire une plage de dates à partir d'un texte",
"filter_by_range": "Filtrer une liste d'interventions selon une période",
"summarize_notes": "Résumer une série de notes médicales",
}
```

Télécharger

Pour les toolbox que nous gérons, l'Intent Map pourra être générée automatiquement à partir d'une métadonnée 'intent' des outils, ou d'une propriété 'intent_map' de la toolbox. Sinon, l'Intent Map devra être écrite manuellement.

L'Intent Map permet à l'orchestrateur (classe ToolRouter) de sélectionner les outils selon l'intention.

De plus, notre outil de création de macro-outil (classe MacroToolBuilder) pourra créer automatiquement la Docstring macroscopique en se fondant sur les intentions des outils qui la composent.

Des cas où l'Intent Map est essentielle !

ToolFactory : Dans cet article ReAct : ToolFactory nous montrons comment la classe ToolFactory peut créer automatiquement des outils à partir de fonctions des bibliothèques Python. On peut constater que les descriptions des fonctions sont particulièrement pauvres et parfois inadaptées à la sélection par un LLM. Dans ce cas, une Intent Map sera essentielle à la bonne sélection des outils. Il est à craindre qu'il faille la construire manuellement !

MCP : Dans le cas des outils MCP (Model Context Protocole), les noms d'outils et leur description sont gérés du côté du serveur MCP, possiblement hors de portée de l'organisation. Si les descriptions sont mal rédigées, ou rédigées avec un vocabulaire hors du métier, une Intent Map sera essentielle à la bonne sélection des outils. Il faudra évidemment la construire manuellement.

Comprendre la sélection des outils

Il est important de considérer la manière dont un agent ReAct sélectionne et priorise les outils. Ce sera la même méthode pour la pré-sélection au niveau de l'orchestrateur.

C'est tool.metadata.description qui est envoyée au LLM.

Le LLM lit la description pour choisir un outil, pas pour comprendre toute la documentation. Lorsqu'un agent ReAct doit choisir un outil, il cherche une correspondance sémantique forte sur les points suivants :

Quel est le nom de l'outil ?
Quelle est l'action principale ?
Sur quel type d'objet travaille-t-il ?

Seule l'intention est réellement utile pour la sélection d'outil.

Le reste (détails, paramètres, avertissements) n'aide pas à la sélection, au contraire : plus la description est longue, plus on augmente le risque d'erreurs de sélection. Une description longue rend l'outil moins distinctif dans l'espace vectoriel du modèle et abouti à une moindre précision dans la sélection.

Bonnes pratiques pour la rédaction des Intentions :**

Les valeurs doivent être des descriptions métier claires, pas des signatures techniques.
Elles doivent être formulées à l'infinitif.
Elles doivent éviter les termes ambigus.
Bien définir le vocabulaire (les mots et leur sémantique) dans un lexique du métier, et s'y conformer.

Exemple concret (de ce qu'il ne faut pas faire) :

Si on envoie ceci :

extract_values_by_key(dict_list, key)
Extract all values associated with a given key from a list of dictionaries.
Retrieve the values corresponding to a specific key within a collection of objects.
Iterates through a list of items and returns only the values for which:
- the item is a dictionary
- the key exists

On augmente les collisions avec d'autres outils. :

“collection of objects” → outil générique
“iterate through items” → ressemble à un filtre
“values” → ressemble à un extracteur
“dictionary” → structure spécifique
“key exists” → condition logique
“list” → structure séquentielle

Ce qu'il faut écrire :

extract_values_by_key(dict_list, key)
Extract all values associated with a given key from a list of dictionaries.

C'est tout !

La génération systématique de la description

Il faut considérer deux champs : tool.description et tool.metadata.description.

Si on ne définit pas le champ 'description' de l'outil, tool.metadata.description sera élaboré par LlamaIndex à partir de la Docstring, en lui appliquant des heuristiques qui ajoutent parfois la signature, reformate, supprime certains éléments, interprète le Markdown, modifie l'ordre des lignes etc.. Bref : on ne peut se fonder dessus pour fournir l'intention.

Pour garantir que la première ligne soit un résumé clair, LlamaIndex ajoute parfois la signature en appliquant cette heuristique :

Si la docstring commence par une phrase simple → pas de signature
Si la docstring commence par du Markdown, une ligne vide, un titre, du gras, etc. → signature ajoutée. Ce comportement est : non documenté, non stable, différent selon les versions, influencé par le format de la docstring. De plus, la signature est sans valeur sémantique, elle ajoute du bruit et dégradera la sélection.

metadata.description doit n'avoir que l'intention sur une ligne

Pour reprendre le contrôle, il faut toujours définir le champ description, et ce, sous la forme d'une Intention. cela écrasera metadata.description. Le LLM verra exactement ce que l'on veut qu'il voie.

La meilleure pratique :

Garder la docstring pour les humains et pour la deuxième intention.
Pour le LLM, fournir explicitement `metadata.description='intention' en une phrase.

Le rôle de la docstring pour la deuxième intention

Il s'agit d'un un autre mécanisme de LlamaIndex qui entre en jeu uniquement après une erreur.

Quand un outil échoue (exception Python, mauvais arguments, etc.), LlamaIndex renvoie au LLM un Tool Error Message. Ce message contient :

l'erreur Python,
la docstring complète de l'outil (ou une version nettoyée),
parfois la signature,
parfois des instructions supplémentaires.

En effet, pour poursuivre le raisonnement en le modifiant (ne pas répéter l'erreur), le LLM doit être capable de :

comprendre pourquoi l'appel a échoué,
reformuler un appel correct,
réessayer avec les bons arguments,
ajuster son comportement.

Et pour ça, il a besoin d'informations plus détaillées que celles utilisées pour la sélection initiale.

Première intention : sélection d'outil → intention courte
Deuxième intention : correction d'erreur → docstring détaillée

En résumé :

Le LLM ne voit que metadata.description pour choisir un outil.
Le LLM voit la docstring complète uniquement après une erreur.
il faut écrire des docstrings détaillées.
on doit mettre uniquement l'intention dans metadata.description.

Sur ce sujet, voir également :
– ReAct : le nommage des outils.

[1] En revanche, la description sera utile pour définir le schéma d'entrées attendues par l'outil.

ReAct : ToolFactory

Bertrand Degoy — 2025-12-02T13:30:48Z

ToolFactory est une bibliothèque d'utilitaires permettant de créer des Outils de Fonction (FunctionTool) à partir d'une bibliothèque de fonctions Python.

La fonction auto_toolkit

Cette fonction génère dynamiquement une liste de `FunctionTool` LlamaIndex à partir des fonctions publiques d'un module Python.

Elle inspecte les fonctions du module fourni, applique des filtres d'inclusion/exclusion, et transforme chaque fonction retenue en outil agentifiable (`FunctionTool`) via l'examen de sa signature et de sa documentation.

Paramètres :
module (ModuleType) :
Le module Python à analyser (ex. : `statistics`, `math`, ou un module métier).
include (List[str], optionnel) :
Liste blanche : noms de fonctions à inclure explicitement. Si None, inclut toutes les fonctions publiques.
exclude (List[str], optionnel) :
Liste noire : noms de fonctions à ignorer. Prioritaire sur `include`.
verbose (bool, optionnel) :
Si True, affiche dans la console les outils ajoutés et les erreurs éventuelles.

Retour :
List[FunctionTool] :
Liste des objets `FunctionTool` générés à partir des fonctions sélectionnées.

Usage :
from modules.tools.tool_factory import auto_toolkit
tools = auto_toolkit(
statistics,
include=["mean", "stdev", "median"],
tags=["statistique"],
verbose=True

Voici l'essentiel du code :

## Usinage ##
def auto_toolkit(
module: ModuleType,
*,
include: List[str] = None,
exclude: List[str] = None,
verbose: bool = False,
**kwargs
) -> List[FunctionTool]:
"""
Génère une liste de FunctionTool LlamaIndex à partir des fonctions publiques d'un module.
Applique automatiquement les décorateurs d'entrée/sortie pour compatibilité agentique.
Test : test_auto_toolkit.py
Paramètres
----------
module : ModuleType
Module Python à inspecter (ex. statistics, math, ou module maison)
include : list of str, optional
Liste blanche : noms de fonctions à inclure (si spécifié)
exclude : list of str, optional
Liste noire : noms de fonctions à ignorer
verbose : bool
Si True, affiche les outils ajoutés
**kwargs : dict
Métadonnées supplémentaires à passer à `as_llama_tool` (ex. tags, metadata, etc.)
Returns
-------
List[FunctionTool]
Liste d'outils LlamaIndex prêts à être enregistrés dans un agent
"""
tools = []
total = 0
success = 0
for name, fn in inspect.getmembers(module, inspect.isfunction):
if name.startswith("_"):
continue
if include and name not in include:
continue
if exclude and name in exclude:
continue
total += 1
try:
# Application des décorateurs d'entrée et de sortie
decorated_fn = react_tool_output(react_tool_input(fn))
decorated_fn = react_tool_output(name)(decorated_fn )
# Création du FunctionTool avec métadonnées
tool = as_llama_tool(
name=name,
**kwargs
)(decorated_fn)
tools.append(tool)
success += 1
if verbose:
trace(f"Outil ajouté : {get_tool_name(tool)}", logger)
except Exception as e:
trace(f"Erreur lors de l'ajout de l'outil '{name}': {e}", logger)
trace(f"{success} outils ajoutés avec succès sur {total} fonctions inspectées.", logger)
return tools

Télécharger

Voici le code pour générer automatiquement des outils de fonction à partir du module 'statistiques. Noter que l'on peut choisir les fonctions à importer.

from modules.tools.tool_factory import auto_toolkit
tools += auto_toolkit(
statistics,
include=["mean", "stdev", "median", "variance"],
verbose=True
)

Télécharger

Modules Python et fonctions utilisables

Tous les modules Python ne sont pas pertinents pour produire des FunctionTool exploitables dans un agent. Voici une sélection affinée, classée selon leur **pertinence, c'est-à-dire leur capacité à fournir des fonctions :

publiques
pures ou quasi-pures
typées
documentées
auto-validables via fn_schema

Module	Pertinence
statistics	Fonctions bien typées, docstring claires, signatures simples
math	Fonctions scalaires pures, typées, robustes
cmath	Idem, mais pour les complexes
decimal	Fonctions précises pour calculs financiers
fractions	Manipulation exacte de rationnels
datetime	Fonctions de manipulation de dates (attention à la mutabilité)
calendar	Fonctions pures sur les jours, semaines, années
itertools	Générateurs utiles, mais nécessite des wrappers pour être agentifiables
functools (partiellement)	Quelques fonctions décorables (ex. reduce) si bien encapsulées

Voici un tableau synthétique des fonctions principales pour chaque module Python standard qui peuvent être transformés en FunctionTool par tool_factory, avec leur description.* Ces fonctions sont typées, documentées, et généralement compatibles avec FunctionTool*.

statistics — Statistiques descriptives

Fonction	Description
mean(data)	Moyenne arithmétique
fmean(data)	Moyenne arithmétique rapide (float uniquement)
geometric_mean(data)	Moyenne géométrique
harmonic_mean(data)	Moyenne harmonique
median(data)	Médiane
median_low(data)	Plus grande valeur ≤ médiane
median_high(data)	Plus petite valeur ≥ médiane
median_grouped(data, interval=1)	Médiane pour données groupées
mode(data)	Valeur la plus fréquente
multimode(data)	Liste des valeurs les plus fréquentes
pstdev(data, mu=None)	Écart-type de la population
stdev(data, xbar=None)	Écart-type de l'échantillon
pvariance(data, mu=None)	Variance de la population
variance(data, xbar=None)	Variance de l'échantillon
quantiles(data, , n=4, method='exclusive')*	Découpe en quantiles
covariance(x, y)	Covariance entre deux séries
correlation(x, y)	Corrélation de Pearson
linear_regression(x, y)	Régression linéaire (renvoie pente et intercept)

math — Mathématiques de base

Fonction	Description
sqrt(x)	Racine carrée
exp(x)	Exponentielle
log(x, base=math.e)	Logarithme (base e par défaut)
log10(x)	Logarithme décimal
log2(x)	Logarithme base 2
pow(x, y)	Puissance ( x^y )
fabs(x)	Valeur absolue
factorial(x)	Factorielle
gcd(a, b)	Plus grand commun diviseur
lcm(a, b)	Plus petit commun multiple
ceil(x)	Arrondi supérieur
floor(x)	Arrondi inférieur
trunc(x)	Troncature (partie entière)
sin(x), cos(x), tan(x)	Fonctions trigonométriques
degrees(x), radians(x)	Conversion angle ↔ radians
isclose(a, b)	Comparaison flottante
isnan(x), isinf(x), isfinite(x)	Tests numériques

cmath — Mathématiques complexes

Fonction	Description
sqrt(x)	Racine carrée complexe
exp(x)	Exponentielle complexe
log(x, base=math.e)	Log complexe
phase(x)	Argument (angle) d'un nombre complexe
polar(x)	Coordonnées polaires
rect(r, phi)	Conversion polaire → cartésien
sin(x), cos(x), tan(x)	Trigonométrie complexe

decimal — Calculs décimaux précis

Fonction	Description
Decimal(x)	Crée un nombre décimal précis
getcontext()	Accès au contexte (précision, arrondi)
setcontext(ctx)	Définit un contexte personnalisé
localcontext()	Contexte temporaire
Méthodes : sqrt(), ln(), exp(), quantize(), etc.	Opérations précises sur Decimal

fractions — Calculs exacts avec fractions

Fonction	Description
Fraction(x)	Crée une fraction exacte
limit_denominator(max_denominator)	Approximation avec dénominateur borné
Opérations : +, -, , /, *	Calculs exacts entre fractions ou entiers

datetime — Dates et heures

Fonction	Description
datetime(year, month, day, ...)	Objet date-heure
date(year, month, day)	Objet date
time(hour, minute, ...)	Objet heure
timedelta(...)	Durée
now(), today(), utcnow()	Horodatages actuels
Méthodes : isoformat(), weekday(), strftime()	Formatage et manipulation

calendar — Calendriers

Fonction	Description
isleap(year)	Année bissextile ?
monthrange(year, month)	Premier jour et nombre de jours
monthcalendar(year, month)	Matrice des semaines
weekday(year, month, day)	Jour de la semaine
month_name, day_name	Noms localisés

Sources : Python 3.14 Standard Library Documentation

Glossaire et conventions de nommage

Bertrand Degoy — 2025-12-02T09:46:42Z

Glossaire et conventions pour outils agentiques (ReAct, FunctionTool, ToolRouter)

Glossaire

Terme	Définition opérationnelle	Remarques
Outil (`Tool`)	Fonction callable exposée à l'agent, avec nom, description, schéma d'entrée, et logique métier	Peut être décorée ou encapsulée
FunctionTool	Représentation structurée d'un outil, incluant nom, description, paramètres typés, fonction Python, etc.	Format utilisé dans LangChain, CrewAI, ou orchestrateurs maison
Observation	Résultat retourné par un outil, interprété par l'agent comme une réponse à une action	Doit être lisible, typée, et sans ambiguïté
ReAct	Paradigme Reasoning + Acting : l'agent réfléchit, choisit un outil, observe le résultat, et recommence	Nécessite des outils bien décrits et des observations claires
Décorateur ReAct	Fonction qui encapsule un outil pour gérer les cas nuls, erreurs, ou formats d'observation	Ex : `@react_tool_output`
Toolkit	Collection d'outils regroupés par domaine ou usage, souvent injectée dans un agent	Peut être statique ou générée dynamiquement
ToolRouter	Mécanisme de filtrage intelligent qui sélectionne dynamiquement les outils pertinents à injecter dans le contexte	Peut être basé sur tags, embeddings, ou règles
Vectorisation	Transformation d'un texte (requête ou description) en vecteur sémantique pour calcul de similarité	Terme préféré à “encodage”
Matching sémantique	Comparaison de vecteurs pour identifier les outils les plus proches d'une requête	Utilise souvent la similarité cosinus
Tag	Étiquette sémantique associée à un outil (`"math"`, `"stat"`, `"juridique"`, etc.) pour faciliter le routage	Peut être manuel ou généré automatiquement
Schéma Pydantic	Définition typée des paramètres d'un outil, utilisée pour validation, documentation, ou génération automatique	Peut être dérivé des annotations Python

Conventions de nommage et structuration

Outils (`FunctionTool`)

Nom : snake_case, explicite (calcul_moyenne, recherche_siret)
Description : phrase complète, actionnable, sans jargon
Paramètres : typés, nommés en français si l'agent est francophone
Retour : typé, clair, sans structure parasite
### Toolkits
Regroupés par domaine : math_tools, stat_tools, admin_tools
Générés via auto_toolkit(module, tags=...) si besoin

Décorateurs

@react_tool_output : appliqué uniquement si gestion des cas nuls ou erreurs souhaitée
@as_function_tool(...) : pour enregistrer automatiquement dans un registre

Routage

ToolRouter vectoriel : basé sur SentenceTransformer ou OpenAIEmbeddings
Tags : utilisés comme filtre rapide avant vectorisation
Matching : top-k outils par similarité cosinus
Fallback : si aucun outil n'est pertinent, retour explicite "Aucun outil pertinent trouvé"

ReAct et intégration des données temps réel avec MCP ( Model Context Protocol )

Bertrand Degoy — 2025-11-25T16:55:27Z

L'intégration du standard MCP ( Model Context Protocol ) dans une architecture ReAct permet de déployer des agents IA capables de raisonner en s'appuyant sur les données de l'entreprise en temps réel tout en simplifiant les connexions, réduisant les coûts d'intégration, et renforçant la sécurité. C'est un levier puissant pour industrialiser l'IA dans les environnements métiers de l'industrie 4.0.

Moteur ReAct et intégration de données actualisées

ReAct ( Reasoning and Acting ) est un algorithme qui permet à une intelligence artificielle de raisonner étape par étape en interagissant avec des outils métier ou des sources de données. Plutôt que de répondre directement à une question, l'IA peut décomposer le problème, expliquer sa démarche, chercher des informations à chaque étape, puis formuler une réponse précise et pertinente. C'est particulièrement utile dans les environnements complexes ou dynamiques, comme ceux de l'industrie 4.0, où les décisions doivent s'appuyer sur des données actualisées et des raisonnements structurés.

Grâce à l'approche ReAct, le système est désormais capable de conduire des raisonnements en plusieurs étapes au sein d'un même échange. Cette capacité lui permet de mieux comprendre les intentions de l'utilisateur, d'ajuster ses hypothèses en temps réel et de formuler des réponses plus précises, contextualisées et explicites. Il s'appuie pour cela sur des données dynamiques, issues en temps réel des outils et services de l'entreprise, croisées intelligemment avec la documentation interne. Ce double ancrage garantit une pertinence accrue des réponses, même dans des contextes complexes, ambigus ou en constante évolution.

Cette faculté d'interaction s'inscrit pleinement dans la logique de l'Industrie 4.0, où l'intelligence artificielle agit comme une aide cognitive, interconnecté aux systèmes physiques et numériques pour renforcer la réactivité, la traçabilité et la prise de décision.

Mais déjà, l'horizon s'élargit : avec l'émergence de l'Industrie 5.0, l'accent se déplace vers une collaboration plus étroite entre l'humain et la machine. Les jumeaux numériques, en particulier, deviennent des instruments puissants d'intelligibilité opérationnelle, offrant aux opérateurs une vision fine, prédictive et explicable des processus industriels.

Architecture modulaire de nos outils ReAct

GeneralToolKit : Fournit des outils génériques toujours disponibles pour tous les raisonnements.
ThemeToolKit : Permet à chaque thème métier d'exposer ses propres outils spécifiques, y compris un outil RAG (Research Augmented Generation) pour exploiter la documentation privée de l'entreprise.
ToolKit temps réel : Un module dédié expose des outils connectés à des sources de données en temps réel, qu'elles soient internes à l'entreprise ou issues de services tiers (cloud ou edge-on-premise).

L'outil RAG (Research Augmented Generation)

La méthode RAG permet de construire des agents conversationnels (chat bots) intégrant la documentation de l'entreprise. Ces données ont un caractère statique, même si de nouveaux documents ou de nouvelles versions des documents peuvent être ingérées très régulièrement. L'entreprise y intègrera ses historiques et sa documentation de référence.

Dans notre architecture, un module RAG est mis à la disposition de la boucle ReAct sous forme d'outil, lui permettant d'appuyer ses raisonnements sur :

des documents historiques (rapports, données informelles ...),
un référentiel documentaire (procédures, notices techniques ...),
des routines permettant d'orienter le raisonnement pour effectuer des tâches répétitives.

Accès aux données d'entreprise en temps réel

Le ToolKit temps réel, fondé sur MCP (Model Context Protocol), est crucial pour les cas d'usage métier avancés. Il permet au moteur ReAct de :

Interroger dynamiquement des données métiers (ERP, CRM, documentation interne, notices techniques, procédures etc.)
Consommer des flux de données actualisées (API internes, capteurs, machines, services cloud)
Fournir des réponses contextuelles et à jour, en s'appuyant sur des données opérationnelles en direct.

Les outils du ToolKit temps réel font appel au standard MCP pour l'importation des données.

Le standard MCP

Le standard MCP permet de connecter facilement une IA à des données et outils d'entreprise en temps réel, ce qui renforce considérablement les capacités du moteur ReAct décrit précédemment.

C'est un protocole ouvert lancé fin 2024 par Anthropic. Il vise à standardiser la connexion entre les modèles d'intelligence artificielle (comme les LLMs ou agents ReAct) et les sources de données ou outils externes (ERP, CRM, bases de données, APIs, capteurs, machines etc.).

On le compare souvent à un "USB-C de l'IA" : une interface universelle qui remplace les intégrations sur mesure, souvent complexes, coûteuses et peu maintenables.

Quels bénéfices avec le moteur ReAct et les données temps réel ?

Dans le contexte du moteur ReAct que nous mettons en oeuvre, MCP apporte plusieurs avantages clés :

Connexion directe aux données d'entreprise en temps réel : MCP permet d'interroger des systèmes internes ou des services cloud sans passer par des intégrations spécifiques. Cela complète parfaitement le ToolKit temps réel mentionné dans ton document.
Recherche par étapes plus fluide : Grâce à MCP, chaque appel du moteur ReAct à un outil externe (comme le QueryEngineTool) peut se faire via une interface unifiée, facilitant les raisonnements multi-étapes avec des données toujours à jour.
Réduction de la dette technique : Plus besoin de maintenir des connecteurs maison ou des orchestrateurs complexes. MCP simplifie l'architecture et améliore la maintenabilité des agents IA.
Interopérabilité et évolutivité : Le moteur ReAct peut s'adapter à différents environnements métiers sans modification profonde, en s'appuyant sur le standard MCP pour accéder aux bons outils et données.
Sécurité renforcée : Le protocole MCP intègre des mécanismes de contrôle d'accès et de journalisation, ce qui est crucial pour les environnements sensibles ou réglementés.

Bénéfices pour la prise de décision

Réactivité accrue : Les agents peuvent s'adapter à l'évolution des données sans redéploiement.
Personnalisation métier : Les outils spécifiques par thème permettent d'aligner les raisonnements sur les données métier et le vocabulaire de chaque domaine.
Interopérabilité : Ouverture aux systèmes d'information existants via des connecteurs temps réel standardisés.

Un outil Hybrid Search pour ReAct

Bertrand Degoy — 2025-11-25T10:27:36Z

Un outil ReAct pour LlamaIndex qui effectue des recherches RAG via embedding-based retrieval.
A partir d'une question de l'utilisateur, c'est une approche en deux temps :
– On construit un outil ReAct prêt à brancher sur nos index RAG existants : un objet RetrieverTool qui exécute une recherche par embeddings, renvoie les passages top‑k formatés pour l'agent, et supporte le filtrage par métadonnées et hybrid search.
– On passe le résultat au LLM pour mettre la réponse en forme.

Nota : développement en cours

Contexte et Prérequis

Contexte :
– un serveur privé,
– le langage Python,
– les bibliothèques LlamaIndex et HugginFace,
– un LLM capable de fonctions (ex. : Mistral medium ou large),
– un modèle d'embeddings compatible (ex. : Sentence-BERT, OpenAI embeddings, BAAI Bge small etc.).

Prérequis :
Un index de documents construit avec nos outils : Ingestion : le RAG Manager, Le Web Service IngestWSG.

La construction de l'outil RetrieverTool

# retriever_tool.py
 from typing import List, Dict, Any
 from llama_index import Document
 
 class RetrieverTool:
 def __init__(self, retriever, embedder=None, hybrid_fn=None):
 self.retriever = retriever
 self.embedder = embedder
 self.hybrid_fn = hybrid_fn
 
 def run(self, query: str, k: int = 5, metadata_filter: Dict[str,Any] = None, hybrid: bool = False) -> List[Dict]:
 # Optionnel : hybrid search combine lexical + vector
 if hybrid and self.hybrid_fn:
 hits = self.hybrid_fn(query, k=k, metadata_filter=metadata_filter)
 else:
 # LlamaIndex retriever: get top-k documents (API may be retrieve or get_relevant_documents)
 hits = self.retriever.retrieve(query, search_kwargs={"k": k, "filter": metadata_filter})
 results = []
 for doc in hits:
 text = getattr(doc, "text", str(doc))
 meta = getattr(doc, "metadata", {})
 # Optionnel : tronquer / extraire passage le plus pertinent
 snippet = text[:1000]
 results.append({"snippet": snippet, "metadata": meta, "source_id": meta.get("source_id")})
 return results

Filtrage par métadonnées

Le filtrage par métadonnées consiste à appliquer des contraintes booléennes ou de plage avant ou après la recherche vectorielle pour ne considérer que les documents pertinents au contexte métier. Exemples de métadonnées : source, langue, date, client_id, mention de confidentialité etc.

En pratique on peut :
• Pré‑filtrer l'ensemble indexé (ex. ) puis exécuter la recherche vectorielle sur ce sous‑ensemble ;
• Post‑filtrer les résultats vectoriels (réduire ou réordonner) si le moteur vectoriel ne supporte pas de filtre natif.
Avantage clé : réduit le bruit et évite que des documents hors‑contexte soient ramenés au LLM, ce qui diminue les hallucinations et le coût des appels LLM.

Patterns d'implémentation
• Filtres simples : dictionnaire transmis au retriever (beaucoup de vector stores supportent un paramètre filter).
• Filtres complexes : expressions booléennes ou fonctions de scoring métier (ex. boost si client_id correspond).
• Sécurité : appliquer les règles d'accès (ACL) en pré‑filtre pour éviter toute fuite d'information.

Bonnes pratiques :
• limiter le nombre de documents renvoyés (k = 3–10),
• renvoyer des snippets + métadonnées pour que l'agent puisse raisonner.

Hybrid Search

Le concept hybrid search désigne la combinaison d'une recherche lexicale (BM25/keyword) et d'une recherche sémantique (embeddings) pour améliorer précision et rappel.

Le hybrid search combine une recherche lexicale (BM25 ou TF‑IDF) et une recherche vectorielle (embeddings) pour tirer parti des forces complémentaires :
– BM25 excelle sur les correspondances exactes et mots‑clés,
- les embeddings capturent le sens et les synonymes.
Le flux typique consiste à exécuter BM25 et vector search séparément, fusionner les listes et reranker (ou reranker uniquement les top N).

Stratégies de fusion et pondération
– Score normalisé : normaliser scores BM25 et vectoriels (min‑max) puis combiner : `score = α * score_vector + (1-α) * score_bm25`. Ajuster `α` selon requête (courte → plus lexical).
– Ensemble / cascade : BM25 pour récupérer candidates (large), puis rerank par similarité vectorielle. Ou inversement si on veut donner la priorité au sémantique.
– Reranking par LLM : prendre top‑N fusionnés et demander au LLM de reranker ou d'extraire les passages clés.

Conseils pratiques et pièges à éviter
– Mesurer : A/B test avec métriques de rappel/precision et qualité des réponses LLM.
– Coût : hybrid augmente les opérations (deux recherches) — cache les embeddings de requêtes et les résultats fréquents.
– Normalisation : tokenisation cohérente entre index lexical et embeddings.
– Sécurité et filtres : toujours appliquer ACL en pré‑filtre.

Exemple minimal (pseudocode)

bm25_hits = bm25.search(query, k=50)
 vec_hits = vector_store.search(query_embedding, k=50, filter=meta_filter)
 candidates = merge_and_dedup(bm25_hits, vec_hits)
 for c in candidates: c.score = alpha*norm(c.vec_score)+(1-alpha)*norm(c.bm25_score)
 top = sorted(candidates, key=lambda x: x.score, reverse=True)[:k]

exemple concret pour FAISS + BM25 (code prêt à brancher sur l'index) :

from rank_bm25 import BM25Okapi
 from sentence_transformers import SentenceTransformer
 import faiss
 import numpy as np
 
 # documents: list of dicts {'id':int,'text':str,'meta':{...}}
 docs = load_documents() 
 
 # BM25
 tokenized = [d['text'].split() for d in docs]
 bm25 = BM25Okapi(tokenized)
 
 # Embeddings + FAISS
 model = SentenceTransformer('paraphrase-MiniLM-L6-v2')
 embs = model.encode([d['text'] for d in docs]).astype('float32')
 index = faiss.IndexFlatL2(embs.shape[1])
 index.add(embs)
 id_map = {i: docs[i]['id'] for i in range(len(docs))}
 meta_map = {d['id']: d['meta'] for d in docs}
 
 def hybrid_search(query, k=10, meta_filter=None, alpha=0.6):
 # BM25 candidates
 bm25_scores = bm25.get_scores(query.split())
 bm25_top = np.argsort(bm25_scores)[-200:][::-1]
 
 # Vector candidates (apply meta_filter by masking ids)
 q_emb = model.encode([query]).astype('float32')
 D, I = index.search(q_emb, 200)
 vec_candidates = I[0]
 
 # Merge and dedupe
 candidates = []
 seen = set()
 for idx in list(bm25_top) + list(vec_candidates):
 doc_id = id_map[idx]
 if meta_filter and not meta_matches(meta_map[doc_id], meta_filter):
 continue
 if doc_id in seen: continue
 seen.add(doc_id)
 candidates.append({
 'doc_id': doc_id,
 'bm25_score': float(bm25_scores[idx]),
 'vec_score': float(1.0 / (1.0 + D[0][list(vec_candidates).index(idx)]) ) if idx in vec_candidates else 0.0
 })
 
 # Normalize and combine
 bm = np.array([c['bm25_score'] for c in candidates])
 ve = np.array([c['vec_score'] for c in candidates])
 if len(bm)>0:
 bm_n = (bm - bm.min())/(bm.ptp()+1e-9)
 ve_n = (ve - ve.min())/(ve.ptp()+1e-9)
 for i,c in enumerate(candidates):
 c['score'] = alpha*ve_n[i] + (1-alpha)*bm_n[i]
 
 topk = sorted(candidates, key=lambda x: x['score'], reverse=True)[:k]
 return topk

LLM-based Retrieval ou Embedding-based Retrieval ?

Bertrand Degoy — 2025-11-25T10:05:11Z

LLM-based Retrieval utilise directement la capacité des grands modèles de langage à comprendre et raisonner sur une requête ; Embedding-based Retrieval transforme documents et requêtes en vecteurs et récupère par similarité.
Chacune a ses forces : compréhension contextuelle et flexibilité pour les LLMs ; scalabilité et rapidité pour les embeddings.

Pour les données structurées et les sélections exhaustives, les LLM sont inadaptés et les embeddings montrent des limites ; la solution proposée combine ReAct (orchestrateur LLM) + outils déterministes + RAG pour tirer parti des deux approches.

Nous évoquons des développements qui iraient dans le même sens : embeddings avec filtrage, recherche hybride.

LLM-based Retrieval et Embedding-based Retrieval sont deux approches utilisées pour récupérer des informations dans un système de recherche, mais elles diffèrent par leur fonctionnement et leurs applications. Voici une comparaison détaillée :

1. LLM-based Retrieval (Basé sur les Large Language Models)

Principe

Les Large Language Models (LLMs), comme OpenAI GPT, MistralAI ou d'autres modèles similaires, sont directement utilisés pour comprendre une requête et récupérer des informations pertinentes.
La récupération se fait en s'appuyant sur la capacité du LLM à comprendre le langage naturel et à raisonner sur les données ou documents disponibles.

Méthode

Le modèle est "interrogé" avec une requête.
Il peut soit :
- Générer une réponse directement en s'appuyant sur son entraînement (s'il est pré-entraîné sur un large corpus).
- S'appuyer sur un context augmenter en consultant des bases de connaissances ou des données supplémentaires pertinentes.

Avantages

Compréhension contextuelle avancée : LLM peut raisonner sur des requêtes complexes en tenant compte des subtilités linguistiques.
Flexible : Peut fournir une réponse directe ou agir comme un intermédiaire intelligent pour filtrer et reformuler des résultats.
Peu d'efforts de pré-traitement nécessaires : La requête peut être en langage naturel.

Inconvénients

Coût computationnel élevé : L'interrogation d'un LLM nécessite généralement beaucoup de ressources.
Risque d'erreurs contextuelles : Si les informations sont absentes ou mal structurées, les LLM peuvent "halluciner" (inventer des réponses).
Moins adapté pour des ensembles de données massifs sans techniques d'indexation supplémentaires.

2. Embedding-based Retrieval (Basé sur les embeddings)

Principe

Les embeddings sont des représentations vectorielles denses de données (textes, requêtes, documents, etc.).
Une récupération basée sur les embeddings repose sur la similarité entre les représentations vectorielles de la requête et des documents.

Méthode

Les textes (documents ou requêtes) sont transformés en vecteurs denses à l'aide d'un modèle pré-entraîné (par exemple, Sentence-BERT, OpenAI embeddings, etc.).
Une fois les vecteurs générés :
- La requête est également convertie en vecteur.
- Une recherche de proximité est effectuée (par exemple, en utilisant la cosine similarity ou une autre métrique) pour trouver les documents les plus pertinents.

Avantages

Efficacité sur de grands ensembles de données : Une fois les embeddings générés, les recherches sont rapides grâce à des techniques comme l'approximation de la recherche des plus proches voisins (ANN).
Robustesse aux variations linguistiques : Les embeddings capturent les relations sémantiques même si les mots exacts diffèrent.
Scalabilité : Bien adapté pour des millions ou milliards de documents.

Inconvénients

Nécessite un prétraitement initial : Les documents doivent être convertis en embeddings à l'avance. Cela va dans le sens de la frugalité et, le plus souvent, c'est la norme s'agissant du RAG dans les entreprises.
Moins bon pour les requêtes complexes : Peut manquer de compréhension contextuelle avancée comparée à un LLM.
Dépend des données d'entraînement du modèle : Si les embeddings ne capturent pas correctement les relations dans un domaine spécifique, la récupération sera sous-optimale.

Résumé des différences

Aspect	LLM-based Retrieval	Embedding-based Retrieval
Approche principale	Récupération basée sur les capacités du LLM à générer ou filtrer des résultats en langage naturel.	Basée sur des vecteurs sémantiques pré-calculés.
Compréhension contextuelle	Très élevée (grâce à la puissance des LLM).	Modérée (limitée aux relations sémantiques capturées).
Efficacité	Moins efficace pour les bases de données massives (coût élevé).	Très efficace après le calcul initial des embeddings.
Coût	Coût computationnel élevé à chaque requête.	Coût initial pour le calcul des embeddings, faible coût pour la recherche.
Applications	Questions complexes, dialogue, synthèse d'informations.	Recherche dans des bases massives de documents.

Cas d'utilisation typiques

LLM-based Retrieval : Systèmes de dialogue, assistant virtuel, recherche contextuelle avancée dans des données limitées.
Embedding-based Retrieval : Moteurs de recherche, récupération de documents scientifiques, bases de données denses. Les deux approches peuvent être combinées dans un système hybride pour tirer parti des forces de chacune (par exemple, utilisation d'embeddings pour une recherche rapide suivie d'un raisonnement contextuel via un LLM). C'est la base des outils RAG que nous développons : Outils d'IA textuels.

Les limites de la recherche par embeddings

Cet article : Theoretical Limitations of Embedding-Based Retrieval met en avant les limitations de la recherche par embeddings.

On y démontre l'incapacité d'une recherche par embeddings à retrouver 46 documents simples parmi un corpus de 50.000 documents ( noter que la recherche par LLM ne fait pas mieux, c'est d'ailleurs la raison pour laquelle l'article mentionné reste sur une solution par embeddings ) .

On peut observer que les "petits documents" sont des assertions simples telles que "Ellis Smith likes apples." Ces documents du genre "X aime Y", "W n'aime pas Z" etc. sont des assertions qui, d'un point de vue sémantique, ont peu ou pas de chances de partager un contexte commun : elles sont donc très dispersées dans l'espace vectoriel. Une requête par embeddings ne peut les sélectionner en une fois. L'expérience étant confirmée par la théorie, ceci est indiscutable.

Une fois cette démonstration faite, la suite de l'article porte sur une amélioration de la recherche par embeddings en introduisant une indexation multi vectorielle. Nous ne pouvons suivre cette voie qui procède de la recherche, pas de l'ingénierie.

Posons un constat :

les "petits documents" ont une forme quasi-formatée, assimilables à des données,
l'objectif du test est d'obtenir une sélection exhaustive,
le nombre de résultats recherchés dépasse largement le petit nombre de résultats qu'un LLM est capable de traiter en aval de la recherche - on s'accorde généralement sur un nombre de 3 à 10 (le fameux paramètre top-k).

La conclusion est évidente :

La recherche par embeddings n'est pas adaptée à la sélection exhaustive de données structurées.

Cependant, n'oublions pas que : La recherche par embeddings a fait ses preuves dans le domaine de la recherche informelle, notamment pour réaliser des chat bots, des aides en ligne etc .

Quelle solution pour traiter des données structurées ?

Nous sommes guidés par ce principe :

Aux outils les sélections déterministes pour sélectionner des données structurées et en extraire de l'informel. A l'IA le travail d'analyse et de synthèse sur de l'informel.

Notre solution - décrite ici RAG : Chat Engine ReAct avec outils - consiste à :

Construire notre application sur un algorithme ReAct (donc un LLM capable de fonctions) accédant à :

des outils de sélection de données métier, structurées ; ces outils sont déterministes et donnent des résultats exhaustifs,
un outil RAG, fondé sur la recherche par embeddings, dont le résultat est fourni au LLM pour analyse et synthèse .

En amont, ReAct sélectionnera les outils en fonction de la question. En aval, ReAct fera appel au LLM pour mettre en forme la réponse.

Prenons le cas idéal de la maintenance technique : les données sont à la fois structurées ( identifiants, catégorie, dates etc. ) et peuvent comporter des informations textuelles.

Les outils de sélection permettent d'accéder aux données de façon déterministe : les réponses sont exactes et complètes.
L'outil RAG sera employé pour synthétiser les informations textuelles contenues dans les réponses (telles que des commentaires, des observations) en effectuant des rapprochements avec les documents métiers (tels que des notices techniques, des prescriptions, des compte-rendus, des historiques etc.) .

Ainsi, des questions de l'utilisateur pourront être :

"Recherche les interventions sur la pompe N-92c et effectue une synthèse des pannes mentionnées"

"Fais moi une synthèse des pannes sur les pompes de la même référence"

Aller plus loin

Hybrid Search

L'article mentionne également la supériorité de l'algorithme BM25. BM25 capte les correspondances exactes et les mots‑clés ; les embeddings captent le sens et les synonymes. Les combiner corrige les faiblesses de chaque méthode. Le concept hybrid search désigne la combinaison d'une recherche lexicale (BM25/keyword) et d'une recherche sémantique (embeddings).

Filtrage par métadonnées

L'hybrid search pourrait être renforcé par filtrage : cela consiste à ne sélectionner que les documents qui respectent des contraintes structurées avant ou après la recherche par embeddings.

• Pré‑filtre : appliquer la contrainte sur une table de métadonnées des documents puis construire la requête dense/BM25 sur ce sous‑ensemble.

• Post‑filtre : exécuter la recherche dense puis éliminer les résultats dont les métadonnées ne correspondent pas (utile si le vector store ne supporte pas de filtre natif).

Il serait idéal de fournir à ReAct un outil de recherche fondé sur ces principes. Il en résulterait non seulement un avantage de précision, mais aussi une économie d'appel au LLM. Time is Energie !

Comparaison entre `class ReActAgent(Workflow)` et `ReActAgent` préconstruit...

Bertrand Degoy — 2025-11-16T08:45:30Z

Cet article compare deux approches pour concevoir un agent ReAct dans LlamaIndex :
– l'utilisation directe de l'agent ReAct fourni par la bibliothèque.
– l'implémentation personnalisée par héritage de `Workflow`

L'approche par héritage de `Workflow` est recommandée pour construire un système évolutif. Elle permet une maîtrise fine du raisonnement, notamment en permettant une meilleure utilisation des outils.

1. Utiliser `ReActAgent` depuis `llama_index.core.agent.workflow`

Définition

Utilisation de l'agent ReAct préconfiguré :

from llama_index.core.agent.workflow import ReActAgent
 
 agent = ReActAgent.from_tools(tools=[...], llm=..., memory=...)
 response = agent.chat("Quel est le prix du bitcoin ?")

Caractéristiques

– Agent ReAct prêt à l'emploi avec moteur de raisonnement, formatter et parser intégrés.
– Ne nécessite pas de définition de graphe ou d'étapes personnalisées.
– Moins flexible pour les cas avancés.

Cas d'usage

Approche adaptée pour :

– Prototypage rapide ou démonstration.
– Cas simples de question-réponse avec outils.
– Utilisation sans personnalisation profonde du raisonnement.

2. Hériter de `Workflow` pour construire un agent personnalisé

Définition

Création d'un agent en héritant explicitement de la classe `Workflow` :

from llama_index.core.workflow import Workflow
 
 class ReActAgent(Workflow):
 ...

Caractéristiques

– Permet de définir un graphe explicite d'étapes connectées via `add_step(...)` et `connect(...)`.
– Offre un contrôle total sur la logique de raisonnement, l'injection de mémoire, la gestion du contexte, l'utilisation des outils, etc.
– Autorise l'ajout d'étapes personnalisées (prétraitement, validation, résumés, appels API…).
– Requiert une bonne compréhension des événements (`StartEvent`, `PrepEvent`, etc.) et du moteur `Workflow`.

Voici, par exemple, une écriture de l'étape handle_tool_call qui permet une validation via introspection Pydantic de l'appel aux outils, avant l'étape d'observation (lignes 15 à 49). En effet, ReAct a la mauvaise habitude d'essayer d'utiliser les outils avant de prendre en compte la définition des schéma d'entrée. On gagne du temps en bloquant les appels faits avec des formats erronés.

@step
async def handle_tool_calls(
self, ctx: Context, ev: ToolCallEvent
) -> PrepEvent:
""" Appeller les outils en toute sécurité en gérant les erreurs et en ajoutant leurs résultats au raisonnement en cours. Ensuite, en émettant un PrepEvent, effectuer une nouvelle itération d'invite et d'analyse ReAct.
"""
tool_calls = ev.tool_calls
tools_by_name = {tool.metadata.get_name(): tool for tool in self.tools}
current_reasoning = await ctx.store.get(
"current_reasoning", default=[]
)
sources = await ctx.store.get("sources", default=[])
'''
validation anticipée via introspection Pydantic
On intercepte chaque appel, et pour chaque outil :
1. Identifier sa classe d'entrée Pydantic.
2. Instancier cette classe avec les tool_kwargs.
3. Si la validation échoue → bloquer l'appel et injecter une observation.
4. Sinon exécuter normalement.
'''
for tool_call in tool_calls:
tool_name = tool_call.tool_name
tool = tools_by_name.get(tool_name)
if not tool:
current_reasoning.append(
ObservationReasoningStep(observation=f"Tool {tool_name} does not exist")
)
continue
# Étape 1 : récupérer la classe Pydantic d'entrée
input_model = getattr(tool.metadata, "input_model", None)
if input_model:
try:
# Étape 2 : valider les kwargs via Pydantic
input_model(**tool_call.tool_kwargs)
except ValidationError as ve:
# Étape 3 : bloquer l'appel et injecter l'erreur
current_reasoning.append(
ObservationReasoningStep(
observation=(
f"Appel bloqué : les paramètres fournis pour l'outil '{tool_name}' "
f"sont invalides selon sa définition. Détail : {ve.errors()}"
)
)
)
continue
# Étape 4 : poursuivre si tout est valide
try:
tool_output = tool(**tool_call.tool_kwargs)
sources.append(tool_output)
current_reasoning.append(
ObservationReasoningStep(observation=tool_output.content)
)
except Exception as e:
current_reasoning.append(
ObservationReasoningStep(
observation=f"Error calling tool {tool.metadata.get_name()}: {e}"
)
)

Télécharger

Cas d'usage

Approche recommandée pour :

– Architectures modulaires et extensibles.
– Tracabilité et audit du raisonnement étape par étape.
– Utilisation du debugger Python dans le moteur ReAct.
– Intégration de politiques techniques explicites.
– Meilleur contrôle de l'utilisation des outils.
– Développement d'agents complexes ou hybrides.

Tableau comparatif

Critère	`class ReActAgent(Workflow)`	`ReActAgent` préconstruit
Architecture	Personnalisée, modulaire	Préconfigurée
Graphe d'étapes	Défini manuellement (`add_step`)	Interne, non modifiable
Injection mémoire/contexte	Libre et dynamique	Partielle via `.chat()`
Contrôle sur le raisonnement	Total	Limité
Extensibilité	Élevée	Faible
Complexité de mise en œuvre	Moyenne à élevée	Faible
Cas d'usage	Agents complexes, auditables, debuggables	Agents simples, rapides

Conclusion

L'approche par héritage de `Workflow` est recommandée pour les systèmes robustes, auditables et évolutifs. Elle permet une maîtrise fine du raisonnement, de l'utilisation des outils et une architecture extensible.
L'agent ReAct préconstruit est utile pour des cas simples ou des prototypes rapides, mais offre peu de flexibilité.

Implémentations

agent ReAct préconfiguré : react_engine_mistral_v100a.py, react_engine_mistral_v12x
agent ReAct construit sur Workflow : react_workflow_v1xx

Nota : il existe également en cours de développement des versions react_workflow_v2xx encore plus middle-level car fondées sur sur BaseWorkflowAgent.

ReAct : Schémas d'entrée et de sortie

Bertrand Degoy — 2025-09-12T08:37:58Z

Une définition complète et rigoureuse d'outils pour ReAct ( Function Tools ) comprend la définition des classes d'E/S Pydantic dans deux buts :
– aider ReAct à identifier le bon outil,
– passer des données d'entrée sous le bon format, valider les schémas de sortie ...
Oui, mais cela ralentit considérablement l'exécution et cela demande d'écrire des centaines de lignes de code.
Inutilement ?

Faut-il utiliser les schémas Pydantic ?

Sans schéma Pydantic = moins de vérifications explicites

Quand on n'utilise pas de classe Pydantic, on relie l'outil via un schéma JSON brut (dans la description de l'outil). Dans ce cas :
• Le LLM ne fait pas de validation stricte côté Python.
• Il fait confiance au schéma JSON pour comprendre les types attendus.
• Il génère les inputs en se basant sur la description, mais sans vérification automatique des types ou des valeurs.
Résultat :
✅ Exécution plus rapide
✅ Moins de friction
⚠️ Moins de sécurité sur les entrées (si l'agent hallucine ou malformate les données)

Avec Pydantic = validation rigoureuse
Si on utilise une classe Pydantic (déclaré dans le paramètre fn_schema du FunctionTool) pour définir les paramètres :
• Le LLM doit conformer les inputs à la structure attendue.
• Chaque champ est validé (type, présence, valeur).
• Tu obtiens des erreurs explicites si l'input est mal formé.
Résultat :
✅ Robustesse
✅ Clarté des erreurs
⚠️ Temps de traitement plus long
⚠️ Risque de blocage si le LLM ne formate pas parfaitement.

Gestion des retours de fonction

C'est un point souvent négligé dans les workflows ReAct : la gestion des retours de fonction.

Comment ReAct gère les retours de fonction
Dans LlamaIndex ReAct, l'agent ne lit pas directement le code Python de la fonction. Il se base sur :
1. La docstring de la fonction (si elle est fournie)
2. Le nom de la fonction
3. Le contexte de la requête utilisateur
4. L'observation du résultat après appel de la fonction
Autrement dit, il ne sait pas à l'avance ce que la fonction retourne, sauf cela lui est expliqué.

Bonnes pratiques pour que ReAct comprenne le retour
Voici comment on peut l'aider à bien interpréter le résultat :
1. Docstring explicite dans la fonction :

def extract_values_by_key(data_list, key):
"""
Retourne une liste contenant les valeurs associées à une clé donnée
dans chaque dictionnaire de la liste.
"""
return [item[key] for item in data_list if key in item]

Télécharger

2. Description claire dans le schéma JSON :

"description": "Retourne une liste des valeurs correspondant à une clé spécifique dans une liste de dictionnaires."

3. Nom de fonction évocateur
Un nom comme 'extract_values_by_key' est déjà très parlant. Éviter les noms trop génériques comme 'process_data'.
4. Observation du résultat
Après appel de la fonction, l'agent voit le retour (par exemple ['Alice','Bob','Charlie']) et peut l'utiliser dans sa chaîne de raisonnement suivante.

L'annotation de type de retour () dans la signature Python est utile pour le développeur, mais elle n'a aucun impact direct sur le comportement de l'agent ReAct :
LlamaIndex ReAct ne lit pas le code source de la fonction. Il ne fait pas d'analyse statique comme un IDE ou un linter. Ce qu'il utilise pour comprendre le comportement d'un outil, c'est :
• Le nom de la fonction,
• La description (dans le schéma JSON ou la docstring),
• Les paramètres définis dans le schéma,
• Le résultat observé après exécution.

Pour aller plus loin…

On peut aussi encapsuler le retour dans un dictionnaire pour le rendre plus lisible :

def extract_values_by_key(data_list, key):
return {"values": [item[key] for item in data_list if key in item]}

Télécharger

Cela permet à l'agent de mieux comprendre la structure du résultat, surtout si tu veux enchaîner avec d'autres outils.

Les services IA de DnC

RAG : Compression contextuelle

C'est devenu indispensable

Les 3 grandes familles de contextual compression

1. Compression par résumé (LLM summarization)

Exemple

2. Compression par extraction (LLM extraction)

3. Compression par filtrage sémantique (embedding‑based filtering)

Comment ça s'intègre dans un pipeline RAG ?

Pourquoi c'est supérieur au RAG naïf ?

Sans compression :

Avec compression :

Les erreurs fréquentes

Comment faire une contextual compression robuste ?

Étape 1 — Retrieval large (top‑20 ou top‑50)

Étape 2 — Re‑ranking (embedding ou cross‑encoder)

Étape 3 — Compression LLM (résumé/extraction)

Étape 4 — Prompt final

ReAct : le nommage des outils.

Exemple d'ambiguïté

Distinction entre fonction unitaire et vectorisée

Pourquoi ce nom est bien compris :

Encore un défaut !

ReAct : la carte des intentions : Intent Map

La carte des intentions (Intent Map)

Des cas où l'Intent Map est essentielle !

Comprendre la sélection des outils

Bonnes pratiques pour la rédaction des Intentions :**

Exemple concret (de ce qu'il ne faut pas faire) :

La génération systématique de la description

Le rôle de la docstring pour la deuxième intention

ReAct : ToolFactory

La fonction auto_toolkit

Modules Python et fonctions utilisables

statistics — Statistiques descriptives

math — Mathématiques de base

cmath — Mathématiques complexes

decimal — Calculs décimaux précis

fractions — Calculs exacts avec fractions

datetime — Dates et heures

calendar — Calendriers

Glossaire et conventions de nommage

Glossaire et conventions pour outils agentiques (ReAct, FunctionTool, ToolRouter)

Glossaire

Conventions de nommage et structuration

Outils (FunctionTool)

Décorateurs

Routage

ReAct et intégration des données temps réel avec MCP ( Model Context Protocol )

Moteur ReAct et intégration de données actualisées

Architecture modulaire de nos outils ReAct

L'outil RAG (Research Augmented Generation)

Accès aux données d'entreprise en temps réel

Le standard MCP

Quels bénéfices avec le moteur ReAct et les données temps réel ?

Bénéfices pour la prise de décision

Un outil Hybrid Search pour ReAct

Contexte et Prérequis

La construction de l'outil RetrieverTool

Filtrage par métadonnées

Hybrid Search

LLM-based Retrieval ou Embedding-based Retrieval ?

1. LLM-based Retrieval (Basé sur les Large Language Models)

Principe

Méthode

Avantages

Inconvénients

2. Embedding-based Retrieval (Basé sur les embeddings)

Principe

Méthode

Avantages

Inconvénients

Résumé des différences

Cas d'utilisation typiques

Les limites de la recherche par embeddings

La recherche par embeddings n'est pas adaptée à la sélection exhaustive de données structurées.

Quelle solution pour traiter des données structurées ?

Aux outils les sélections déterministes pour sélectionner des données structurées et en extraire de l'informel. A l'IA le travail d'analyse et de synthèse sur de l'informel.

Aller plus loin

Hybrid Search

Outils (`FunctionTool`)