Donner des outils à un agent sans qu’il hallucine

Pourquoi il hallucine

Un LLM ne ment pas : il complète. Quand tu lui demandes de résumer l'activité d'un dépôt qu'il ne peut pas lire, il produit la suite la plus plausible — une roadmap crédible, mais inventée. Le problème n'est pas le modèle, c'est qu'on lui a coupé l'accès au réel.

Un outil, c'est une fonction décrite

Un outil, c'est trois choses : un nom, une description (en langage naturel, c'est elle que le modèle lit), et un schéma d'entrée. Le modèle décide quand l'appeler à partir de la description — donc elle compte autant que le code.

import { tool } from "@langchain/core/tools";
import { z } from "zod";
// un outil = une fonction + un schema. Le modele l'appelle quand il en a besoin.
const getGitlabActivity = tool(
  async ({ projectId }) => {
    const commits = await gitlab.commits(projectId);   // donnees REELLES
    return JSON.stringify(commits.slice(0, 20));
  },
  {
    name: "get_gitlab_activity",
    description: "Lit les commits reels d'un projet GitLab. A utiliser avant de resumer une roadmap.",
    schema: z.object({ projectId: z.string() }),
  },
);

Le modèle décide, le graphe exécute

On attache les outils au modèle. À chaque tour, il peut soit répondre, soit demander un appel d'outil. Le nœud exécute l'appel, réinjecte le résultat, et redonne la main au modèle — c'est la boucle agentique.

import { ChatOpenAI } from "@langchain/openai";
// on "donne" les outils au modele — il decide seul quand les appeler
const model = new ChatOpenAI({ model: "gpt-4o" }).bindTools([
  getGitlabActivity,
  listProjects,
  readMemory,
]);
// dans le noeud : si le modele demande un outil, on l'execute et on reboucle
const res = await model.invoke(messages);
if (res.tool_calls?.length) {
  // ... execute les outils, ajoute les resultats, rappelle le modele
}

Les garde-fous

Donner des outils ne suffit pas : il faut cadrer leur usage, sinon l'agent boucle, appelle trop, ou ignore les outils et invente quand même.

Concevoir le schéma comme un contrat

Le schéma d'entrée n'est pas de la paperasse : c'est le contrat qui empêche le modèle d'improviser. En mode strict, le fournisseur garantit que les arguments produits collent exactement au schéma — plus de champ inventé, plus de type approximatif. Côté Anthropic, on ajoute `strict: true` à la définition ; côté OpenAI, la même option exige `additionalProperties: false` et tous les champs en `required` (un champ optionnel se modélise en union avec `null`).

Avec Zod, tu écris le schéma une seule fois et LangChain le convertit en JSON Schema pour l'appel d'outil, puis valide et parse la réponse à la volée — pas de parsing manuel côté toi (doc structured output). Le même objet Zod sert donc à décrire l'entrée au modèle et à vérifier la sortie avant de la laisser continuer.

Nommer sans ambiguïté

Un paramètre `user` invite le modèle à deviner : un id ? un nom ? un email ? Un paramètre `user_id` ne laisse pas le choix. Anthropic résume ça par le « test du stagiaire » : si un nouvel arrivant ne peut pas utiliser l'outil avec la seule description et les seuls noms de champs, le modèle ne le pourra pas non plus (writing tools for agents).

Rattraper les erreurs, mesurer les appels

Même bien décrit, un outil renvoie parfois une erreur, ou le modèle passe un argument que la validation métier refuse. La bonne réaction n'est pas de planter : c'est de renvoyer l'erreur *au modèle* comme un résultat d'outil, avec un message actionnable, pour qu'il corrige au tour suivant. Anthropic recommande des messages « spécifiques et actionnables » plutôt que des codes opaques (writing tools for agents).

const parsed = ToolInput.safeParse(rawArgs);
if (!parsed.success) {
  // On ne plante pas : on renvoie l’erreur au modèle comme tool_result
  return {
    role: "tool",
    tool_call_id: call.id,
    content: `Validation failed. Fix these fields and retry:\n\${parsed.error.issues
      .map((i) => `- \${i.path.join(".")}: \${i.message}`)
      .join("\n")}`,
  };
}
// parsed.data est typé et validé — on peut exécuter l’outil en confiance
const result = await runTool(parsed.data);

Limiter la surface d'outils

Plus tu donnes d'outils, plus le modèle se trompe de cible et plus le contexte se remplit. Anthropic conseille de rester sous ~20 outils actifs et de consolider : un `schedule_event` vaut mieux que `list_users` + `list_events` + `create_event`. Au-delà, on passe à la découverte d'outils à la demande plutôt que de tout charger dans le contexte.

Évaluer, pas juste espérer

« Ça marche sur mon exemple » ne suffit pas. On évalue l'usage des outils à trois niveaux : la réponse finale, l'étape isolée (a-t-il choisi le bon outil ?), et la *trajectoire* entière (a-t-il suivi le bon chemin d'appels ?). Le package `agentevals` fournit des évaluateurs prêts à l'emploi : match strict, non ordonné, ou sous-ensemble sur les appels d'outils attendus.

Sources & ressources