Concevoir un module agentique IA dans vos projets TypeScript, React ou Python

En 2025, les chatbots généraient du texte. En 2026, les agents IA prennent des décisions, exécutent des actions et collaborent entre eux. La différence n'est pas cosmétique : elle transforme la façon dont on conçoit des logiciels.

Si vous travaillez sur un projet TypeScript, React, Node.js ou Python, vous avez probablement déjà envisagé d'y intégrer une brique d'IA. Mais entre un simple appel API à un LLM et un véritable module agentique, il y a un fossé. Cet article vous donne les clés pour le franchir : les patterns fondamentaux, les frameworks disponibles et les choix d'architecture à faire.

Qu'est-ce qu'un agent IA (et qu'est-ce que ce n'est pas) ?

Un chatbot prend une question et renvoie une réponse. Un agent IA prend un objectif et décide seul comment l'atteindre.

Concrètement, un agent :

• Raisonne sur la tâche à accomplir avant d'agir
• Utilise des outils (API, bases de données, systèmes de fichiers) pour collecter des informations ou exécuter des actions
• Itère en boucle jusqu'à ce que le résultat soit satisfaisant
• Gère un contexte qui persiste entre les étapes

Un formulaire de contact "intelligent" qui reformule un email n'est pas un agent. Un système qui analyse un ticket de support, consulte la documentation technique, identifie la cause probable et propose un correctif dans une pull request en est un.

Les patterns architecturaux fondamentaux

Avant de choisir un framework, il faut comprendre les mécanismes qui font fonctionner un agent. Quatre patterns reviennent systématiquement.

La boucle agentique

C'est le cœur de tout agent. Le modèle reçoit une instruction, raisonne, décide s'il doit utiliser un outil, observe le résultat, puis recommence jusqu'à atteindre son objectif. On parle souvent du pattern ReAct (Reasoning + Acting).

// Pseudo-code d'une boucle agentique
while (!taskCompleted) {
  const reasoning = await llm.think(context)
  const action = reasoning.nextAction

  if (action.type === 'tool_call') {
    const result = await executeTool(action.tool, action.params)
    context.addObservation(result)
  } else if (action.type === 'final_answer') {
    taskCompleted = true
    return action.answer
  }
}

En pratique, vous n'écrirez pas cette boucle à la main. Les frameworks modernes l'implémentent pour vous. Mais comprendre ce mécanisme est indispensable pour debugger un agent qui ne se comporte pas comme prévu.

Tool calling (appel d'outils)

Le tool calling permet à un LLM de "sortir de sa bulle" et d'interagir avec le monde extérieur. Vous déclarez des outils avec un schéma d'entrée typé et le modèle décide quand et comment les appeler.

const tools = {
  searchDatabase: {
    description: 'Recherche dans la base de donnees clients',
    parameters: z.object({
      query: z.string(),
      limit: z.number().default(10),
    }),
    execute: async ({ query, limit }) => {
      return await db.clients.search(query, { limit })
    },
  },
}

Tous les LLM majeurs supportent le tool calling nativement : Claude (Anthropic), GPT-5.6 (OpenAI), Gemini (Google). C'est devenu le standard d'interaction entre un modèle et votre code.

MCP : le protocole qui standardise tout

Le Model Context Protocol (MCP) est un standard ouvert créé par Anthropic qui définit comment un agent IA se connecte à des sources de données et des outils externes. Pensez-y comme le "USB-C des agents IA" : une interface universelle.

Avant MCP, chaque intégration nécessitait du code spécifique. Avec MCP, un serveur MCP expose des outils que n'importe quel client compatible peut utiliser. L'écosystème a explosé en 2026 :

• Zapier MCP connecte vos agents à plus de 7 000 applications
• Supabase MCP expose vos données Postgres directement aux agents
• GitHub, Slack, Notion, Jira ont tous des serveurs MCP officiels
• Azure MCP Server est intégré nativement dans Visual Studio 2026

Le choix est simple : si vous construisez un outil qu'un agent doit utiliser, exposez-le via MCP. Vous le rendez compatible avec tout l'écosystème d'un coup.

Mémoire et contexte

Un agent sans mémoire oublie tout entre chaque échange. Trois types de mémoire coexistent :

Pour la mémoire à long terme, la technique la plus répandue est le RAG (Retrieval-Augmented Generation) : vos documents sont indexés dans une base vectorielle et l'agent y puise le contexte pertinent avant de répondre.

Panorama des frameworks en 2026

L'écosystème des frameworks agentiques a considérablement mûri. Voici les options les plus solides selon votre stack technique.

Claude Agent SDK (Anthropic)

Le SDK officiel d'Anthropic donne accès aux mêmes outils qui font tourner Claude Code. Disponible en TypeScript et Python.

Points forts :

• Support natif de MCP (serveurs locaux, HTTP, ou embarqués dans votre app)
• Sous-agents avec contextes isolés et coordination automatique
• Agent Teams (nouveauté Opus 4.6, février 2026) : décomposition d'une tâche en rôles spécialisés (planificateur, chercheur, codeur, testeur) qui travaillent en parallèle
• Tool search dynamique pour éviter de saturer la fenêtre de contexte

import { Agent, tool } from '@anthropic-ai/agent'
import { z } from 'zod'

const analyzeCode = tool({
  name: 'analyze_code',
  description: 'Analyse statique du code source',
  inputSchema: z.object({
    filePath: z.string(),
    checks: z.array(z.enum(['security', 'performance', 'style'])),
  }),
  handler: async ({ filePath, checks }) => {
    const results = await runStaticAnalysis(filePath, checks)
    return { content: [{ type: 'text', text: JSON.stringify(results) }] }
  },
})

const agent = new Agent({
  model: 'claude-sonnet-5',
  instructions: 'Tu es un assistant de revue de code.',
  tools: [analyzeCode],
})

Idéal pour : les projets qui misent sur Claude, les cas d'usage nécessitant de l'orchestration multi-agents, l'intégration avec l'écosystème MCP.

Vercel AI SDK 6

La version 6 du AI SDK de Vercel fait de l'agent une abstraction de premier ordre avec la classe ToolLoopAgent. L'intégration avec Next.js et React est native.

Points forts :

• ToolLoopAgent : boucle agentique clé-en-main avec gestion automatique des appels d'outils (jusqu'à 20 étapes par défaut)
• Interface Agent extensible pour implémenter vos propres abstractions
• Streaming natif pour des interfaces React réactives
• Agnostique au modèle (OpenAI, Anthropic, Google, Mistral)

import { ToolLoopAgent } from 'ai'
import { anthropic } from '@ai-sdk/anthropic'

const agent = new ToolLoopAgent({
  model: anthropic('claude-sonnet-5'),
  instructions: 'Tu es un assistant de planification de projet.',
  tools: {
    createTask: {
      description: 'Cree une tache dans le gestionnaire de projet',
      parameters: z.object({
        title: z.string(),
        assignee: z.string(),
        priority: z.enum(['low', 'medium', 'high']),
      }),
      execute: async (params) => await projectManager.createTask(params),
    },
  },
  maxSteps: 15,
})

const result = await agent.generate({
  prompt: 'Planifie le sprint de la semaine prochaine.',
})

Idéal pour : les projets Next.js / React existants, les équipes qui veulent rester agnostiques au fournisseur LLM, le prototypage rapide.

Google Agent Development Kit (ADK)

ADK est le framework open-source de Google, disponible en TypeScript et Python. Il est optimisé pour Gemini mais compatible avec d'autres modèles.

Points forts :

• Architecture multi-agents native avec agents superviseurs et sous-agents
• Typage end-to-end en TypeScript
• CLI et Developer UI intégrés pour le debugging
• Streaming bidirectionnel audio/vidéo
• Deploy anywhere : conteneurs, serverless, Google Cloud Run

Idéal pour : les projets liés à l'écosystème Google Cloud, les applications nécessitant du streaming multimédia, les équipes qui veulent un outillage de debug avancé.

Mastra

Framework TypeScript open-source qui se démarque par son approche "batteries incluses". Il combine agents, workflows et observabilité dans un seul package.

Points forts :

• Workflows déclaratifs sous forme de machines à états (branchement, pause, reprise)
• Système de mémoire intégré (court terme et long terme)
• RAG natif avec une API unifiée de vector store
• Observabilité et scoring intégrés pour mesurer la qualité des réponses
• Documentation embarquée dans le package npm pour faciliter le travail avec des outils IA

Idéal pour : les projets TypeScript/Node.js qui veulent un framework tout-en-un, les équipes qui valorisent l'observabilité de leurs agents.

Comment choisir ?

Le choix dépend de trois facteurs : votre stack existante, le LLM que vous ciblez et la complexité de l'orchestration dont vous avez besoin. Pour un projet React/Next.js, le Vercel AI SDK 6 offre l'intégration la plus fluide. Pour de l'orchestration multi-agents poussée, le Claude Agent SDK ou Google ADK seront plus adaptés.

Intégrer un agent dans un projet existant

Ajouter un module agentique à un projet existant ne devrait pas nécessiter une réécriture. Voici les principes qui marchent en pratique.

Commencer par un périmètre réduit

Ne construisez pas un agent généraliste. Identifiez une tâche répétitive et bien définie dans votre application, puis automatisez-la. Exemples :

• Un agent qui analyse les retours clients et catégorise les tickets
• Un agent qui génère des rapports hebdomadaires à partir de données structurées
• Un agent qui assiste les développeurs dans la revue de code

Isoler le module agentique

Votre agent doit être un module autonome, découplé du reste de l'application. En TypeScript :

// src/agents/support-agent/index.ts
export class SupportAgent {
  private agent: ToolLoopAgent

  constructor(config: SupportAgentConfig) {
    this.agent = new ToolLoopAgent({
      model: config.model,
      instructions: SUPPORT_AGENT_PROMPT,
      tools: this.buildTools(config),
      maxSteps: config.maxSteps ?? 10,
    })
  }

  async analyzeTicket(ticket: SupportTicket): Promise<TicketAnalysis> {
    const result = await this.agent.generate({
      prompt: `Analyse ce ticket de support : ${JSON.stringify(ticket)}`,
    })
    return parseAnalysis(result.text)
  }

  private buildTools(config: SupportAgentConfig) {
    return {
      searchDocs: createDocSearchTool(config.docsIndex),
      getClientHistory: createClientHistoryTool(config.db),
      createFollowUp: createFollowUpTool(config.ticketSystem),
    }
  }
}

Cette encapsulation vous permet de :

• Tester l'agent indépendamment du reste de l'application
• Changer de framework ou de modèle sans toucher au code appelant
• Contrôler finement les permissions et les outils accessibles

Gérer les erreurs et les limites

Un agent peut échouer de plusieurs façons : le LLM hallucine, un outil renvoie une erreur, la boucle tourne indéfiniment. Prévoyez :

1. Un nombre maximum d'itérations pour éviter les boucles infinies
2. Un timeout global sur l'exécution de l'agent
3. Une validation des sorties avant de les utiliser dans votre application
4. Un fallback vers un comportement déterministe si l'agent échoue

const result = await Promise.race([
  agent.analyzeTicket(ticket),
  timeout(30_000, 'Agent timeout'),
])

if (!isValidAnalysis(result)) {
  return fallbackAnalysis(ticket)
}

Tester un agent

Tester un agent est différent de tester du code déterministe. Trois niveaux de tests sont utiles :

• Tests unitaires sur les outils : chaque outil doit fonctionner correctement avec des entrées valides et invalides
• Tests d'intégration avec le LLM : vérifiez que l'agent appelle les bons outils dans le bon ordre pour des scénarios connus
• Tests de non-régression sur les sorties : stockez des paires entrée/sortie attendues et mesurez la déviation

describe('SupportAgent', () => {
  it('devrait consulter la documentation pour un bug technique', async () => {
    const agent = new SupportAgent(testConfig)
    const result = await agent.analyzeTicket(technicalBugTicket)

    expect(result.category).toBe('bug_technique')
    expect(result.toolsCalled).toContain('searchDocs')
    expect(result.suggestedAction).toBeDefined()
  })
})

Scorer les sorties de votre agent

Les tests vous disent si l'agent fonctionne. Les scorers vous disent à quel point il fonctionne bien. La différence est importante : un agent peut appeler les bons outils dans le bon ordre et produire une réponse techniquement correcte mais inutile, vague ou hors sujet.

Un scorer est une fonction qui prend la sortie de votre agent et renvoie un score entre 0 et 1. Deux approches coexistent :

• Scorers déterministes : des règles codées en dur (présence de mots-clés, format JSON valide, longueur de réponse, distance de Levenshtein). Rapides, gratuits, reproductibles.
• LLM-as-a-judge : un LLM évalue la sortie d'un autre LLM selon des critères en langage naturel (pertinence, exactitude, ton). Plus nuancé, mais plus lent et plus coûteux.

import { Factuality } from 'autoevals'

// Scorer deterministe : verifie la structure de la reponse
const formatScorer = ({ output }: { output: string }) => {
  const parsed = JSON.parse(output)
  const hasRequiredFields = 'category' in parsed && 'priority' in parsed
  return { name: 'Format', score: hasRequiredFields ? 1 : 0 }
}

// LLM-as-a-judge : evalue l'exactitude factuelle
const factualityScore = await Factuality({
  input: 'Quel est le delai de livraison standard ?',
  output: agent.lastResponse,
  expected: 'Le delai standard est de 3 a 5 jours ouvrables.',
})
// factualityScore.score → 0.0 a 1.0

En pratique, combinez les deux. Les scorers déterministes servent de garde-fous rapides (format, sécurité, longueur). Les scorers LLM-as-a-judge mesurent les dimensions subjectives (pertinence, clarté, ton).

Des librairies comme autoevals (Braintrust) fournissent des scorers prêts à l'emploi : factualité, similarité sémantique, détection de modération, qualité de résumé. Mastra intègre directement un système de scorers dans son framework avec la fonction createScorer. Pour le Vercel AI SDK, la combinaison avec Vitest permet d'intégrer les evals dans votre pipeline de CI.

L'objectif n'est pas d'atteindre un score parfait, mais de détecter les régressions. Chaque nouveau prompt, chaque changement d'outil ou de modèle peut dégrader la qualité sans qu'un test classique ne le détecte. Les scorers rendent cette dégradation visible et mesurable.

Ce qui change en production

Le passage en production d'un agent IA introduit des contraintes spécifiques.

Coût. Chaque itération de la boucle agentique consomme des tokens. Un agent mal configuré qui tourne en boucle peut générer une facture imprévue. Monitorez le nombre de tokens par requête et définissez des budgets par agent.

Latence. Un agent qui enchaîne 5 appels d'outils avec un LLM distant prend du temps. Concevez votre UX en conséquence : streaming des résultats intermédiaires, indicateurs de progression et possibilité pour l'utilisateur d'interrompre l'exécution.

Sécurité. Un agent avec accès à vos outils est aussi puissant que dangereux. Appliquez le principe du moindre privilège : chaque agent ne doit avoir accès qu'aux outils strictement nécessaires à sa tâche. Validez les paramètres des appels d'outils côté serveur.

Observabilité. Loggez chaque étape de la boucle agentique : le raisonnement du modèle, les outils appelés, les résultats obtenus. Sans ces logs, debugger un comportement inattendu est quasiment impossible.

Conclusion

L'IA agentique n'est plus un concept de recherche. Les frameworks sont matures, les patterns sont documentés et l'écosystème MCP fournit une couche d'intégration standardisée. Le vrai défi n'est plus technique, il est stratégique : identifier les bonnes tâches à automatiser et concevoir des agents qui s'intègrent proprement dans votre architecture existante.

Les points clés à retenir :

• Un agent IA n'est pas un chatbot : il raisonne, utilise des outils et itère
• Quatre patterns fondamentaux : boucle agentique, tool calling, MCP, mémoire
• Choisissez votre framework selon votre stack et vos besoins d'orchestration
• Isolez votre module agentique pour garder votre codebase maintenable
• En production, surveillez les coûts, la latence et la sécurité

L'intégration d'un module agentique dans un projet existant est un investissement mesuré qui peut transformer radicalement la valeur de votre produit. Le plus important est de commencer petit, avec une tâche concrète et d'itérer. C'est exactement le périmètre que je cadre et je livre sur une prestation de produits web IA-first.