Tự build AI Agent Framework trên Cloudflare — Tại sao và Như thế nào

Series: Build Your Own AI Agent Framework trên Cloudflare Bài: 1 / 7 — Overview & Motivation

Tại sao lại tự build?

Khi bắt đầu xây dựng edu-ai-platform — một nền tảng học từ vựng chạy hoàn toàn trên Cloudflare — câu hỏi đầu tiên là: dùng framework nào để xây dựng AI agent?

Các lựa chọn phổ biến:

Mastra — orchestration framework mạnh, nhưng thiết kế cho Node.js/VPS, không native trên Cloudflare Workers
LangChain.js — quá nhiều abstraction, khó debug, bundle size lớn
Cloudflare Agents SDK — tốt cho execution layer, nhưng không có LLM router, workflow engine, memory abstraction
Flue (withastro) — runtime-agnostic, hay nhưng tập trung vào sandbox execution — không phải thứ mình cần

Vấn đề chung của tất cả: chúng thêm nhiều thứ mình không cần, và giấu đi những thứ mình cần hiểu.

Mục tiêu của series này

Build một AI Agent Framework nhỏ, rõ ràng, kiểm soát được — đủ để:

Gọi bất kỳ LLM nào (Groq, Workers AI, Ollama) mà không đổi code
Chạy agent loop với tool calling
Persist memory qua KV và D1
Stream response về client qua SSE
Tái sử dụng được cho nhiều project khác nhau

Không build:

CLI generator
Sandbox/container execution
50+ provider integrations
Guardrails, handoff protocol

Kiến trúc tổng quan

┌─────────────────────────────────────────┐
│           flare-agent                   │
│                                         │
│  @flare-agent/types   (interfaces)      │
│  @flare-agent/providers (LLM adapters)  │
│  @flare-agent/memory  (KV/D1/Vectorize) │
│  @flare-agent/core    (Agent Loop)      │
│  @flare-agent/workflow (Graph engine)   │
└─────────────────────────────────────────┘
         ↓
  Cloudflare Workers + Durable Objects

Nguyên tắc thiết kế

1. Interface-first — Define interface trước, implement sau. Mọi thứ đều swap được.

2. Dependency Inversion — Core không biết gì về Cloudflare. Cloudflare chỉ là một adapter.

3. Thin adapter — Layer adapter càng mỏng càng tốt. Logic nằm hết trong core.

4. No magic — Không có hidden behavior. Đọc code là hiểu ngay.

Dependency graph

types          ← zero dependencies
  ↑
providers      ← chỉ phụ thuộc types
  ↑
memory         ← chỉ phụ thuộc types
  ↑
core           ← phụ thuộc types + providers + memory
  ↑
workflow       ← phụ thuộc core

Mỗi layer chỉ phụ thuộc xuống, không bao giờ lên. Đây là nguyên tắc giúp mở rộng không bị circular dependency.

Các bài tiếp theo trong series

Bài	Nội dung
Bài 2	`@flare-agent/types` — Thiết kế interfaces
Bài 3	`@flare-agent/providers` — LLM Router (Groq, WorkersAI, Ollama)
Bài 4	`@flare-agent/memory` — KV, D1, Vectorize adapters
Bài 5	`@flare-agent/core` — Agent Loop & Tool Registry
Bài 6	`@flare-agent/workflow` — Graph-based Workflow Engine
Bài 7	Áp dụng thực tế vào edu-ai-platform

Tech stack

Layer	Công nghệ
Runtime	Cloudflare Workers + Durable Objects
Language	TypeScript 5.x
Monorepo	Turborepo + pnpm workspaces
Bundle	tsup (ESM + CJS)
Versioning	changesets

Bài tiếp theo: Thiết kế Types & Interfaces — Nền tảng của mọi abstraction