Xây dựng một agent AI trên Cloudflare Workers là bước tiếp theo để chuyển dịch từ các câu lệnh (prompt) AI đơn giản sang quy trình làm việc tự động. Các hệ thống này, được gọi là agent AI, sử dụng các Mô hình Ngôn ngữ Lớn (LLM) để gọi các công cụ bên ngoài, đưa ra quyết định và tự thực thi các tác vụ. Mặc dù việc chạy các agent trước đây yêu cầu máy chủ cồng kềnh, hướng dẫn này sẽ trình bày cách xây dựng và lưu trữ các agent AI không máy chủ (serverless) bằng Cloudflare Workers và LangChain.js .

TL;DR

  • Hiểu về agent AI: Các agent sử dụng LLM để đưa ra quyết định và gọi các API bên ngoài (công cụ/tool) để giải quyết các truy vấn của người dùng một cách tự động.
  • Sử dụng LangChain.js trên biên (edge): LangChain.js hoàn toàn tương thích với môi trường runtime V8 dung lượng nhẹ của Cloudflare Workers.
  • Viết các công cụ tùy chỉnh để truy xuất dữ liệu, đọc cơ sở dữ liệu hoặc thực thi logic từ handler fetch của Worker.
  • Tận dụng liên kết (bindings) serverless: Kết nối agent của bạn với Cloudflare D1 cho bộ nhớ trạng thái SQL, hoặc KV cho bộ nhớ đệm (caching) phiên.
  • Thiết lập giới hạn (guardrails) và thời gian chờ (timeout) để ngăn chặn các vòng lặp thực thi vô hạn và kiểm soát chi phí token API.

Agent AI là gì?

Một chatbot tiêu chuẩn hoạt động theo vòng lặp yêu cầu-phản hồi đơn giản: bạn gửi câu lệnh và mô hình trả về văn bản. Ngược lại, một agent AI trên Cloudflare Workers hoạt động một cách tự động. Bạn xác định mục tiêu của agent và cung cấp cho nó một tập hợp các “công cụ” (các hàm JavaScript tùy chỉnh gọi API, tìm kiếm cơ sở dữ liệu hoặc thực hiện phép toán). Mô hình sẽ quyết định công cụ nào cần gọi, kiểm tra đầu ra của công cụ đó và lặp lại cho đến khi giải quyết được yêu cầu của bạn. Logic agent này rất phù hợp cho hỗ trợ khách hàng phức tạp, tự động hóa nền và quản lý cơ sở dữ liệu. Để biết chi tiết về cách thiết lập các API biên cơ bản, hãy xem hướng dẫn của chúng tôi về xây dựng API serverless với Cloudflare Workers .

Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo bạn có sẵn những thứ sau:

  • Tài khoản Cloudflare đã bật Workers (gói miễn phí là đủ để thực hiện).
  • Node.js 18 trở lên và Wrangler CLI (npm install -g wrangler).
  • Khóa API OpenAI hoặc thông tin xác thực cho một nhà cung cấp khác mà LangChain.js hỗ trợ.
  • Hiểu biết cơ bản về JavaScript promise và handler fetch của Workers.

Cài đặt các gói LangChain cần thiết. Nhập thư viện chi tiết thay vì tải toàn bộ framework vì Workers thực thi giới hạn dung lượng bundle nén:

 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}

Tích hợp LangChain.js với Workers

LangChain là một framework phổ biến để xây dựng các ứng dụng LLM. Phiên bản JavaScript (LangChain.js) được thiết kế chạy trên các API tiêu chuẩn web, giúp nó tương thích hoàn toàn với runtime V8 nhẹ của Cloudflare.

Để bắt đầu, bạn khởi tạo agent bên trong handler fetch của 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};

Thiết lập này chạy hoàn toàn ở biên, gần với người dùng của bạn, với thời gian khởi động lạnh (cold start) gần như bằng không. Nếu bạn muốn cấu hình các mô hình cục bộ serverless thay vì gọi OpenAI, hãy khám phá hướng dẫn Cloudflare Workers AI của chúng tôi.

Cấu hình dự án Worker

LangChain.js phụ thuộc vào một số tính năng tích hợp sẵn của Node.js, vì vậy Worker của bạn sẽ không biên dịch được cho đến khi bạn bật flag nodejs_compat. Hãy thiết lập nó trong wrangler.toml, cùng với bất kỳ liên kết (bindings) nào mà các công cụ của bạn sử dụng:

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

Không bao giờ hard-code khóa API của bạn. Thay vào đó, hãy lưu trữ nó dưới dạng secret được mã hóa:

1npx wrangler secret put OPENAI_API_KEY

Để phát triển cục bộ, hãy đặt cùng một giá trị đó vào tệp .dev.vars (đã được thêm vào .gitignore) để wrangler dev có thể đọc được mà không làm lộ khóa trong hệ thống quản lý mã nguồn.

Quản lý trạng thái và bộ nhớ của Agent

Vì các Workers serverless là không lưu trạng thái (stateless) giữa các yêu cầu, bạn phải cung cấp cho agent một hệ thống bộ nhớ để lưu trữ lịch sử cuộc hội thoại.

Bạn có thể kết nối agent của mình với một cơ sở dữ liệu SQL serverless như Cloudflare D1. Khi agent nhận được yêu cầu, nó sẽ truy vấn D1 để lấy lịch sử tin nhắn trước đó, chuyển nó đến mô hình tư duy và lưu phản hồi mới trở lại cơ sở dữ liệu. Để tìm hiểu cách thiết lập các bảng quan hệ, hãy xem hướng dẫn thiết lập cơ sở dữ liệu biên Cloudflare D1 .

Trong thực tế, một kho lưu trữ tin nhắn tối giản chỉ cần hai hàm hỗ trợ: một hàm để tải lịch sử cuộc hội thoại và một hàm để lưu thêm từng lượt trò chuyện mới. Tạo bảng với lệnh CREATE TABLE messages (id INTEGER PRIMARY KEY, session_id TEXT, role TEXT, content TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP);, sau đó kết nối nó:

 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ải lịch sử cuộc hội thoại khi bắt đầu mỗi yêu cầu, chuyển nó đến mô hình làm ngữ cảnh trước đó, sau đó lưu cả thông tin nhập của người dùng và câu trả lời cuối cùng của agent trước khi trả về phản hồi. Đối với các phiên làm việc ngắn hạn, nơi độ bền của dữ liệu không quá quan trọng, Cloudflare KV là lựa chọn tiết kiệm chi phí hơn so với D1.

Giới hạn an toàn và kiểm soát chi phí trong môi trường Production

Vì các agent chạy theo vòng lặp (tư duy → thực thi công cụ → tư duy), một agent được định nghĩa kém có thể rơi vào vòng lặp vô hạn, nhanh chóng làm tăng hóa đơn API của bạn.

  • Đặt số lần lặp tối đa (Max Iterations): Giới hạn số lần lặp tối đa mà agent có thể thực hiện (ví dụ: giới hạn tối đa 5 lượt).
  • Cấu hình thời gian chờ (Timeout): Cloudflare Workers thực thi các giới hạn thực thi CPU. Đảm bảo các công cụ của bạn phản hồi nhanh chóng để tránh yêu cầu bị hủy.
  • Triển khai giới hạn tần suất (Rate Limiting): Bảo vệ endpoint biên của bạn khỏi việc lạm dụng token bằng cách áp dụng các giới hạn tần suất.

Trong mã nguồn, các tùy chọn executor giúp thiết lập rõ ràng hai giới hạn đầu tiên:

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

Khi đã thiết lập maxIterations, vòng lặp sẽ dừng sau năm chu kỳ tư duy ngay cả khi mô hình chưa đưa ra câu trả lời cuối cùng, giúp giới hạn mức tiêu thụ token trong trường hợp xấu nhất cho mỗi yêu cầu.

Để biết cái nhìn chi tiết về quản lý ngữ cảnh, hãy xem hướng dẫn của chúng tôi về xây dựng chatbot với API OpenAI .

Các lỗi thường gặp và cách khắc phục

Hầu hết các lần triển khai đầu tiên thất bại vì một số lý do phổ biến có thể dự đoán được. Bảng dưới đây ánh xạ lỗi bạn có thể gặp phải với nguyên nhân và cách khắc phục:

Triệu chứngNguyên nhân có thểCách khắc phục
Lỗi Cannot find module 'node:async_hooks' khi buildThiếu flag nodejs_compatThêm compatibility_flags = ["nodejs_compat"] và một compatibility_date gần đây
Bundle vượt quá giới hạn kích thước khi deployViệc import chung (barrel imports) tải toàn bộ frameworkImport từ các subpath cụ thể (@langchain/openai) và bỏ các công cụ không sử dụng
Lỗi OPENAI_API_KEY is not definedChưa thiết lập secret hoặc thiếu tệp .dev.vars cục bộChạy lệnh wrangler secret put; thêm khóa vào tệp .dev.vars khi chạy wrangler dev
Yêu cầu bị timeout khi chịu tảiMột công cụ chạy chậm hoặc vòng lặp vô hạnGiảm maxIterations; thêm thời gian chờ bên trong hàm func của mỗi công cụ
Agent bỏ qua công cụ đáng lẽ phải dùngMô tả công cụ (description) bị mơ hồViết lại mô tả để nêu rõ chính xác khi nào mô hình nên gọi công cụ đó

Có hai chi tiết nhỏ cần lưu ý. Thứ nhất, Workers tách biệt thời gian thực tế trôi qua (wall-clock time) và thời gian CPU: việc chờ đợi phản hồi từ LLM hoặc cơ sở dữ liệu được tính là I/O chứ không phải thời gian CPU, vì vậy các cuộc gọi mô hình dài hiếm khi tự vi phạm giới hạn CPU, nhưng việc phân tích cú pháp JSON nặng trong một vòng lặp hẹp thì có thể. Thứ hai, chất lượng quyết định của agent phụ thuộc nhiều vào cách bạn mô tả các công cụ của nó. Hãy xem mỗi trường description như một câu lệnh riêng và ghi rõ định dạng đầu vào mong đợi, nếu không mô hình sẽ gọi sai công cụ.

Thử nghiệm và triển khai môi trường Production

Phát triển trên môi trường runtime cục bộ trước khi phát hành. Lệnh wrangler dev chạy Worker của bạn trong chính engine Workerd mà Cloudflare sử dụng trong môi trường production, vì vậy các hành vi sẽ khớp rất chính xác với biên:

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

Khi đã chạy chính thức, bạn cần khả năng giám sát các vòng lặp tư duy của agent. Bật tính năng khả năng quan sát (observability) để ghi lại các cuộc gọi công cụ và lỗi, sau đó truyền nhật ký (stream logs) trong thời gian thực:

1[observability]
2enabled = true

Sử dụng lệnh npx wrangler tail để theo dõi các yêu cầu khi chúng xảy ra. Bên cạnh việc ghi nhật ký, một vài thói quen tốt sẽ giúp duy trì các agent chạy ổn định: xác thực và làm sạch mọi đầu vào của người dùng trước khi chuyển đến một công cụ tương tác với cơ sở dữ liệu; trả về một thông báo dự phòng thân thiện khi mô hình vượt quá số lần lặp thay vì hiển thị lỗi thô; và giám sát lượng token sử dụng cho mỗi phiên để một người dùng lạm dụng không thể làm tăng hóa đơn của bạn. Đối với khối lượng công việc thông lượng cao, hãy cân nhắc stream phản hồi để người dùng thấy đầu ra khi nó được tạo ra thay vì chờ toàn bộ vòng lặp hoàn thành.

Các điểm mấu chốt cần nhớ

  • Các agent AI sử dụng các mô hình tư duy để quyết định công cụ tùy chỉnh nào cần gọi để giải quyết các truy vấn phức tạp.
  • LangChain.js chạy hiệu quả trong môi trường runtime cô lập V8 nhẹ của Cloudflare Workers.
  • Định nghĩa các công cụ tùy chỉnh dưới dạng các hàm JavaScript kết nối với cơ sở dữ liệu, API hoặc tệp tin.
  • Duy trì bộ nhớ của agent trên các yêu cầu không trạng thái bằng cách sử dụng cơ sở dữ liệu SQL serverless Cloudflare D1.
  • Triển khai giới hạn số lần lặp vòng lặp và thời gian chờ yêu cầu để kiểm soát chi phí API và ngăn chặn sự cố thực thi.

Mở rộng quy trình làm việc Agent của bạn

Xây dựng các agent AI sẵn sàng cho production đòi hỏi kiến thức chuyên môn về kiến trúc serverless, kỹ thuật cơ sở dữ liệu và thiết kế câu lệnh. Mecanik cung cấp các dịch vụ tích hợp AI chuyên nghiệp và các đội ngũ phát triển chuyên dụng thông qua trang thuê nhà phát triển web . Chúng tôi xây dựng các hệ thống agent nhanh, bảo mật, giúp tự động hóa hoạt động và mở rộng quy mô một cách rõ ràng. Hãy liên hệ với chúng tôi hôm nay để thảo luận về dự án tiếp theo của bạn.

Câu hỏi thường gặp (FAQ)

Sự khác biệt giữa chatbot AI và agent AI là gì? Một chatbot AI chỉ trả về câu trả lời bằng văn bản cho các câu lệnh. Một agent AI hoạt động tự động: nó đánh giá yêu cầu của bạn và quyết định API bên ngoài (công cụ) nào sẽ chạy trong một vòng lặp để hoàn thành tác vụ.

Tôi có thể chạy LangChain trên Cloudflare Workers không? Có. LangChain.js được thiết kế bằng các API tiêu chuẩn web, giúp nó tương thích hoàn toàn với V8 engine của Cloudflare Workers (vốn không chạy toàn bộ môi trường Node.js).

Làm cách nào để cung cấp quyền truy cập cơ sở dữ liệu cho một agent AI? Bạn bao bọc các truy vấn cơ sở dữ liệu bên trong một công cụ tùy chỉnh LangChain. Khi agent quyết định cần thông tin cơ sở dữ liệu, nó sẽ gọi hàm của công cụ đó để thực thi truy vấn.

Làm cách nào để ngăn một agent AI lặp vô hạn? Bạn cấu hình giới hạn số lần lặp tối đa trong agent executor (ví dụ: maxIterations: 5) và thiết lập thời gian chờ nghiêm ngặt cho các hàm công cụ của bạn.

Môi trường lưu trữ tốt nhất cho các agent AI là gì? Lưu trữ biên serverless như Cloudflare Workers là lý tưởng vì nó cung cấp khả năng phân phối toàn cầu, khởi động lạnh gần như bằng không và liên kết trực tiếp với các cơ sở dữ liệu như D1 và R2.