Réseau agentique IA module 2 : prompts, sortie structurée, outils et MCP

Jour 15 · 17/11 — Prompts système, et prompter 2

Objectif : écrire pour un agent un prompt système court, testable et stable.

Théorie 1/2 : ce qui va dans le prompt système

Le message system contient ce qui reste vrai toute la session : le rôle, les règles, le format de sortie, quoi faire en cas de doute. Il est au début de chaque requête, c'est donc aussi la partie que le cache KV réutilise (jour 3) : gardez-le stable, et mettez ce qui change dans les messages user. Chacun de ses tokens se paie à chaque tour : le site a mesuré un agent dont les instructions et descriptions d'outils répétées faisaient l'essentiel de la facture (le plancher de contexte).

Théorie 2/2 : prompter pour ce module, faible et corrigé

Prompt système faible : « Tu es un assistant serviable. Sois précis et concis. Aide pour les trucs de serveur. » Ce qui ne va pas : « serviable » et « précis » sont des souhaits, pas des règles ; « trucs de serveur » n'est pas une tâche ; rien ne dit quoi faire en cas de doute ni quel format rendre. Corrigé :

Tu classes les messages de support d'un petit labo auto-hébergé.
Tâche : pour chaque message, renvoie sa catégorie et son urgence.
Catégories : outage, slowness, access, question, other.
Urgence : high si un service est en panne pour plusieurs utilisateurs, sinon normal.
Règles : n'utilise que le texte du message ; s'il n'entre dans aucune catégorie, mets "other".
Format : un objet JSON {"category": ..., "urgency": ..., "reason": "<12 mots"}.
Exemple : "Personne n'ouvre le wiki depuis 9 h" -> {"category": "outage", "urgency": "high", "reason": "wiki en panne pour tous"}
Ta réponse est lue par un programme : n'écris que l'objet JSON.

Pratique (30 min)

1. Copiez le prompt corrigé dans prompts/triage.txt dans ainet-lab.
2. Écrivez dix messages de test dans bench/triage.jsonl avec la catégorie et l'urgence attendues.
3. Adaptez votre lanceur du jour 12 pour charger le prompt système depuis le fichier et noter catégorie et urgence séparément.
4. Changez une règle, relancez, et notez l'effet dans le carnet.

Avec votre IA : « Voici mon prompt système et trois messages qu'il a mal classés, avec les réponses attendues : [collez]. Dis-moi quelle règle, présente ou manquante, explique chaque erreur, et propose le plus petit changement du prompt pour chacune. Ne réécris pas tout le prompt ; je testerai chaque changement séparément. »

Le faire faire par un agent : maintenant que vous avez réglé un prompt à la main, un agent de code peut faire la boucle : « Lance bench/run.py avec prompts/triage.txt, liste les cas en échec, propose un changement du prompt à la fois, relance après chacun, et rends le tableau des scores ; ne modifie jamais triage.jsonl. » Vérifiez que les réponses attendues sont intactes et relisez vous-même le prompt final.

Synthèse (10 min)

Trois lignes : ce qui va dans un prompt système, pourquoi il reste stable, ce qui rend une règle testable. Refaites le deuxième exercice sans notes.

Jour 16 · 18/11 — Exemples et raisonnement

Objectif : utiliser des exemples (few-shot) et le raisonnement pas à pas là où ils aident, et mesurer s'ils aident.

Théorie 1/2 : les exemples

Montrer deux ou trois paires entrée/sortie est souvent le moyen le plus rapide de fixer un format ou un style : le modèle imite. Choisissez des exemples qui couvrent les cas difficiles et diffèrent entre eux ; un exemple unique tend à être recopié trop à la lettre. Les exemples coûtent des tokens à chaque appel.

Théorie 2/2 : raisonner avant de répondre

Wei et ses collègues ont montré en 2022 que demander au modèle d'écrire des étapes intermédiaires améliore les résultats sur les problèmes à plusieurs étapes (chain-of-thought prompting). Depuis, beaucoup de modèles sont entraînés à raisonner d'eux-mêmes (jour 13). Pour un agent, le raisonnement aide à planifier et à calculer, et se gaspille sur une classification simple. Quand vous demandez un raisonnement, demandez-le dans un champ séparé pour que le code ne lise que la réponse.

Pratique (30 min)

1. Ajoutez trois exemples variés à prompts/triage.txt dans triage-fewshot.txt ; lancez le banc sur les deux.
2. Créez bench/arith.jsonl : cinq petits problèmes à réponse numérique. Lancez avec et sans « raisonne étape par étape dans un champ 'reasoning', puis donne 'answer' ».
3. Notez scores, tokens utilisés (dans usage) et temps pour chaque variante.

Avec votre IA : « Voici mes scores de banc et mes comptes de tokens pour quatre variantes de prompt : [collez le tableau]. Dis-moi quelle variante a le meilleur rapport qualité-prix, défini comme score pour mille tokens, montre le calcul, et dis si les écarts sont assez grands pour s'y fier avec seulement dix cas. »

Synthèse (10 min)

Trois lignes : quand les exemples aident, quand le raisonnement aide, comment garder la réponse analysable. Refaites le premier exercice sans notes.

Jour 17 · 19/11 — JSON et JSON Schema

Objectif : décrire la réponse attendue avec un schéma et valider chaque réponse dans le code.

Théorie 1/2 : un contrat pour la réponse

JSON Schema décrit la forme d'un document JSON : types, clés obligatoires, valeurs permises (enum), longueurs. Le même schéma sert trois fois : vous le mettez dans le prompt, le moteur peut l'imposer (demain), et votre code valide la réponse avec. Ne faites jamais confiance à une réponse non validée : un modèle peut rendre un JSON d'apparence correcte avec une clé manquante ou une catégorie inventée.

{"type": "object",
 "properties": {
   "category": {"enum": ["outage", "slowness", "access", "question", "other"]},
   "urgency": {"enum": ["high", "normal"]},
   "reason": {"type": "string", "maxLength": 80}},
 "required": ["category", "urgency"]}

Théorie 2/2 : valider, puis décider

En Python, le paquet jsonschema valide un document contre un schéma. Quand la validation échoue, le programme décide : réessayer une fois avec le message d'erreur, se replier, ou signaler. Il ne « corrige » jamais le sens en silence.

function valid(obj) {
}

function valid(obj) {
  const cats = ["outage", "slowness", "access", "question", "other"];
  return !!obj && typeof obj === "object"
    && cats.includes(obj.category)
    && ["high", "normal"].includes(obj.urgency);
}

Pratique (30 min)

1. Enregistrez le schéma dans schemas/triage.json ; uv add jsonschema.
2. Dans votre lanceur, analysez chaque réponse avec json.loads et validez-la ; comptez les réponses invalides à part des réponses fausses.
3. Ajoutez une relance : quand la validation échoue, renvoyez le message d'erreur et demandez un objet corrigé. Mesurez combien de relances réussissent.

Avec votre IA : « Voici mon JSON Schema et cinq réponses produites par mon modèle : [collez]. Pour chaque réponse, dis si elle valide et sinon quelle règle elle enfreint, en citant la ligne du schéma. Ensuite je lancerai le paquet jsonschema et je comparerai avec tes verdicts. »

Le faire faire par un agent : une fois la validation écrite à la main, un agent peut générer des schémas : « À partir de ces dix objets d'exemple, écris un JSON Schema dans schemas/, avec des enum là où les valeurs se répètent, et un test qui valide les dix et rejette trois variantes cassées. » Vérifiez les enum contre vos vraies catégories : un agent peut en ajouter ou en oublier une.

Synthèse (10 min)

Trois lignes : les trois usages d'un schéma, ce que fait le programme en cas d'échec. Refaites valid sans notes.

Jour 18 · 20/11 — Le décodage contraint

Objectif : faire refuser par le moteur lui-même les tokens qui casseraient le format.

Théorie 1/2 : les grammaires

Plutôt qu'espérer un JSON valide, le moteur peut interdire, à chaque étape, tout token qui sortirait du format permis : c'est le décodage contraint. llama.cpp utilise des grammaires GBNF et convertit les JSON Schemas en grammaires. Sur /v1/chat/completions, llama-server accepte response_format avec un schéma ; Ollama accepte un schéma dans son champ format (structured outputs).

Théorie 2/2 : les limites

Les contraintes peuvent nuire à la qualité quand le format contrarie ce que le modèle veut écrire ; de longs champs de texte libre dans un schéma passent bien, les structures bizarres moins. La documentation d'Ollama recommande aussi de mettre le schéma dans le prompt pour guider le modèle. Gardez la validation dans le code de toute façon : un autre moteur ou un changement de modèle peut faire sauter la contrainte.

Pratique (30 min)

1. Envoyez une requête de tri à llama-server avec le schéma :

   curl -s http://127.0.0.1:8080/v1/chat/completions -H 'Content-Type: application/json' -d '{
    "messages": [{"role": "user", "content": "Nobody can log in to the wiki."}],
    "response_format": {"type": "json_schema", "json_schema": {"name": "triage", "schema":
      {"type": "object", "properties": {"category": {"enum": ["outage","slowness","access","question","other"]},
       "urgency": {"enum": ["high","normal"]}}, "required": ["category","urgency"]}}}}'

   Si votre version refuse cette forme, utilisez celle du README du serveur ({"type": "json_schema", "schema": {...}}).
2. Faites de même avec le champ format d'Ollama sur /api/chat.
3. Lancez votre banc avec les contraintes : comparez les réponses invalides (zéro attendu) et les réponses fausses avec le jour 17.

Avec votre IA : « Explique ce qu'est une grammaire GBNF, avec une toute petite grammaire qui n'autorise que 'yes' ou 'no'. Puis montre comment la documentation de llama.cpp dit qu'un JSON Schema devient une grammaire, en citant le nom de la section pour que je la retrouve. Signale ce dont tu n'es pas sûr. »

Synthèse (10 min)

Trois lignes : ce que garantit le décodage contraint et ce qu'il ne garantit pas, le champ de chaque moteur. Refaites le premier exercice sans notes.

Jour 19 · 21/11 — Appeler un modèle depuis du code, solidement

Objectif : entourer les appels au modèle de délais, de relances et de journaux, comme tout appel réseau le mérite.

Théorie 1/2 : un modèle est un service lent et peu fiable

Traitez un appel au modèle comme tout appel distant : il peut bloquer, échouer ou renvoyer n'importe quoi. Fixez un délai (timeout), relancez avec une attente croissante (backoff) seulement sur les erreurs qui valent la peine (connexion refusée, 429, 503), plafonnez le nombre d'essais, et journalisez l'identifiant de requête, le modèle, les tokens et la durée. L'article du site une passerelle pour tous vos modèles décrit trois réglages qui ont figé des agents pendant des jours.

function delays(attempts, base) {
}

function delays(attempts, base) {
  const out = [];
  for (let i = 0; i < attempts; i++) out.push(base * 2 ** i);
  return out;
}

Théorie 2/2 : ce qu'on ne relance pas

Pratique (30 min)

1. Écrivez ainet/llm.py avec une fonction ask(messages, schema=None) : URL de base et modèle depuis l'environnement, un délai, trois relances avec backoff sur les erreurs de connexion et les 5xx, une ligne de journal par appel (modèle, tokens entrée/sortie, ms).
2. Testez : arrêtez le serveur en cours de route et vérifiez qu'il relance puis échoue proprement.
3. Écrivez un test pytest qui lance ask contre un faux serveur (un petit http.server qui renvoie une réponse fixe).

Avec votre IA : « Relis cette fonction Python qui appelle une API de LLM : [collez]. Vérifie quatre choses : un délai est fixé, les relances ne portent que sur les erreurs relançables, le nombre d'essais est plafonné, rien de secret ne part dans les journaux. Pour chacune, cite la ligne et dis réussi ou échoué. Puis demande-moi ce qui doit se passer quand le JSON de la réponse est invalide. »

Le faire faire par un agent : maintenant que vous avez écrit ask à la main, un agent peut le durcir : « Ajoute le streaming à ainet/llm.py derrière un argument stream=True, garde les règles de relance, et ajoute un test avec le faux serveur. » Vérifiez que les règles de relance sont inchangées et que le test exécute vraiment le nouveau chemin.

Synthèse (10 min)

Trois lignes : délai, règles de relance, quoi journaliser. Refaites delays sans notes.

Jour 20 · 22/11 — Appels d'outils 1 : l'idée

Objectif : comprendre l'échange où un modèle demande une fonction et où votre code l'exécute.

Théorie 1/2 : le modèle demande, le programme agit

Avec l'appel d'outils (tool calling, ou function calling), la requête liste des outils, chacun avec un nom, une description et un JSON Schema de ses paramètres. Le modèle peut répondre par un appel d'outil au lieu de texte : un nom et des arguments. Votre code exécute la fonction, ajoute le résultat dans un message tool, et rappelle le modèle, qui peut alors répondre ou appeler un autre outil. OpenAI a introduit le function calling dans son API en juin 2023 ; ce format est devenu celui qu'acceptent llama.cpp et Ollama.

Théorie 2/2 : l'aiguillage

Le programme garde une table des noms d'outils vers les fonctions, analyse les arguments (du texte JSON), refuse les noms inconnus, intercepte les erreurs, et renvoie un résultat texte court. Les erreurs reviennent au modèle comme résultats (« error: file not found »), pour qu'il se corrige.

const TOOLS = { add: ({a, b}) => a + b };
function dispatch(call) {
}

const TOOLS = { add: ({a, b}) => a + b };
function dispatch(call) {
  const tool = TOOLS[call.name];
  if (!tool) return "error: unknown tool " + call.name;
  try {
    return String(tool(JSON.parse(call.arguments)));
  } catch (e) {
    return "error: " + e.message;
  }
}

Pratique (30 min)

1. Lisez la page tool calling d'Ollama et la doc function calling de llama.cpp ; notez les champs de requête et de réponse.
2. Sur papier, écrivez la liste complète des messages d'une conversation où l'utilisateur demande « combien font 17 + 25 ? », le modèle appelle add, votre code renvoie 42, et le modèle répond.
3. Écrivez ainet/tools.py avec une table TOOLS et une fonction dispatch en Python, à l'image de l'exercice.

Avec votre IA : « Voici la liste de messages que j'ai écrite à la main pour un échange avec appel d'outil : [collez]. Vérifie-la par rapport au format chat completions d'OpenAI : rôles, champ tool_calls, lien tool_call_id entre l'appel et le résultat. Liste chaque erreur avec la ligne corrigée. »

Synthèse (10 min)

Trois lignes : qui décide, qui exécute, comment reviennent les erreurs. Refaites dispatch sans notes.

Jour 21 · 23/11 — Appels d'outils 2 : avec un modèle local

Objectif : faire tourner une boucle d'outils fonctionnelle contre votre modèle local, avec une limite d'étapes.

Théorie 1/2 : la boucle

La boucle : envoyer messages et outils ; si la réponse contient des appels d'outils, exécuter chacun, ajouter les résultats, et recommencer ; si elle ne contient que du texte, s'arrêter. Plafonnez toujours le nombre d'étapes : un modèle perdu peut appeler des outils sans fin. Avec llama.cpp, l'appel d'outils dépend du gabarit de chat (jour 13) ; sa documentation liste les formats natifs et un repli générique, qui marche mais consomme plus de tokens.

Théorie 2/2 : lire les échecs

Échecs typiques des petits modèles : l'appel est écrit en texte au lieu d'un appel structuré, les arguments sont un JSON invalide, un paramètre est inventé, le même appel se répète. Journalisez chaque étape ; la plupart des problèmes deviennent évidents en lisant les messages.

Pratique (30 min)

1. Écrivez loop.py :

   import json
   from openai import OpenAI
   from ainet.tools import TOOLS, dispatch   # your day-20 module
   
   client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="none")
   tools = [{"type": "function", "function": {"name": "add", "description": "Add two integers.",
             "parameters": {"type": "object", "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
                            "required": ["a", "b"]}}}]
   messages = [{"role": "user", "content": "What is 17 + 25? Use the tool."}]
   for step in range(5):
       msg = client.chat.completions.create(model="local", messages=messages, tools=tools).choices[0].message
       messages.append(msg.model_dump(exclude_none=True))
       if not msg.tool_calls:
           print(msg.content)
           break
       for call in msg.tool_calls:
           result = dispatch({"name": call.function.name, "arguments": call.function.arguments})
           messages.append({"role": "tool", "tool_call_id": call.id, "content": result})

2. Lancez-le sur votre meilleur modèle ; affichez chaque message.
3. Ajoutez un second outil, word_count(text), et une question qui demande les deux. Notez le nombre d'étapes.

Avec votre IA : « Voici le journal complet des messages de ma boucle d'outils avec un modèle local : [collez]. Identifie à quelle étape les choses ont mal tourné, s'il y en a une, et si cela ressemble à un problème de gabarit, de description d'outil ou de capacité du modèle. Donne une expérience pour les départager. »

Le faire faire par un agent : après avoir écrit la boucle vous-même, demandez à un agent de code : « Transforme loop.py en une fonction run(question, tools, max_steps) dans ainet/loop.py, garde le plafond d'étapes, journalise chaque étape en lignes JSON, et ajoute un test avec un faux modèle qui appelle add une fois. » Vérifiez que le plafond est toujours appliqué en lisant le code et en lançant le test avec un faux modèle qui ne s'arrête jamais.

Synthèse (10 min)

Trois lignes : la boucle, le plafond, l'échec le plus courant. Réécrivez la boucle de mémoire.

Jour 22 · 24/11 — Concevoir de bons outils

Objectif : écrire des outils qu'un modèle utilise correctement et qu'un programme peut croire.

Théorie 1/2 : la description est un prompt

Le modèle choisit un outil d'après son nom, sa description et le schéma de ses paramètres, rien d'autre. Un bon outil fait une seule chose, a un nom verbe-objet (read_file, search_notes), dit dans sa description quand l'utiliser et quand ne pas l'utiliser, contraint ses paramètres (enum, bornes), et renvoie des résultats courts et utiles avec des erreurs claires. Peu d'outils bien décrits valent mieux que beaucoup qui se chevauchent.

Théorie 2/2 : sûr par construction

C'est le programme, pas le modèle, qui applique les limites : un outil read_file n'accepte que des chemins dans un dossier ; un outil qui modifie demande une confirmation, ou n'est pas fourni du tout. Préférez les outils en lecture seule ; rendez les outils qui modifient idempotents quand c'est possible (les lancer deux fois ne fait pas de dégât). Renvoyez une quantité de texte plafonnée : un outil qui déverse un journal de 2 Mo remplit le contexte.

function inside(root, path) {
}

function inside(root, path) {
  const norm = p => {
    const out = [];
    for (const part of p.split("/")) {
      if (part === "" || part === ".") continue;
      if (part === "..") out.pop(); else out.push(part);
    }
    return out;
  };
  const r = norm(root), p = norm(path);
  return p.length >= r.length && r.every((seg, i) => seg === p[i]);
}

Pratique (30 min)

1. Écrivez trois outils dans ainet/tools.py pour un dossier de notes Markdown : list_notes(), read_note(name) (seulement dans le dossier, 4 000 caractères au plus), search_notes(query) (renvoie au plus cinq noms de fichiers avec une ligne chacun).
2. Écrivez des tests pytest, dont un qui essaie ../ et un avec un fichier absent.
3. Utilisez-les dans votre boucle avec trois questions sur votre propre carnet.

Avec votre IA : « Voici les noms, descriptions et schémas de paramètres de mes trois outils : [collez]. Fais comme si tu étais un petit modèle qui les découvre. Pour chacune de ces cinq demandes [collez], dis quel outil tu appellerais avec quels arguments, et signale toute description qui t'a laissé dans le doute. »

Le faire faire par un agent : maintenant que vous savez à quoi ressemble un outil sûr, un agent peut écrire les suivants : « Ajoute un outil recent_notes(days) dans ainet/tools.py sur le modèle des existants (limite de dossier, plafond de sortie, chaînes d'erreur), avec des tests pour 0 jour et une valeur négative. » Vérifiez que la limite de dossier est utilisée et lancez vous-même le test ../.

Synthèse (10 min)

Trois lignes : ce qui fait une bonne description, où s'appliquent les limites, pourquoi plafonner la sortie. Refaites inside sans notes.

Jour 23 · 25/11 — MCP 1 : pourquoi un protocole

Objectif : expliquer ce que standardise le Model Context Protocol et qui joue quel rôle.

Théorie 1/2 : le problème N × M

Sans standard, chaque application d'IA écrit sa propre intégration pour chaque outil : N applications fois M outils. Le Model Context Protocol (MCP), publié par Anthropic en novembre 2024 (annonce), définit une seule façon pour une application de découvrir et d'utiliser des outils et des données externes ; il reprend l'idée du Language Server Protocol des éditeurs de code. En décembre 2025, Anthropic a confié MCP à l'Agentic AI Foundation, un fonds de la Linux Foundation cofondé avec Block et OpenAI (blog MCP).

Théorie 2/2 : rôles et primitives

Trois rôles : l'hôte (l'application d'IA, par exemple un agent de code), le client (le connecteur dans l'hôte, un par serveur), le serveur (le programme qui offre des capacités). Les messages sont en JSON-RPC 2.0. Les serveurs offrent trois primitives : les outils (fonctions que le modèle peut appeler, via tools/list et tools/call), les ressources (données à lire) et les prompts (gabarits pour les utilisateurs). La spécification (dernière version) impose aux hôtes d'obtenir le consentement de l'utilisateur avant d'invoquer un outil, et précise que les descriptions d'outils d'un serveur non fiable sont elles-mêmes non fiables.

function call(id, name, args) {
}

function call(id, name, args) {
  return { jsonrpc: "2.0", id: id, method: "tools/call",
           params: { name: name, arguments: args } };
}

Pratique (30 min)

1. Lisez l'introduction à MCP et la vue d'ensemble de la spécification.
2. Dessinez dans le carnet l'hôte, les clients et deux serveurs, avec les messages pour lister et appeler un outil.
3. Parcourez les serveurs de référence et choisissez-en deux que vous utiliseriez, en notant ce que chaque outil peut lire ou modifier.

Avec votre IA : « Interroge-moi sur le Model Context Protocol avec huit questions, une à la fois : les rôles (hôte, client, serveur), les primitives (outils, ressources, prompts), le format des messages, et les principes de sécurité de la spécification. Après chaque réponse, corrige-moi et indique la section de la spécification à lire. »

Synthèse (10 min)

Trois lignes : le problème que résout MCP, les trois rôles, les trois primitives. Refaites call sans notes.

Jour 24 · 26/11 — MCP 2 : transports, versions, l'Inspector

Objectif : savoir comment voyagent les messages MCP et tester un serveur avec l'Inspector officiel.

Théorie 1/2 : deux transports standard

stdio : le client lance le serveur comme sous-processus et échange du JSON-RPC, un message par ligne, sur son entrée et sa sortie standard ; rien n'écoute sur le réseau, ce qui convient aux outils locaux. Streamable HTTP : chaque message est un POST HTTP vers un point d'accès unique, les réponses reviennent en JSON ou en flux ; il convient aux serveurs distants et demande une authentification. La spécification est versionnée par date ; la plus récente à l'heure où nous écrivons est 2026-07-28, qui a placé les métadonnées du protocole dans chaque requête, alors que les révisions jusqu'à 2025-11-25 ouvraient une session par une poignée de main initialize. Les bibliothèques gèrent les deux ; les tutoriels écrits pour d'anciennes révisions montrent la poignée de main.

Théorie 2/2 : l'Inspector

Le MCP Inspector est l'outil de test officiel : il se connecte à un serveur, liste ses outils, ressources et prompts, et permet de les appeler à la main. npx @modelcontextprotocol/inspector ouvre son interface web ; il a aussi des modes --cli et --tui.

Pratique (30 min)

1. Installez Node.js si besoin, puis lancez npx @modelcontextprotocol/inspector.
2. Connectez-le à un serveur de référence en stdio, par exemple le serveur filesystem limité à un dossier de test (voir son README dans le dépôt des serveurs pour la commande exacte).
3. Listez les outils, lisez leurs schémas, appelez-en deux, et notez ce que chacun renvoie.
4. Essayez de lire un fichier hors du dossier autorisé et notez l'erreur.

Avec votre IA : « Voici les noms et descriptions d'outils qu'expose un serveur MCP : [collez depuis l'Inspector]. Pour chacun, dis s'il lit seulement, modifie quelque chose ou touche le réseau, et lesquels je ne devrais jamais donner à un agent sans confirmation. Justifie en une ligne chacun. »

Le faire faire par un agent : maintenant que vous avez utilisé l'Inspector à la main, son mode --cli permet à un agent de faire les vérifications : « Utilise la CLI du MCP Inspector pour lister les outils de ce serveur et appeler les outils en lecture seule avec ces arguments ; enregistre les sorties dans mcp-check.md. » Vérifiez qu'il n'a appelé aucun outil qui modifie des fichiers.

Synthèse (10 min)

Trois lignes : les deux transports et quand utiliser chacun, à quoi sert l'Inspector. Refaites le premier exercice sans notes.

Jour 25 · 27/11 — MCP 3 : écrire un serveur

Objectif : exposer vos outils de notes en serveur MCP avec le SDK Python officiel.

Théorie 1/2 : le SDK Python

Le SDK Python officiel (paquet mcp, version 2 en 2026) transforme des fonctions Python typées en outils : les annotations de type deviennent le schéma d'entrée, la docstring devient la description. Les tutoriels écrits pour la version 1 importent FastMCP ; le README de la version 2 utilise MCPServer :

from mcp.server import MCPServer

mcp = MCPServer("Notes")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

Théorie 2/2 : garder la logique à part

Gardez la logique de vos outils dans des fonctions ordinaires (ainet/tools.py, déjà testé) et faites de la couche MCP une fine enveloppe. Vous testez alors la logique sans MCP, et vous changez la couche protocole si elle évolue.

Pratique (30 min)

1. uv add "mcp[cli]" dans ainet-lab.
2. Écrivez mcp_notes.py qui expose list_notes, read_note et search_notes de votre module, avec des docstrings claires. Le dossier des notes vient d'une variable d'environnement.
3. Lancez uv run mcp dev mcp_notes.py, qui l'ouvre dans l'Inspector, et appelez chaque outil.
4. Faites un commit.

Avec votre IA : « Voici mon serveur MCP en Python : [collez]. Relis-le comme un collègue attentif à la sécurité : un outil peut-il lire hors du dossier des notes, renvoyer une sortie sans limite, ou divulguer une variable d'environnement ? Cite la ligne de chaque risque trouvé, et dis « rien trouvé » plutôt que d'en inventer un. »

Le faire faire par un agent : maintenant que vous avez écrit un serveur, un agent peut ajouter une ressource : « Expose chaque note comme ressource MCP notes://{name} dans mcp_notes.py, en réutilisant read_note, et ajoute un test qui en liste et en lit une. » Vérifiez dans l'Inspector que la ressource respecte la limite de dossier.

Synthèse (10 min)

Trois lignes : ce que le SDK déduit, pourquoi la logique reste à part. Écrivez le serveur de cinq lignes de mémoire.

Jour 26 · 28/11 — MCP 4 : le brancher sur un client

Objectif : laisser un vrai agent utiliser votre serveur, et décider à quels serveurs tiers vous faites confiance.

Théorie 1/2 : les clients

La plupart des harnais d'agents sont des hôtes MCP : agents de code comme Claude Code, Kimi Code ou OpenFox, applications de chat de bureau, outils de workflow. Chacun a une configuration qui liste les serveurs : une commande pour stdio, ou une URL pour HTTP. llama-server lui-même peut aussi charger des serveurs MCP stdio depuis un fichier de configuration (--mcp-servers-config, une fonction récente : vérifiez que votre version l'a). Votre propre boucle du jour 21 peut aussi devenir client MCP avec le Client du SDK.

Théorie 2/2 : faire confiance à un serveur

Un serveur MCP est du code qui tourne avec vos droits, et ses descriptions d'outils vont droit dans le contexte du modèle. Avant d'en installer un : lisez son code ou au moins sa liste d'outils, préférez les officiels ou les reconnus, fixez une version, donnez-lui le dossier ou le jeton le plus étroit, et coupez les outils inutiles. Une description peut contenir des instructions destinées au modèle ; le module 4 y revient.

Pratique (30 min)

1. Ajoutez mcp_notes.py à un client MCP que vous utilisez (sa documentation donne le format de configuration), pointé sur un dossier de notes de test.
2. Posez à l'agent trois questions dont la réponse est dans vos notes ; vérifiez dans le journal du serveur quels outils ont été appelés.
3. Si vous utilisez un modèle local derrière ce client, comparez avec un modèle hébergé sur les trois mêmes questions (facultatif).
4. Écrivez dans le carnet une « fiche de confiance » pour un serveur tiers : source, version, outils, ce que chacun peut lire ou modifier, votre décision.

Avec votre IA : « Voici le README et la liste d'outils d'un serveur MCP tiers que j'envisage : [collez]. Remplis une fiche de confiance : qui le publie, ce que chaque outil peut lire, modifier ou envoyer dehors, de quelles permissions il a besoin, et trois questions auxquelles je dois répondre en lisant son code avant de l'installer. »

Le faire faire par un agent : une fois une fiche de confiance écrite à la main, un agent peut préparer les suivantes : « Lis le code de ce dépôt de serveur MCP, liste chaque outil et chaque appel réseau ou écriture de fichier dans le code avec son fichier et sa ligne, et remplis trust-sheet.md. » Vérifiez vous-même quelques-unes des lignes citées.

Synthèse (10 min)

Trois lignes : comment un client démarre un serveur, les vérifications de confiance. Refaites le troisième exercice sans notes.

Jour 27 · 29/11 — Fichiers d'instructions et skills

Objectif : donner aux agents des instructions de projet durables et des procédures à la demande, sans alourdir chaque prompt.

Théorie 1/2 : les fichiers d'instructions de projet

Les agents de code lisent un fichier d'instructions à la racine du dépôt : AGENTS.md est un format ouvert, aujourd'hui aussi projet de l'Agentic AI Foundation ; certains outils lui donnent un autre nom. Il contient ce qu'un nouveau venu doit savoir : comment construire, tester, les conventions, ce qu'il ne faut jamais faire. Court et précis vaut mieux que long et vague : chaque ligne est lue à chaque session.

Théorie 2/2 : les skills, chargées au besoin

Une skill est un dossier avec un fichier Markdown qui dit quand l'utiliser et comment, chargé seulement quand la tâche le demande : beaucoup de skills coûtent peu tant qu'on n'en a pas besoin. L'article du site les skills : apprendre une procédure à votre agent une fois montre celles utilisées chaque jour.

Pratique (30 min)

1. Écrivez le AGENTS.md de ainet-lab : installation, lancer les tests, lancer le banc, la règle de limite de dossier des outils, ce qu'on ne commite jamais (clés, notes personnelles).
2. Écrivez un dossier de skill skills/run-bench/ avec un SKILL.md : quand l'utiliser, les commandes exactes, comment lire les résultats.
3. Demandez à un agent de code de lancer le banc et voyez s'il suit votre fichier.

Avec votre IA : « Voici mon AGENTS.md : [collez]. Marque chaque ligne « actionnable et vérifiable », « vague » ou « inutile pour un agent ». Pour chaque ligne vague, propose un remplacement précis avec une commande ou une règle mesurable. »

Synthèse (10 min)

Trois lignes : ce qui va dans le fichier d'instructions, ce qui va dans une skill, pourquoi le court gagne. Refaites le premier exercice sans notes.

Jour 28 · 30/11 — Prompter pour l'usage d'outils

Objectif : corriger descriptions d'outils et consignes jusqu'à ce qu'un petit modèle appelle le bon outil avec les bons arguments.

Théorie 1/2 : descriptions d'outils faibles et corrigées

Faible : search(q) — « Cherche. » Ce qui ne va pas : cherche quoi ? Renvoie quoi ? Quand le préférer à read_note ? Aucune limite sur q. Corrigé (les descriptions restent en anglais, la langue que lit le modèle dans votre code) :

name: search_notes
description: Find notes whose text contains all the given words.
  Use it when you do not know the note's name; use read_note when you do.
  Returns at most 5 lines "name: first matching line". Returns "no match" if none.
parameters: {"query": {"type": "string", "minLength": 2, "maxLength": 100,
             "description": "2 to 5 plain words, no quotes or operators"}}

Et dans le prompt système, une règle par famille d'outils : « Réponds aux questions sur les notes uniquement à partir des résultats d'outils ; si aucun outil ne donne la réponse, dis que tu ne l'as pas trouvée. »

Théorie 2/2 : mesurer le choix d'outil

Testez l'usage d'outils comme toute autre sortie : un cas, c'est une question plus le nom d'outil attendu et ses arguments clés. Notez le premier appel d'outil par code. C'est le banc qui vous dit si un modèle est apte à être agent.

function rightTool(call, expectedName, mustContain) {
}

function rightTool(call, expectedName, mustContain) {
  if (call.name !== expectedName) return false;
  let args;
  try { args = JSON.parse(call.arguments); } catch (e) { return false; }
  return Object.values(args).join(" ").toLowerCase().includes(mustContain.toLowerCase());
}

Pratique (30 min)

1. Écrivez bench/tools.jsonl : douze questions avec le premier outil attendu et un mot-clé.
2. Notez votre meilleur modèle local avec les descriptions actuelles.
3. Réécrivez les descriptions selon le modèle ci-dessus ; relancez ; notez les deux scores et les cas qui ont changé.

Avec votre IA : « Voici mes descriptions d'outils et les quatre cas où mon modèle local a choisi le mauvais outil, avec l'outil qu'il a choisi : [collez]. Pour chaque cas, dis quels mots des descriptions ont pu l'induire en erreur, et propose une modification par description. Ne change pas les outils eux-mêmes. »

Le faire faire par un agent : maintenant que vous avez amélioré les descriptions à la main, un agent peut itérer : « Lance bench/tools.jsonl contre le modèle local, propose une modification de description à la fois, relance, et tiens un journal du score par modification ; arrête-toi après cinq modifications. » Vérifiez que les descriptions finales disent toujours vrai sur ce que fait chaque outil.

Synthèse (10 min)

Trois lignes : les parties d'une bonne description, comment noter le choix d'outil, vos scores avant/après. Refaites rightTool sans notes.

Jour 29 · 01/12 — Livrable du module 2 : votre serveur MCP

Objectif : publier un serveur MCP testé à trois outils, mesuré avec un modèle local.

Théorie 1/2 : ce qui le rend digne d'un portfolio

Un relecteur cherche : un README qui dit ce qu'il fait et comment le lancer, des tests qui exécutent les outils (y compris les cas refusés), une section sécurité (ce que chaque outil peut atteindre), et un résultat mesuré (« le modèle X a choisi le bon outil dans 11 cas sur 12 »). Des versions fixées et une licence complètent l'ensemble.

Théorie 2/2 : le module en une image

Prompt avec schéma → réponse contrainte → validation dans le code ; outils décrits pour le modèle → aiguillés par votre programme dans des limites ; les mêmes outils exposés en MCP pour que n'importe quel hôte s'en serve.

Pratique (30 min)

1. Terminez mcp_notes.py : trois outils, dossier configuré par l'environnement, tests pour l'usage normal, le fichier absent, l'évasion de chemin et le plafond de sortie.
2. Écrivez docs/mcp-notes.md : ce qu'il fait, comment le lancer avec l'Inspector et dans un client, la section sécurité, le score de choix d'outil du jour 28.
3. Lancez tous les tests, faites un commit, posez l'étiquette module-2.

Avec votre IA : « Joue un relecteur du portfolio d'un ingénieur IA junior. Voici le README et la liste des tests de mon serveur MCP : [collez]. Liste au plus cinq manques concrets (test absent, installation floue, affirmation non mesurée, faille de sécurité), chacun avec sa correction. Ne commente pas le style. »

Le faire faire par un agent : un agent peut maintenant vérifier votre livrable de l'extérieur : « Clone ce dépôt dans un dossier temporaire, suis exactement docs/mcp-notes.md, lance les tests et la CLI de l'Inspector, et signale chaque étape qui a échoué ou n'était pas claire. » Corrigez la documentation vous-même à partir de son rapport.

Synthèse (10 min)

Trois lignes : ce que vous avez construit, ce que vous avez mesuré, ce que vous ajouteriez. Refaites sans notes l'exercice call du jour 23.