MI-Ágensek Építése Cloudflare Workers És LangChain Segítségével

Egy Cloudflare Workers MI-ágens felépítése a következő szintet jelenti az egyszerű promptoktól az autonóm munkafolyamatok felé vezető úton. Ezek a rendszerek, más néven MI-ágensek (AI agents), nagy nyelvi modelleket (LLM-eket) használnak arra, hogy külső eszközöket hívjanak meg, döntéseket hozzanak, és önállóan hajtsanak végre feladatokat. Miközben az ágensek futtatása hagyományosan erőteljes szervereket igényelt, ez az útmutató bemutatja, hogyan építhet és hosztolhat szerver nélküli (serverless) MI-ágenseket a Cloudflare Workers és a LangChain.js segítségével.

TL;DR

• Ismerje meg az MI-ágenseket: Az ágensek LLM-eket használnak döntéshozatalra, és külső API-kat (eszközöket/tools) hívnak meg a felhasználói kérések önálló megoldásához.
• Használja a LangChain.js-t a hálózat peremén (edge): A LangChain.js teljes mértékben kompatibilis a Cloudflare Workers könnyűsúlyú V8 futtatókörnyezetével.
• Írjon egyedi eszközöket adatok lekéréséhez, adatbázisok olvasásához vagy logikai műveletek futtatásához közvetlenül a Worker fetch handleréből.
• Használja ki a szerver nélküli kötéseket (bindings): Csatlakoztassa ágensét Cloudflare D1-hez az SQL állapotmemóriához, vagy KV-hoz a munkamenetek gyorsítótárazásához.
• Alkalmazzon korlátokat és időkorlátokat (timeouts) a végtelen futási hurkok elkerülése és az API token költségek kontrollálása érdekében.

Mi az az MI-ágens?

Egy standard chatbot egy egyszerű kérés-válasz ciklus: Ön elküld egy promptot, a modell pedig szöveget ad vissza. Ezzel szemben egy Cloudflare Workers MI-ágens autonóm módon cselekszik. Ön meghatározza az ágens célját, és biztosít számára egy sor „eszközt” (olyan egyedi JavaScript függvényeket, amelyek API-kat hívnak meg, adatbázisokban keresnek vagy számításokat végeznek). A modell dönti el, hogy melyik eszközt hívja meg, megvizsgálja az eszköz kimenetét, és addig ismétli a folyamatot, amíg meg nem oldja a kérést. Ez az ágensi logika kiválóan alkalmas komplex ügyfélszolgálati feladatokhoz, háttér-automatizációhoz és adatbázis-kezeléshez. A peremhálózati alap API-k beállításáról részletesebben a szerver nélküli API építése Cloudflare Workers segítségével útmutatónkban olvashat.

Előfeltételek

Mielőtt elkezdené, győződjön meg arról, hogy rendelkezik a következőkkel:

• Egy Cloudflare-fiók engedélyezett Workers-szolgáltatással (az ingyenes csomag is elegendő).
• Node.js 18 vagy újabb verzió és a Wrangler CLI (npm install -g wrangler).
• Egy OpenAI API-kulcs, vagy a LangChain.js által támogatott egyéb szolgáltató hitelesítő adatai.
• Alapszintű jártasság a JavaScript Promise-ok és a Workers fetch kezelőjének terén.

Telepítse a szükséges LangChain csomagokat. Érdemes pontosan importálni ahelyett, hogy a teljes keretrendszert behúzná, mivel a Workers szigorú tömörített csomagméret-korlátot alkalmaz:

 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}

A LangChain.js integrálása Workers-szolgáltatással

A LangChain egy népszerű keretrendszer LLM-alkalmazások építésére. A JavaScript verzió (LangChain.js) web-standard API-kra épül, így teljesen kompatibilis a Cloudflare könnyűsúlyú V8 futtatókörnyezetével.

Első lépésként inicializálja az ágenst a Worker fetch kezelőjében:

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

Ez a konfiguráció teljesen a hálózat peremén fut, közel a felhasználókhoz, szinte nulla hidegindítási (cold start) idővel. Ha OpenAI hívása helyett helyi szerver nélküli modelleket szeretne beállítani, tekintse meg a Cloudflare Workers AI útmutatónkat .

A Worker projekt konfigurálása

A LangChain.js támaszkodik néhány Node.js beépített modulra, így a Worker nem fog lefordulni mindaddig, amíg nem engedélyezi a nodejs_compat jelzőt. Ezt a wrangler.toml fájlban állíthatja be, a használt kötésekkel (bindings) együtt:

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

Soha ne égesse be az API-kulcsát a kódba. Ehelyett tárolja titkosított adatként (secret):

1npx wrangler secret put OPENAI_API_KEY

Lokális fejlesztéshez helyezze el ugyanezt az értéket egy .dev.vars fájlban (amelyet hozzáad a .gitignore-hoz), így a wrangler dev képes lesz beolvasni anélkül, hogy a kulcs kikerülne a verziókövető rendszerbe.

Állapotkezelés és az ágens memóriája

Mivel a szerver nélküli Workers példányok az egyes kérések között állapotmentesek (stateless), biztosítania kell az ágens számára egy memóriarendszert a beszélgetési előzmények tárolására.

Csatlakoztathatja ágensét egy szerver nélküli SQL-adatbázishoz, mint amilyen a Cloudflare D1. Amikor az ágens kérést kap, lekérdezi a D1-et a korábbi üzenetváltásokért, átadja azokat a döntési modellnek, majd az új választ elmenti az adatbázisba. A relációs táblák létrehozásáról a Cloudflare D1 edge adatbázis beállítása cikkünkben olvashat.

A gyakorlatban egy minimális üzenettárnak mindössze két segédfüggvényre van szüksége: egyre az előzmények betöltéséhez, és egyre az új üzenet elmentéséhez. Hozza létre a táblát a CREATE TABLE messages (id INTEGER PRIMARY KEY, session_id TEXT, role TEXT, content TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP); paranccsal, majd kösse be:

 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}

Töltse be az előzményeket minden kérés elején, adja át környezeti kontextusként a modellnek, majd mentse el mind a felhasználói bevitelt, mind az ágens végső válaszát, mielőtt visszatérne az eredménnyel. Rövid életű munkamenetek esetén, ahol a tartósság nem kritikus, a Cloudflare KV olcsóbb választás a D1-nél.

Biztonsági korlátok és költségkontroll éles környezetben

Mivel az ágensek hurkokban futnak (döntés → eszköz futtatása → döntés), egy nem megfelelően konfigurált ágens végtelen ciklusba léphet, gyorsan megduplázva az API számlát.

• Maximális iteráció beállítása: Korlátozza az ágens által végrehajtható hurkok számát (pl. maximum 5 kör).
• Időkorlátok beállítása: A Cloudflare Workers szigorú CPU futási korlátokat alkalmaz. Ügyeljen arra, hogy az eszközök gyorsan lefussanak a kérések megszakításának elkerülése érdekében.
• Rátakorlátozás (Rate Limiting): Védje meg a peremhálózati végpontot a tokenekkel való visszaélésektől rátakorlátozások alkalmazásával.

A kódban az executor opciók segítségével teheti egyértelművé az első két biztonsági korlátot:

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

A maxIterations beállításával a hurok öt döntési ciklus után leáll még akkor is, ha a modell nem jutott el a végső válaszig, ami minimalizálja az egy kérésre jutó token-kiadásokat a legrosszabb forgatókönyv esetén.

A kontextuskezelés részletes bemutatásáért tekintse meg az OpenAI API chatbot építéséről szóló útmutatónkat .

Gyakori hibák és elhárításuk

A legtöbb kezdeti telepítés néhány előre jelezhető ok miatt hiúsul meg. Az alábbi táblázat bemutatja a leggyakoribb hibákat, azok okait és a javítási lépéseket:

Két apróságot érdemes kiemelni. Először is, a Workers megkülönbözteti a valós időt (wall-clock) a CPU-időtől: az LLM vagy adatbázis válaszára való várakozás I/O műveletnek számít, nem pedig CPU-időnek, így a hosszú modellhívások önmagukban ritkán lépik túl a CPU-korlátot, a szoros ciklusban végzett nehéz JSON-feldolgozás viszont igen. Másodszor, az ágens döntéseinek minősége nagymértékben függ az eszközök leírásától. Kezeljen minden description mezőt önálló promptként, és fogalmazzon pontosan a várt bemenetről, különben a modell rossz eszközt fog meghívni.

Tesztelés és élesítés

A közzététel előtt fejlesszen lokális futtatókörnyezetben. A wrangler dev ugyanabban a Workerd motorban futtatja a Worker-t, mint amit a Cloudflare éles környezetben használ, így a viselkedés megegyezik a peremhálózaton tapasztalhatóval:

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

Miután az ágens élesbe került, szükség van a döntési folyamatok átláthatóságára. Engedélyezze az obszervabilitást az eszközhívások és hibák rögzítéséhez, majd kövesse a naplókat valós időben:

1[observability]
2enabled = true

Használja a npx wrangler tail parancsot a beérkező kérések valós idejű megtekintéséhez. A naplózáson kívül néhány gyakorlat segít fenntartani a rendszer egészségét: ellenőrizze és tisztítsa meg a felhasználói beviteleket, mielőtt azok elérnének egy adatbázist érintő eszközt; adjon vissza elegáns hibakezelő üzenetet, ha a modell eléri a maximális iterációs számot; és kövesse nyomon a munkamenetenkénti tokenhasználatot, hogy egyetlen rosszindulatú felhasználó se generálhasson kiugró költségeket. Nagyobb átmenő forgalmú rendszerek esetén érdemes megfontolni a válaszok streamelését, hogy a felhasználók azonnal láthassák a generált kimenetet.

Legfontosabb tanulságok

• Az MI-ágensek döntési modelleket használnak az összetett kérések megoldásához szükséges egyedi eszközök kiválasztására.
• A LangChain.js hatékonyan fut a Cloudflare Workers könnyűsúlyú V8 izolációs környezetében.
• Határozzon meg egyedi eszközöket olyan JavaScript függvényekként, amelyek adatbázisokhoz, API-khoz vagy fájlokhoz kapcsolódnak.
• Biztosítsa az ágens memóriáját a kérések között a Cloudflare D1 szerver nélküli SQL-adatbázis segítségével.
• Alkalmazzon iterációs korlátokat és időtúllépéseket a kérésekre az API-költségek kézben tartása és a leállások megelőzése érdekében.

Skálázza ágensi munkafolyamatait

A termelésre kész MI-ágensek felépítése szakértői ismereteket igényel a szerver nélküli architektúra, az adatbázis-tervezés és a prompt-tervezés terén. A Mecanik professzionális MI-integrációs szolgáltatásokat és dedikált fejlesztői csapatokat biztosít a webfejlesztő bérlése oldalon keresztül. Gyors, biztonságos ágensi rendszereket építünk, amelyek automatizálják a működést és tisztán skálázhatók. Lépjen kapcsolatba velünk még ma a következő projektje kapcsán.

Gyakran ismételt kérdések (GYIK)

Mi a különbség egy MI-chatbot és egy MI-ágens között? Egy MI-chatbot csupán szöveges válaszokat ad a promptokra. Ezzel szemben egy MI-ágens önállóan működik: értékeli a kérést, és eldönti, hogy milyen külső API-kat (eszközöket) kell meghívnia egy ciklusban a feladat elvégzéséhez.

Futtatható a LangChain Cloudflare Workers-szolgáltatáson? Igen. A LangChain.js web-standard API-k használatával készült, így teljesen kompatibilis a Cloudflare Workers V8 motorjával, amely nem futtat teljes Node.js környezetet.

Hogyan adhatok hozzáférést az MI-ágensnek az adatbázisaimhoz? Az adatbázis-lekérdezéseket beágyazza egy egyedi LangChain eszközbe. Amikor az ágens úgy dönt, hogy adatbázis-információra van szüksége, meghívja az eszköz függvényét, amely végrehajtja a lekérdezést.

Hogyan akadályozhatom meg, hogy az MI-ágens végtelen ciklusba kerüljön? Konfiguráljon egy maximális iterációs korlátot az executorban (pl. maxIterations: 5), és alkalmazzon szigorú időkorlátokat az eszközfüggvényekben.

Melyik a legjobb hoszting az MI-ágensek számára? A szerver nélküli peremhálózati hoszting, mint amilyen a Cloudflare Workers, ideális választás, mert globális eloszlást, szinte nulla hidegindítási időt biztosít, és közvetlenül kapcsolódik az olyan adatbázisokhoz, mint a D1 és az R2.