Les outils¶
Le système d'outils permet aux agents d'agir au-delà de la génération de texte — calculs, consultations de mémoire, lecture de fichiers, appels à un sous-modèle. Les outils suivent une conception pilotée par la spécification, avec un moteur de répartition central et la prise en charge du format d'appel de fonctions d'OpenAI.
L'architecture¶
Agent --> Engine (with tool defs) --> tool_calls response --> ToolExecutor --> Tool.execute()
^ |
| v
+------------------------------- ToolResult <--------------------------------------------+
La classe abstraite BaseTool¶
Tous les outils implémentent la classe de base abstraite BaseTool.
from abc import ABC, abstractmethod
from diapason.tools._stubs import ToolSpec
from diapason.core.types import ToolResult
class BaseTool(ABC):
tool_id: str
@property
@abstractmethod
def spec(self) -> ToolSpec:
"""Rend la spécification de l'outil."""
@abstractmethod
def execute(self, **params) -> ToolResult:
"""Exécute l'outil avec les paramètres donnés."""
def to_openai_function(self) -> dict:
"""Convertit au format d'appel de fonctions d'OpenAI."""
La méthode to_openai_function() est fournie par la classe de base : elle convertit la spécification de l'outil dans le format qu'attendent les API compatibles OpenAI.
{
"type": "function",
"function": {
"name": "calculator",
"description": "Evaluate a mathematical expression safely.",
"parameters": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "Math expression to evaluate"
}
},
"required": ["expression"]
}
}
}
ToolSpec¶
La dataclasse ToolSpec décrit l'interface et les caractéristiques d'un outil.
| Champ | Type | Défaut | Description |
|---|---|---|---|
name |
str |
-- | Identifiant unique de l'outil |
description |
str |
-- | Description lisible par un humain (envoyée au modèle) |
parameters |
dict[str, Any] |
{} |
Le JSON Schema des paramètres de l'outil |
category |
str |
"" |
Catégorie de l'outil (math, memory, reasoning, par exemple) |
cost_estimate |
float |
0.0 |
Coût estimé par appel |
latency_estimate |
float |
0.0 |
Latence estimée par appel |
requires_confirmation |
bool |
False |
Si l'outil exige une confirmation de l'utilisateur |
metadata |
dict[str, Any] |
{} |
Métadonnées supplémentaires |
ToolResult¶
La dataclasse ToolResult porte le résultat de l'exécution d'un outil.
| Champ | Type | Défaut | Description |
|---|---|---|---|
tool_name |
str |
-- | Nom de l'outil appelé |
content |
str |
-- | La sortie de l'outil (du texte) |
success |
bool |
True |
Si l'exécution a réussi |
usage |
dict[str, Any] |
{} |
Consommation de jetons (pour l'outil LLM) |
cost_usd |
float |
0.0 |
Coût réel de l'appel |
latency_seconds |
float |
0.0 |
Latence d'exécution mesurée |
metadata |
dict[str, Any] |
{} |
Métadonnées supplémentaires |
ToolExecutor¶
ToolExecutor est le moteur de répartition central des appels d'outils. Il tient un jeu d'instances d'outils, analyse les arguments JSON, mesure la latence d'exécution et publie des événements sur le bus d'événements.
from diapason.tools._stubs import ToolExecutor
executor = ToolExecutor(tools=[calculator, think_tool], bus=event_bus)
# Récupérer les définitions d'outils au format OpenAI
openai_tools = executor.get_openai_tools()
# Exécuter un appel d'outil
from diapason.core.types import ToolCall
tc = ToolCall(id="call_1", name="calculator", arguments='{"expression": "2+2"}')
result = executor.execute(tc)
print(result.content) # "4"
Le déroulé d'une exécution¶
- Analyse des arguments : la chaîne JSON
argumentsduToolCallest désérialisée. - Publication de l'événement de départ :
TOOL_CALL_STARTest émis sur le bus d'événements, avec le nom de l'outil et ses arguments. - Exécution : la méthode
execute()de l'outil est appelée avec les paramètres analysés. - Mesure de la latence : le temps d'exécution est consigné dans
result.latency_seconds. - Publication de l'événement de fin :
TOOL_CALL_ENDest émis, avec le succès et la latence. - Retour du résultat : le
ToolResultest rendu à l'appelant.
Si le nom de l'outil est inconnu, un ToolResult avec success=False est rendu. Si l'analyse JSON échoue ou si l'outil lève une exception, l'erreur est capturée et rendue sous forme de ToolResult en échec.
Les méthodes¶
| Méthode | Rend | Description |
|---|---|---|
execute(tool_call) |
ToolResult |
Analyse les arguments, répartit, mesure, émet les événements |
available_tools() |
list[ToolSpec] |
Rend les spécifications de tous les outils enregistrés |
get_openai_tools() |
list[dict] |
Rend les outils au format de fonctions d'OpenAI |
build_tool_descriptions()¶
La fonction build_tool_descriptions() est la source unique de vérité pour produire les descriptions enrichies d'outils qu'on trouve dans les prompts système des agents. Tous les agents textuels (NativeReActAgent, NativeOpenHandsAgent, RLMAgent, OrchestratorAgent en mode structuré) passent par elle pour produire leurs sections d'outils en Markdown.
Les paramètres¶
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
tools |
list[BaseTool] |
-- | La liste des instances d'outils à décrire |
include_category |
bool |
True |
Si la ligne Category: est incluse |
include_cost |
bool |
False |
Si les lignes d'estimation de coût et de latence sont incluses |
L'usage¶
from diapason.tools._stubs import build_tool_descriptions
from diapason.tools.calculator import CalculatorTool
from diapason.tools.think import ThinkTool
tools = [CalculatorTool(), ThinkTool()]
desc = build_tool_descriptions(tools)
print(desc)
# ### calculator
# Evaluate a mathematical expression safely.
# Category: math
# Parameters:
# - expression (string, required): Math expression to evaluate
#
# ### think
# Reasoning scratchpad ...
Les agents qui utilisent ce constructeur¶
- NativeReActAgent — il injecte les descriptions dans le prompt système ReAct
- NativeOpenHandsAgent — il les injecte dans le prompt système CodeAct
- RLMAgent — il ajoute une section
## Available Toolsau prompt système du REPL - OrchestratorAgent (en mode structuré) — il passe
tools=àbuild_system_prompt(), qui délègue à ce constructeur
Les outils intégrés, en résumé¶
Tous les outils intégrés sont enregistrés par @ToolRegistry.register() et sont accessibles par leur nom depuis les agents et depuis la ligne de commande.
| Catégorie | Clé de registre | Description |
|---|---|---|
| Raisonnement | think |
Bloc-notes de raisonnement sans coût, pour la chaîne de pensée |
| Mathématiques | calculator |
Évaluateur d'expressions mathématiques sûr (fondé sur ast) |
| Code | code_interpreter |
Exécute du Python dans un sous-processus isolé |
| Code | code_interpreter_docker |
Exécute du Python dans un conteneur Docker jetable |
| Code | repl |
REPL Python persistant, qui garde son état d'un appel à l'autre |
| Recherche | web_search |
Recherche web rendant des résultats numérotés et datés [N] |
| Recherche | web_read |
Lit une page : texte principal, titre, date de publication |
| Fichiers | file_read |
Lit le contenu d'un fichier, avec des contrôles de sûreté |
| HTTP | http_request |
Émet des requêtes HTTP, avec protection contre le SSRF |
| Mémoire | retrieval |
Cherche dans le moteur de mémoire le contexte pertinent |
| Mémoire | memory_store |
Range du contenu dans le moteur de mémoire |
| Mémoire | memory_retrieve |
Récupère du contenu pertinent depuis le moteur de mémoire |
| Mémoire | memory_search |
Recherche plein texte dans toute la mémoire stockée |
| Mémoire | memory_index |
Indexe un fichier ou un dossier dans le moteur de mémoire |
| Inférence | llm |
Délègue une sous-question à un moteur d'inférence |
| Canal | channel_send |
Envoie un message par un canal (Telegram, Discord, etc.) |
| Canal | channel_list |
Liste les canaux de messagerie disponibles |
| Canal | channel_status |
Vérifie l'état de connexion d'un canal de messagerie |
| Planification | schedule_task |
Planifie une tâche, ponctuelle ou récurrente |
| Planification | list_scheduled_tasks |
Liste toutes les tâches planifiées |
| Planification | pause_scheduled_task |
Met en pause une tâche planifiée active |
| Planification | resume_scheduled_task |
Reprend une tâche mise en pause |
| Planification | cancel_scheduled_task |
Annule définitivement une tâche planifiée |
| Intégration | mcp_adapter |
Pont vers des serveurs d'outils MCP externes (voir Les serveurs MCP externes) |
Les outils intégrés en détail¶
Calculator¶
Clé de registre : calculator | Catégorie : math
Évalue des expressions mathématiques sans risque, avec le module ast de Python. Aucune exécution de code arbitraire — seules les opérations de la liste blanche sont permises.
Paramètres :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
expression |
string | Oui | Expression mathématique ("2+3*4", "sqrt(16)", par exemple) |
Les opérations prises en charge :
| Catégorie | Opérations |
|---|---|
| Arithmétique | +, -, *, /, // (division entière), % (modulo), ** (puissance) |
| Fonctions | abs, round, min, max, sqrt, log, log10, log2 |
| Trigonométrie | sin, cos, tan |
| Arrondis | ceil, floor |
| Constantes | pi, e |
Exemple :
from diapason.tools.calculator import CalculatorTool
calc = CalculatorTool()
result = calc.execute(expression="sqrt(144) + 3**2")
print(result.content) # "21.0"
print(result.success) # True
Think¶
Clé de registre : think | Catégorie : reasoning
Un bloc-notes de raisonnement sans coût. L'entrée est renvoyée telle quelle en sortie, ce qui laisse le modèle « penser à voix haute » pendant une boucle d'appel d'outils. C'est ce qui rend possible le raisonnement en chaîne de pensée à l'intérieur du flux de l'agent.
Paramètres :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
thought |
string | Oui | Le raisonnement, ou le cheminement de pensée |
Exemple :
from diapason.tools.think import ThinkTool
think = ThinkTool()
result = think.execute(thought="Décomposons ce problème en étapes...")
print(result.content) # "Décomposons ce problème en étapes..."
print(result.success) # True
Coût et latence
L'outil Think ne coûte rien et sa latence est quasi nulle : il est idéal pour structurer un raisonnement sans consommer de ressources supplémentaires.
Retrieval¶
Clé de registre : retrieval | Catégorie : memory
Cherche dans le moteur de mémoire le contexte pertinent et rend des résultats mis en forme, avec l'attribution de leur source.
Paramètres :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
query |
string | Oui | La requête de recherche |
top_k |
integer | Non | Nombre de résultats (5 par défaut) |
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
backend |
MemoryBackend |
None |
Le moteur de mémoire à interroger |
top_k |
int |
5 |
Nombre de résultats par défaut |
Exemple :
from diapason.tools.retrieval import RetrievalTool
from diapason.memory.sqlite import SQLiteMemory
backend = SQLiteMemory(db_path="./memory.db")
retrieval = RetrievalTool(backend=backend)
result = retrieval.execute(query="apprentissage automatique")
print(result.content) # Le contexte mis en forme, avec les étiquettes de source
LLM¶
Clé de registre : llm | Catégorie : inference
Délègue une sous-question à un moteur d'inférence. Utile pour résumer, pour poser une question intermédiaire ou pour produire une sortie structurée à l'intérieur du flux d'un agent.
Paramètres :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
prompt |
string | Oui | Le prompt à envoyer au modèle |
system |
string | Non | Un message système facultatif, pour le contexte |
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
engine |
InferenceEngine |
None |
Le moteur d'inférence à utiliser |
model |
str |
"" |
L'identifiant du modèle |
Exemple :
from diapason.tools.llm_tool import LLMTool
llm = LLMTool(engine=my_engine, model="qwen3:8b")
result = llm.execute(
prompt="Résume : l'IA transforme des industries entières...",
system="Tu résumes de façon concise.",
)
print(result.content)
FileRead¶
Clé de registre : file_read | Catégorie : filesystem
Lit le contenu d'un fichier, avec des contrôles de sûreté. Il accepte une restriction facultative à certains dossiers, une limite de taille de fichier (1 Mo au maximum) et une limite sur le nombre de lignes.
Paramètres :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
path |
string | Oui | Le chemin du fichier à lire |
max_lines |
integer | Non | Nombre maximum de lignes rendues (tout, par défaut) |
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
allowed_dirs |
list[str] |
None |
Restreint l'accès aux fichiers à ces dossiers |
Les garde-fous :
- Validation du chemin contre les dossiers autorisés (quand ils sont configurés)
- Taille maximale du fichier : 1 Mo
- Encodage UTF-8 exigé (les fichiers binaires sont refusés)
- Contrôles d'existence et de type de fichier
Exemple :
from diapason.tools.file_read import FileReadTool
reader = FileReadTool(allowed_dirs=["/home/user/projects"])
result = reader.execute(path="/home/user/projects/README.md", max_lines=50)
print(result.content)
print(result.metadata) # {"path": "/home/user/projects/README.md", "size_bytes": 1234}
WebSearch¶
Clé de registre : web_search | Catégorie : search
Cherche sur le web et rend un résumé des résultats. Utile pour les questions qui demandent une information à jour.
Paramètres :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
query |
string | Oui | La requête de recherche |
max_results |
integer | Non | Nombre maximum de résultats (5 par défaut) |
recency |
string | Non | day, week, month ou year |
news |
boolean | Non | Cherche d'abord dans les médias d'information (articles datés) |
Les résultats sont numérotés [N], avec le domaine de la source et la date ;
le chat les cite par leur numéro et les affiche en pastilles cliquables. La
région suit DIAPASON_SEARCH_REGION (ca-fr par défaut).
WebRead¶
Clé de registre : web_read | Catégorie : search
Lit une page web et rend son texte principal (navigation, pieds de page et
bandeaux de cookies retirés ; les tableaux gardés en lignes a | b | c), son
titre et ses dates de publication et de modification (JSON-LD, <meta>,
<time>, puis l'en-tête HTTP Last-Modified — une date ambiguë est rendue
comme absente, jamais devinée). Utilise-le après web_search quand les
extraits ne disent pas le fait demandé. Pour une question sur le titulaire
d'une fonction, le chat lit de lui-même la page de la fonction après la
première recherche (affiché web_read · auto).
Paramètres :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
url |
string | Oui | L'URL de la page (http/https ; les adresses privées sont refusées) |
focus |
string | Non | Les mots à chercher ; les passages qui les entourent viennent en premier |
La sortie est bornée à 3 600 caractères ; la page compte comme une source
[N], exactement comme un résultat de recherche.
CodeInterpreter¶
Clé de registre : code_interpreter | Catégorie : code
Exécute des bouts de code Python dans un environnement isolé et en rend la sortie. C'est ce dont se sert NativeOpenHandsAgent pour l'exécution façon CodeAct.
Paramètres :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
code |
string | Oui | Le code Python à exécuter |
Les outils de planification¶
Les outils de planification exposent les opérations de TaskScheduler comme des outils découvrables par MCP. Ils laissent les agents créer, gérer et inspecter des tâches planifiées par programme. Tous sont dans la catégorie scheduler et exigent qu'une instance de TaskScheduler soit configurée dans le système.
La dépendance au planificateur
Les outils de planification ne fonctionnent que si un TaskScheduler est câblé dans le système (par SystemBuilder). Sans planificateur configuré, tous leurs appels rendent un résultat success=False, accompagné d'un message disant que le planificateur n'est pas disponible.
schedule_task¶
Clé de registre : schedule_task | Catégorie : scheduler
Planifie une nouvelle tâche, ponctuelle ou récurrente.
Paramètres :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
prompt |
string | Oui | La question, ou le prompt, à exécuter à l'heure dite |
schedule_type |
string | Oui | L'un de "cron", "interval" ou "once" |
schedule_value |
string | Oui | Une expression cron, un intervalle en secondes, ou une date-heure ISO 8601 pour une exécution unique |
agent |
string | Non | L'agent qui exécutera ("simple" par défaut) |
tools |
string | Non | Les noms d'outils de l'agent, séparés par des virgules ("calculator,think", par exemple) |
Des exemples de types de planification :
schedule_type |
schedule_value |
Ce que ça veut dire |
|---|---|---|
once |
"2026-03-01T09:00:00Z" |
Une seule fois, à cette heure UTC |
interval |
"3600" |
Toutes les 3600 secondes (1 heure) |
cron |
"0 9 * * 1-5" |
À 09:00 UTC, du lundi au vendredi |
Rend : du JSON avec task_id, next_run (ISO 8601) et status.
Exemple (par un appel d'outil d'agent) :
from diapason.scheduler.tools import ScheduleTaskTool
from diapason.scheduler.scheduler import TaskScheduler
from diapason.scheduler.store import SchedulerStore
store = SchedulerStore(db_path="~/.diapason/scheduler.db")
scheduler = TaskScheduler(store=store, system=diapason_system)
scheduler.start()
tool = ScheduleTaskTool()
tool._scheduler = scheduler
result = tool.execute(
prompt="Résume l'actualité du jour",
schedule_type="cron",
schedule_value="0 8 * * *",
agent="simple",
)
# result.content: '{"task_id": "a3f9b12c", "next_run": "2026-02-26T08:00:00+00:00", "status": "active"}'
list_scheduled_tasks¶
Clé de registre : list_scheduled_tasks | Catégorie : scheduler
Rend toutes les tâches planifiées, filtrées par statut si on le demande.
Paramètres :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
status |
string | Non | Filtre par statut : "active", "paused", "completed", "cancelled" |
Rend : un tableau JSON d'objets de tâche.
pause_scheduled_task¶
Clé de registre : pause_scheduled_task | Catégorie : scheduler
Met en pause une tâche planifiée active. La tâche est conservée et peut être reprise plus tard.
Paramètres :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
task_id |
string | Oui | L'identifiant de la tâche à mettre en pause |
resume_scheduled_task¶
Clé de registre : resume_scheduled_task | Catégorie : scheduler
Reprend une tâche mise en pause. L'heure de next_run est recalculée à partir de l'heure courante.
Paramètres :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
task_id |
string | Oui | L'identifiant de la tâche à reprendre |
cancel_scheduled_task¶
Clé de registre : cancel_scheduled_task | Catégorie : scheduler
Annule définitivement une tâche (statut mis à "cancelled" et next_run effacé). Une tâche annulée ne s'exécute plus jamais.
Paramètres :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
task_id |
string | Oui | L'identifiant de la tâche à annuler |
L'enregistrement d'un outil¶
Les outils s'enregistrent avec le décorateur @ToolRegistry.register(), ce qui les rend découvrables par leur nom à l'exécution.
from diapason.core.registry import ToolRegistry
from diapason.tools._stubs import BaseTool, ToolSpec
from diapason.core.types import ToolResult
@ToolRegistry.register("my_tool")
class MyTool(BaseTool):
tool_id = "my_tool"
@property
def spec(self) -> ToolSpec:
return ToolSpec(
name="my_tool",
description="Un outil maison qui fait quelque chose d'utile.",
parameters={
"type": "object",
"properties": {
"input": {
"type": "string",
"description": "L'entrée à traiter.",
},
},
"required": ["input"],
},
category="custom",
)
def execute(self, **params) -> ToolResult:
value = params.get("input", "")
return ToolResult(
tool_name="my_tool",
content=f"Traité : {value}",
success=True,
)
Une fois enregistré, l'outil s'utilise avec un agent :
Utiliser les outils avec les agents¶
Depuis la ligne de commande¶
Les outils se donnent en liste séparée par des virgules, avec l'option --tools. Il faut choisir un agent (orchestrator, en général) :
# Un seul outil
diapason ask --agent orchestrator --tools calculator "Combien font 15 % de 340 ?"
# Plusieurs outils
diapason ask --agent orchestrator --tools calculator,think "Résous : 2x + 5 = 13"
# Tous les outils disponibles (il faut les énumérer)
diapason ask --agent orchestrator --tools calculator,think,retrieval,file_read "..."
Depuis le SDK Python¶
Les outils se passent en liste de noms :
from diapason import Diapason
j = Diapason()
# Utiliser les outils calculator et think
result = j.ask_full(
"Quelle est l'aire d'un cercle de rayon 7 ?",
agent="orchestrator",
tools=["calculator", "think"],
)
for tr in result["tool_results"]:
print(f" {tr['tool_name']}: {tr['content']} (success={tr['success']})")
j.close()
Le SDK instancie tout seul les objets d'outils avec les dépendances qu'il faut. L'outil retrieval reçoit par exemple le moteur de mémoire configuré, et l'outil llm le moteur et le modèle actifs.