Créer un agent IA en production : les étapes que personne ne montre

Les tutoriels sur les agents IA s’arrêtent tous au même endroit : le prototype qui marche dans un Jupyter notebook. Ici je couvre ce qui vient après — créer un agent qui tourne en production avec de vrais utilisateurs.

Ce qu’est réellement un agent IA (en pratique)

Un agent IA, c’est une boucle : le modèle reçoit un contexte, décide d’une action, exécute l’outil correspondant, récupère le résultat, et recommence jusqu’à avoir une réponse finale.

Architecture minimale :

interface AgentStep {
  thought: string;
  tool?: string;
  toolInput?: Record<string, unknown>;
  observation?: string;
  finalAnswer?: string;
}

async function runAgent(userQuery: string, tools: Tool[]): Promise<string> {
  const messages: Message[] = [{ role: 'user', content: userQuery }];

  for (let i = 0; i < MAX_STEPS; i++) {
    const response = await callClaude({ messages, tools });
    const step = parseAgentResponse(response);

    if (step.finalAnswer) return step.finalAnswer;
    if (!step.tool) throw new Error('Agent stuck: no tool, no answer');

    const result = await executeTool(step.tool, step.toolInput);
    messages.push(
      { role: 'assistant', content: response.content },
      { role: 'user', content: `Tool result: ${result}` }
    );
  }
  throw new Error(`Agent exceeded MAX_STEPS (${MAX_STEPS})`);
}

MAX_STEPS est non négociable. Sans ça, un agent peut loofer indéfiniment.

Définir les outils avec précision

La qualité des outils est ce qui fait la différence entre un agent utile et un agent qui hallucine.

Chaque outil a besoin :

• D’un nom explicite (search_database, pas search)
• D’une description qui dit quand l’utiliser ET quand ne pas l’utiliser
• D’un schéma JSON strict pour les paramètres

const searchTool = {
  name: "search_client_database",
  description: `Search the client database by name, SIRET, or email.
    Use when: the user asks about a specific client or wants client details.
    Do NOT use for: general statistics or reports — use get_stats instead.`,
  input_schema: {
    type: "object",
    properties: {
      query: { type: "string", description: "Name, SIRET, or email" },
      limit: { type: "number", description: "Max results, default 5" }
    },
    required: ["query"]
  }
};

Plus la description est précise, moins l’agent fait d’appels inutiles.

Gérer les états et la persistance

Un agent de prod a besoin d’état persistant entre les sessions. J’utilise un pattern simple :

interface AgentSession {
  id: string;
  userId: string;
  messages: Message[];
  context: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
}

En pratique : Redis pour les sessions actives (TTL 30min), PostgreSQL pour l’historique long terme.

Tests avant mise en production

Ce que je teste systématiquement :

• Happy path : l’agent complète la tâche en ≤ N étapes
• Tool failure : un outil retourne une erreur — l’agent doit se dégrader gracieusement
• Boucle infinie : MAX_STEPS est atteint — l’agent doit sortir proprement
• Input malveillant : injection de prompt, dépassement de contexte
• Coût moyen : valider que le coût par session reste dans le budget

describe('AgentCore', () => {
  it('completes booking in ≤5 steps', async () => {
    const result = await runAgent('Book a meeting for next Tuesday', mockTools);
    expect(result).toContain('confirmed');
    expect(stepCount).toBeLessThanOrEqual(5);
  });

  it('handles tool failure gracefully', async () => {
    mockTools.search_calendar.mockRejectedValue(new Error('timeout'));
    const result = await runAgent('Check my schedule', mockTools);
    expect(result).toContain('unavailable');
  });
});

Monitoring en production

Deux métriques critiques à surveiller en temps réel :

1. Nombre de steps moyen par session — si ça monte, un outil est cassé ou le prompt est ambigu
2. Taux de session MAX_STEPS — si > 2%, il y a un bug dans la logique de l’agent

Sans monitoring, tu découvres les problèmes quand l’utilisateur se plaint. Avec, tu les vois avant.

Ce qu’on ne fait pas

• On ne met pas en prod sans jeu de tests de régression
• On ne dépasse pas 10 outils par agent (au-delà, le modèle se perd)
• On ne laisse pas un agent modifier des données critiques sans confirmation humaine