Xây dựng Pipeline ATDD đa tác nhân với LangGraph và Kiến trúc Lục Giác

Pipeline tự động dựa trên Acceptance Test Driven Development (ATDD) được phát triển kết hợp nhiều agent AI có vai trò riêng biệt, phối hợp nhịp nhàng qua máy trạng thái LangGraph. Bài viết chia sẻ trải nghiệm và kỹ thuật giúp thay thế hàng đợi Celery truyền thống bằng cấu trúc rõ ràng, dễ hiểu hơn rất nhiều.

Vấn đề khi phát triển AI một mình

Phát triển sản phẩm một mình quả thật rất khắc nghiệt khi bạn phải kiêm luôn Product Owner, kiến trúc sư, nhà phát triển và QA cùng lúc. Agent AI hỗ trợ lập trình cũng không phải nút bấm thần kỳ, mà chỉ là một "đồng đội" cần được giao nhiệm vụ rõ ràng, công việc ngắn gọn, và định nghĩa kết thúc có thể xác minh được.

Ban đầu, tác giả thử dùng một agent với prompt dài để làm mọi thứ nhưng thất bại vì mô hình dễ bị lệch ngữ cảnh và tạo ra sản phẩm sai. Giải pháp tiếp theo là áp dụng nguyên tắc chia nhỏ nhiệm vụ: mỗi agent chỉ thực hiện một vai trò, với ngữ cảnh rất cụ thể và đủ để làm tốt công việc.

ATDD và sự phù hợp với pipeline đa tác nhân

Acceptance Test Driven Development (ATDD) yêu cầu viết tiêu chí chấp nhận (acceptance criteria) trước, thường dưới dạng kịch bản Gherkin, rồi xây dựng đến khi vượt qua các tiêu chí đó.

Pipeline đa tác nhân giúp ứng dụng ATDD hiệu quả:

• Kiến trúc sư (người và AI Claude): định nghĩa yêu cầu, viết tiêu chí, tinh chỉnh câu chuyện người dùng (user stories)
• Kỹ sư kiểm thử (tự động): viết unit test và integration test ở trạng thái đỏ (RED), trước khi code
• Lập trình viên (tự động): sửa code để các test đỏ chuyển thành xanh (GREEN)
• Tester (tự động): kiểm tra chất lượng (quality gate) với các công cụ như ruff, mypy
• Worker ATF (tự động): chạy các kịch bản Gherkin với Playwright và Behave

Mỗi agent tập trung nhiệm vụ riêng, chuyển đổi trạng thái của câu chuyện thông qua các bước kiểm thử là minh bạch rõ ràng, không ai được bỏ qua hay tự xác nhận thành công.

story.md → status: ready
      │
      ▼
test_engineer  → tests đỏ
      │
      ▼
developer    → tests xanh
      │
      ▼
tester     → quality gate
      │
      ▼
atf_worker   → acceptance pass
      │
      ▼
status: accepted  ✓

Kiến trúc lục giác và vai trò của LangGraph

Pipeline được thiết kế dựa trên kiến trúc lục giác (hexagonal architecture) với các lớp:

• Domain: Thuần Python, không phụ thuộc thư viện ngoài
• Application: Chỉ nhập domain (định nghĩa các use case)
• Infrastructure: Nhập domain, application và các thư viện bên ngoài (như Celery, LangGraph)

Domain định nghĩa các cổng giao tiếp (ports) như StoryRepository, CodeRunner, TaskQueue. Các use case (ví dụ RunDeveloper) chỉ làm việc với cổng này, không biết cụ thể backend là gì (database, API hay hàng đợi).

Điều này cho phép thay đổi hạ tầng vật lý (infrastructure) mà không ảnh hưởng đến logic nghiệp vụ.

Từ Celery + Redis tới LangGraph state machine

Trước đây tác giả dùng Celery với Redis làm hàng đợi cho từng vai trò agent. Tuy hiệu quả, cách làm này vẫn tồn tại nhiều bất tiện:

• Cần Redis cả khi phát triển local
• Cơ chế state machine không rõ ràng, nằm rải rác trong nhiều file và nhiều chỗ enqueue gọi
• Việc retry thủ công phức tạp, dùng thao tác enqueue lại scattered trong code
• Khó khăn trong việc chạy pipeline đơn giản trên máy cá nhân (phải docker compose up)

LangGraph là một thư viện để xây dựng đồ thị công việc trạng thái, rất phù hợp với luồng xử lý đa tác nhân AI như pipeline ATDD này.

Bạn định nghĩa:

• State dưới dạng Python TypedDict lưu trữ mọi thông tin trạng thái cần thiết như story_id, status, số lần retry,...
• Nodes tương ứng các bước xử lý agent, gọi lại use case và trả về trạng thái mới
• Edges có điều kiện cho phép chuyển trạng thái rõ ràng, minh bạch

Ví dụ luồng trạng thái được định nghĩa bằng function duy nhất, ai cũng đọc hiểu dễ dàng:

• test_engineer → READY_TO_DEV → developer
• developer → READY_TO_TEST → tester
• tester → READY_TO_ATF → atf
• tester → READY_TO_DEV → developer (retry tối đa 3 lần)
• atf → DONE → END

Cuối cùng, dispatcher chạy vòng lặp duyệt tất cả câu chuyện ở trạng thái INBOX sau đó kích hoạt pipeline lúc khởi đầu.

Ưu điểm:

• Không cần broker, worker process, hay docker compose nữa
• Có thể chạy đơn giản với vài lệnh pip install và python

Các quyết định thiết kế đáng chú ý

• Lưu trạng thái trong file story.md có frontmatter YAML thay vì database, giúp mọi tác nhân (con người, công cụ) có thể đọc sửa dễ dàng, trạng thái tồn tại lâu dài qua restart, và lịch sử migrate rõ ràng bằng Git.

• Vai trò kiến trúc sư (Architect) không tự động hóa vì đây là phần cần sự phán đoán của con người để đảm bảo không xây dựng sai yêu cầu.

• Vẫn giữ Celery cho các trường hợp cần mở rộng quy mô chạy trên nhiều máy, LangGraph chỉ ưu tiên cho local và môi trường đơn máy. Cả hai dùng chung domain và use cases, chỉ thay đổi adapter hạ tầng.

• Mô hình NoOpQueue được dùng để ẩn các call enqueue trong use cases khi dùng LangGraph, tránh phải thay đổi use case làm đứt mạch chạy bằng Celery.

Ứng dụng thực tế và triển vọng tương lai

Pipeline này đã chạy thử với dự án nguồn mở atf-ai — một CLI kiểm thử chấp nhận tự động bằng Playwright.

Trong 5 câu chuyện người dùng, 4 đạt trạng thái accepted tự động, 1 story bị block do vướng kiến trúc cần review chặn đúng cách.

Dự kiến sẽ phát triển thêm:

• Chức năng checkpoint LangGraph để lưu trạng thái và khôi phục sau sự cố
• Hỗ trợ chạy song song nhiều câu chuyện với asyncio
• Tăng khả năng quan sát, phát hành sự kiện để debug dễ dàng hơn
• Kiến trúc sư tự động sửa lỗi khi nhận biết story bị block nhờ Claude AI

Kết luận

Điều gây bất ngờ lớn nhất không phải là phần AI mà là sự tinh gọn, rõ ràng trong điều phối các agent khi máy trạng thái được làm explicit bằng LangGraph.

Với Celery, workflow rải rác, logic retry rườm rà, khó đọc — bạn phải dò nhiều file để hiểu tình huống sau lỗi. Với LangGraph, toàn bộ vòng đời câu chuyện hiện ra rõ ràng trong một hàm duy nhất. Điều này vô giá nếu bạn làm việc một mình, hoặc trở lại code sau nhiều tuần.

Nếu bạn đang phát triển pipeline đa tác nhân, hãy làm cho máy trạng thái trở nên rõ ràng ngay từ đầu — tương lai của bạn sẽ biết ơn vì điều đó.

---

Nguồn dự án và mã nguồn mở: https://github.com/csotelo/atdd-framework