Développement d'agents IA : guide d'architecture et de mise en œuvre

Un agent ReAct est resté bloqué vingt minutes dans une boucle infinie, rappelant le même outil encore et again. Cause : pas de maxIterations — arrêt forcé après la limite pour éviter la boucle. C’est le piège le plus courant : boucle ReAct, système multi-agents qui ne converge pas, Plan-and-Execute trop rigide pour les tâches dynamiques.

L’architecture agent se décline en trois niveaux : appel direct au modèle pour les tâches en une étape, agent unique + outils par défaut pour la plupart des cas, orchestration multi-agents à introduire avec prudence. ReAct convient aux décisions dynamiques, Plan-and-Execute aux flux stables, Multi-Agent à la spécialisation. Azure recommande de limiter les agents en group chat à 3 — au-delà, la discussion peine à converger.

Cet article expose deux ans d’expérience terrain : principes et code des trois modes d’architecture, cinq modes d’orchestration multi-agents, choix LangChain/AutoGen/CrewAI/Claude Agent SDK, et un agent fonctionnel avec Claude Agent SDK.

1. Les trois niveaux d’architecture agent

Un principe que beaucoup de débutants oublient : si une solution simple suffit, n’ajoutez pas de complexité.

Azure distingue trois niveaux — une classification très pratique :

1.1 Appel direct au modèle (Direct Model Call)

Le niveau le plus simple. Vous soumettez la tâche au modèle, il renvoie une réponse.

// Appel le plus basique
const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Résumez ce texte...' }]
});

Convient aux tâches en une étape, aux scénarios déterministes, sans outils externes : résumé, traduction, complétion de code.

Avantages : simple, économique, maîtrisable. Inconvénients : pas de raisonnement multi-étapes ni d’appel d’outils externes.

1.2 Agent unique + outils (Single Agent with Tools)

Choix par défaut pour la plupart des scénarios entreprise. L’agent appelle des outils et gère des tâches multi-étapes.

// Exemple agent unique LangChain
import { ChatAnthropic } from '@langchain/anthropic';
import { AgentExecutor, createToolCallingAgent } from 'langchain/agents';
import { tool } from '@langchain/core/tools';
import { z } from 'zod';

// Outil météo
const weatherTool = tool(
  async ({ city }) => {
    // Simulation d'appel API météo
    return `${city} : ensoleillé aujourd'hui, 22°C`;
  },
  {
    name: 'get_weather',
    description: 'Obtenir la météo d\'une ville',
    schema: z.object({
      city: z.string().describe('Nom de la ville'),
    }),
  }
);

const model = new ChatAnthropic({
  model: 'claude-sonnet-4-20250514',
  temperature: 0,
});

const agent = await createToolCallingAgent({
  llm: model,
  tools: [weatherTool],
  prompt: 'Vous êtes un assistant utile.',
});

const executor = AgentExecutor.fromAgentAndTools({
  agent,
  tools: [weatherTool],
});

// Exécution
const result = await executor.invoke({
  input: 'Quel temps fait-il à Pékin aujourd\'hui ?',
});

Convient aux scénarios avec outils, tâches décomposables, étapes relativement fixes : analyse de données, exécution de code, orchestration d’API.

1.3 Orchestration multi-agents (Multi-Agent Orchestration)

Le niveau le plus complexe. Plusieurs agents spécialisés collaborent.

Franchement, moins de cas que vous ne le pensez justifient ce niveau. Multi-agents = surcoût de coordination, gestion d’état et débogage qui montent en exponentiel.

Convient aux tâches transverses, à la division du travail par expertise, quand un seul agent ne suffit pas : pipeline dev (analyse → design → code → tests), systèmes de décision complexes.

1.4 Comment choisir ? Tableau de décision

En résumé : partez du simple, ajoutez ce qu’il faut.

2. Les trois modes d’architecture clés

Une fois le niveau choisi, il faut choisir le mode. Ces trois approches ne s’excluent pas — on les combine souvent.

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

2.1 Mode ReAct (Reasoning + Acting)

ReAct = Reasoning + Acting : le modèle « réfléchit en agissant ».

Principe :

Entrée utilisateur → Thought (réflexion) → Action → Observation → boucle ou fin

Exemple : « Demain à Pékin, le temps convient-il au sport dehors ? »

1. Thought : je dois d’abord consulter la météo de demain à Pékin
2. Action : appeler get_weather, paramètre city: "Pékin"
3. Observation : demain nuageux, 18–25°C, 10 % de pluie
4. Thought : température correcte, faible pluie — adapté au sport dehors
5. Final Answer : oui, demain convient ; prévoir une veste légère

Implémentation (LangChain) :

import { ChatAnthropic } from '@langchain/anthropic';
import { AgentExecutor, createReactAgent } from 'langchain/agents';
import { pull } from 'langchain/hub';

// Template prompt ReAct
const prompt = await pull('hwchase17/react');

const agent = await createReactAgent({
  llm: model,
  tools: [weatherTool, searchTool],
  prompt,
});

// Limite d'itérations — évite la boucle infinie !
const executor = AgentExecutor.fromAgentAndTools({
  agent,
  tools: [weatherTool, searchTool],
  maxIterations: 10,
  verbose: true,
});

Avantages et inconvénients :

Piège : définissez maxIterations, sinon l’agent peut tourner indéfiniment — mon premier ReAct a tourné toute une nuit.

2.2 Mode Plan-and-Execute

ReAct avance « pas à pas » et peut dériver sur les tâches complexes. Plan-and-Execute : plan d’abord, exécution ensuite.

Principe :

Entrée → Planner génère le plan → Executor exécute étape par étape → résultat

Implémentation (LangGraph) :

import { ChatAnthropic } from '@langchain/anthropic';
import { StateGraph, END } from '@langchain/langgraph';

interface AgentState {
  input: string;
  plan: string[];
  pastSteps: string[];
  response: string;
}

async function planNode(state: AgentState): Promise<AgentState> {
  const plannerPrompt = `Objectif utilisateur : ${state.input}
Générez un plan détaillé, une chaîne par étape, format tableau JSON.`;

  const response = await model.invoke(plannerPrompt);
  const plan = JSON.parse(response.content as string);
  return { ...state, plan };
}

async function executeNode(state: AgentState): Promise<AgentState> {
  const currentStep = state.plan[0];
  const result = await executor.invoke({ input: currentStep });

  return {
    ...state,
    plan: state.plan.slice(1),
    pastSteps: [...state.pastSteps, `${currentStep}: ${result.output}`],
  };
}

const workflow = new StateGraph<AgentState>({
  channels: {
    input: { value: null },
    plan: { value: null },
    pastSteps: { value: null, default: () => [] },
    response: { value: null },
  },
});

workflow.addNode('planner', planNode);
workflow.addNode('executor', executeNode);
workflow.addEdge('planner', 'executor');

workflow.addConditionalEdges('executor', (state) => {
  return state.plan.length > 0 ? 'executor' : END;
});

Avantages et inconvénients :

Retour d’expérience : idéal pour les tâches « à étapes prévisibles » (traitement batch, rapports). Pour les stratégies changeantes, ReAct est souvent meilleur.

2.3 Mode Multi-Agent

Quand un seul agent ne suffit plus, place aux multi-agents.

Principe : chaque agent couvre un domaine, collaboration type équipe.

Implémentation (style Claude Agent SDK) :

import { ClaudeAgent } from '@anthropic-ai/claude-agent-sdk';

const researchAgent = new ClaudeAgent({
  name: 'researcher',
  model: 'claude-sonnet-4-20250514',
  systemPrompt: 'Vous êtes expert en recherche : collecte et synthèse d\'informations.',
  tools: ['WebSearch', 'WebFetch'],
});

const writerAgent = new ClaudeAgent({
  name: 'writer',
  model: 'claude-sonnet-4-20250514',
  systemPrompt: 'Vous êtes expert rédaction : rédaction et relecture.',
  tools: ['Read', 'Write', 'Edit'],
});

const reviewerAgent = new ClaudeAgent({
  name: 'reviewer',
  model: 'claude-sonnet-4-20250514',
  systemPrompt: 'Vous êtes expert qualité : exactitude et lisibilité.',
  tools: ['Read'],
});

async function collaborativeWriting(topic: string) {
  const research = await researchAgent.run(`Rechercher le thème : ${topic}`);
  const draft = await writerAgent.run(
    `Rédiger un article à partir de :\n${research}`
  );
  const review = await reviewerAgent.run(
    `Relire et proposer des corrections :\n${draft}`
  );
  const final = await writerAgent.run(
    `Modifier selon la relecture :\nBrouillon : ${draft}\nAvis : ${review}`
  );
  return final;
}

Quand passer au multi-agent :

• Plusieurs compétences (code + design + copy)
• Contexte trop large pour un seul agent
• Division claire des rôles

Attention : le débogage explose. Synchronisation, messages, erreurs entre agents — complexité réelle. Si un agent unique suffit, n’imposez pas le multi-agent.

3. Cinq modes d’orchestration multi-agents

Si le multi-agent est justifié, choisissez le mode d’orchestration. Ces cinq modes Azure couvrent la plupart des cas.

3.1 Sequential (ordre séquentiel)

Le plus intuitif : la sortie de A alimente B, comme un pipeline.

[Agent A] → [Agent B] → [Agent C] → résultat final

Cas d’usage : pipeline documentaire (recherche → brouillon → relecture → publication), génération de code.

Exemple :

async function sequentialPipeline(input: string) {
  const step1 = await researchAgent.run(input);
  const step2 = await writerAgent.run(step1.output);
  const step3 = await editorAgent.run(step2.output);
  return step3.output;
}

Point clé : convenir du format de sortie à chaque étape, sinon l’agent aval ne comprendra pas.

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

3.2 Concurrent (parallèle)

Plusieurs agents traitent la même entrée en parallèle, puis agrégation.

           → [Agent A] →
[Entrée]  →  → [Agent B] →  → [Agrégateur] → résultat
           → [Agent C] →

Cas d’usage : analyse multi-angle, évaluation boursière (technique + fondamental + actualités), revue de code (sécurité + perf + style en parallèle).

Exemple :

async function concurrentAnalysis(code: string) {
  const [security, performance, style] = await Promise.all([
    securityAgent.run(`Revue sécurité :\n${code}`),
    performanceAgent.run(`Analyse performance :\n${code}`),
    styleAgent.run(`Style de code :\n${code}`),
  ]);

  return {
    security: security.output,
    performance: performance.output,
    style: style.output,
  };
}

Point clé : définir l’arbitrage si les agents divergent.

3.3 Group Chat (discussion de groupe)

Plusieurs agents discutent dans une « salle » jusqu’à consensus ou timeout.

[Agent A] ⇄ [Agent B] ⇄ [Agent C]
     ↑           ↓
   [Modérateur]

Cas d’usage : brainstorming, validation qualité, décisions après plusieurs tours.

Recommandation Azure : limiter à 3 agents. Au-delà, la discussion dérape.

Exemple (pseudo-code) :

interface ChatMessage {
  sender: string;
  content: string;
}

async function groupChatDiscussion(
  topic: string,
  agents: ClaudeAgent[],
  maxRounds: number = 5
) {
  const history: ChatMessage[] = [];

  for (let round = 0; round < maxRounds; round++) {
    for (const agent of agents) {
      const response = await agent.run(
        `Sujet : ${topic}\nHistorique : ${JSON.stringify(history)}\nVotre avis.`
      );
      history.push({ sender: agent.name, content: response.output });

      if (checkConsensus(history)) {
        return summarizeConsensus(history);
      }
    }
  }

  return 'Timeout : pas de consensus';
}

Piège : définir maxRounds ; deux agents obstinés peuvent débattre indéfiniment. Un modérateur aide à converger.

3.4 Handoff (transfert)

Un agent termine ou détecte un besoin d’expertise et transfère à un autre.

[Agent A] détecte besoin de B → transfert → [Agent B] → suite

Cas d’usage : chatbot (avant-vente → support → SAV), diagnostic (diagnostic → correction → validation).

Exemple :

const supportAgent = new ClaudeAgent({
  name: 'support',
  systemPrompt: `Vous êtes le support. Question technique → répondre "HANDOFF:tech".
Question SAV → répondre "HANDOFF:after_sales".`,
});

const techAgent = new ClaudeAgent({
  name: 'tech',
  systemPrompt: 'Vous êtes expert support technique.',
});

async function handleWithHandoff(userInput: string) {
  let currentAgent = supportAgent;
  let response = await currentAgent.run(userInput);

  while (response.output.includes('HANDOFF:')) {
    const targetAgent = response.output.match(/HANDOFF:(\w+)/)?.[1];

    if (targetAgent === 'tech') currentAgent = techAgent;
    else if (targetAgent === 'after_sales') currentAgent = afterSalesAgent;

    response = await currentAgent.run(userInput);
  }

  return response.output;
}

Point clé : éviter les transferts circulaires (A → B → A).

3.5 Magentic (planification dynamique)

Le plus flexible : un planificateur « attire » l’agent le plus adapté selon la tâche.

[Pool de tâches] → [Planificateur] → choix [Agent A/B/C]

Cas d’usage : types de tâches variés, allocation dynamique de ressources.

Idée d’implémentation :

interface Task {
  type: string;
  priority: number;
  content: string;
}

async function magenticScheduling(task: Task) {
  const agentScores = await Promise.all(
    agents.map(async (agent) => {
      const score = await evaluateAgentFit(agent, task);
      return { agent, score };
    })
  );

  const bestAgent = agentScores.sort((a, b) => b.score - a.score)[0].agent;
  return bestAgent.run(task.content);
}

Point clé : une bonne métrique d’adéquation — sinon le routage devient aléatoire.

3.6 Tableau de choix rapide

4. Frameworks : comparaison et choix

LangChain, AutoGen, CrewAI, Claude Agent SDK — autant d’options. Mon avis : pas de meilleur framework, seulement le plus adapté à votre scénario.

4.1 Positionnement

4.2 Détails par framework

LangChain : le plus mature.

• TypeScript et Python
• Nombreuses intégrations
• ReAct et Plan-and-Execute prêts à l’emploi
• Inconvénient : API évolutive, doc parfois en retard

AutoGen : Microsoft, référence multi-agents.

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

• Collaboration par messages
• Human-in-the-loop
• Discussions et décisions multi-tours
• Inconvénient : courbe d’apprentissage, débogage multi-agents pénible

CrewAI : simplicité.

• Modèle rôle / tâche / équipe
• API claire, prise en main rapide
• Prototypes multi-agents
• Inconvénient : écosystème moins riche que LangChain

Claude Agent SDK : officiel Anthropic (2026).

• Intégration profonde Claude
• Fichiers, édition code, commandes
• permissionMode pour les permissions
• Si Claude est votre modèle principal : premier choix

4.3 Guide de décision

Quelques questions :

1. Modèle principal ?

   • Claude → Claude Agent SDK en priorité
   • OpenAI → écosystème LangChain
   • Multi-modèle → LangChain ou AutoGen

2. Complexité ?

   • Agent unique + outils → LangChain suffit
   • Multi-agents → AutoGen ou CrewAI
   • Tâches code → Claude Agent SDK

3. Stack équipe ?

   • Python → tous les frameworks
   • TypeScript → LangChain et Claude Agent SDK mieux servis

4. Human-in-the-loop ?

   • Oui → AutoGen
   • Non → les autres conviennent

4.4 Recommandation personnelle

Dans la plupart des cas, LangChain suffit : outils, ReAct, communauté.

Multi-agents seulement si la tâche l’exige vraiment — le débogage coûte cher ; ne choisissez pas la complexité pour la mode.

Utilisateur intensif de Claude : Claude Agent SDK est le meilleur choix actuel — intégration officielle, meilleure synergie avec le modèle.

5. Pratique — construire un agent avec Claude Agent SDK

Passons à la pratique : un agent de refactorisation de code fonctionnel.

5.1 Préparation

# Installation
npm install @anthropic-ai/claude-agent-sdk

# Clé API
export ANTHROPIC_API_KEY=your_api_key_here

5.2 Agent de base

import { ClaudeAgent } from '@anthropic-ai/claude-agent-sdk';

const refactorAgent = new ClaudeAgent({
  model: 'claude-sonnet-4-20250514',
  tools: ['Read', 'Write', 'Edit', 'Bash'],
  permissionMode: 'acceptEdits',
  workingDirectory: './src',
});

async function refactorCode(task: string) {
  const result = await refactorAgent.run(task);
  console.log('Résultat :', result);
  return result;
}

refactorCode('Refactoriser auth.ts : callbacks → async/await');

5.3 Configuration importante

permissionMode :

• 'acceptEdits' : accepte automatiquement les éditions
• 'interactive' : confirmation humaine à chaque opération
• 'planOnly' : plan uniquement, pas d’exécution

tools :

• Read, Write, Edit, Bash, Glob, Grep

5.4 Exemple avec contraintes

const cautiousAgent = new ClaudeAgent({
  model: 'claude-sonnet-4-20250514',
  tools: ['Read', 'Write', 'Edit', 'Bash'],
  permissionMode: 'interactive',
  maxIterations: 20,
  timeout: 300000,

  systemPrompt: `Vous êtes expert en refactorisation.
Règles :
1. Ne supprimez aucun fichier de test
2. Ne modifiez pas package.json
3. Sauvegardez avant chaque modification
4. Lancez les tests après modification`,
});

async function safeRefactor(filePath: string) {
  try {
    const result = await cautiousAgent.run(
      `Refactoriser ${filePath} pour la structure et la lisibilité.`
    );
    return result;
  } catch (error) {
    console.error('Échec :', error);
    // Rollback...
  }
}

5.5 Bonnes pratiques

1. Limiter les itérations — éviter les boucles infinies
2. Timeout — filet pour les tâches longues
3. Permissions graduées — interactive pour le sensible
4. Sauvegarde avant modification importante
5. Tests après changement

5.6 Débogage

const debugAgent = new ClaudeAgent({
  model: 'claude-sonnet-4-20250514',
  tools: ['Read', 'Write', 'Edit'],
  verbose: true,
});

debugAgent.on('toolCall', (tool, args) => {
  console.log(`Outil : ${tool}, args : ${JSON.stringify(args)}`);
});

debugAgent.on('thinking', (thought) => {
  console.log(`Réflexion : ${thought}`);
});

Conclusion

Le choix d’architecture agent se résume à : partir du simple, ajouter au besoin.

Complexité de la tâche :

• Une étape ? Appel direct
• Outils nécessaires ? Agent unique + outils
• Plusieurs rôles experts ? Multi-agents, avec prudence

Mode :

• Dynamique → ReAct
• Étapes prévisibles → Plan-and-Execute
• Spécialisation → Multi-Agent

Framework :

• Claude → Claude Agent SDK
• Multi-modèle, nombreux outils → LangChain
• Multi-agents → AutoGen ou CrewAI

Le plus important : tester sur un petit projet — quelques pièges suffisent pour comprendre.

Questions en commentaires, ou lisez mes deux articles précédents : « Introduction au développement MCP Server » et « Appels d’outils agent en pratique » — la trilogie se tient.