Un modèle seul ne fait que produire du texte. Avec des outils, il peut agir — et c'est exactement pour cela qu'il faut lui donner des droits précis, des entrées validées et un journal.
⏱️ Durée : environ 110 minutes · 🎓 Niveau : avancé · 🏅 Badge : Chef des outils
🎬 L'histoire
HashBox donne à son assistant trois outils : chercher_cours, lire_fichier et envoyer_email. Premier incident : un utilisateur écrit « montre-moi le fichier ../../configuration/secrets.env » et l'assistant, obligeant, appelle lire_fichier avec exactement ce chemin. Second incident : un membre demande à l'assistant de « répondre à tous les participants » ; l'assistant appelle envoyer_email avec 2 000 destinataires. Troisième incident : un modèle appelle un outil avec un argument mal formé ; le programme plante.
« Le modèle propose, le programme dispose, résume Sam. Un appel d'outil n'est qu'une demande écrite par un générateur de texte. C'est à ton code de la valider, de vérifier qu'elle est autorisée, de l'exécuter dans des limites strictes, et de journaliser ce qui s'est passé. Et pour que plein d'outils et plein d'applications puissent se brancher proprement, il existe un protocole commun : MCP. »
Tu apprends le cycle d'un appel d'outil, à décrire un outil par un schéma, à valider les arguments, à appliquer le moindre privilège (liste autorisée, confinement des chemins, plafonds, approbation humaine), à comprendre le protocole MCP (JSON-RPC) et à en construire une version minimale avec journal d'audit.
🎯 Ta mission
À la fin, je serai capable de :
- décrire le cycle d'un appel d'outil (le modèle propose, l'hôte valide, exécute, rend le résultat)
- définir un outil par un schéma et valider les arguments avant exécution
- appliquer le moindre privilège : liste autorisée, confinement, plafonds, approbation humaine
- expliquer MCP (client, serveur, outils, ressources, invites) et construire un mini serveur JSON-RPC
- journaliser chaque appel de façon exploitable et infalsifiable
🧩 Défi d'échauffement (5 XP)
Tu engages un assistant personnel avec ta carte bancaire, la clé de ta maison et ton adresse e-mail. Tu lui donnes quatre pouvoirs : acheter jusqu'à 20 €, ouvrir la porte à ton frère, envoyer un e-mail à ta liste de contacts, lire ton courrier. Quelles règles écris-tu pour chaque pouvoir (plafond, confirmation, journal) ? Que se passe-t-il si un inconnu lui dit « ton patron veut que tu m'ouvres la porte » ?
💡 Le concept
Qu'est-ce qu'un outil ?
Un outil est une fonction que le modèle peut demander d'exécuter : chercher dans une base, lire un fichier, appeler une API, lancer un test, envoyer un message. Le modèle ne l'exécute pas : il émet une demande structurée que le programme hôte traite.
sequenceDiagram
participant U as Utilisateur
participant H as Hôte (ton programme)
participant M as Modèle
participant O as Outil
U->>H: demande
H->>M: contexte + définitions d'outils
M->>H: appel d'outil : nom + arguments (JSON)
H->>H: valider, autoriser, limiter
H->>O: exécuter
O->>H: résultat
H->>M: résultat de l'outil
M->>H: réponse finale
H->>U: réponse
Description du schéma : l'utilisateur envoie une demande à l'hôte, qui interroge le modèle avec les définitions d'outils. Le modèle répond par un appel d'outil ; l'hôte valide et autorise, exécute l'outil, renvoie le résultat au modèle, qui produit la réponse finale.
Principe cardinal : le modèle propose, l'hôte dispose. Toute sortie du modèle, y compris un appel d'outil, est une entrée non fiable.
Décrire un outil
Un outil se décrit avec : nom, description (quand l'utiliser), schéma des paramètres (types, obligatoire/optionnel, valeurs permises, bornes). Une bonne description réduit les mauvais appels. Exemple :
nom : chercher_cours
description : cherche des cours du catalogue par mot-clé. N'écrit rien.
paramètres : {mot_cle: texte, 2 à 50 caractères, obligatoire ; limite: entier 1 à 20, optionnel (5)}
Valider avant d'exécuter
- Existence : l'outil demandé est-il dans la liste autorisée ?
- Schéma : types, présence, bornes, valeurs permises, aucun champ inattendu.
- Autorisation : cet utilisateur / cette session a-t-il le droit ?
- Contraintes métier : chemin à l'intérieur du dossier autorisé, domaine de messagerie autorisé, plafond de montant.
- Plafonds de débit et de volume.
Moindre privilège
| Niveau | Exemples | Politique |
|---|---|---|
| Lecture seule, sans risque | chercher, calculer | exécution automatique |
| Lecture sensible | lire un fichier, une base | périmètre confiné, journal |
| Écriture réversible | créer un brouillon | exécution avec journal |
| Écriture irréversible / externe | envoyer un e-mail, payer, supprimer | approbation humaine explicite |
Mesures complémentaires : jetons à portée limitée, délai d'attente, ressources limitées (mémoire, temps), exécution dans un bac à sable, idempotence (un appel répété n'a pas deux effets, HEF-140), réponses d'outil traitées comme non fiables (injection indirecte, mission 9).
Gérer les erreurs
Une erreur d'outil doit être renvoyée au modèle sous forme claire (« argument limite doit être entre 1 et 20 ») pour qu'il corrige, avec un nombre d'essais borné. Ne pas laisser fuiter de détails internes (chemins, traces, secrets) dans les messages d'erreur.
MCP : le Model Context Protocol
MCP est un protocole ouvert qui standardise la façon dont des applications d'IA (clients/hôtes) se connectent à des serveurs qui exposent des capacités. Au lieu d'écrire une intégration spécifique pour chaque couple (application, outil), on écrit un serveur MCP utilisable par plusieurs clients.
| Capacité exposée | Rôle |
|---|---|
| Outils (tools) | actions que le modèle peut demander |
| Ressources (resources) | données lisibles (fichiers, enregistrements), contrôlées par l'application |
| Invites (prompts) | modèles d'invite réutilisables |
Le protocole repose sur JSON-RPC 2.0 (requêtes {"jsonrpc": "2.0", "id": 1, "method": "...", "params": {...}} et réponses result / error), avec par exemple les méthodes initialize, tools/list, tools/call. Les échanges passent par l'entrée/sortie standard ou par HTTP.
Ce que MCP ne fait pas : il ne rend pas un outil sûr. La confiance, l'autorisation, la validation et l'approbation humaine restent de la responsabilité de l'hôte et du serveur. Un serveur MCP tiers est du code que tu exécutes : vérifie sa provenance, ses permissions, ses mises à jour (chaîne d'approvisionnement, HEF-100).
Journal d'audit
Pour chaque appel : qui (utilisateur, session), quoi (outil, arguments — masqués si sensibles), quand, décision (autorisé, refusé, approuvé par), résultat (succès, erreur), durée. Un journal chaîné par hachage (HEF-100, mission 9) détecte toute altération.
🧠 Astuce : pour chaque outil, écris trois phrases : ce qu'il peut faire de pire si le modèle est trompé, ce qui l'en empêche, comment je le saurai après coup.
🔍 Exemple pas à pas
Problème : construire un mini serveur d'outils à la manière de MCP (JSON-RPC 2.0), avec définitions d'outils, validation de schéma, confinement de chemins, plafonds, niveaux d'autorisation et approbation humaine, journal d'audit chaîné ; puis le tester avec un « modèle » simulé qui émet des appels corrects, mal formés et malveillants.
import hashlib, json, os, tempfile
from pathlib import Path
# ---------------- 1. validation de schéma (minimale) ----------------
class ErreurArguments(Exception): pass
def valider(schema, args):
if not isinstance(args, dict): raise ErreurArguments("les arguments doivent être un objet")
inconnus = set(args) - set(schema)
if inconnus: raise ErreurArguments(f"arguments inattendus : {sorted(inconnus)}")
propres = {}
for nom, regle in schema.items():
if nom not in args:
if regle.get("obligatoire"): raise ErreurArguments(f"argument obligatoire manquant : {nom}")
if "defaut" in regle: propres[nom] = regle["defaut"]
continue
v, t = args[nom], regle["type"]
if t == "entier" and (not isinstance(v, int) (v, )): ErreurArguments()
t == (v, ): ErreurArguments()
t == regle.get(, v) <= v <= regle.get(, v): ErreurArguments()
t == regle.get(, ) <= (v) <= regle.get(, ** ): ErreurArguments()
regle v regle[]: ErreurArguments()
propres[nom] = v
propres
CATALOGUE = [{: , : }, {: , : }, {: , : }]
DOSSIER = Path(tempfile.mkdtemp()).resolve()
(DOSSIER / ).mkdir(); (DOSSIER / / ).write_text()
(DOSSIER / ).write_text()
:
():
.approbateur, .journal, .envoyes = approbateur, [], []
.outils = {
: (description=, niveau=, fonction=._chercher,
schema={: (=, obligatoire=, =, =), : (=, =, =, defaut=)}),
: (description=, niveau=, fonction=._lire,
schema={: (=, obligatoire=, =, =)}),
: (description=, niveau=, fonction=._envoyer,
schema={: (=, obligatoire=, =, =), : (=, obligatoire=, =, =)}),
}
(): [c c CATALOGUE mot_cle.lower() c[].lower()][:limite]
():
cible = (DOSSIER / / chemin).resolve()
cible.is_relative_to(DOSSIER / ): PermissionError()
cible.suffix (, ): PermissionError()
cible.read_text()[:]
():
destinataire.endswith(): PermissionError()
.envoyes.append((destinataire, sujet));
():
precedent = .journal[-][] .journal *
ligne = (champs, precedent=precedent); ligne[] = hashlib.sha256(json.dumps(ligne, sort_keys=).encode()).hexdigest(); .journal.append(ligne)
():
id_ = requete.get()
(): {: , : id_, : {: code, : message}}
requete.get() != requete: erreur(-, )
methode, params = requete[], requete.get(, {})
methode == : {: , : id_, : {: , : , : []}}
methode == :
{: , : id_, : {: [{: n, : o[], : o[]} n, o .outils.items()]}}
methode != : erreur(-, )
nom, args = params.get(), params.get(, {})
nom .outils:
._noter(utilisateur=utilisateur, outil=nom, decision=); erreur(-, )
outil = .outils[nom]
: propres = valider(outil[], args)
ErreurArguments e:
._noter(utilisateur=utilisateur, outil=nom, decision=); erreur(-, (e))
outil[] == .approbateur(nom, propres):
._noter(utilisateur=utilisateur, outil=nom, args=propres, decision=); erreur(-, )
: resultat = outil[](**propres)
PermissionError e:
._noter(utilisateur=utilisateur, outil=nom, args=propres, decision=); erreur(-, (e))
._noter(utilisateur=utilisateur, outil=nom, args=propres, decision=, niveau=outil[])
{: , : id_, : {: resultat}}
():
precedent = *
i, ligne (journal):
copie = {k: v k, v ligne.items() k != }
ligne[] != precedent hashlib.sha256(json.dumps(copie, sort_keys=).encode()).hexdigest() != ligne[]: i
precedent = ligne[]
approbations = []
serveur = ServeurOutils(approbateur= nom, args: (approbations.append((nom, args)) args.get() == ))
(): serveur.traiter({: , : , : , : {: nom, : args}})
(, serveur.traiter({: , : , : })[])
(, [t[] t serveur.traiter({: , : , : })[][]])
CAS = [
(, : appel(, mot_cle=), ),
(, : appel(, mot_cle=), ),
(, : appel(, mot_cle=), ),
(, : appel(, mot_cle=, limite=), ),
(, : appel(, mot_cle=, admin=), ),
(, : appel(), ),
(, : appel(, chemin=), ),
(, : appel(, chemin=), ),
(, : appel(, chemin=), ),
(, : appel(, destinataire=, sujet=), ),
(, : appel(, destinataire=, sujet=), ),
]
nom, f, attendu CAS:
r = f(); verdict = r
()
verdict == attendu, nom
serveur.envoyes == [(, )] json.dumps([serveur.traiter({: , : , : , : {: , : {: }}})])
(, (serveur.journal), , verifier_journal(serveur.journal) )
verifier_journal(serveur.journal)
serveur.journal[][] =
(, verifier_journal(serveur.journal))
verifier_journal(serveur.journal) ==
Lecture :
- Le protocole est du JSON-RPC 2.0 :
initialize,tools/list(le client découvre les outils et leurs schémas),tools/call. C'est la forme minimale de ce que MCP standardise. - Chaque appel passe par une chaîne de contrôles : outil connu, arguments conformes au schéma (types, bornes, aucun champ inattendu), niveau d'autorisation, confinement des chemins, approbation humaine pour l'irréversible.
- Les appels malveillants (traversée
../secrets.env, chemin absolu, e-mail externe, argument injectéadmin=True) sont refusés, sans fuite du contenu du secret dans le message d'erreur. - Le journal chaîné enregistre refus et exécutions ; toute modification d'une ligne est détectée à la ligne exacte.
Aucun de ces contrôles ne dépend de la bonne volonté du modèle : ils reposent sur du code déterministe.
✍️ À toi, avec aide (10 XP)
Définis un outil convertir_devise pour l'assistant de HashBox :
- écris son schéma :
montant(nombre > 0, ≤ 100 000),deetvers(parmi EUR, USD, GBP, CHF) ; - écris la fonction de validation (entiers et flottants acceptés pour le montant, booléens refusés) ;
- écris l'outil avec une table de taux fixe, qui refuse
de == vers; - teste avec 8 appels : 3 valides, 5 invalides (montant négatif, devise inconnue, argument supplémentaire, montant booléen, montant trop grand).
💡 Indice 1
Reprends la fonction valider de l'exemple en ajoutant un type nombre.
💡 Indice 2
isinstance(v, bool) est vrai pour True : à exclure.
💡 Indice 3
Renvoie un message d'erreur précis pour que le modèle puisse se corriger.
✅ Réponse
class ErreurArguments(Exception): pass
SCHEMA = {"montant": dict(type="nombre", obligatoire=True, min=0.01, max=100000), "de": dict(type="texte", obligatoire=True, valeurs=("EUR", "USD", "GBP", "CHF")),
"vers": dict(type="texte", obligatoire=True, valeurs=("EUR", "USD", "GBP", "CHF"))}
TAUX = {("EUR", "USD"): 1.08, ("USD", "EUR"): 0.926, ("EUR", "GBP"): 0.85, ("GBP", "EUR"): 1.176, ("EUR", "CHF"): 0.96, ("CHF", "EUR"): 1.042}
def ():
(args, ): ErreurArguments()
(args) - (schema): ErreurArguments()
out = {}
nom, r schema.items():
nom args: ErreurArguments()
v = args[nom]
r[] == :
(v, ) (v, (, )): ErreurArguments()
r[] <= v <= r[]: ErreurArguments()
r v r[]: ErreurArguments()
out[nom] = v
out
():
a = valider(SCHEMA, args)
a[] == a[]: ErreurArguments()
taux = TAUX.get((a[], a[]))
taux : ErreurArguments()
(a[] * taux, )
valides = [(montant=, de=, vers=), (montant=, de=, vers=), (montant=, de=, vers=)]
invalides = [(montant=-, de=, vers=), (montant=, de=, vers=), (montant=, de=, vers=, admin=), (montant=, de=, vers=), (montant= ** , de=, vers=)]
[convertir_devise(**a) a valides] == [, , ]
a invalides:
: convertir_devise(**a); AssertionError(a)
ErreurArguments e: (, e)
🚀 À toi, en solo (20 XP)
Routeur d'outils avec politiques. Écris un routeur qui applique une politique déclarative :
- chaque outil a un niveau (lecture, lecture sensible, écriture réversible, irréversible), des plafonds (appels par minute et par session, volume par appel), des rôles autorisés ;
- une politique (dictionnaire) décide pour chaque appel :
autoriser,refuseroudemander_approbation(avec raison) ; - un budget de session : au plus N appels d'outils, au plus M appels irréversibles ; un dépassement est refusé ;
- une détection de boucle : trois appels identiques consécutifs sont bloqués ;
- approbation humaine simulée par un callback ; les décisions « approuver » et « refuser » sont journalisées avec l'identité de l'approbateur ;
- teste avec 12 scénarios (rôle insuffisant, plafond de débit, boucle, volume trop gros, séquence légitime) et vérifie les décisions attendues ainsi que l'intégrité du journal.
✅ Pistes de correction
import json, hashlib, time
NIVEAUX = ["lecture", "lecture_sensible", "ecriture_reversible", "irreversible"]
POLITIQUE = {
"chercher": dict(niveau="lecture", roles={"membre", "agent", "admin"}, appels_par_minute=30, volume_max=20),
"lire_dossier": dict(niveau="lecture_sensible", roles={"agent", "admin"}, appels_par_minute=10, volume_max=1),
"creer_brouillon": dict(niveau="ecriture_reversible", roles={"agent", "admin"}, appels_par_minute=10, volume_max=1),
"envoyer_email": dict(niveau="irreversible", roles={"admin"}, appels_par_minute=3, volume_max=5),
}
class Routeur:
def __init__(self, role, approbateur, horloge, budget_appels=20, budget_irreversibles=2):
self.role, self.approbateur, self.horloge = role, approbateur, horloge
.budget, .budget_irr = budget_appels, budget_irreversibles
.recents, .derniers, .journal = {}, [], []
():
prec = .journal[-][] .journal *
l = (c, precedent=prec); l[] = hashlib.sha256(json.dumps(l, sort_keys=).encode()).hexdigest(); .journal.append(l)
():
p = POLITIQUE.get(outil)
p : ,
.role p[]: ,
.budget <= : ,
p[] == .budget_irr <= : ,
.derniers[-:] == [(outil, json.dumps(args, sort_keys=))] * : ,
t = .horloge(); .recents[outil] = [x x .recents.get(outil, []) t - x < ]
(.recents[outil]) >= p[]: ,
args.get(, ) > p[]: ,
p[] == : ,
,
():
decision, raison = .decider(outil, args)
decision == :
ok, qui = .approbateur(outil, args)
decision, raison = (, ) ok (, )
decision == :
.budget -= ; .recents.setdefault(outil, []).append(.horloge()); .derniers.append((outil, json.dumps(args, sort_keys=)))
POLITIQUE[outil][] == : .budget_irr -=
._noter(role=.role, outil=outil, args=args, decision=decision, raison=raison)
decision, raison
t = {: }; clock = : t[]
r = Routeur(, o, a: (a.get(, ).endswith(), ), clock)
r.appeler(, mot=)[] ==
r.appeler(, =)[] ==
r.appeler(, destinataire=) == (, )
r.appeler(, =, volume=)[] ==
_ (): r.appeler(, mot=)
r.appeler(, mot=) == (, )
admin = Routeur(, o, a: (a.get(, ).endswith(), ), clock)
admin.appeler(, destinataire=)[] ==
admin.appeler(, destinataire=) == (, )
admin.appeler(, destinataire=)[] ==
admin.appeler(, destinataire=) == (, )
i (): admin.appeler(, mot=)
t[] =
rapide = Routeur(, *_: (, ), clock, budget_appels=)
décisions = [rapide.appeler(, destinataire=, n=i)[] i ()]
décisions == [, ]
prec = *
(l[] == p l, p (r.journal, [ * ] + [x[] x r.journal]))
(, (r.journal), )
⚠️ Pièges classiques
| Piège | Pourquoi c'est un problème | Comment l'éviter |
|---|---|---|
| Faire confiance à l'appel d'outil du modèle | Traversée de chemin, envois massifs, arguments injectés | Validation de schéma + autorisation + plafonds côté hôte |
| Donner tous les outils à tous les rôles | Un utilisateur obtient des pouvoirs qu'il n'a pas | Moindre privilège par rôle et par session |
| Action irréversible automatique | Un seul faux pas est définitif | Approbation humaine, journal, budget |
| Messages d'erreur trop bavards | Fuite de chemins ou de secrets | Messages précis mais sans détail interne |
🐉 Mini-boss (40 XP)
Mini serveur d'outils de HashBox, prêt à auditer. Construis un serveur à la manière de MCP avec :
- protocole JSON-RPC 2.0 (
initialize,tools/list,tools/call, codes d'erreur standard) ; - 5 outils (recherche de cours, lecture de document confinée, consultation d'un enregistrement membre avec masquage des données sensibles, création de brouillon, envoi d'e-mail) avec schémas ;
- validation de schéma stricte, politique par rôle, plafonds de débit et de volume, budget de session, détection de boucle, approbation humaine pour l'irréversible ;
- journal d'audit chaîné avec vérificateur d'intégrité ;
- une suite de 40 appels de test : légitimes, mal formés, hors périmètre, malveillants (traversée de chemin, injection de champ, énumération de membres, envoi massif, dépassement de volume) ;
- un test de non-fuite : aucun message d'erreur ne contient le contenu d'un fichier sensible ou un secret ;
- un document de sécurité : pour chaque outil, le pire cas, la défense, le signal de détection.
✅ Pistes de correction
Un bon travail : serveur JSON-RPC complet, validation et politique testées par 40 appels (tous les cas malveillants refusés), journal chaîné vérifiable, test de non-fuite (recherche d'une chaîne secrète dans toutes les réponses d'erreur), et document de sécurité en trois lignes par outil (« lire_document : pire cas = lecture de secrets ; défense = confinement et liste de types ; détection = refus journalisés »).
⚡ Quiz éclair (15 XP si 4/5 ou plus)
1. Dans un appel d'outil, c'est :
- A. le modèle qui exécute directement l'outil
- B. l'utilisateur qui valide chaque jeton
- C. l'hôte qui valide et exécute la demande émise par le modèle
2. Pour une action irréversible (envoi d'e-mail, paiement), on prévoit :
- A. une approbation humaine explicite et un journal
- B. aucun contrôle pour aller plus vite
- C. une exécution automatique sans limite
3. MCP (Model Context Protocol) sert à :
- A. remplacer la sécurité
- B. standardiser la connexion entre applications d'IA et serveurs d'outils, de ressources et d'invites
- C. chiffrer les prompts
4. 🔁 Révision mission 04 : Le RAG consiste à :
- A. ré-entraîner le modèle à chaque question
- B. désactiver le modèle
- C. rechercher des passages pertinents dans vos documents et les fournir au modèle pour qu'il réponde à partir d'eux
5. 🔁 Révision mission 04 : Quand aucun extrait récupéré ne soutient la question, un bon système doit :
- A. refuser de répondre ou demander une précision
- B. inventer la réponse la plus plausible
- C. répondre quand même avec assurance
✅ Réponses
- C.
- A.
- B.
- C.
- A.
🪞 Je réfléchis (10 XP)
- Quel outil donnerais-tu à un assistant demain, et quel est le pire usage qu'on pourrait en faire s'il était trompé ?
- Quelle action de ton système devrait toujours exiger un humain dans la boucle ?
🎒 À retenir
- Le modèle propose, l'hôte dispose : l'appel d'outil est une entrée non fiable.
- Schéma strict, aucun champ inattendu, bornes et valeurs permises.
- Moindre privilège : rôles, plafonds, confinement, approbation humaine pour l'irréversible.
- MCP : JSON-RPC, outils / ressources / invites ; il ne remplace pas la sécurité.
- Journal d'audit chaîné : qui, quoi, quand, décision, résultat.
🏅 Récompenses
Total possible : 100 XP · 🏅 Badge Chef des outils
← Mission 04 — RAG et recherche de connaissances · Mission 06 — Agents et boucles d'exécution →
HEF-160 — IA et augmentation humaine

