Erstellung Von KI-Agenten Mit Cloudflare Workers Und LangChain

Der Aufbau eines Cloudflare Workers KI-Agenten ist der nächste Schritt beim Übergang von einfachen KI-Prompts zu autonomen Arbeitsabläufen. Diese Systeme, bekannt als KI-Agenten, nutzen große Sprachmodelle (LLMs), um externe Tools aufzurufen, Entscheidungen zu treffen und Aufgaben selbstständig auszuführen. Während der Betrieb von Agenten traditionell schwere Server erforderte, zeigt dieses Tutorial, wie man serverlose KI-Agenten mit Cloudflare Workers und LangChain.js erstellt und hostet.

TL;DR

• Verstehen Sie KI-Agenten: Agenten nutzen LLMs, um Entscheidungen zu treffen und externe APIs (Tools) aufzurufen, um Benutzeranfragen autonom zu lösen.
• Nutzen Sie LangChain.js auf dem Edge: LangChain.js ist vollständig kompatibel mit der leichtgewichtigen V8-Laufzeitumgebung von Cloudflare Workers.
• Schreiben Sie benutzerdefinierte Tools, um Daten abzurufen, Datenbanken zu lesen oder Logik aus Ihrem Worker-Fetch-Handler auszuführen.
• Nutzen Sie serverlose Bindungen: Verbinden Sie Ihren Agenten mit Cloudflare D1 für den SQL-Zustandsspeicher oder KV für das Session-Caching.
• Implementieren Sie Sicherheitsbarrieren und Timeouts, um unendliche Ausführungsschleifen zu verhindern und die Kosten für Token-APIs zu kontrollieren.

Was ist ein KI-Agent?

Ein Standard-Chatbot ist eine einfache Anfrage-Antwort-Schleife: Sie senden einen Prompt, und das Modell gibt Text zurück. Ein Cloudflare Workers KI-Agent hingegen agiert autonom. Sie definieren das Ziel des Agenten und stellen ihm eine Reihe von „Tools“ zur Verfügung (benutzerdefinierte JavaScript-Funktionen, die APIs abfragen, Datenbanken durchsuchen oder Berechnungen durchführen). Das Modell entscheidet, welche Tools aufgerufen werden sollen, inspiziert die Tool-Ausgabe und wiederholt die Schleife, bis es Ihre Anfrage gelöst hat. Diese agentische Logik eignet sich hervorragend für komplexe Kundenunterstützung, Hintergrundautomatisierung und Datenbankverwaltung. Weitere Informationen zum Einrichten grundlegender Edge-APIs finden Sie in unserem Leitfaden zum Erstellen einer serverlosen API mit Cloudflare Workers .

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass folgende Voraussetzungen erfüllt sind:

• Ein Cloudflare-Konto mit aktivierten Workers (der kostenlose Tarif reicht aus).
• Node.js 18 oder neuer und die Wrangler-CLI (npm install -g wrangler).
• Ein OpenAI-API-Schlüssel oder Anmeldedaten für einen anderen von LangChain.js unterstützten Provider.
• Grundlegende Vertrautheit mit JavaScript-Promises und dem Fetch-Handler von Workers.

Installieren Sie die benötigten LangChain-Pakete. Importieren Sie gezielt, anstatt das gesamte Framework einzubinden, da Workers ein komprimiertes Limit für die Bundle-Größe vorschreiben:

 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}

Integration von LangChain.js mit Workers

LangChain ist ein beliebtes Framework zum Erstellen von LLM-Anwendungen. Die JavaScript-Version (LangChain.js) basiert auf Web-Standard-APIs, wodurch sie vollständig mit der leichtgewichtigen V8-Laufzeitumgebung von Cloudflare kompatibel ist.

Initialisieren Sie den Agenten zunächst im fetch-Handler Ihres Workers:

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

Dieses Setup läuft vollständig auf dem Edge, nah an Ihren Benutzern, mit Kaltstarts nahe Null. Wenn Sie lokale serverlose Modelle konfigurieren möchten, anstatt OpenAI aufzurufen, lesen Sie unser Cloudflare Workers AI-Tutorial .

Konfiguration des Worker-Projekts

LangChain.js stützt sich auf eine Reihe von Node.js-Kompabilitäten, sodass Ihr Worker erst kompiliert wird, wenn Sie das Flag nodejs_compat aktivieren. Stellen Sie es in wrangler.toml ein, zusammen mit allen Bindungen, die Ihre Tools verwenden:

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

Geben Sie Ihren API-Schlüssel niemals direkt im Code an. Speichern Sie ihn stattdessen als verschlüsseltes Geheimnis (Secret):

1npx wrangler secret put OPENAI_API_KEY

Für die lokale Entwicklung hinterlegen Sie denselben Wert in einer .dev.vars-Datei (die zu .gitignore hinzugefügt wird), damit wrangler dev ihn auslesen kann, ohne den Schlüssel in der Versionsverwaltung offenzulegen.

Zustandsverwaltung und Agenten-Speicher

Da serverlose Workers zwischen den Anfragen zustandslos sind, müssen Sie dem Agenten ein Speichersystem bereitstellen, um den Gesprächsverlauf zu sichern.

Sie können Ihren Agenten mit einer serverlosen SQL-Datenbank wie Cloudflare D1 verbinden. Wenn der Agent eine Anfrage erhält, fragt er D1 ab, um den vorherigen Nachrichtenverlauf abzurufen, übergibt ihn an das Argumentationsmodell und speichert die neue Antwort wieder in der Datenbank. Wie Sie relationale Tabellen einrichten, erfahren Sie unter Cloudflare D1 Edge-Datenbank-Setup .

In der Praxis benötigt ein minimaler Nachrichtenspeicher nur zwei Hilfsfunktionen: eine zum Laden des Verlaufs und eine zum Anhängen jeder neuen Nachricht. Erstellen Sie die Tabelle mit CREATE TABLE messages (id INTEGER PRIMARY KEY, session_id TEXT, role TEXT, content TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP); und binden Sie sie ein:

 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}

Laden Sie den Verlauf zu Beginn jeder Anfrage, übergeben Sie ihn als Kontext an das Modell und speichern Sie sowohl die Benutzereingabe als auch die endgültige Antwort des Agenten, bevor Sie die Antwort zurückgeben. Für kurzlebige Sitzungen, bei denen die Dauerhaftigkeit keine Rolle spielt, ist Cloudflare KV eine kostengünstigere Wahl als D1.

Sicherheitsbarrieren und Kostenkontrolle in der Produktion

Da Agenten in Schleifen laufen (Argumentation → Ausführung des Tools → Argumentation), kann ein schlecht definierter Agent in eine Endlosschleife geraten und Ihre API-Kosten schnell in die Höhe treiben.

• Setzen Sie maximale Iterationen: Begrenzen Sie die maximale Anzahl von Schleifendurchläufen, die der Agent ausführen darf (z. B. auf 5 Runden begrenzen).
• Timeouts konfigurieren: Cloudflare Workers erzwingen Limits für die CPU-Ausführungszeit. Stellen Sie sicher, dass Ihre Tools schnell aufgelöst werden, um einen Abbruch der Anfrage zu verhindern.
• Rate Limiting implementieren: Schützen Sie Ihren Edge-Endpunkt vor Token-Missbrauch, indem Sie Ratenbegrenzungen anwenden.

Im Code machen die Executor-Optionen die ersten beiden Barrieren explizit:

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

Mit aktivierter maxIterations-Option stoppt die Schleife nach fünf Argumentationszyklen, selbst wenn das Modell noch keine endgültige Antwort geliefert hat. Dies begrenzt die Token-Ausgaben im schlimmsten Fall pro Anfrage.

Einen detaillierten Einblick in das Kontextmanagement finden Sie in unserem Leitfaden zum Erstellen eines OpenAI-API-Chatbots .

Häufige Fehler und Fehlerbehebung

Die meisten ersten Bereitstellungen scheitern an einer kleinen Anzahl vorhersehbarer Ursachen. Die folgende Tabelle ordnet Fehler ihrer Ursache und Behebung zu:

Zwei Besonderheiten sind erwähnenswert. Erstens trennen Workers die Echtzeit von der CPU-Zeit: Das Warten auf ein LLM oder eine Datenbankantwort zählt als I/O, nicht als CPU-Zeit. Daher verletzen lange Modellaufrufe die CPU-Limits selten allein, wohl aber intensives JSON-Parsing in einer engen Schleife. Zweitens hängt die Qualität der Entscheidungen eines Agenten stark davon ab, wie Sie seine Tools beschreiben. Behandeln Sie jedes description-Feld als eigenständigen Prompt und definieren Sie die erwartete Eingabe präzise, da das Modell sonst das falsche Tool aufruft.

Testen und Bereitstellen in der Produktion

Entwickeln Sie zunächst gegen eine lokale Laufzeitumgebung, bevor Sie das Projekt veröffentlichen. wrangler dev führt Ihren Worker in derselben Workerd-Engine aus, die Cloudflare in der Produktion verwendet, sodass das Verhalten dem Edge-Verhalten genau entspricht:

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

Sobald das System online ist, benötigen Sie Einblick in die Argumentationsschleifen des Agenten. Aktivieren Sie die Observability, damit Tool-Aufrufe und Fehler erfasst werden, und streamen Sie Protokolle in Echtzeit:

1[observability]
2enabled = true

Verwenden Sie npx wrangler tail, um Anfragen live zu verfolgen. Neben der Protokollierung helfen einige Gewohnheiten, produktive Agenten gesund zu halten: Validieren und bereinigen Sie alle Benutzereingaben, bevor sie ein Tool erreichen, das auf Ihre Datenbank zugreift. Geben Sie eine freundliche Ausweichnachricht aus, wenn das Modell sein Iterationslimit überschreitet, anstatt einen rohen Fehler anzuzeigen. Überwachen Sie zudem den Token-Verbrauch pro Sitzung, damit ein einzelner missbräuchlicher Aufrufer nicht Ihre Rechnung in die Höhe treiben kann. Bei Workloads mit höherem Durchsatz sollten Sie das Streamen der Antwort in Betracht ziehen, damit Benutzer Ausgaben sehen, während sie generiert werden, anstatt auf das Ende der gesamten Schleife zu warten.

Wichtige Erkenntnisse

• KI-Agenten nutzen Argumentationsmodelle, um zu entscheiden, welche benutzerdefinierten Tools aufgerufen werden sollen, um komplexe Anfragen zu lösen.
• LangChain.js läuft effizient in der leichtgewichtigen V8-Isolat-Laufzeitumgebung von Cloudflare Workers.
• Definieren Sie benutzerdefinierte Tools als JavaScript-Funktionen, die Verbindungen zu Datenbanken, APIs oder Dateien herstellen.
• Sichern Sie den Agenten-Speicher über zustandslose Anfragen hinweg durch die serverlose SQL-Datenbank Cloudflare D1.
• Implementieren Sie Iterationsbegrenzungen und Timeouts für Anfragen, um die API-Kosten zu kontrollieren und Systemabstürze zu verhindern.

Skalieren Sie Ihre agentischen Workflows

Der Aufbau produktionsreifer KI-Agenten erfordert Expertenwissen in serverloser Architektur, Datenbanktechnik und Prompt-Design. Mecanik bietet professionelle KI-Integrationsdienste und dedizierte Entwicklungsteams über die Seite Webentwickler mieten an. Wir bauen schnelle, sichere agentische Systeme, die Abläufe automatisieren und sauber skalieren. Kontaktieren Sie uns noch heute, um Ihr nächstes Projekt zu besprechen.

Häufig gestellte Fragen (FAQ)

Was ist der Unterschied zwischen einem KI-Chatbot und einem KI-Agenten? Ein KI-Chatbot gibt lediglich Textantworten auf Prompts zurück. Ein KI-Agent agiert autonom: Er bewertet Ihre Anfrage und entscheidet in einer Schleife, welche externen APIs (Tools) ausgeführt werden sollen, um die Aufgabe zu lösen.

Kann ich LangChain auf Cloudflare Workers ausführen? Ja. LangChain.js basiert auf Web-Standard-APIs, wodurch es vollständig mit der V8-Engine von Cloudflare Workers kompatibel ist, die keine vollständige Node.js-Umgebung ausführt.

Wie gebe ich einem KI-Agenten Zugriff auf meine Datenbanken? Sie verpacken Datenbankabfragen in ein benutzerdefiniertes LangChain-Tool. Wenn der Agent entscheidet, dass er Datenbankinformationen benötigt, ruft er die Tool-Funktion auf, die die Abfrage ausführt.

Wie verhindere ich, dass ein KI-Agent in einer Endlosschleife läuft? Sie konfigurieren ein maximales Iterationslimit im Agent-Executor (z. B. maxIterations: 5) und implementieren strikte Timeouts für Ihre Tool-Funktionen.

Was ist das beste Hosting für KI-Agenten? Serverloses Edge-Hosting wie Cloudflare Workers ist ideal, da es globale Verteilung, Kaltstarts nahe Null bietet und direkt an Datenbanken wie D1 und R2 angebunden ist.