Creazione Di Agenti D'IA Con Cloudflare Workers E LangChain

La creazione di un agente d’IA Cloudflare Workers rappresenta il passo successivo nel passaggio da semplici prompt testuali a flussi di lavoro autonomi. Questi sistemi, noti come agenti d’IA, utilizzano modelli linguistici di grandi dimensioni (LLM) per chiamare strumenti esterni, prendere decisioni ed eseguire attività in autonomia. Mentre l’esecuzione di agenti richiedeva tradizionalmente server pesanti, questo tutorial dimostra come creare e ospitare agenti d’IA serverless utilizzando Cloudflare Workers e LangChain.js .

TL;DR

• Comprendere gli agenti d’IA: gli agenti utilizzano gli LLM per prendere decisioni e chiamare API esterne (strumenti) per risolvere le richieste degli utenti in modo autonomo.
• Utilizzare LangChain.js sul edge: LangChain.js è completamente compatibile con il runtime V8 leggero di Cloudflare Workers.
• Scrivere strumenti personalizzati per recuperare dati, leggere database o eseguire logiche direttamente dal fetch handler del tuo Worker.
• Sfruttare i binding serverless: collega il tuo agente a Cloudflare D1 per la memoria di stato SQL, o a KV per la memorizzazione nella cache della sessione.
• Applicare limiti e timeout per prevenire cicli di esecuzione infiniti e controllare i costi delle API dei token.

Cos’è un agente d’IA?

Un chatbot standard è un semplice ciclo di richiesta-risposta: invii un prompt e il modello restituisce testo. Un agente d’IA Cloudflare Workers, al contrario, agisce in modo autonomo. Definisci l’obiettivo dell’agente e gli fornisci una serie di “strumenti” (funzioni JavaScript personalizzate che interrogano API, cercano database o eseguono calcoli). Il modello decide quali strumenti chiamare, ispeziona l’output dello strumento e ripete il ciclo fino a quando non risolve la tua richiesta. Questa logica agentica è particolarmente adatta per l’assistenza clienti complessa, l’automazione in background e la gestione dei database. Per dettagli sulla configurazione delle API edge di base, consulta la nostra guida su come creare un’API serverless con Cloudflare Workers .

Prerequisiti

Prima di iniziare, assicurati di avere i seguenti elementi:

• Un account Cloudflare con Workers abilitato (il piano gratuito è sufficiente).
• Node.js 18 o successivo e la CLI di Wrangler (npm install -g wrangler).
• Una chiave API OpenAI o le credenziali di un altro provider supportato da LangChain.js.
• Familiarità di base con le Promise JavaScript e il fetch handler di Workers.

Installa i pacchetti LangChain necessari. Importa in modo mirato piuttosto che caricare l’intero framework, poiché i Workers applicano un limite rigido per la dimensione del pacchetto compresso:

 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}

Integrazione di LangChain.js con Workers

LangChain è un framework molto diffuso per la creazione di applicazioni LLM. La versione JavaScript (LangChain.js) è progettata per funzionare su API standard del web, rendendola completamente compatibile con il runtime V8 leggero di Cloudflare.

Per iniziare, inizializzi l’agente all’interno del gestore fetch del tuo 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};

Questa configurazione viene eseguita interamente sul edge, vicino ai tuoi utenti, con avvii a freddo (cold starts) quasi nulli. Se desideri configurare modelli locali serverless invece di chiamare OpenAI, esplora il nostro tutorial Cloudflare Workers AI .

Configurazione del progetto Worker

LangChain.js si basa su alcune funzionalità native di Node.js, pertanto il tuo Worker non verrà compilato finché non avrai abilitato il flag nodejs_compat. Impostalo nel file wrangler.toml, insieme a tutti i binding utilizzati dai tuoi strumenti:

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>"

Non codificare mai la chiave API nel codice. Memorizzala invece come segreto crittografato (secret):

1npx wrangler secret put OPENAI_API_KEY

Per il sviluppo locale, inserisci lo stesso valore in un file .dev.vars (aggiunto al .gitignore) in modo che wrangler dev possa leggerlo senza esporre la chiave nel sistema di controllo versione.

Gestione dello stato e della memoria dell’agente

Poiché i Workers serverless sono privi di stato (stateless) tra le richieste, devi fornire all’agente un sistema di memoria per memorizzare la cronologia delle conversazioni.

Puoi connettere il tuo agente a un database SQL serverless come Cloudflare D1. Quando l’agente riceve una richiesta, interroga D1 per recuperare la cronologia precedente dei messaggi, la passa al modello di ragionamento e salva la nuova risposta nel database. Per scoprire come configurare le tabelle relazionali, consulta la configurazione del database D1 edge .

Nella pratica, un archivio messaggi minimo richiede solo due funzioni helper: una per caricare la cronologia e una per aggiungere ogni nuovo messaggio. Crea la tabella con CREATE TABLE messages (id INTEGER PRIMARY KEY, session_id TEXT, role TEXT, content TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP);, quindi collegala:

 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}

Carica la cronologia all’inizio di ogni richiesta, passala al modello come contesto precedente, quindi salva sia l’input dell’utente sia la risposta finale dell’agente prima di restituire la risposta. Per le sessioni di breve durata in cui la durabilità non ha importanza, Cloudflare KV rappresenta una scelta più economica rispetto a D1.

Limiti e controllo dei costi in produzione

Poiché gli agenti vengono eseguiti in cicli (ragionamento → esecuzione dello strumento → ragionamento), un agente mal configurato può entrare in un ciclo infinito, facendo lievitare rapidamente i costi delle API.

• Impostare le iterazioni massime: Limita il numero massimo di cicli che l’agente può eseguire (ad esempio, limitare a 5 cicli).
• Configurare i timeout: Cloudflare Workers applica limiti rigorosi al tempo di esecuzione della CPU. Assicurati che i tuoi strumenti si completino rapidamente per evitare l’annullamento delle richieste.
• Implementare il Rate Limiting: Proteggi il tuo endpoint edge dall’abuso di token applicando limiti di frequenza delle richieste.

Nel codice, le opzioni dell’esecutore rendono espliciti i primi due limiti:

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

Con maxIterations impostato, il ciclo si interrompe dopo cinque cicli di ragionamento, anche se il modello non ha ancora prodotto una risposta finale, limitando il consumo di token per singola richiesta nel peggiore dei casi.

Per uno sguardo dettagliato alla gestione del contesto, consulta la nostra guida su come creare un chatbot con l’API OpenAI .

Errori comuni e risoluzione dei problemi

La maggior parte dei primi deployment fallisce per un piccolo numero di motivi prevedibili. La tabella seguente mappa l’errore probabile con la sua causa e risoluzione:

Due sottigliezze meritano attenzione. In primo luogo, i Workers separano il tempo di clock reale dal tempo di CPU: l’attesa di una risposta di LLM o di un database conta come I/O, non come tempo CPU, quindi le lunghe chiamate del modello raramente violano i limiti della CPU da sole, mentre l’analisi JSON complessa all’interno di un ciclo sì. In secondo luogo, la qualità delle decisioni di un agente dipende fortemente da come descrivi i suoi strumenti. Tratta ogni campo description come un prompt vero e proprio e sii specifico sull’input previsto, altrimenti il modello chiamerà lo strumento errato.

Test e deployment in produzione

Sviluppa su un runtime locale prima di pubblicare il codice. wrangler dev esegue il tuo Worker nello stesso motore Workerd utilizzato da Cloudflare in produzione, garantendo che il comportamento sia coerente con il edge:

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

Una volta online, avrai bisogno di visibilità sui cicli di ragionamento dell’agente. Abilita l’osservabilità in modo che le chiamate degli strumenti e gli errori vengano acquisiti, quindi esegui lo streaming dei log in tempo reale:

1[observability]
2enabled = true

Usa npx wrangler tail per monitorare le richieste in tempo reale. Oltre alla registrazione dei log, alcune buone abitudini mantengono in salute gli agenti in produzione: convalida e ripulisci qualsiasi input dell’utente prima che raggiunga uno strumento che interagisce con il database; restituisci un messaggio di fallback pulito quando il modello supera il limite di iterazioni anziché mostrare un errore non formattato; e monitora il consumo di token per sessione per evitare che un utente abusivo faccia lievitare la fattura. Per carichi di lavoro a throughput elevato, valuta la possibilità di implementare lo streaming della risposta in modo che gli utenti possano vedere l’output man mano che viene generato.

Punti chiave

• Gli agenti d’IA utilizzano modelli di ragionamento per decidere quali strumenti personalizzati chiamare per risolvere query complesse.
• LangChain.js funziona in modo efficiente all’interno del runtime leggero di isolati V8 di Cloudflare Workers.
• Definisci strumenti personalizzati come funzioni JavaScript che si connettono a database, API o file.
• Conserva la memoria dell’agente tra le richieste stateless utilizzando il database SQL serverless Cloudflare D1.
• Implementa limiti alle iterazioni del ciclo e timeout per controllare i costi delle API ed evitare arresti di esecuzione.

Scala i tuoi flussi di lavoro agentici

La creazione di agenti d’IA pronti per la produzione richiede competenze approfondite in architettura serverless, ingegneria dei database e prompt design. Mecanik fornisce servizi di integrazione d’IA professionali e team di sviluppo dedicati attraverso la nostra pagina di assunzione sviluppatore web . Progettiamo sistemi autonomi rapidi e sicuri che automatizzano le operazioni aziendali e si adattano in modo pulito alla scala. Contattaci oggi stesso per discutere del tuo prossimo progetto.

Domande frequenti (FAQ)

Qual è la differenza tra un chatbot d’IA e un agente d’IA? Un chatbot d’IA si limita a restituire risposte testuali in base ai prompt forniti. Un agente d’IA è autonomo: valuta la richiesta e decide quali API esterne (strumenti) chiamare in ciclo per portare a termine l’attività.

Posso eseguire LangChain su Cloudflare Workers? Sì. LangChain.js è progettato utilizzando API standard del web, rendendolo completamente compatibile con il motore V8 di Cloudflare Workers, che non esegue un ambiente Node.js completo.

Come posso dare a un agente d’IA l’accesso ai miei database? Avvolgi le query del database all’interno di uno strumento personalizzato LangChain. Quando l’agente decide che ha bisogno di informazioni dal database, chiama la funzione dello strumento, che esegue la query.

Come posso evitare che un agente d’IA entri in un ciclo infinito? Configura un limite massimo di iterazioni nell’esecutore dell’agente (ad esempio, maxIterations: 5) e implementa timeout rigorosi sulle funzioni dei tuoi strumenti.

Qual è l’hosting migliore per gli agenti d’IA? L’hosting serverless sul edge come Cloudflare Workers è ideale perché offre distribuzione globale, avvii a freddo quasi nulli e si collega direttamente a database come D1 e R2.