Agents IA : boucle agentique et pattern ReAct

Chatbot : Question → Réponse → Question → Réponse

Agent : Objectif → [Réflexion → Action → Observation]* → Résultat

// Tu sais d'avance ce qui va se passer
const response = await chat("Lance un d20");
// Le LLM appelle roll_dice, tu exécutes, il répond

// L'agent choisit le chemin
const result = await runAgent("Quelles sont les nouveautés de TypeScript 5.4 ?", config);
// Il décide : une recherche, deux pages à lire, peut-être une seconde recherche, puis la synthèse

THOUGHT: Le code plante à la ligne 42. L'erreur mentionne "undefined".
         Je dois d'abord comprendre d'où vient cette variable.
ACTION:  read_file({ path: "src/utils.ts", lines: "35-50" })
OBSERVATION: [contenu du fichier]
THOUGHT: La variable `user` vient de la fonction `getUser()` qui peut retourner null.
         Le bug est un accès sans vérification. Je vais proposer un fix.
ACTION:  [aucune - réponse finale]
ANSWER:  Le bug est à la ligne 42 : `user.name` sans vérifier que `user` existe...

const AGENT_SYSTEM_PROMPT = `Tu es un agent autonome capable d'accomplir des tâches complexes.

Méthode :
- Avant chaque appel d'outil, écris en une ou deux phrases ce que tu cherches et pourquoi.
- Une seule action à la fois : attends le résultat avant de décider de la suivante.
- Si un outil échoue ou ne donne rien, change d'approche au lieu de recommencer à l'identique.
- Quand l'objectif est atteint, ou si tu constates qu'il est impossible, réponds directement sans appeler d'outil.`;

mkdir agent-recherche && cd agent-recherche
npm init -y
npm pkg set type=module
npm install @mistralai/mistralai zod mathjs
npm install -D tsx typescript @types/node
export MISTRAL_API_KEY="ta-clé"

import { Mistral } from "@mistralai/mistralai";
import type {
  AssistantMessage,
  ChatCompletionRequest,
} from "@mistralai/mistralai/models/components";

export const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

// Le type d'un message, tel que le SDK l'attend
export type Message = ChatCompletionRequest["messages"][number];

// Le contenu d'une réponse est une string ou une liste de morceaux :
// on n'en garde que le texte
export function textOf(content: AssistantMessage["content"]): string {
  if (typeof content === "string") return content;
  return (content ?? [])
    .map((chunk) => (chunk.type === "text" ? chunk.text : ""))
    .join("");
}

import type { Tool } from "@mistralai/mistralai/models/components";
import { client, textOf, type Message } from "./mistral";

export interface AgentConfig {
  model: string;
  systemPrompt: string;
  tools: Tool[];
  // Exécute un outil et retourne son résultat (on l'écrit juste après)
  executeTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
  maxIterations?: number;
}

export async function runAgent(
  objective: string,
  config: AgentConfig
): Promise<string> {
  const maxIterations = config.maxIterations ?? 10;

  const messages: Message[] = [
    { role: "system", content: config.systemPrompt },
    { role: "user", content: objective },
  ];

  for (let iteration = 1; iteration <= maxIterations; iteration++) {
    console.log(`\n--- Itération ${iteration} ---`);

    const response = await client.chat.complete({
      model: config.model,
      messages,
      tools: config.tools,
      parallelToolCalls: false, // une seule action à la fois
    });

    const choice = response.choices[0];
    const assistantMessage = choice?.message;
    if (!assistantMessage) throw new Error("Pas de réponse du modèle");

    messages.push({ ...assistantMessage, role: "assistant" });

    // La réflexion, quand le modèle l'écrit avant d'agir
    const thought = textOf(assistantMessage.content);

    // Cas 1 : le LLM veut utiliser des outils
    if (choice.finishReason === "tool_calls" && assistantMessage.toolCalls) {
      if (thought) console.log(`💭 ${thought}`);

      for (const toolCall of assistantMessage.toolCalls) {
        const name = toolCall.function.name;
        const rawArgs = toolCall.function.arguments;
        const args = typeof rawArgs === "string" ? JSON.parse(rawArgs) : rawArgs;

        console.log(`🔧 Action: ${name}`, args);
        const result = await config.executeTool(name, args);

        // Un résultat trop long noierait le contexte : on tronque
        const content = (
          typeof result === "string" ? result : JSON.stringify(result)
        ).slice(0, 4000);
        console.log(`📋 Observation: ${content.slice(0, 200)}`);

        messages.push({ role: "tool", toolCallId: toolCall.id, name, content });
      }
      continue;
    }

    // Cas 2 : le LLM a terminé
    console.log(`✅ Agent terminé après ${iteration} itération(s)`);
    return thought;
  }

  throw new Error(`Agent arrêté après ${maxIterations} itérations`);
}

import { all, create } from "mathjs";
import { z } from "zod";
import type { Tool } from "@mistralai/mistralai/models/components";

// mathjs a son propre parseur : il n'exécute jamais de JavaScript.
// On retire quand même les fonctions qui modifient l'instance.
const math = create(all);
const evaluate = math.evaluate;
const disabled = () => {
  throw new Error("Fonction désactivée");
};
math.import(
  { import: disabled, createUnit: disabled, evaluate: disabled, parse: disabled },
  { override: true }
);

// Lie un schéma Zod à son implémentation : les arguments du LLM
// sont validés avant d'arriver dans execute
function defineTool<S extends z.ZodType>(def: {
  description: string;
  schema: S;
  dangerous?: boolean; // on s'en sert plus bas, dans les garde-fous
  execute: (args: z.infer<S>) => Promise<unknown>;
}) {
  return {
    description: def.description,
    dangerous: def.dangerous ?? false,
    parameters: z.toJSONSchema(def.schema, { io: "input" }),
    run: (rawArgs: unknown) => def.execute(def.schema.parse(rawArgs)),
  };
}

const toolRegistry: Record<string, ReturnType<typeof defineTool>> = {
  web_search: defineTool({
    description:
      "Recherche sur le web. Retourne une liste de résultats avec titre, URL et extrait.",
    schema: z.object({
      query: z.string().describe("La requête de recherche"),
    }),
    execute: async ({ query }) => {
      // Tavily ici, mais n'importe quelle API de recherche convient
      const response = await fetch("https://api.tavily.com/search", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${process.env.TAVILY_API_KEY}`,
        },
        body: JSON.stringify({ query, max_results: 5 }),
      });
      return response.json();
    },
  }),

  read_url: defineTool({
    description: "Lit le contenu d'une page web et retourne le texte.",
    schema: z.object({
      url: z.url({ protocol: /^https?$/ }).describe("L'URL à lire"),
    }),
    execute: async ({ url }) => {
      const response = await fetch(url);
      const html = await response.text();
      // Extraction basique (en prod, regarde du côté de @mozilla/readability)
      return html
        .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
        .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
        .replace(/<[^>]+>/g, " ")
        .replace(/\s+/g, " ")
        .trim();
    },
  }),

  calculate: defineTool({
    description: "Évalue une expression mathématique, par exemple (12 + 7) * 3.",
    schema: z.object({
      expression: z.string().max(200).describe("L'expression à calculer"),
    }),
    execute: async ({ expression }) => String(evaluate(expression)),
  }),
};

// La liste des outils, au format attendu par l'API
export const tools: Tool[] = Object.entries(toolRegistry).map(
  ([name, tool]) => ({
    type: "function",
    function: {
      name,
      description: tool.description,
      parameters: tool.parameters,
    },
  })
);

export async function executeToolCall(
  name: string,
  args: Record<string, unknown>
): Promise<unknown> {
  const tool = toolRegistry[name];
  if (!tool) {
    return { error: `Outil inconnu: ${name}` };
  }

  try {
    return await tool.run(args);
  } catch (error) {
    // L'erreur repart vers le LLM, qui peut corriger et réessayer
    return { error: String(error) };
  }
}

import { z } from "zod";
import { runAgent, type AgentConfig } from "./agent";
import { client, textOf } from "./mistral";

const planSchema = z.object({
  plan: z.array(
    z.object({
      step: z.number(),
      description: z.string(),
      tools_needed: z.array(z.string()),
    })
  ),
});

type PlanStep = z.infer<typeof planSchema>["plan"][number];

function buildPlanningPrompt(config: AgentConfig): string {
  const toolsList = config.tools
    .map((t) => `- ${t.function.name}: ${t.function.description}`)
    .join("\n");

  return `Tu es un agent de planification.

Outils disponibles :
${toolsList}

Étant donné un objectif, crée un plan d'action.
Chaque étape doit être :
- Spécifique et actionnable
- Vérifiable (on peut savoir si c'est fait)
- Réalisable avec les outils listés ci-dessus

Réponds en JSON :
{
  "plan": [
    { "step": 1, "description": "...", "tools_needed": ["nom_outil"] },
    { "step": 2, "description": "...", "tools_needed": ["nom_outil"] }
  ]
}`;
}

async function planTask(objective: string, config: AgentConfig): Promise<PlanStep[]> {
  const response = await client.chat.complete({
    model: config.model,
    messages: [
      { role: "system", content: buildPlanningPrompt(config) },
      { role: "user", content: objective },
    ],
    responseFormat: { type: "json_object" },
  });

  const content = textOf(response.choices[0]?.message?.content);
  // Le JSON vient d'un LLM : on le valide avant de s'en servir
  return planSchema.parse(JSON.parse(content)).plan;
}

export async function runPlanningAgent(
  objective: string,
  config: AgentConfig
): Promise<string> {
  console.log("📝 Phase de planification...");
  const plan = await planTask(objective, config);
  plan.forEach((step) => console.log(`  ${step.step}. ${step.description}`));

  const results: string[] = [];

  for (const step of plan) {
    console.log(`\n🎯 Étape ${step.step}: ${step.description}`);

    const stepResult = await runAgent(
      `Tu exécutes l'étape ${step.step} d'un plan plus large.
Objectif global : ${objective}
Ta tâche : ${step.description}
Résultats des étapes précédentes :
${results.join("\n")}`,
      config
    );

    results.push(`Étape ${step.step}: ${stepResult}`);
  }

  // Synthèse finale : un appel simple, sans outil
  const synthesis = await client.chat.complete({
    model: config.model,
    messages: [
      {
        role: "user",
        content: `Synthétise ces résultats pour répondre à l'objectif "${objective}" :\n${results.join("\n")}`,
      },
    ],
  });
  return textOf(synthesis.choices[0]?.message?.content);
}

import { client, textOf, type Message } from "./mistral";

// 1. Fenêtre glissante : on garde la consigne, l'objectif et les N derniers messages
export function trimMessages(messages: Message[], maxRecent: number): Message[] {
  const head = messages.slice(0, 2); // system + objectif
  const rest = messages.slice(2);
  if (rest.length <= maxRecent) return messages;

  let start = rest.length - maxRecent;
  // Un message "tool" sans l'appel qui le précède est refusé par l'API :
  // on avance jusqu'au prochain message qui n'est pas un résultat d'outil
  while (start < rest.length && rest[start].role === "tool") start++;

  return [...head, ...rest.slice(start)];
}

// 2. Résumé : on condense les vieux messages en un seul texte
export async function summarizeContext(messages: Message[]): Promise<string> {
  const response = await client.chat.complete({
    model: "mistral-small-latest",
    messages: [
      {
        role: "system",
        content:
          "Résume cet échange en gardant les faits établis, les sources et ce qu'il reste à faire.",
      },
      { role: "user", content: JSON.stringify(messages) },
    ],
  });
  return textOf(response.choices[0]?.message?.content);
}

interface Memory {
  id: string;
  content: string;
  embedding: number[];
  timestamp: Date;
  metadata: Record<string, unknown>;
}

export class LongTermMemory {
  private memories: Memory[] = [];

  async store(content: string, metadata: Record<string, unknown> = {}): Promise<void> {
    this.memories.push({
      id: crypto.randomUUID(),
      content,
      embedding: await this.embed(content),
      timestamp: new Date(),
      metadata,
    });
  }

  async recall(query: string, limit = 5): Promise<Memory[]> {
    const queryEmbedding = await this.embed(query);

    // Recherche par similarité cosinus
    return this.memories
      .map((memory) => ({
        memory,
        score: this.cosineSimilarity(queryEmbedding, memory.embedding),
      }))
      .sort((a, b) => b.score - a.score)
      .slice(0, limit)
      .map((result) => result.memory);
  }

  private async embed(text: string): Promise<number[]> {
    const response = await client.embeddings.create({
      model: "mistral-embed",
      inputs: [text],
    });
    const embedding = response.data[0]?.embedding;
    if (!embedding) throw new Error("Pas d'embedding retourné");
    return embedding;
  }

  private cosineSimilarity(a: number[], b: number[]): number {
    const dot = a.reduce((sum, val, i) => sum + val * b[i], 0);
    const normA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0));
    const normB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0));
    return dot / (normA * normB);
  }
}

// Trois fois de suite la même action avec les mêmes arguments : l'agent tourne en rond
export function detectLoop(actionHistory: string[]): boolean {
  const last3 = actionHistory.slice(-3);
  return last3.length === 3 && last3.every((action) => action === last3[0]);
}

import * as readline from "node:readline/promises";

export async function askUserConfirmation(prompt: string): Promise<boolean> {
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  });
  const answer = await rl.question(`${prompt} (o/n) : `);
  rl.close();
  return answer.trim().toLowerCase() === "o";
}

import { mkdir, writeFile } from "node:fs/promises";
import path from "node:path";
import { askUserConfirmation } from "./guards";

// À ajouter dans toolRegistry
  save_report: defineTool({
    description: "Enregistre un rapport en Markdown dans le dossier rapports/.",
    dangerous: true,
    schema: z.object({
      filename: z.string().describe("Nom du fichier, par exemple typescript.md"),
      content: z.string().describe("Le contenu du rapport"),
    }),
    execute: async ({ filename, content }) => {
      // basename : le LLM ne choisit pas le dossier d'écriture
      const target = path.join("rapports", path.basename(filename));
      await mkdir("rapports", { recursive: true });
      await writeFile(target, content);
      return `Rapport enregistré dans ${target}`;
    },
  }),

export async function executeToolCall(
  name: string,
  args: Record<string, unknown>
): Promise<unknown> {
  const tool = toolRegistry[name];
  if (!tool) {
    return { error: `Outil inconnu: ${name}` };
  }

  if (tool.dangerous) {
    console.log(`⚠️  Action sensible: ${name}`, args);
    const confirmed = await askUserConfirmation("Autoriser cette action ?");
    if (!confirmed) {
      return { error: "Action refusée par l'utilisateur" };
    }
  }

  try {
    return await tool.run(args);
  } catch (error) {
    return { error: String(error) };
  }
}

export class CostTracker {
  private inputTokens = 0;
  private outputTokens = 0;

  // Prix de Mistral Small 4 en novembre 2026, en dollars par million de tokens
  constructor(
    private readonly maxBudgetUSD: number,
    private readonly inputPricePerMillion = 0.15,
    private readonly outputPricePerMillion = 0.6
  ) {}

  track(usage: { promptTokens?: number; completionTokens?: number }): void {
    this.inputTokens += usage.promptTokens ?? 0;
    this.outputTokens += usage.completionTokens ?? 0;
  }

  getCost(): number {
    return (
      (this.inputTokens * this.inputPricePerMillion +
        this.outputTokens * this.outputPricePerMillion) /
      1_000_000
    );
  }

  isOverBudget(): boolean {
    return this.getCost() > this.maxBudgetUSD;
  }

  report(): string {
    return `Tokens: ${this.inputTokens} in / ${this.outputTokens} out (~$${this.getCost().toFixed(6)})`;
  }
}

import type { Tool } from "@mistralai/mistralai/models/components";
import { CostTracker, detectLoop } from "./guards";
import { trimMessages } from "./memory";
import { client, textOf, type Message } from "./mistral";

export interface AgentConfig {
  model: string;
  systemPrompt: string;
  tools: Tool[];
  executeTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
  maxIterations?: number;
  maxBudgetUSD?: number;
}

export async function runAgent(
  objective: string,
  config: AgentConfig
): Promise<string> {
  const maxIterations = config.maxIterations ?? 10;
  const costs = new CostTracker(config.maxBudgetUSD ?? 0.05);
  const actionHistory: string[] = [];

  let messages: Message[] = [
    { role: "system", content: config.systemPrompt },
    { role: "user", content: objective },
  ];

  for (let iteration = 1; iteration <= maxIterations; iteration++) {
    console.log(`\n--- Itération ${iteration} ---`);

    // Garde-fou 1 : le contexte ne grossit pas indéfiniment
    messages = trimMessages(messages, 20);

    const response = await client.chat.complete({
      model: config.model,
      messages,
      tools: config.tools,
      parallelToolCalls: false,
    });

    // Garde-fou 2 : le budget
    costs.track(response.usage);
    if (costs.isOverBudget()) {
      throw new Error(`Budget dépassé. ${costs.report()}`);
    }

    const choice = response.choices[0];
    const assistantMessage = choice?.message;
    if (!assistantMessage) throw new Error("Pas de réponse du modèle");

    messages.push({ ...assistantMessage, role: "assistant" });
    const thought = textOf(assistantMessage.content);

    if (choice.finishReason === "tool_calls" && assistantMessage.toolCalls) {
      if (thought) console.log(`💭 ${thought}`);

      // Garde-fou 3 : la même action trois fois de suite
      actionHistory.push(
        JSON.stringify(assistantMessage.toolCalls.map((call) => call.function))
      );
      if (detectLoop(actionHistory)) {
        throw new Error("Boucle détectée : l'agent répète la même action");
      }

      for (const toolCall of assistantMessage.toolCalls) {
        const name = toolCall.function.name;
        const rawArgs = toolCall.function.arguments;
        const args = typeof rawArgs === "string" ? JSON.parse(rawArgs) : rawArgs;

        console.log(`🔧 Action: ${name}`, args);
        // Garde-fou 4 : executeTool demande confirmation pour les outils sensibles
        const result = await config.executeTool(name, args);

        const content = (
          typeof result === "string" ? result : JSON.stringify(result)
        ).slice(0, 4000);
        console.log(`📋 Observation: ${content.slice(0, 200)}`);

        messages.push({ role: "tool", toolCallId: toolCall.id, name, content });
      }
      continue;
    }

    console.log(`✅ Terminé en ${iteration} itération(s). ${costs.report()}`);
    return thought;
  }

  // Garde-fou 5 : la limite d'itérations
  throw new Error(`Agent arrêté après ${maxIterations} itérations`);
}

import { runAgent } from "./agent";
import { executeToolCall, tools } from "./tools";

const SYSTEM_PROMPT = `Tu es un agent de recherche. Tu aides l'utilisateur à trouver des informations fiables.

Méthode :
- Avant chaque appel d'outil, écris en une ou deux phrases ce que tu cherches et pourquoi.
- Commence par une recherche web, puis lis les 2 ou 3 pages les plus prometteuses.
- Si un outil échoue ou ne donne rien, change d'approche au lieu de recommencer à l'identique.
- Quand tu as assez d'éléments, réponds directement, sans appeler d'outil.

Règles :
- Privilégie les sources officielles et récentes, et cite-les.
- Distingue ce qui vient des sources de ce qui est ton analyse.
- Si tu ne trouves pas l'information, dis-le.`;

const answer = await runAgent(
  process.argv[2] ?? "Quelles sont les nouveautés de TypeScript 5.4 ?",
  {
    model: "mistral-small-latest",
    systemPrompt: SYSTEM_PROMPT,
    tools,
    executeTool: executeToolCall,
    maxIterations: 10,
    maxBudgetUSD: 0.05,
  }
);

console.log("\n📝 Réponse finale :\n", answer);

export TAVILY_API_KEY="ta-clé-tavily"
npx tsx src/main.ts "Quelles sont les nouveautés de TypeScript 5.4 ?"

--- Itération 1 ---
🔧 Action: web_search { query: 'TypeScript 5.4 new features' }
📋 Observation: {"results":[{"title":"Announcing TypeScript 5.4","url":"https://devblogs.microsoft.com/typescript/announcing-typescript-5-4/", ...

--- Itération 2 ---
🔧 Action: read_url { url: 'https://devblogs.microsoft.com/typescript/announcing-typescript-5-4/' }
📋 Observation: TypeScript 5.4 brings several improvements including...

--- Itération 3 ---
✅ Terminé en 3 itération(s).

📝 Réponse finale :
TypeScript 5.4 (mars 2024) apporte plusieurs nouveautés :

1. Preserved Narrowing in Closures : le type narrowing est maintenant préservé dans les closures après la dernière assignation.

2. NoInfer Utility Type : nouveau type utilitaire pour empêcher l'inférence sur certains paramètres génériques.

3. Object.groupBy et Map.groupBy : support de ces nouvelles méthodes.

Source : Blog officiel TypeScript (https://devblogs.microsoft.com/typescript/announcing-typescript-5-4/)