pi-dynamic-workflows: Fan-out công việc cho AI Agent như Claude Code

Bạn đã bao giờ đưa cho AI một task phức tạp kiểu "audit toàn bộ codebase" hay "review kiến trúc từ nhiều góc độ" rồi ngồi chờ nó xử lý tuần tự từng bước một chưa? Mình thì nhiều lần rồi. Và cảm giác đó giống như xem một người cố gắng bưng 10 đĩa thức ăn ra bàn, mỗi lần một đĩa.

Đó chính là vấn đề mà pi-dynamic-workflows giải quyết. Thay vì một agent làm mọi thứ sequential, nó cho phép model tự viết một đoạn JavaScript script để fan-out công việc ra nhiều isolated subagent chạy đồng thời, rồi tổng hợp kết quả lại.

Bối cảnh: Dynamic Workflows là gì và tại sao nên quan tâm?

Nếu bạn đã dùng Claude Code của Anthropic, có thể bạn đã nghe về concept dynamic workflows ý tưởng rằng thay vì hard-code một pipeline cố định, ta để AI model tự thiết kế workflow dựa trên yêu cầu cụ thể. Model sẽ quyết định cần bao nhiêu bước, bước nào chạy song song, bước nào phụ thuộc kết quả của bước trước.

pi-dynamic-workflows mang concept này vào Pi dưới dạng một extension. Repo hiện tại đã có 657 stars và 37 forks, cho thấy cộng đồng khá quan tâm.

Theo kinh nghiệm của mình, những use case phù hợp nhất với pattern này là:

• Codebase audit: Scan nhiều module cùng lúc, mỗi subagent phụ trách một phần
• Multi-perspective review: Cùng một đoạn code nhưng review từ góc security, performance, maintainability song song
• Large refactors: Phân tích impact trên nhiều file/service đồng thời
• Fan-out research: Tìm hiểu nhiều chủ đề liên quan rồi tổng hợp

Cài đặt và bắt đầu

Cài đặt đơn giản đến mức không có gì để nói nhiều:

1pi install npm:pi-dynamic-workflows

Hoặc nếu bạn clone repo về local:

1pi install /path/to/pi-dynamic-workflows

Sau đó trong Pi, gõ /reload là xong. Extension tự register một workflow tool và activate khi session bắt đầu.

Điều mình thấy hay là bạn không cần config gì thêm. Không có file YAML dài dằng dặc, không có environment variables phải set. Install xong là dùng được.

Cách hoạt động: Workflow Script

Đây là phần core và cũng là phần thú vị nhất. Khi bạn yêu cầu Pi chạy một workflow, model sẽ tự viết một đoạn plain JavaScript với cấu trúc nhất định.

Một workflow script bắt buộc phải export meta object ở đầu file:

1export const meta = {
2  name: 'inspect_project',
3  description: 'Inspect a repository and summarize the main modules',
4  phases: [
5    { title: 'Scan' },
6    { title: 'Analyze' },
7  ],
8}
9
10phase('Scan')
11const inventory = await agent('Inspect the repository structure.', {
12  label: 'repo inventory',
13})
14
15phase('Analyze')
16const summary = await agent(
17  'Summarize the main modules from this inventory:\n' + inventory,
18  { label: 'module summary' },
19)
20
21return { inventory, summary }

Điểm đáng chú ý: phases được discover dynamically khi script chạy. Nghĩa là bạn có thể dùng conditional logic hoặc loop để tạo phase nếu một branch bị skip, phase đó đơn giản là không xuất hiện trong progress view. Không có empty row trống trơn làm rối mắt.

Các globals có sẵn trong workflow

Đây là bộ API mà bạn (hoặc model) có thể dùng trong workflow script:

Điều mình thấy thiết kế rất tốt ở đây là sự phân biệt rõ ràng giữa parallel và pipeline.

parallel là khi bạn có N task độc lập, muốn chạy cùng lúc:

1const results = await parallel([
2  () => agent('Review security aspects'),
3  () => agent('Review performance aspects'),
4  () => agent('Review maintainability aspects'),
5])

pipeline là khi bạn có N items cần đi qua cùng một chuỗi xử lý các items fan-out nhưng mỗi item vẫn đi qua stages tuần tự. Rất giống pattern map-reduce mà chúng ta hay dùng trong data processing.

Live Progress và khả năng cancel

Khi workflow chạy, bạn sẽ thấy progress inline kiểu:

1◆ Workflow: inspect_project (3/3 done)
2  ✓ Scan 1/1
3    #1 ✓ repo inventory
4  ✓ Analyze 2/2
5    #2 ✓ source modules
6    #3 ✓ final summary

Nhấn Esc để cancel workflow đang chạy. Các subagent đang active sẽ bị abort và hiển thị là "skipped". Đây là một chi tiết nhỏ nhưng quan trọng không ai muốn phải kill cả process chỉ vì một workflow chạy sai hướng.

Editor IntelliSense

Nếu bạn viết reusable workflow files (thay vì để model tự generate), bạn có thể thêm dòng này ở đầu file để có autocomplete trong editor:

1/// <reference types="pi-dynamic-workflows/workflow" />

Dòng này declare tất cả globals agent, parallel, pipeline, phase, log, args, cwd, budget cho TypeScript-aware editors. Một chi tiết nhỏ nhưng cho thấy maintainer nghĩ đến developer experience khá kỹ.

So sánh với cách tiếp cận truyền thống

Theo kinh nghiệm của mình, dynamic workflows không phải silver bullet. Với task đơn giản kiểu "fix bug này" hay "viết unit test cho function kia", một agent đơn lẻ vẫn nhanh và hiệu quả hơn. Dynamic workflows tỏa sáng khi task có thể decompose thành nhiều phần độc lập hoặc bán độc lập.

Những điều đáng lưu ý

Một vài điểm mình muốn highlight sau khi đọc qua repo:

• 12 issues đang mở project còn khá mới và đang active development. Expect breaking changes.
• Workflow script là plain JavaScript, không phải DSL riêng. Điều này có nghĩa là learning curve gần như bằng 0 nếu bạn đã biết JS.
• Subagent là isolated chúng không share context với nhau. Nếu cần truyền data giữa các agent, bạn phải explicitly pass qua prompt hoặc return value.
• Pattern này inspired by Anthropic's Claude Code nên nếu bạn đã quen với cách Claude Code hoạt động, mental model sẽ rất tương đồng.

Ai nên thử?

Nếu bạn đang dùng Pi và thường xuyên làm việc với codebase lớn multi-module, monorepo, hoặc cần audit/review ở scale lớn thì đây là extension đáng thử. Chi phí thử nghiệm thấp (install một dòng, uninstall cũng một dòng), nhưng potential upside khá rõ ràng.

Còn nếu bạn chưa dùng Pi, thì ít nhất concept dynamic workflows vẫn đáng để tìm hiểu. Đây là hướng đi mà nhiều AI coding tool đang adopt và hiểu nó sớm sẽ giúp bạn tận dụng tốt hơn bất kể tool nào bạn chọn dùng.

Repo: github.com/Michaelliv/pi-dynamic-workflows