Les services IA de DnC

Comment ReActAgent s'insère dans le Workflow LlamaIndex

Bertrand Degoy — 2026-04-13T10:15:10Z

Dans LlamaIndex, la boucle ReAct repose sur un principe simple : le workflow orchestre, l'agent raisonne. À chaque appel, génère un prompt, interroge le LLM, reconstruit une étape de raisonnement et laisse le finalizer décider de la suite. Une mécanique minimale côté workflow, une intelligence maximale côté agent.

La boucle de raisonnement ReAct

Comment `ReActAgent` s'insère dans le Workflow LlamaIndex

LlamaIndex ReActAgent, construit sur Workflow, fournit le code du step dans un workflow. Le workflow appelle :

BaseAgent.run_agent_step() → ReActAgent.take_step()

Donc :

le workflow = chef d'orchestre (encore un !)
l'agent = une étape du workflow
take_step() = la logique ReAct pour une étape

Comment sont construites les steps ReAct ?

En vérité : Le Workflow ne construit pas des steps ReAct. C'est ReActAgent qui les fait construire par le LLM. Le Workflow ne fait que :

appeler take_step()
attendre un AgentStepOutput (Thought, Action, Action Input ...)
décider avec ReActFinalizer si une nouvelle étape doit être exécutée

Voici ce qui se passe dans ReActAgent.take_step() pour construire une étape :

Étape 1 — Construire le prompt ReAct

L'agent génère le prompt ReAct qui fixe les règles que devra suivre le LLM pour élaborer les THOUGHT, ACTION et ACTION INPUT, pour appeler les outils etc. Le prompt contient également l'historique des échanges et, in fine, la question de l'utilisateur. Voici un exemple très naïf :

You are a ReAct agent.
First, think step-by-step and write:
THOUGHT:
Then, if needed, write:
ACTION:
ACTION INPUT:

Étape 2 — Appeler le LLM

L'agent appelle :

llm.stream(prompt)

Le LLM génère la réponse au prompt. → Le LLM produit progressivement, par petits fragments, les deltas.

Étape 3 — Le parser reconstruit les blocs

Le ReActStreamParser transforme les deltas en blocs :

THOUGHT: ...
ACTION: ...
OBSERVATION: ...
...
FINAL_ANSWER: ...

Étape 4 — Le ReActFinalizer décide si l'étape est terminée

Le finalizer :

valide les blocs
détecte les erreurs
empêche les boucles
décide si une nouvelle étape doit être lancée

Étape 5 — Le workflow relance `take_step()` si nécessaire

Si le finalizer dit “continue”, alors :

workflow → BaseAgent.run_agent_step → ReActAgent.take_step()

Et une nouvelle étape ReAct est produite.

En résumé : rôle du Workflow

Le workflow LlamaIndex ne fait qu'appeler take_step() en boucle.
ReActAgent.take_step() génère une étape ReAct en appelant le LLM.
Le ReActStreamParser reconstruit les blocs ReAct à partir des deltas.
Le ReActFinalizer décide si une nouvelle étape doit être lancée.
Le workflow relance take_step() si nécessaire.

Voyez aussi :
– ReActEngine v1 : Modules et traitements

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é"

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.

RAG : Chat Engine ReAct avec outils

Bertrand Degoy — 2025-08-02T14:08:00Z

Cette nouvelle version du ChatEngine met en oeuvre un moteur d'inférences React et des outils. Le Query Engine RAG des versions précédentes est intégré comme l'un de ces outils. Les autres outils comprennent des outils généraux (par exemple calculs mathématiques et statistiques) et des outils particularisés selon le métier et définis dans le thème.
Une attention particulière est apportée à l'extraction de données en temps réel, notamment avec des outils obtenus par Model Context Protocol (MCP) .

L'évolution consiste à utiliser un moteur d'inférences 'React' (Reasoning and Acting).
Cela permet à l'agent LLM de raisonner et agir en utilisant des outils, dans une boucle logique inspirée du document : Synergizing Reasoning and Acting in Language Models.

Dans cette architecture, les outils comprennent :
– un outil QueryEngineTool pour mettre en oeuvre le RAG sur les index créés par RAG Manager ou IngestCmd ;
– des outils généraux tels que calculs statistiques etc.
– des outils personnalisés (FunctionTools) selon le thème. On peut par exemple intégrer de façon dynamique des données "temps réel".

L'outil Query Engine RAG

Un QueryEngine semblable à celui des versions précédentes est intégré au moteur d'inférences React en tant que QueryEngineTool, directement dans la classe ChatEngine. Il fonctionne avec le même paramétrage que les versions précédentes et ne requiert donc aucune modification de ChattyBot.

Contrairement aux versions précédentes dans lesquelles le Query Engine n'était appelé qu'une fois par cycle question-réponse (une seule inférence), le moteur d'inférences peut l'appeler plusieurs fois pour une recherche par étapes dans le cadre d'un raisonnement. Ceci améliore grandement la qualité des réponses, notamment leur concision au regard de la question posée.

Les outils généraux

La classe GeneralToolKit (modules/tools/_general_.py) expose des outils généraux. Ses outils sont systématiquement mis à disposition du moteur d'inférences React.

Les outils personnalisés

Chaque thème peut, de façon optionnelle, mettre des outils spécifiques à disposition du moteur d'inférences React.
Une classe ThemeToolKit (modules/tools/theme.py) expose des outils spécifiques du thème.

Saisie de données "temps réel"

Un ToolKit particulier expose des outils capables de fournir des données "temps réel" issues d'applications ou de service tiers (qu'ils soient privés ou sur le cloud).

Principe général
Par données "temps réel", nous entendons des valeurs obtenues au moyen d'un outil qui interroge un service selon un protocole donné. Le service répond en fournissant les dernières valeurs ou informations connues avec datation. Nous nous limitons à une interrogation "passive", ainsi, la sécurité du système de données du côté du serveur est préservée, aucune action n'étant déclenchée du côté de l'application serveur.

Les données "temps réel" peuvent être saisies par appel à un simple Web Service attaché à une source de données.
Il est également possible d'utiliser Model Context Protocol (MCP) pour accéder à des sources sous ce standard.

Choix entre MCP ou Web Service simple

Critère	MCP	WS
Externalisation de traitement LLM	standard	non
définition des outils	côté serveur	côté client
protocole	standard	propriétaire
sécurité publique	OAuth2 et OpenID Connect	à développer

Au vu de ce simple tableau, on voit que MCP est adapté à des traitements d'IA répartis sur réseau ouvert, au prix d'une certaine complexité côté serveur.

Dans le cas de MCP, il faut noter que la description d'un outil est effectuée côté serveur, ce qui peut poser des problème de compréhension de leur fonctionnalité par le moteur d'inférence, d'instructions mal adaptées ou manquantes ou encore des conflits avec d'autres outils.

Dans tous les cas, il est utile (nécessaire ?) d'orchestrer le choix des outils par la boucle ReAct au moyen d'instructions particulières. Ceci se fait du côté client au moyen du routage, en définissant un plan pour chaque outil ainsi que des formats de question et de réponse.

En conclusion :
– Si on veut utiliser des outils existants (par exemple WolframAlpha) ainsi que des ressources LLM, le serveur MCP, lorsqu'il est offert, sera une alternative à la création d'outils sur l'API.
– Si on n'a besoin que d'une simple extraction de données en communiquant dans un espace de confiance, un Web Service est plus simple et mieux maîtrisable. Ceci est d'autant plus vrai que le serveur MCP peut être construit sur une API REST ou équivalent.

Un peu de stratégie...

Le principe d'un outil, vu de l'IA, est d'exécuter une tâche au cours de la boucle d'exécution ReAct. Un des outils est notre bon vieux RAG qui travaille sur des données informelles. Les autres sont des fonctions déterministes auxquelles la boucle ReAct passe des paramètres pour obtenir un retour formel. Elle choisit ses outils d'après leur description fonctionnelle et celle des E/S.

Le propre de l'IA générative est de travailler sur de l'informel. Lui faire faire des sélections de façon déterministe, c'est le marteau-pilon qui écrase la mouche, les pingouins qui se désespèrent etc.

Voici donc le principe qui doit nous guider :

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.

La boucle ReAct "native"

Le moteur ReAct de LlamaIndex fonctionne comme ceci :
– Le modèle (LLM) reçoit le prompt.
– Il réfléchit (Reasoning), choisit un outil (Action), l'exécute (Observation).
à cette étape, le modèle peut :
- Revenir au prompt pour vérifier s'il manque des éléments ou s'il faut ajuster le raisonnement.
- Comparer l'observation au prompt pour voir si elle répond à la demande ou si elle nécessite une nouvelle action.
- Utiliser l'observation pour nourrir une nouvelle phase de raisonnement (parfois en intégrant des sous-questions implicites du prompt).
– Il répète le cycle jusqu'à produire une réponse.

Dans la boucle ReAct "native" de Llamaindex, l'outil sélectionné dépend entièrement :
– du contenu du prompt, y compris un system prompt par défaut,
– de la description des outils (ToolMetadata.description)
– et de la logique d'analyse du LLM.

On notera que :
– Le routage (décrit par la suite) permet la prise en compte, au bon moment du raisonnement, d'outils particuliers.
– Le modèle utilise le prompt initial comme point de départ pour raisonner. Mais lorsqu'il décide d'appeler un outil, il formule un nouveau prompt, adapté à cet outil. Ce nouveau prompt est souvent :
– Plus ciblé : reformulé pour coller à ce que l'outil attend ou peut gérer.
– Contextualisé : enrichi avec des éléments issus du raisonnement ou d'une observation précédente.
– Optimisé : pour maximiser la qualité ou la pertinence de la réponse de l'outil.

Ainsi décrite, la boucle ReAct est un processus réflexif par lequel le moteur d'inférences peut revenir au prompt tout au long du cycle pour réévaluer ou réorienter sa stratégie dans le but de fournir une réponse pertinente [1].

Prompt(s)

Il faut distinguer :
– le prompt de l'utilisateur (que nous préférons appeler "question" ou "query" ou encore "user query"),
– le system prompt du Query Engine RAG,
– celui de l'agent ReAct.

System prompt du Query Engine RAG
Nous avons deux possibilités :
– transformer en outil un des Query Engines RAG construits précédemment sans modification, donc avec son system prompt,
– recréer sur ces modèles un Query Engine simplifié, ayant notamment un system prompt minimal, ou pas de system prompt, et utiliser le routage pour lui affecter un system prompt et des formats particuliers.

System prompt de l'agent ReAct, par défaut
le ReActAgent dans LlamaIndex utilise un system prompt par défaut appelé react_header, qui définit son comportement général, son format de réponse, et la manière dont il interagit avec les outils.

You are designed to help with a variety of tasks, from answering questions to providing summaries and other types of analyses.
 
 ## Tools
 You have access to a wide variety of tools. You are responsible for using the tools in any sequence you deem appropriate to complete the task at hand.
 This may require breaking the task into subtasks and using different tools to complete each subtask.
 
 You have access to the following tools: {tool_desc}
 
 ## Output Format
 Please answer in the same language as the question and use the following format:
 
 Thought: The current language of the user is: (user's language). I need to use a tool to help me answer the question.
 Action: tool name (one of {tool_names})
 Action Input: JSON format of the tool input
 
 Observation: tool response
 
 Repeat until you can answer without tools.
 
 Then respond with:
 Thought: I can answer without using any more tools.
 Answer: [your answer here]

On notera l'absence de format de réponse dans ce system prompt. Ce sera réglé dans le cadre du routage.

Le system prompt par défaut est injecté automatiquement lors de la création du ReActAgent via ReActAgent.from_tools(...). On peut le récupérer ou le modifier avec :

agent.get_prompts()["react_header"]

On peut le modifier comme ceci :

from llama_index.core import PromptTemplate
custom_prompt = PromptTemplate("...ton prompt ici...")
agent.update_prompts({"react_header": custom_prompt})

Télécharger

Routage

Le routeur
Un routeur, comme la fonction detect_tool_and_plan(query), intervient avant ReAct. Il sert à :
– répondre à une requête simple par appel direct à un l'outil approprié (Direct Agent),
– rediriger certaines requêtes vers des agents ou des plans dédiés (wikipedia_plan, rag_plan, etc.) (Tool Agent),
– décider s'il faut exécuter un plan complexe, une requête enrichie, ou laisser ReAct agir (React Agent).

C'est un niveau d'orchestration au-dessus de ReAct.
Il permet d'avoir une logique métier plus explicite :
“Si on parle de documents → je préfère un plan RAG avec rag_search plutôt que laisser ReAct improviser.”

Un plan est un script pour l'enchaînement logique qui précise :
– quel outil appeler (ex : rag_search, arxiv_api, wikipedia, etc.),
– comment poser la question à l'outil (formulation, prompt),
– éventuellement comment reformuler ou enrichir la réponse.

La fonction detect_tool_and_plan() agit comme un routeur sémantique, en amont de la logique ReAct :
– Elle choisit un “plan” selon les mots-clés → chaque plan génère un prompt_enrichi.
– Ce prompt est envoyé à ton SmartReActAgent, qui choisit l'outil en se basant sur son raisonnement LLM et les descriptions de tools.
– Finalement, l'agent exécute l'action (ex : recherche, calcul, extraction) et renvoie une réponse.

Qu'est-ce qu'un “routeur intelligent” ?
C'est une composante logique qui analyse une requête (ou un signal) en s'appuyant sur un LLM et décide dynamiquement de quel chemin suivre ou quelle action déclencher. L'intelligence vient de sa capacité à :
– Comprendre le contexte ou les mots-clés dans la requête
– Choisir parmi plusieurs options selon des critères (domaines, intentions, fiabilité, etc.)
– Rediriger vers une méthode adaptée – ici, un plan spécifique qui enrichit le prompt pour ReAct.

Sauter ReAct ?
Comme nous sommes en amont de ReAct, il sera possible de répondre à une requête simple par un appel direct à un outil, sans poursuivre avec la boucle ReAct.
Deux cas s'imposent :
– la question est une requête de données élémentaire (comme l'interrogation d'une table),
– la question ne nécessite que l'outil RAG, et on répondra directement avec cet outil.

Pourquoi “intelligent” ?
Ce n'est pas juste un if...else statique. Le routeur peut :
– Gérer plusieurs entrées lexicales ou sémantiques
– S'adapter à de nouveaux mots-clés,
– Faire des choix de plan ou même court-circuiter ReAct si besoin.
Il est même possible de l'enrichir avec un système de scoring ou une couche classificatrice ML légère, pour qu'il anticipe encore mieux le plan optimal.

Outils "simples"
Ces outils sont stateless, locaux et déterministes, donc il n'y a pas besoin de routage complexe comme pour les outils d'info ou de recherche.

Les outils comme calcul_tool, tva_tool, stats_tool, etc. :
– Ne requièrent pas d'accès à des sources externes
– Ont une structure d'appel directe : input → output
– Peuvent être utilisés dès que leur nécessité est détectée dans la requête
De ce fait, il n'y a pas besoin de sélectionner dynamiquement entre eux — on peut déclencher leur usage avec un simple pattern matching ou un classificateur sémantique.
La méthode call_tool() permet d'interroger un outil sans passer par un agent.

Routage ou non ?
On peut très bien combiner les deux approches :
– Le routeur pré-analyse la requête
– Si elle concerne un domaine spécifique (scientifique, corpus…) → il lance un plan
– Sinon → il laisse le moteur ReAct la traiter avec ses propres outils.
Ça donne une architecture hybride où la sémantique métier guide l'agent ReAct, mais sans l'enfermer.

Pourquoi les plans ne sont pas des méthodes de la classe d'outil correspondante ? [2]

Bien que chaque plan utilise un outil, il est conçu comme une stratégie indépendante, pour permettre :

1. Découplage clair entre logique métier et exécution technique
– Le plan décrit quoi faire et pourquoi (thought), l'outil exécute comment le faire.
– Ce découplage permet de composer plusieurs outils dans un plan — donc un outil ne peut pas forcément posséder le plan qui l'utilise.

2. Flexibilité multi-outils
– Un plan peut appeler plusieurs outils en séquence (exemple : stats_tool → format_tool → alert_tool).
– Du coup, aucun outil seul ne peut représenter cette orchestration complète.

3. Réutilisation des outils dans différents plans
– Un outil comme stats_tool pourrait être utilisé dans :
– stats_plan
– alerte_plan
– fallback_plan [3]
– Si le plan vivait dans l'outil, cette flexibilité serait réduite.

4. Contrôle sur les prompts enrichis
– Le plan peut adapter le action_input ou injecter des thought spécifiques selon le contexte.
– C'est une logique située, pas générale — donc mieux gérée en dehors de l'outil.

Fixer les formats dans le system prompt ou dans le plan du routeur ?

Le format (ou schéma) permet de valider et documenter les données.

Fixer le format de question/réponse dans le system prompt ou dans le plan du routeur (comme dans un MultiModalRouter ou QueryPlan) peut sembler similaire, mais ces deux approches ont des implications différentes en termes de contrôle, flexibilité et modularité.

1. System Prompt
Le format est défini dans le prompt initial de l'agent (ex. : react_header pour ReActAgent).
Cependant il est difficile d'adapter le format à des outils requérant un format de requête et/ou de réponse particulier.
Si plusieurs outils ou branches du raisonnement sont impliqués, le format unique peut ne pas convenir à tous.

2. Plan du routeur (Router Plan / QueryPlan)
Le format est défini dans chaque branche ou étape du plan, souvent via des prompts ou des instructions spécifiques à chaque outil ou sous-agent. Cette solution présente l'avantage d'adapter le format à chaque sous-tâche ou outil (ex. : tableau pour l'analyse, texte libre pour la synthèse).

Notre approche consistera à conserver le format général défini dans le system prompt de ReAct, complété par les formats d'objets particuliers (par exemple stats_descriptives) définis dans les plans du routeur (voir 'Orchestrateur' et 'Routines').

Annexe : Lister les outils disponibles

Nous nous plaçons dans un thème-métier du suivi de maintenance .

Pour obtenir la liste des outils et leur description, posons la question à ChattyBot :

Q :
De quels function tools disposes-tu ?

R :
Voici la liste des outils fonctionnels (tools) dont je dispose, organisés par catégories pour faciliter leur utilisation :
1. Recherche et Accès aux Connaissances

rag_search : Recherche des informations dans une base documentaire indexée pour répondre à des questions factuelles.

2. Gestion des Entités

Récupération d'entités :
entitiesGetEntityByEntityId : Par ID d'entité.
entitiesGetEntitiesByEntitiesIds : Plusieurs entités par leurs IDs.
entitiesGetEntityIdByName : ID d'une entité par son nom exact.
entitiesGetFirstEntityIdByStartOfName : ID de la première entité dont le nom commence par une chaîne donnée.
entitiesGetFirstEntityIdByPartOfName : ID de la première entité dont le nom contient une chaîne donnée.

Comptage d'entités :
entitiesGetEntitiesCount : Nombre total d'entités.
entitiesGetCountByTemplateName : Nombre d'entités par nom de modèle.
entitiesGetCountByTemplateCode : Nombre d'entités par code de modèle.

3. Gestion des Modèles (Templates)

templatesGetTemplateCodeByName : Code d'un modèle par son nom exact.
templatesGetFirstTemplateCodeByStartOfName : Code du premier modèle dont le nom commence par une chaîne donnée.
templatesGetFirstTemplateCodeByPartOfName : Code du premier modèle dont le nom contient une chaîne donnée.

4. Gestion des Interventions

Récupération par ID :
interventionsGetInterventionByInterventionId : Une intervention par son ID.
interventionsGetInterventionsByInterventionsIds : Plusieurs interventions par leurs IDs.

Filtres temporels par statut :
interventionsGetCompletedInterventionsOfEntityId : Interventions terminées entre deux timestamps.
interventionsGetStartedInterventionsOfEntityId : Interventions démarrées entre deux timestamps.
interventionsGetScheduledInterventionsOfEntityId : Interventions planifiées entre deux timestamps.
interventionsGetInterventionsOfEntityIdWorkedOnWithinInterval : Interventions en cours de traitement entre deux timestamps.
interventionsGetInterventionsOfEntityIdFullyDoneWithinInterval : Interventions ayant complété un cycle complet (de "démarré" à "terminé") entre deux timestamps.

5. Conversion et Validation de Dates/Timestamps

current_timestamp_ms : Timestamp actuel en millisecondes.
timestamp_from_date : Conversion d'une date (YYYY-MM-DD) en timestamp (ms).
timestamp_from_date_batch : Conversion groupée de dates en timestamps.
is_valid_timestamp : Vérifie si un timestamp est plausible (entre 2000 et 2100).

6. Traitement de Données

filter_data_list : Filtre une liste de dictionnaires selon des critères (ex : "key" : "age", "value" : 30, "operator" : "gt").
extract_values_by_key : Extrait les valeurs d'une clé spécifique dans une liste de dictionnaires.

7. Calculs Mathématiques et Financiers

arithmetic_tool : Opérations arithmétiques (add, sub, mul, div, etc.).
Prix et TVA :
price_tva_tool : Calcule la TVA à partir d'un prix HT.
price_ttc_tool : Calcule le prix TTC à partir d'un prix HT + taux de TVA.
price_ht_tool : Calcule le prix HT à partir d'un prix TTC + taux de TVA.

8. Analyses Statistiques

stats_descriptives : Statistiques descriptives (moyenne, médiane, écart-type, tendance linéaire) sur une série temporelle.
alerte_deviation_temporelle : Détecte les écarts significatifs par rapport à une tendance linéaire.
valeurs_hors_tendance : Identifie les valeurs anormales dans une série temporelle.

Notes

Class CallToolResult

Structure des répertoires, exemples de fichiers

Structure des répertoires sur https://chat.ia.dnc.global :

PythonApp/chat/
 │
 ├── chatitego/
 │ ├── streamlit_custom/ 
 │ ├── __init__.py 
 │ ├── chatitego_v122.py 
 │ ├── chatitego_v123.py
 │ └── ... 
 ├── modules/
 │ ├── __init__.py 
 │ ├── reactagent/
 │ │ ├── __init__.py
 │ │ ├── reactagent.py
 │ │ ├── utils/
 │ │ │ ├── __init__.py
 │ │ │ └── _routeur.py
 │ │ └── toolkits/
 │ │ ├── __init__.py
 │ │ ├── _general_.py
 │ │ ├── _mcp_client_.py
 │ │ ├── _multisource_.py
 │ │ └── ...
 │ ├── chatengine_mistral_v120.py
 │ ├── chatengine_mistral_v132.py
 │ ├── chatengine_mistral_react_v100.py
 │ ├── config.ini
 │ └── ...
 ├── tools/
 │ ├── __init__.py 
 │ ├── configloader.py
 │ ├── logger.py
 │ ├── prompt.py
 │ ├── themelock.py
 ├── __init__.py
 └── chatitego.py # appelle (par exemple) chatitego_v123.py

[1] On notera que ceci conduit à des réponses très ciblées, voire succinctes, car tout contenu ne répondant pas directement à la question est éliminé. Ceci contraste avec un simple moteur de recherche en une passe qui donnera des informations connexes. On en déduit que :
– ReAct est approprié à l'élaboration de réponses précises à des questions détaillées, voire complexes,
– Un simple Query Engine donne des réponses détaillées à des questions simples.
La deuxième approche convient à une démarche de découverte par un néophyte (comme un chatbot de FAQ), tandis que la deuxième serait plus professionnelle (comme un outil pour data analyst).

[2] On comprend que je me suis égaré un long moment à créer une méthode d'outil pour fournir le plan : fausse piste ! Parfois la programmation OO n'est qu'une tentation esthétique...

[3] Mauvais exemple !

Routage

Bertrand Degoy — 2025-08-02T07:54:51Z

Objectif : épargner les ressources et l'environnement.
Il s'agit de créer un pipeline hybride avec Llama-index où :
– Les requêtes simples sont traitées directement par un outil léger.
– Les requêtes complexes sont routées vers un ReAct agent (avec les outils), le routeur fondé sur un LLM décidant dynamiquement du chemin à suivre.

Note : le Routage fait partie l'Orchestration qui ordonne l'ensemble du processus.

Objectif et principe du routage

Le routage intervient en amont de ReAct, le but étant d'éviter d'utiliser un marteau-pilon pour écraser une mouche. Avec sa conséquence pour l'environnement :

Nous décrirons :
– la classification de la requête,
– la logique du routage,
– l'intégration des outils.

Classification de la requête

On commence par classer la requête avec un LLM router (ou Query Classifier). Nous distinguons trois classifications : 'direct', 'tool', 'react'.

class ComplexityRouter:
def __init__(self, tools: list[FunctionTool]):
self.tools = tools
def route(self, query: str) -> list[FunctionTool]:
# Heuristique simple : route selon mots-clés
if any(word in query.lower() for word in ["moyenne", "écart", "tendance"]):
return [t for t in self.tools if getattr(t, "complexity", None) == "tool"]
elif any(word in query.lower() for word in ["tva", "prix", "ht", "ttc"]):
return [t for t in self.tools if getattr(t, "complexity", None) == "simple"]
elif any(word in query.lower() for word in ["croiser", "relier", "jointure"]):
return [t for t in self.tools if getattr(t, "complexity", None) == "react"]
else:
# Fallback : tout proposer
return self.tools

Télécharger

Ce code est simpliste : dans un scénario réel, on développera le routage en s'appuyant de façon dynamique, toujours avec un appel au LLM, sur la description des outils sélectionnés ou créés pour les besoins du scénario.
On comprend que la classification va dépendre étroitement de l'application, raison pour laquelle nous avons défini des thèmes permettant des configurations particularisées dans une approche multi-utilisateurs.

def classify_query(query: str) -> str:
prompt = f"""Classify the following query:
- If it's factual/simple, return 'direct'
- If it needs a tool (search, calculator, etc.), return 'tool'
- If it needs reasoning and tool use, return 'react' :
Query: {query}
Classification:"""
return llm.predict(prompt).strip().lower()

Télécharger

Pourquoi un LLM est pertinent ici ?
– Il comprend le langage naturel dans sa richesse.
– Il peut détecter des requêtes multi-étapes, même si elles sont formulées subtilement.
– Il peut juger si une requête nécessite du raisonnement, de la planification, ou une coordination d'outils.

Logique du routage

def route_query(query: str):
category = classify_query(query)
if category == "direct":
return direct_agent.query(query)
elif category == "tool":
return tool_agent.query(query)
else category == "react":
return react_agent.query(query)

Télécharger

On observera que ReAct devra traiter non seulement les questions complexes, mais également, en dernier ressort, celles qui n'auront pas été classifiées comme 'simple' ou 'tool'.

Il est important de noter que, si ReAct est mis en jeu, tous les outils pourront être sélectionnés aux étapes du raisonnement.

intégration des outils

Une de ces trois classes d'agent sera utilisée en fonction de la classification :

Direct Agent
On retrouvera dans cette classe notre agent RAG : un moteur de requête sur un VectorStoreIndex.

Tool Agent
Agent outil : utilise ToolNode ou QueryTool avec des API externes, en particulier fournies par Model Context Protocol (MCP) .

ReAct Agent
– Agent ReAct : utilise LLMRouter et ReActAgent du framework d'agents LlamaIndex.
Tous les outils seront mis à disposition de la boucle ReAct.

La classification "react" est spéciale : elle ne décrit pas un outil en soi, mais plutôt une stratégie de raisonnement. Autrement dit :
– Un outil "simple" : répond directement (recherche, calcul, transformation),
– Un outil "tool" : interagit avec une source externe ou fait un traitement structuré,
– Un outil "react" : n'est pas un outil, mais une combinaison d'outils orchestrée par un agent ReAct.

Le processus de sélection et d'exécution de ReAct se déroule comme ceci :

Les services IA de DnC

Comment ReActAgent s'insère dans le Workflow LlamaIndex

La boucle de raisonnement ReAct

Comment ReActAgent s'insère dans le Workflow LlamaIndex

Comment sont construites les steps ReAct ?

Étape 1 — Construire le prompt ReAct

Étape 2 — Appeler le LLM

Étape 3 — Le parser reconstruit les blocs

Étape 4 — Le ReActFinalizer décide si l'étape est terminée

Étape 5 — Le workflow relance take_step() si nécessaire

En résumé : rôle du Workflow

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

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

Filtrage par métadonnées

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

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

Comment `ReActAgent` s'insère dans le Workflow LlamaIndex

Étape 5 — Le workflow relance `take_step()` si nécessaire

Outils (`FunctionTool`)