Crearea De Agenți De IA Cu Cloudflare Workers Și LangChain

Construirea unui agent de IA în Cloudflare Workers este următorul pas în tranziția de la simple instrucțiuni text (prompts) la fluxuri de lucru autonome. Aceste sisteme, cunoscute sub numele de agenți de IA, utilizează Modele de Limbaj Mari (LLM) pentru a apela instrumente externe, a lua decizii și a executa sarcini pe cont propriu. Deși rularea agenților necesita în mod tradițional servere robuste, acest tutorial demonstrează cum să construiți și să găzduiți agenți de IA serverless folosind Cloudflare Workers și LangChain.js .

TL;DR

• Înțelegeți agenții de IA; aceștia utilizează LLM-uri pentru a lua decizii și apelează API-uri externe (instrumente/tools) pentru a rezolva cererile utilizatorilor în mod autonom.
• Utilizați LangChain.js pe edge; LangChain.js este pe deplin compatibil cu runtime-ul V8 ușor al Cloudflare Workers.
• Scrieți instrumente personalizate pentru a prelua date, a citi baze de date sau a executa logică din handlerul fetch al Worker-ului dumneavoastră.
• Beneficiați de legăturile serverless (bindings); conectați-vă agentul la Cloudflare D1 pentru memoria de stare SQL sau la KV pentru cache-ul sesiunilor.
• Implementați limite de iterație și timeout-uri pentru a preveni buclele de execuție infinite și a controla costurile API de tokeni.

Ce este un agent de IA?

Un chatbot standard funcționează ca o simplă buclă de cerere-răspuns: trimiteți o întrebare, iar modelul returnează un text. În schimb, un agent de IA în Cloudflare Workers acționează autonom. Definiți scopul agentului și îi puneți la dispoziție un set de „instrumente” (funcții JavaScript personalizate care apelează API-uri, caută în baze de date sau execută calcule). Modelul decide ce instrumente să apeleze, examinează rezultatul acestora și rulează în buclă până când rezolvă solicitarea dumneavoastră. Această logică agentică este extrem de potrivită pentru servicii complexe de asistență clienți, automatizări de fundal și gestionarea bazelor de date. Pentru detalii despre configurarea API-urilor de bază pe edge, consultați ghidul nostru despre construirea unui API serverless cu Cloudflare Workers .

Cerințe preliminare

Înainte de a începe, asigurați-vă că aveți următoarele:

• Un cont Cloudflare cu serviciul Workers activat (planul gratuit este suficient).
• Node.js 18 sau mai nou și Wrangler CLI (npm install -g wrangler).
• O cheie API OpenAI sau acreditări pentru un alt furnizor acceptat de LangChain.js.
• O cunoaștere de bază a Promise-urilor JavaScript și a handlerului fetch din Workers.

Instalați pachetele LangChain necesare. Importați punctual, mai degrabă decât să includeți întregul framework, deoarece platforma Workers impune o limită strictă de dimensiune pentru bundle-ul comprimat:

 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}

Integrarea LangChain.js cu Workers

LangChain este un framework popular pentru construirea de aplicații bazate pe LLM. Versiunea în JavaScript (LangChain.js) este proiectată să ruleze pe API-uri standard web, ceea ce o face complet compatibilă cu runtime-ul V8 ușor al Cloudflare.

Pentru început, inițializați agentul în interiorul handlerului fetch al Worker-ului dumneavoastră:

 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};

Această configurație rulează în întregime pe edge, aproape de utilizatorii dumneavoastră, cu timpi de pornire la rece (cold start) aproape de zero. Dacă doriți să configurați modele locale serverless în loc să apelați OpenAI, explorați tutorialul nostru despre Cloudflare Workers AI .

Configurarea proiectului Worker

LangChain.js se bazează pe câteva module native Node.js, așa că Worker-ul dumneavoastră nu se va compila până când nu activați flagul nodejs_compat. Configurați-l în wrangler.toml, alături de legăturile (bindings) folosite de instrumentele dumneavoastră:

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

Nu introduceți niciodată cheia API direct în cod. Stocați-o sub formă de secret criptat:

1npx wrangler secret put OPENAI_API_KEY

Pentru dezvoltarea locală, plasați aceeași valoare într-un fișier .dev.vars (adăugat în .gitignore), astfel încât wrangler dev să o poată citi fără a expune cheia în sistemul de versiuni.

Gestionarea stării și a memoriei agentului

Deoarece serverele de tip serverless Workers sunt fără stare (stateless) între solicitări, trebuie să puneți la dispoziție agentului un sistem de memorie pentru a păstra istoricul conversațiilor.

Vă puteți conecta agentul la o bază de date SQL serverless, cum este Cloudflare D1. Când agentul primește o solicitare, interoghează D1 pentru a obține istoricul conversației, îl trimite către modelul de raționament și salvează noul răspuns înapoi în baza de date. Pentru a învăța cum să configurați tabele relaționale, consultați ghidul de configurare pentru baza de date Cloudflare D1 pe edge .

În practică, un magazin minimal de mesaje necesită doar două funcții ajutătoare: una pentru a încărca istoricul și una pentru a adăuga fiecare replică nouă. Creați tabelul folosind CREATE TABLE messages (id INTEGER PRIMARY KEY, session_id TEXT, role TEXT, content TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP);, apoi conectați-l:

 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}

Încărcați istoricul la începutul fiecărei solicitări, trimiteți-l ca context către model, apoi salvați atât mesajul utilizatorului, cât și răspunsul final al agentului înainte de a returna rezultatul. Pentru sesiuni de scurtă durată în care persistența nu este critică, Cloudflare KV reprezintă o variantă mai ieftină decât D1.

Limite de siguranță și controlul costurilor în producție

Deoarece agenții rulează în bucle (raționament → execuție instrument → raționament), un agent configurat greșit poate intra într-o buclă infinită, generând rapid costuri uriașe pe API-ul de tokeni.

• Setați iterațiile maxime: Plafonați numărul maxim de bucle pe care agentul le poate executa (de exemplu, limitați la 5 runde).
• Configurați timeout-urile: Platforma Cloudflare Workers impune limite stricte pentru timpul de rulare pe CPU. Asigurați-vă că instrumentele dumneavoastră finalizează execuția rapid pentru a preveni anularea solicitării.
• Implementați limitarea ratei de acces (Rate Limiting): Protejați-vă endpoint-ul de pe edge împotriva abuzului de tokeni prin aplicarea unor limite de trafic.

În cod, opțiunile executorului fac explicite primele două limite de siguranță:

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

Prin setarea parametrului maxIterations, bucla se oprește după cinci cicluri de raționament, chiar dacă modelul nu a oferit încă un răspuns final, ceea ce limitează cheltuielile cu tokenii în cel mai nefavorabil scenariu per solicitare.

Pentru o analiză detaliată a gestionării contextului, consultați ghidul nostru despre construirea unui chatbot cu API-ul OpenAI .

Probleme comune și depanare

Cele mai multe implementări inițiale eșuează dintr-un set restrâns de motive previzibile. Tabelul de mai jos corelează erorile probabile cu cauzele și soluțiile lor:

Merită menționate două aspecte subtile. În primul rând, serviciul Workers separă timpul real scurs de timpul CPU: așteptarea unui răspuns de la LLM sau baza de date contează ca I/O, nu ca timp CPU, astfel încât apelurile lungi de model rareori depășesc limita CPU de la sine, însă analizarea unor structuri JSON complexe în bucle strânse o poate face. În al doilea rând, calitatea deciziilor unui agent depinde direct de modul în care îi descrieți instrumentele. Tratați fiecare câmp description ca pe o instrucțiune directă și fiți exacți cu privire la datele de intrare așteptate, altfel modelul va apela un instrument greșit.

Testarea și lansarea în producție

Dezvoltați aplicația într-un mediu local înainte de lansare. wrangler dev rulează Worker-ul în același motor Workerd folosit de Cloudflare în producție, astfel încât comportamentul se potrivește perfect cu cel de pe edge:

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

Odată ce aplicația este live, aveți nevoie de vizibilitate asupra buclelor de raționament ale agentului. Activați funcțiile de monitorizare (observability) pentru a înregistra apelurile de instrumente și erorile, apoi urmăriți logurile în timp real:

1[observability]
2enabled = true

Folosiți npx wrangler tail pentru a vizualiza solicitările pe măsură ce sosesc. Pe lângă logare, câteva practici mențin sănătatea agenților în producție: validați și igienizați orice date introduse de utilizatori înainte ca acestea să ajungă la un instrument care interacționează cu baza de date; returnați un răspuns elegant de fallback atunci când modelul își depășește limita de iterații, în loc să afișați o eroare brută; și monitorizați consumul de tokeni pe sesiune pentru ca un singur utilizator abuziv să nu vă încarce facturile. Pentru volume mari de date, luați în considerare trimiterea răspunsului în mod progresiv (streaming), astfel încât utilizatorii să vadă rezultatul pe măsură ce este generat, în loc să aștepte finalizarea întregii bucle.

Concluzii principale

• Agenții de IA folosesc modele de raționament pentru a decide ce instrumente personalizate să apeleze pentru a rezolva solicitări complexe.
• LangChain.js rulează eficient în runtime-ul ușor cu izolate V8 din Cloudflare Workers.
• Definiți instrumente personalizate sub formă de funcții JavaScript conectate la baze de date, API-uri sau fișiere.
• Păstrați memoria agentului între solicitările fără stare prin utilizarea bazei de date SQL serverless Cloudflare D1.
• Implementați limite de iterație a buclei și timeout-uri de solicitare pentru a controla costurile API și a preveni blocarea execuției.

Extindeți fluxurile de lucru de tip agentic

Construirea de agenți de IA pregătiți pentru producție necesită cunoștințe de specialitate în arhitectura serverless, ingineria bazelor de date și proiectarea prompturilor. Mecanik oferă servicii de integrare IA profesionale și echipe dedicate de ingineri prin pagina de angajare dezvoltatori web . Dezvoltăm sisteme de tip agentic rapide și securizate care automatizează operațiunile și scalează curat. Contactați-ne astăzi pentru a discuta despre următorul dumneavoastră proiect.

Întrebări frecvente (FAQ)

Care este diferența dintre un chatbot cu IA și un agent de IA? Un chatbot cu IA doar returnează răspunsuri textuale la întrebări. Un agent de IA este autonom: evaluează solicitarea dumneavoastră și decide ce API-uri externe (instrumente) să ruleze în buclă pentru a finaliza sarcina.

Pot rula LangChain pe Cloudflare Workers? Da. LangChain.js este dezvoltat pe baza API-urilor standard web, fiind complet compatibil cu motorul V8 din Cloudflare Workers, care nu folosește un mediu Node.js complet.

Cum ofer agentului de IA acces la bazele mele de date? Împachetați interogările bazei de date în interiorul unui instrument personalizat LangChain. Când agentul decide că are nevoie de informații din baza de date, apelează acea funcție, care execută interogarea.

Cum împiedic un agent de IA să ruleze într-o buclă infinită? Configurați o limită maximă de iterații în executorul agentului (de exemplu, maxIterations: 5) și implementați timeout-uri stricte pe funcțiile instrumentelor dumneavoastră.

Care este cel mai bun mediu de găzduire pentru agenții de IA? Găzduirea serverless pe edge, cum este Cloudflare Workers, este ideală deoarece oferă distribuție globală, timpi de pornire la rece aproape de zero și se conectează direct la baze de date precum D1 și R2.