La création d’un agent d’IA Cloudflare Workers est l’étape suivante pour passer de simples invites textuelles (prompts) à des flux de travail autonomes. Ces systèmes, appelés agents d’IA, utilisent de grands modèles de langage (LLM) pour appeler des outils externes, prendre des décisions et exécuter des tâches par eux-mêmes. Alors que l’exécution d’agents nécessitait traditionnellement des serveurs lourds, ce tutoriel montre comment créer et héberger des agents d’IA serverless en utilisant Cloudflare Workers et LangChain.js .

TL;DR

  • Comprendre les agents d’IA : les agents utilisent des LLM pour prendre des décisions et appeler des API externes (outils) afin de résoudre les requêtes des utilisateurs de manière autonome.
  • Utiliser LangChain.js sur le edge : LangChain.js est entièrement compatible avec le runtime V8 léger de Cloudflare Workers.
  • Écrire des outils personnalisés pour récupérer des données, lire des bases de données ou exécuter de la logique à partir de votre gestionnaire de requêtes (fetch handler) de Worker.
  • Exploiter les liaisons (bindings) serverless : connectez votre agent à Cloudflare D1 pour une mémoire d’état SQL, ou à KV pour le cache de session.
  • Mettre en place des garde-fous et des délais d’attente (timeouts) pour éviter les boucles d’exécution infinies et contrôler les coûts d’API de tokens.

Qu’est-ce qu’un agent d’IA ?

Un chatbot standard est une simple boucle requête-réponse : vous envoyez un prompt et le modèle renvoie du texte. Un agent d’IA Cloudflare Workers, en revanche, agit de manière autonome. Vous définissez l’objectif de l’agent et lui fournissez un ensemble d’« outils » (des fonctions JavaScript personnalisées qui interrogent des API, effectuent des recherches dans des bases de données ou exécutent des calculs). Le modèle décide des outils à appeler, inspecte le résultat de l’outil et boucle jusqu’à ce qu’il résolve votre requête. Cette logique agentique est particulièrement adaptée aux supports clients complexes, à l’automatisation en arrière-plan et à la gestion de bases de données. Pour plus de détails sur la configuration des API de base sur le edge, consultez notre guide sur la création d’une API serverless avec Cloudflare Workers .

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

  • Un compte Cloudflare avec Workers activé (l’offre gratuite est suffisante).
  • Node.js 18 ou plus récent et Wrangler CLI (npm install -g wrangler).
  • Une clé API OpenAI, ou les identifiants d’un autre fournisseur pris en charge par LangChain.js.
  • Une familiarité de base avec les promesses JavaScript et le gestionnaire fetch de Workers.

Installez les packages LangChain dont vous avez besoin. Importez de manière ciblée plutôt que d’intégrer l’ensemble du framework, car les Workers imposent une limite stricte de taille de bundle compressé :

 1{
 2  "dependencies": {
 3    "@langchain/openai": "^0.3.0",
 4    "@langchain/core": "^0.3.0",
 5    "langchain": "^0.3.0"
 6  },
 7  "devDependencies": {
 8    "wrangler": "^3.0.0"
 9  }
10}

Intégration de LangChain.js avec Workers

LangChain est un framework populaire pour créer des applications de LLM. La version JavaScript (LangChain.js) est conçue pour fonctionner sur des API standards du web, ce qui la rend entièrement compatible avec le runtime V8 léger de Cloudflare.

Pour commencer, vous initialisez l’agent à l’intérieur du gestionnaire fetch de votre Worker :

 1import { ChatOpenAI } from "@langchain/openai";
 2import { initializeAgentExecutorWithOptions } from "langchain/agents";
 3import { DynamicTool } from "@langchain/core/tools";
 4
 5export default {
 6  async fetch(request, env) {
 7    // 1. Define custom tools for the agent
 8    const databaseTool = new DynamicTool({
 9      name: "DatabaseQuery",
10      description: "Queries the customer database for billing status.",
11      func: async (input) => {
12        // Query database (e.g. Cloudflare D1)
13        return `Customer ${input} billing status is Active.`;
14      }
15    });
16
17    const tools = [databaseTool];
18
19    // 2. Initialize the reasoning model
20    const model = new ChatOpenAI({ 
21      apiKey: env.OPENAI_API_KEY,
22      modelName: "gpt-4o-mini"
23    });
24
25    // 3. Create the executor
26    const executor = await initializeAgentExecutorWithOptions(tools, model, {
27      agentType: "openai-functions",
28    });
29
30    // 4. Run the query
31    const result = await executor.call({ input: "Check status for Customer 101" });
32    return Response.json(result);
33  }
34};

Cette configuration s’exécute entièrement sur le edge, au plus près de vos utilisateurs, avec des démarrages à froid (cold starts) quasi nuls. Si vous souhaitez configurer des modèles locaux serverless plutôt que d’appeler OpenAI, explorez notre tutoriel Cloudflare Workers AI .

Configuration du projet Worker

LangChain.js s’appuie sur quelques composants natifs de Node.js, votre Worker ne compilera donc pas tant que vous n’aurez pas activé le drapeau nodejs_compat. Définissez-le dans le fichier wrangler.toml, aux côtés des liaisons que vos outils utilisent :

1name = "ai-agent-worker"
2main = "src/index.js"
3compatibility_date = "2024-09-23"
4compatibility_flags = ["nodejs_compat"]
5
6[[d1_databases]]
7binding = "DB"
8database_name = "agent-memory"
9database_id = "<your-database-id>"

Ne codez jamais votre clé API en dur. Stockez-la plutôt sous forme de secret chiffré :

1npx wrangler secret put OPENAI_API_KEY

Pour le développement local, placez la même valeur dans un fichier .dev.vars (ajouté au .gitignore) afin que wrangler dev puisse la lire sans exposer la clé dans votre système de contrôle de version.

Gestion de l’état et de la mémoire de l’agent

Puisque les Workers serverless sont sans état (stateless) entre les requêtes, vous devez fournir à l’agent un système de mémoire pour stocker l’historique des conversations.

Vous pouvez connecter votre agent à une base de données SQL serverless comme Cloudflare D1. Lorsque l’agent reçoit une requête, il interroge D1 pour récupérer le fil de discussion précédent, le transmet au modèle de raisonnement et enregistre la nouvelle réponse dans la base de données. Pour apprendre à configurer des tables relationnelles, consultez la configuration de la base de données D1 edge .

En pratique, un stockage minimal de messages n’a besoin que de deux assistants : un pour charger le fil de discussion et un pour ajouter chaque nouveau message. Créez la table avec CREATE TABLE messages (id INTEGER PRIMARY KEY, session_id TEXT, role TEXT, content TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP);, puis câblez le tout :

 1async function loadHistory(db, sessionId) {
 2  const { results } = await db
 3    .prepare(
 4      "SELECT role, content FROM messages WHERE session_id = ? ORDER BY created_at ASC"
 5    )
 6    .bind(sessionId)
 7    .all();
 8  return results ?? [];
 9}
10
11async function saveMessage(db, sessionId, role, content) {
12  await db
13    .prepare("INSERT INTO messages (session_id, role, content) VALUES (?, ?, ?)")
14    .bind(sessionId, role, content)
15    .run();
16}

Chargez l’historique au début de chaque requête, transmettez-le au modèle en tant que contexte préalable, puis enregistrez à la fois l’entrée de l’utilisateur et la réponse finale de l’agent avant de renvoyer la réponse. Pour les sessions de courte durée où la durabilité importe peu, Cloudflare KV est un choix plus économique que D1.

Garde-fous et contrôle des coûts en production

Puisque les agents fonctionnent en boucle (raisonnement → exécution de l’outil → raisonnement), un agent mal configuré peut entrer dans une boucle infinie et faire exploser rapidement votre facturation d’API.

  • Définir un nombre maximal d’itérations : Plafonnez le nombre maximal de boucles que l’agent peut exécuter (par exemple, limiter à 5 itérations).
  • Configurer des délais d’attente (timeouts) : Cloudflare Workers impose des limites d’exécution du processeur (CPU). Assurez-vous que vos outils s’exécutent rapidement pour éviter l’annulation des requêtes.
  • Mettre en œuvre la limitation de débit (rate limiting) : Protégez votre point de terminaison edge contre l’abus de tokens en appliquant des limites de requêtes.

Dans le code, les options de l’exécuteur rendent explicites les deux premiers garde-fous :

1const executor = await initializeAgentExecutorWithOptions(tools, model, {
2  agentType: "openai-functions",
3  maxIterations: 5,
4  earlyStoppingMethod: "generate",
5  verbose: false,
6});

Une fois maxIterations configuré, la boucle s’arrête après cinq cycles de raisonnement, même si le modèle n’a pas encore produit de réponse finale, ce qui plafonne les dépenses de tokens dans le pire des cas par requête.

Pour un aperçu détaillé de la gestion du contexte, consultez notre guide sur la création d’un chatbot avec l’API OpenAI .

Pièges courants et dépannage

La plupart des premiers déploiements échouent pour un petit nombre de raisons prévisibles. Le tableau ci-dessous associe les erreurs probables à leurs causes et solutions :

SymptômeCause probableSolution
Cannot find module 'node:async_hooks' lors du buildLe drapeau nodejs_compat est manquantAjoutez compatibility_flags = ["nodejs_compat"] et une date compatibility_date récente
Le bundle dépasse la limite de taille lors du déploiementImportations globales qui importent tout le frameworkImportez depuis des sous-chemins spécifiques (@langchain/openai) et supprimez les outils inutilisés
OPENAI_API_KEY is not definedLe secret n’est pas défini, ou .dev.vars est manquant localementExécutez wrangler secret put ; ajoutez la clé à .dev.vars pour wrangler dev
La requête expire sous la chargeUn outil lent ou une boucle infinieRéduisez maxIterations ; ajoutez des timeouts dans la fonction func de chaque outil
L’agent ignore un outil qu’il devrait utiliserDescription de l’outil (description) trop vagueRéécrivez la description pour indiquer exactement quand le modèle doit l’appeler

Deux subtilités méritent d’être soulignées. Premièrement, les Workers séparent le temps réel écoulé du temps CPU : l’attente d’une réponse de LLM ou d’une base de données compte comme de l’I/O et non du temps CPU. Ainsi, les longs appels de modèle dépassent rarement les limites de CPU à eux seuls, contrairement à l’analyse JSON intensive dans une boucle serrée. Deuxièmement, la qualité des décisions d’un agent dépend fortement de la façon dont vous décrivez ses outils. Traitez chaque champ description comme une invite textuelle à part entière et soyez précis sur l’entrée attendue, sous peine de voir le modèle appeler le mauvais outil.

Test et déploiement en production

Développez sur un runtime local avant d’expédier votre code. wrangler dev exécute votre Worker dans le même moteur Workerd que Cloudflare utilise en production, le comportement est donc très proche du edge :

1npx wrangler dev      # local iteration with hot reload
2npx wrangler deploy   # publish to the edge

Une fois en ligne, vous devez avoir de la visibilité sur les boucles de raisonnement de l’agent. Activez l’observabilité afin que les appels d’outils et les erreurs soient capturés, puis diffusez les journaux en temps réel :

1[observability]
2enabled = true

Utilisez npx wrangler tail pour surveiller les requêtes en temps réel. Au-delà de la journalisation, quelques bonnes habitudes maintiennent les agents de production en bonne santé : validez et assainissez toute entrée utilisateur avant qu’elle n’atteigne un outil qui touche à votre base de données ; renvoyez un message de repli propre lorsque le modèle dépasse sa limite d’itérations plutôt que d’afficher une erreur brute ; et surveillez l’utilisation des tokens par session afin qu’un utilisateur abusif ne puisse pas faire exploser votre facture. Pour les charges de travail à haut débit, envisagez de diffuser la réponse en continu (streaming) afin que les utilisateurs voient le résultat au fur et à mesure de sa génération au lieu d’attendre la fin de la boucle complète.

Points clés à retenir

  • Les agents d’IA utilisent des modèles de raisonnement pour décider quels outils personnalisés appeler afin de résoudre des requêtes complexes.
  • LangChain.js s’exécute efficacement dans le runtime léger d’isolats V8 de Cloudflare Workers.
  • Définissez des outils personnalisés sous forme de fonctions JavaScript se connectant à des bases de données, des API ou des fichiers.
  • Conservez la mémoire de l’agent à travers les requêtes sans état en utilisant la base de données SQL serverless Cloudflare D1.
  • Limitez le nombre d’itérations de boucle et mettez en place des délais d’attente pour contrôler les coûts d’API et éviter les plantages d’exécution.

Faites évoluer vos flux de travail autonomes

La création d’agents d’IA prêts pour la production nécessite une expertise pointue en architecture serverless, en ingénierie de bases de données et en conception d’invites (prompt design). Mecanik propose des services d’intégration d’IA professionnels et des équipes de développement dédiées via notre page de recrutement de développeur web . Nous concevons des systèmes autonomes rapides et sécurisés qui automatisent vos opérations et s’adaptent proprement à l’échelle. Contactez-nous dès aujourd’hui pour discuter de votre prochain projet.

Foire aux questions (FAQ)

Quelle est la différence entre un chatbot d’IA et un agent d’IA ? Un chatbot d’IA renvoie uniquement des réponses textuelles à des invites. Un agent d’IA est autonome : il évalue votre requête et décide des API externes (outils) à exécuter en boucle pour accomplir la tâche.

Puis-je exécuter LangChain sur Cloudflare Workers ? Oui. LangChain.js est conçu en utilisant des API standards du web, ce qui le rend entièrement compatible avec le moteur V8 de Cloudflare Workers, qui n’exécute pas un Node.js complet.

Comment donner à un agent d’IA l’accès à mes bases de données ? Vous enveloppez les requêtes de base de données dans un outil personnalisé LangChain. Lorsque l’agent décide qu’il a besoin d’informations de la base de données, il appelle la fonction de l’outil, qui exécute la requête.

Comment empêcher un agent d’IA de tourner en boucle indéfiniment ? Vous configurez une limite d’itérations maximale dans l’exécuteur de l’agent (par exemple, maxIterations: 5) et implémentez des délais d’attente stricts sur vos fonctions d’outils.

Quel est le meilleur hébergement pour les agents d’IA ? L’hébergement serverless sur le edge comme Cloudflare Workers est idéal car il offre une distribution mondiale, des démarrages à froid quasi nuls et se connecte directement aux bases de données comme D1 et R2.