Thực chiến IvyClaw: Xây dựng hệ thống phát triển đa tác tử có khả năng lập kế hoạch, viết mã, kiểm thử và đánh giá

I. IvyClaw là gì

IvyClaw là một hệ thống kỹ thuật Agent AI đa tác tử dành cho các nhiệm vụ nghiên cứu và phát triển phần mềm, được xây dựng dựa trên DeepAgents và LangGraph. Hệ thống không chỉ thực hiện một lần gọi mô hình ngôn ngữ lớn, mà tổ chức việc hiểu yêu cầu, lập kế hoạch nhiệm vụ, tra cứu tài liệu, triển khai mã, kiểm thử tự động, đánh giá mã và trả về kết quả thành một Agent Workflow có thể chạy liên tục.

Dự án sử dụng các công nghệ như Python, FastAPI, PostgreSQL, Redis, ARQ, Docker, Prometheus và Grafana, phù hợp để học tập và thực hành triển khai AI Agent theo hướng kỹ thuật hóa.

Cần lưu ý rằng một số khả năng trong kho mã vẫn đang ở dạng nguyên mẫu kỹ thuật hoặc bản triển khai minh họa. Nếu sử dụng trong môi trường production, cần tiếp tục hoàn thiện xác thực danh tính, kiểm soát quyền hạn, cách ly bảo mật và cấu hình hạ tầng.

Địa chỉ dự án: Kho lưu trữ IvyClaw trên GitHub.

II. Workflow cốt lõi và kiến trúc hệ thống

IvyClaw chia một yêu cầu phát triển thành nhiều Agent có trách nhiệm rõ ràng. Quy trình điển hình như sau:

User Request
      ↓
   Gateway
      ↓
  Dispatcher
      ↓
   Planner
      ↓
Researcher（khi cần）
      ↓
    Coder
      ↓
   Tester
      ↓
  Reviewer
      ↓
Final Response

Planner chịu trách nhiệm hiểu yêu cầu, lập kế hoạch nhiệm vụ và đưa ra quyết định; Researcher tra cứu và tổng hợp tài liệu khi cần; Coder triển khai và chỉnh sửa mã; Tester thực hiện kiểm thử và xác định vấn đề; Reviewer đánh giá mã đối với kết quả cuối cùng.

Yêu cầu thường đi vào API Gateway trước, sau đó được bộ điều hợp kênh và Dispatcher chuyển cho Agent Runtime. PostgreSQL chịu trách nhiệm lưu trữ bền vững trạng thái phiên cùng dữ liệu LangGraph Checkpointer và Store; Redis được dùng cho bộ nhớ đệm, giới hạn tốc độ, trạng thái runtime và hàng đợi nhiệm vụ. Các nhiệm vụ mất nhiều thời gian được giao cho ARQ Worker xử lý bất đồng bộ.

III. Chuẩn bị môi trường chạy

Trước khi bắt đầu, hãy chuẩn bị môi trường chạy dự án Python, các dịch vụ PostgreSQL và Redis khả dụng, cùng API mô hình đáp ứng yêu cầu cấu hình của dự án. Dự án sử dụng uv để quản lý các dependency Python.

Trước tiên, sao chép kho mã và đi vào thư mục dự án:

git clone https://github.com/ivyfan-toowell/IvyClaw.git
cd IvyClaw

Sau đó tạo cấu hình môi trường cục bộ từ tệp mẫu. Trên môi trường Linux, macOS hoặc Unix tương tự, có thể thực thi:

cp .env.example .env

Trong Windows PowerShell, có thể thực thi:

Copy-Item .env.example .env

Điền các cấu hình cần thiết vào .env theo môi trường cục bộ, ví dụ:

IVC_API_KEY=your_api_key_here
IVC_POSTGRES_URL=postgresql://user:password@localhost:5432/ivyclaw
IVC_DATABASE_URL=postgresql://user:password@localhost:5432/ivyclaw
IVC_REDIS_URL=redis://localhost:6379/0

Không đưa tệp .env thực tế lên GitHub. LLM API Key, LangSmith API Key, Feishu App Secret, mật khẩu cơ sở dữ liệu và API Key gateway thực tế cần được lưu trữ cục bộ hoặc trong môi trường triển khai an toàn.

IV. Cài đặt dependency và khởi động dịch vụ

Cài đặt dependency Python

Thực thi trong thư mục gốc của dự án:

uv sync

Lệnh này sẽ đồng bộ môi trường Python và các dependency theo cấu hình dự án.

Khởi động FastAPI API

Sử dụng lệnh sau để khởi động máy chủ phát triển:

uv run uvicorn api.app:app --reload --port 8000

Sau khi khởi động, mở http://localhost:8000/docs để xem tài liệu API Swagger do FastAPI tự động tạo.

Khởi động ARQ Worker

Nếu cần xử lý các nhiệm vụ Agent mất nhiều thời gian, hãy khởi động ARQ Worker trong một terminal khác:

uv run arq tasks.worker.WorkerSettings

Yêu cầu có thể được gửi đến Worker thông qua hàng đợi Redis. Worker sẽ gọi Agent Runtime và lưu trữ bền vững kết quả nhiệm vụ. Quy trình nhiệm vụ bất đồng bộ thường bao gồm Job ID, truy vấn trạng thái nhiệm vụ, thực thi nền, gửi yêu cầu idempotent và lấy kết quả.

Khởi động kết nối dài Feishu

Khi cần kết nối Feishu qua WebSocket, có thể thực thi:

uv run python -m channels.feishu_ws

IvyClaw cũng hỗ trợ Feishu Webhook, Generic Webhook và CLI cùng nhiều điểm vào khác. Các kênh khác nhau sẽ được chuyển đổi thống nhất thành InboundMessage, sau đó dùng chung handle_message() và logic xử lý Agent.

V. Tìm hiểu việc gọi công cụ của Agent

IvyClaw phân bổ cho mỗi Agent một bộ công cụ tối thiểu phù hợp với trách nhiệm, nhằm giảm các lần gọi không cần thiết và nguy cơ thao tác sai. Các loại công cụ được dự án hỗ trợ gồm:

• Git: xem và thao tác với phiên bản mã.
• pytest: thực hiện kiểm thử tự động.
• Python và Shell: chạy các lệnh phát triển.
• Web Search: tra cứu thông tin thông qua Tavily hoặc Exa.
• MCP: kết nối các công cụ và dịch vụ bên ngoài.
• File Tools: đọc và chỉnh sửa tệp trong workspace.
• Sandbox: thực thi cách ly mã do Agent tạo ra.

Dự án cũng sử dụng skills/ để tích lũy các quy trình phát triển có thể tái sử dụng, bao gồm làm rõ yêu cầu, gỡ lỗi có hệ thống, phát triển hướng kiểm thử, kiểm thử đơn vị và xác minh trước khi hoàn tất. Các thư mục tiêu biểu gồm:

skills/
├── fastapi-endpoint/
├── requirements-clarification/
├── systematic-debugging/
├── test-driven-development/
├── unit-test/
└── verification-before-completion/

VI. Sandbox mã và thực thi an toàn

Mã do Agent tạo ra không được thực thi trực tiếp trong tiến trình dịch vụ chính mà có thể được đưa vào môi trường cách ly để chạy. IvyClaw hỗ trợ Docker Sandbox và Daytona Sandbox, đồng thời hỗ trợ thực thi các lệnh Python, pytest và Git.

Khả năng sandbox bao gồm thư mục làm việc độc lập, tái sử dụng sandbox và quản lý vòng đời, cùng các giới hạn tài nguyên như CPU, Memory và PID. Môi trường production mặc định sử dụng Docker Sandbox, đồng thời dành chỗ mở rộng cho các runtime cách ly mạnh hơn như gVisor hoặc Kata.

Khi cấu hình sandbox, cần đánh giá quyền mạng, phạm vi truy cập tệp, giới hạn tài nguyên và quy mô đồng thời dựa trên rủi ro thực tế. README nêu rõ rằng môi trường production vẫn cần tăng cường cách ly bảo mật hơn nữa; không nên xem cấu hình minh họa hiện tại là một giải pháp bảo mật hoàn chỉnh.

VII. Lưu trữ bền vững trạng thái và nhiệm vụ bất đồng bộ

Các thành phần lưu trữ bền vững

PostgreSQL chủ yếu lưu LangGraph Checkpointer, Store, trạng thái phiên và các dữ liệu cần lưu trữ bền vững khác; Redis đảm nhiệm bộ nhớ đệm, giới hạn tốc độ, hàng đợi nhiệm vụ và trạng thái runtime. Nhờ Checkpointer và Store, ngữ cảnh thực thi Agent có thể tiếp tục tồn tại qua nhiều yêu cầu.

Quy trình nhiệm vụ bất đồng bộ

Đối với các nhiệm vụ phát triển có thời gian thực thi dài, nên để FastAPI tạo nhiệm vụ, sau đó Redis và ARQ Worker xử lý bất đồng bộ:

Client
  ↓
FastAPI
  ↓
Create Job
  ↓
Redis Queue
  ↓
ARQ Worker
  ↓
Agent Runtime
  ↓
Persist Result
  ↓
Query Job Status

Cách này giúp tránh chiếm dụng các yêu cầu HTTP đồng bộ trong thời gian dài, đồng thời tạo nền tảng cho việc truy vấn trạng thái nhiệm vụ, thử lại và lưu trữ bền vững kết quả.

VIII. Human-in-the-Loop: thêm phê duyệt cho các thao tác rủi ro cao

Các thao tác như xóa tệp hoặc thực hiện thay đổi mang tính phá hoại không phù hợp để tự động hóa hoàn toàn. IvyClaw hỗ trợ Human-in-the-Loop: khi Agent yêu cầu gọi công cụ có rủi ro cao, quá trình có thể bị ngắt và chờ quyết định của con người.

Agent requests risky action
          ↓
       Interrupt
          ↓
    Human Approval
       ↓       ↓
    Approve   Reject
       ↓
 Command(resume)
       ↓
Agent continues

Sau khi được con người phê duyệt, quá trình tiếp tục thông qua lệnh khôi phục; nếu bị từ chối, quy trình hiện tại sẽ kết thúc hoặc thay đổi. Cơ chế này tạo ra một điểm kiểm soát giữa hiệu quả tự động hóa và an toàn thao tác.

IX. Gateway, đa tenant và quản trị tính ổn định

Trước khi đi vào Agent Runtime, yêu cầu sẽ đi qua lớp gateway để hoàn tất nhận diện danh tính và quản trị cơ bản. Các khả năng hiện có trong kho mã gồm:

• Xác thực API Key.
• Nhận diện và cách ly Tenant.
• Rate Limit.
• Kiểm soát Idempotency.
• Request Context.
• Audit Log.

README đặc biệt lưu ý rằng Key và Tenant hiện chủ yếu là cấu hình minh họa. Môi trường production nên kết nối với cơ sở dữ liệu hoặc hệ thống xác thực danh tính chuyên dụng, đồng thời tiếp tục hoàn thiện quyền hạn tenant và cách ly dữ liệu.

Lớp hạ tầng cũng cung cấp các cơ chế như Retry, Timeout, Fallback, Concurrency Control, PostgreSQL Connection Pool, Redis Connection Pool và Sandbox Pool để ứng phó với tải đồng thời cao, lỗi mô hình và sự chập chờn của hạ tầng.

X. Khả năng quan sát, kiểm thử và đánh giá

IvyClaw tích hợp nhiều thành phần quan sát hệ thống. LangSmith dùng để theo dõi chuỗi gọi Agent và LLM, Prometheus phụ trách thu thập chỉ số, Grafana dùng để giám sát trực quan; ngoài ra còn có nhật ký có cấu trúc và nhật ký kiểm toán.

Trong runtime, có thể tập trung theo dõi các chỉ số sau:

• Độ trễ và tỷ lệ lỗi của yêu cầu.
• Số lượng yêu cầu đồng thời.
• Số lần gọi LLM.
• Lượng Token sử dụng và chi phí.
• Trạng thái ARQ Worker.
• Trạng thái Sandbox.

Dự án cũng bao gồm các thư mục tests/, eval/ và loadtest/, bao phủ kiểm thử tự động bằng pytest, kiểm thử Agent Runtime, Code Cases, Execution Scorer, LLM Judge, Baseline Evaluation, Reviewer Flow Test và kiểm thử tải bằng Locust.

Nên xây dựng vòng xác minh khép kín theo thứ tự “phát triển, kiểm thử tự động, Agent Evaluation, kiểm thử tải, quan sát chỉ số, tối ưu vấn đề”, thay vì chỉ dựa vào một cuộc hội thoại thủ công để đánh giá độ tin cậy của Agent.

XI. Triển khai production bằng Docker

Nếu cần khởi động toàn bộ service stack, có thể sử dụng cấu hình Compose dành cho production do kho mã cung cấp:

docker compose -f docker-compose.prod.yml up -d --build

Triển khai production bao gồm dịch vụ Web FastAPI, ARQ Worker, dịch vụ Feishu, PostgreSQL, Redis, Prometheus và Grafana. API và Worker có thể cùng truy cập Agent Runtime, còn Agent Runtime thực thi mã được tạo thông qua Docker Sandbox.

Trước khi chính thức đưa vào vận hành, cần kiểm tra kết nối cơ sở dữ liệu và Redis, quản lý khóa, xác thực API, cô lập tenant, chiến lược giới hạn tốc độ, giới hạn tài nguyên sandbox, kiểm toán nhật ký, cũng như cấu hình giám sát và cảnh báo.

Mười hai, định vị mã từ cấu trúc dự án

Nắm rõ cấu trúc thư mục giúp mở rộng chức năng nhanh chóng:

IvyClaw/
├── agent/          # Agent chính và điều phối tác vụ
├── api/            # API FastAPI
├── channels/       # Tích hợp CLI / Feishu / Webhook
├── gateway/        # Xác thực API, Tenant, giới hạn tốc độ
├── infra/          # PostgreSQL, Redis, LLM Router
├── middleware/     # Ngữ cảnh yêu cầu, đồng thời, kiểm toán, thống kê chi phí
├── obs/            # Metrics và khả năng quan sát
├── profiles/       # Profile của model và Agent
├── sandbox/        # Sandbox Docker / Daytona
├── skills/         # Agent Skills
├── subagents/      # Planner / Researcher / Coder / Tester / Reviewer
├── tasks/          # Tác vụ bất đồng bộ ARQ
├── tools/          # Công cụ Git / pytest / Search / MCP
├── eval/           # Đánh giá Agent
├── loadtest/       # Kiểm thử tải Locust
├── tests/          # Kiểm thử tự động
├── scripts/        # Script phát triển, kiểm thử và trình diễn
├── web/            # Web UI
├── Dockerfile
├── docker-compose.prod.yml
├── pyproject.toml
└── .env.example

Mười ba, đề xuất sử dụng thực tế

1. Trước tiên cấu hình .env, PostgreSQL và Redis, đồng thời xác nhận API có thể truy cập thông qua tài liệu Swagger.
2. Trước tiên xác thực Agent Workflow cơ bản bằng API đồng bộ hoặc CLI, sau đó khởi động ARQ Worker để xử lý các tác vụ dài.
3. Kiểm tra riêng quyền sử dụng công cụ của Coder, Tester và Reviewer, tránh cấp cho một Agent các khả năng rủi ro cao không cần thiết.
4. Bật thực thi mã được tạo trong sandbox, đồng thời thiết lập giới hạn hợp lý cho CPU, bộ nhớ, số lượng tiến trình và thư mục làm việc.
5. Khi có thao tác xóa hoặc thay đổi mang tính phá hủy, hãy bật Human-in-the-Loop, không mặc định tự động phê duyệt.
6. Sử dụng LangSmith, Prometheus, Grafana và nhật ký có cấu trúc để theo dõi luồng yêu cầu, chi phí, độ trễ và lỗi.
7. Trước khi đưa vào vận hành, chạy pytest, Agent Evaluation và kiểm thử tải Locust, sau đó điều chỉnh định tuyến model, mức độ đồng thời và chiến lược thử lại dựa trên kết quả.

Lời kết

Trọng tâm của IvyClaw không nằm ở việc gọi một model đơn lẻ, mà là kết hợp cộng tác đa tác nhân, gọi công cụ, sandbox mã, lưu trữ trạng thái bền vững, thực thi bất đồng bộ, phê duyệt thủ công, quản trị gateway và khả năng quan sát thành một hệ thống kỹ thuật Agent phục vụ phát triển phần mềm.

Sau khi hoàn tất khởi động cục bộ, bạn có thể bắt đầu với subagents/, tools/ và skills/ hiện có để từng bước tìm hiểu cách Planner, Researcher, Coder, Tester và Reviewer phối hợp, sau đó mở rộng kênh, công cụ hoặc quy trình đánh giá theo nhu cầu nghiệp vụ.