Multi-Agent Gemini Worker Pool

Claude Leader điều phối Gemini Worker Pool

Claude Code đóng vai Leader: tự đánh giá yêu cầu, có thể tự làm một mình hoặc chia nhỏ thành nhiều task độc lập giao cho tối đa MAX_CONCURRENCY luồng Gemini Worker chạy song song. Backend thật là Antigravity CLI (agy) — dùng chung gói Antigravity Pro miễn phí đã đăng nhập sẵn, chạy thẳng bằng subprocess trên HP1, không cần Docker/GUI/Xvfb/noVNC cho việc sử dụng hàng ngày.

Backend: agy CLI Gói Antigravity Pro (miễn phí) Không cần Docker

🔄

Vòng Đời Một Task — Từ Yêu Cầu Đến Kết Quả

Claude tự đánh giá

Đọc yêu cầu, tự quyết có nên chia nhỏ giao Worker hay tự làm (xem hộp "Khi nào chia việc" bên dưới).

Gọi MCP Tool

gemini_dispatch_task / _batch — WorkerPoolManager đọc lại Multi_Agent.conf, kiểm DISPATCH_MODE.

Xếp hàng Semaphore

Tối đa MAX_CONCURRENCY task chạy cùng lúc; worker nào xong tự nhận task tiếp theo trong hàng đợi.

Subprocess agy

agy -p ... --add-dir --model --conversation --output-format json chạy thật trong workspace.

Worker BẮT BUỘC tự test

System prompt ép Worker tự chạy test_command/tự kiểm tra TRƯỚC khi báo cáo — không được đùn việc phát hiện lỗi cho Claude. Input mơ hồ/sai → Worker trả NEED_CLARIFICATION:, không đụng file.

Self-verify lớp 2 (độc lập)

MCP tự chạy lại py_compile + test_command — không tin lời khai của Worker, sinh Git diff ngắn gọn.

Claude review diff

Kết quả (diff + test_result + token) trả về cho Claude đọc và đánh giá.

Approve / Feedback / Rollback

Đạt → approve_task. Chưa đạt → send_feedback (giữ ngữ cảnh, tối đa MAX_ITERATIONS_PER_TASK vòng). Sai hướng → rollback_task.

🧭

Khi Nào Claude Tự Làm, Khi Nào Chia Việc?

Không có cơ chế tự động phân luồng. Quyết định do chính Claude cân nhắc tại thời điểm nhận yêu cầu, trừ khi bị ép bởi DISPATCH_MODE trong Multi_Agent.conf:

AUTOMặc định — Claude tự cân nhắc: task độc lập, mô tả rõ, ít cần phán đoán kiến trúc → hợp để chia.

ALWAYSKhuyến khích Claude ưu tiên chia việc khi có ≥2 task độc lập (chỉ là gợi ý hành vi, không ép được ở tầng code).

NEVERKhoá cứng ở tầng code — mọi lệnh gọi Worker bị chặn ngay, Claude bắt buộc tự làm 100%.

🧠

Model Xử Lý Của Worker

Mặc định (MODEL_INDEX=0) worker dùng đúng model mặc định của tài khoản Antigravity — đo thực tế lúc viết tài liệu này là:

model_config_manager.go: Propagating selected model
override to backend: label="Gemini 3.7 Flash (High)"

Đổi model bằng cách sửa MODEL_INDEX trong Multi_Agent.conf (bảng đầy đủ 15 lựa chọn ở Tab 3) — có hiệu lực ngay từ task tiếp theo, không cần khởi động lại gì.

💰

Kinh Tế Token — Vì Sao Một Câu Hỏi Đơn Giản Cũng Tốn Hàng Chục Nghìn Token

Đo thực tế trực tiếp qua agy: prompt chỉ vỏn vẹn "Trả lời đúng 1 từ: OK" vẫn tốn 32.193 input token. Đây là chi phí cố định của mỗi cuộc hội thoại MỚI (system prompt nội bộ của agy + tool schema + 2 file quy ước GEMINI.md/AGENTS.md ở gốc repo — hiện đồng bộ đầy đủ 136 dòng từ CLAUDE.md) — KHÔNG phải do cờ --add-dir nạp toàn bộ workspace vào context (cờ này chỉ cấp quyền đọc/ghi thư mục, agent tự quyết định đọc file nào qua tool call khi thật sự cần, giống hệt cách Claude Code tự đọc file).

Kịch bản đo thật	Input Token	Cache Read Token	Ghi chú
Lượt 1 — hội thoại mới (`gemini_dispatch_task`)	32.193	0	Toàn bộ chi phí cố định phải trả trọn vẹn
Lượt 2 — cùng hội thoại qua `--conversation` (`gemini_send_feedback`)	35.964	28.563	~79% chi phí cố định được tái sử dụng từ cache, rẻ hơn nhiều

⇒ Đòn bẩy tối ưu duy nhất đang kiểm soát được: (1) rút gọn GEMINI.md/AGENTS.md nếu chấp nhận đánh đổi Worker biết ít kiến thức dự án hơn; (2) luôn dùng send_feedback (giữ conversation_id) thay vì tạo task_id mới cho cùng một việc, để tận dụng cache.

⏳

Quota & Giới Hạn Thực Thi

Nguồn Quota

Dùng chung gói Antigravity Pro miễn phí của tài khoản — không phải API key trả phí. Giới hạn fair-use không công bố số liệu cụ thể, chỉ phát hiện khi dính 429/RESOURCE_EXHAUSTED.

Cooldown Thông Minh

Hết quota → khoá theo mốc thời gian tuyệt đối (không đếm lại từ đầu). Đã trôi 4h trong chu kỳ 5h thì chỉ báo chờ đúng 1h còn lại.

Timeout & Song Song

Mỗi lượt gọi giới hạn TASK_TIMEOUT_SEC (mặc định 600s); tối đa MAX_CONCURRENCY luồng chạy cùng lúc (mặc định 5) — cả hai chỉnh được trong Multi_Agent.conf.

🤖

Nhóm Giao & Phản Hồi Task

gemini_dispatch_task
Giao 1 nhiệm vụ (task_id, description, target_files, test_command?, code_instruction?) — tự kiểm cú pháp + sinh Git diff.
gemini_dispatch_batch
Giao đồng loạt danh sách task, tự chạy song song tối đa MAX_CONCURRENCY luồng. Kèm pool_report nếu AUTO_REPORT=YES.
gemini_send_feedback
Gửi phản hồi sửa lỗi cho task chưa đạt — Gemini giữ đúng conversation_id, không mất ngữ cảnh.
gemini_approve_task
Nghiệm thu (APPROVED), đóng session và dọn bản backup của task.
gemini_rollback_task
Từ chối, khôi phục toàn bộ file về trạng thái trước khi Gemini sửa.

📊

Nhóm Giám Sát Pool

gemini_get_pool_status
Số worker đang chạy/chờ, tổng lượt gọi, trạng thái quota, và toàn bộ config hiệu lực hiện tại (đọc trực tiếp từ Multi_Agent.conf) kèm config_warnings.
gemini_get_metrics_summary
Bảng thống kê đầy đủ: tổng số task, tổng token, thời gian, và chi tiết từng task theo từng task_id.

⚠️ Toàn bộ trạng thái task chỉ nằm trong bộ nhớ tiến trình MCP (self.tasks của WorkerPoolManager) — không ghi ra đĩa, mất sạch khi restart MCP server / phiên Claude Code.

🔀

Sơ Đồ Trạng Thái Một Task

QUEUED→ RUNNING→ READY_FOR_REVIEW→ APPROVED

RUNNING→ SELF_TEST_FAILED hoặc FAILED→ gửi send_feedback → RUNNING (lặp tối đa MAX_ITERATIONS_PER_TASK vòng, quá ngưỡng → MAX_ITERATIONS_REACHED)

RUNNING→ NEEDS_CLARIFICATION — Worker phát hiện input mơ hồ/sai, trả NEED_CLARIFICATION: kèm câu hỏi cụ thể, KHÔNG đụng file nào. Claude phải bổ sung thông tin rồi gọi lại send_feedback (không tính là 1 vòng sửa lỗi)

RATE_LIMITED — hết quota, chờ theo QUOTA_EXHAUSTED_MODE (xem Tab 3) rồi gọi lại đúng task_id

DISPATCH_DISABLED — DISPATCH_MODE=NEVER đang bật, bị chặn ngay từ đầu, không tốn quota

bất kỳ trạng thái nào→ rollback_task → khôi phục file gốc, đóng session

Multi_Agent.conf — Cấu Hình Không Cần Khởi Động Lại

File tại Library/A0_Gemini_Worker_MCP/Multi_Agent.conf được đọc lại từ đĩa MỖI LẦN gọi tool (không cache) — sửa xong lưu là có hiệu lực ngay từ lượt gọi tiếp theo, khác hẳn việc sửa file .py (luôn cần khởi động lại MCP server / phiên Claude Code).

Không cần restart Sai giá trị → tự fallback an toàn

📋

Toàn Bộ 7 Tham Số Cấu Hình

Key	Ý nghĩa	Mặc định	Khoảng / Lựa chọn hợp lệ
`MAX_CONCURRENCY`	Số luồng Worker chạy song song tối đa. Worker rảnh tự nhận task tiếp theo trong hàng đợi (`ResizableSemaphore`).	5	1 – 20
`TASK_TIMEOUT_SEC`	Thời gian tối đa (giây) cho 1 lượt Worker xử lý 1 tác vụ, bao gồm cả tự code + tự test lại nội bộ. Áp cho cả `--print-timeout` của `agy` lẫn timeout subprocess bên ngoài.	600	30 – 3600 (giây)
`MODEL_INDEX`	Model Gemini/Claude/GPT xử lý — nhập số index theo bảng model bên dưới.	0	0 – 14 (xem bảng model)
`DISPATCH_MODE`	Chính sách chia task: `AUTO` (Claude tự quyết) / `ALWAYS` (khuyến khích ưu tiên chia) / `NEVER` (khoá cứng, không tốn quota).	AUTO	AUTO / ALWAYS / NEVER
`MAX_ITERATIONS_PER_TASK`	Số vòng `send_feedback` sửa lỗi tối đa cho 1 task trước khi báo `MAX_ITERATIONS_REACHED` cần Claude/người can thiệp tay.	5	1 – 20
`QUOTA_EXHAUSTED_MODE`	`WAIT` (chờ đúng phần thời gian còn lại của chu kỳ 5h, tự hồi phục) hoặc `STOP` (Claude phải tự làm nốt ngay, không chờ).	WAIT	WAIT / STOP
`AUTO_REPORT`	Tự động đính kèm bảng thống kê Worker (`pool_report`) vào kết quả `gemini_dispatch_batch` hay không. `gemini_get_metrics_summary` vẫn luôn gọi được thủ công.	YES	YES / NO

🧠

Bảng 15 Lựa Chọn MODEL_INDEX

Index	Model
`0`	(mặc định tài khoản, không ép model)
`1`	gemini-3.7-flash-high
`2`	gemini-3.7-flash-medium
`3`	gemini-3.7-flash-low
`4`	gemini-3.6-flash-high
`5`	gemini-3.6-flash-medium
`6`	gemini-3.6-flash-low
`7`	gemini-3.5-flash-high
`8`	gemini-3.5-flash-medium
`9`	gemini-3.5-flash-low
`10`	gemini-3.1-pro-high
`11`	gemini-3.1-pro-low
`12`	claude-sonnet-4-6
`13`	claude-opus-4-6-thinking
`14`	gpt-oss-120b-medium

Danh sách lấy từ lệnh agy models ngày 2026-08-17. Antigravity có thể đổi danh sách theo thời gian — chạy lại lệnh đó rồi cập nhật MODEL_CHOICES trong multi_agent_config.py nếu nghi ngờ lỗi thời.

📄

Ví Dụ File Multi_Agent.conf

# Song song nhiều luồng hơn, model rẻ/nhanh hơn mặc định
MAX_CONCURRENCY=8
TASK_TIMEOUT_SEC=300
MODEL_INDEX=6  # gemini-3.6-flash-low
DISPATCH_MODE=AUTO
MAX_ITERATIONS_PER_TASK=3
QUOTA_EXHAUSTED_MODE=STOP
AUTO_REPORT=YES

Sai kiểu dữ liệu hoặc ngoài khoảng hợp lệ (VD MAX_CONCURRENCY=abc hoặc =99) → tự động fallback về giá trị mặc định an toàn, KHÔNG làm crash MCP. Xem cảnh báo cụ thể qua:

gemini_get_pool_status()
→ result.config.config_warnings

1. Khi nào Claude tự làm một mình, khi nào làm leader chia việc cho Gemini Worker?

Không có cơ chế tự động — quyết định hoàn toàn do Claude cân nhắc tại thời điểm nhận yêu cầu (task có độc lập, mô tả rõ, ít cần phán đoán kiến trúc hay không), trừ khi Multi_Agent.conf ép bằng DISPATCH_MODE=NEVER (khoá cứng, không dùng Worker được nữa) hoặc ALWAYS (chỉ là gợi ý ưu tiên, không ép được ở tầng code).

2. Gemini Worker đang dùng bản model nào? Đổi được không?

Mặc định (MODEL_INDEX=0) dùng đúng model mặc định hiện tại của tài khoản Antigravity — đo thực tế là Gemini 3.7 Flash (High). Đổi bằng cách sửa MODEL_INDEX trong Multi_Agent.conf theo bảng 15 lựa chọn ở Tab 3, có hiệu lực ngay từ task tiếp theo.

3. Dựa vào báo cáo nào để biết Claude đã chia bao nhiêu task, worker nào nhận task nào?

Gọi gemini_get_metrics_summary (bảng chi tiết từng task: trạng thái, số vòng lặp, thời gian, token, diff) hoặc gemini_get_pool_status (trạng thái tức thời + cấu hình hiệu lực). Nếu AUTO_REPORT=YES (mặc định), gemini_dispatch_batch tự đính kèm báo cáo pool_report ngay trong kết quả trả về.

Lưu ý: dữ liệu này chỉ nằm trong bộ nhớ tiến trình MCP, mất khi phiên/MCP server restart.

4. Chia nhỏ task cho Gemini có đảm bảo chất lượng tương đương Claude tự làm không?

Không đảm bảo tương đương — đây là đánh đổi tốc độ (chạy song song tối đa MAX_CONCURRENCY luồng) lấy chất lượng có kiểm soát, không phải nâng chất lượng. Model Gemini Flash nói chung yếu hơn Claude ở suy luận phức tạp/kiến trúc nhiều ràng buộc.

Hệ thống bù lại bằng vòng an toàn: backup file tự động, tự kiểm cú pháp/test_command, sinh diff, và bắt buộc Claude review trước khi approve_task/rollback_task — chất lượng cuối chỉ tốt bằng đúng mức Claude review kỹ diff, không tự động ngang bằng.

5. Quota và thời gian thực thi hoạt động ra sao?

Dùng chung gói Antigravity Pro miễn phí — giới hạn fair-use không công bố số liệu, chỉ phát hiện khi dính 429/RESOURCE_EXHAUSTED. Khi hết quota, hệ thống tự khoá theo mốc thời gian tuyệt đối hồi phục (không đếm lại từ đầu — đã trôi 4h trong chu kỳ 5h thì chỉ báo chờ đúng 1h còn lại).

QUOTA_EXHAUSTED_MODE=WAIT (mặc định): Claude có thể gọi lại sau mốc hồi phục. =STOP: Claude phải tự làm nốt phần còn lại ngay, không chờ. Mỗi lượt gọi giới hạn TASK_TIMEOUT_SEC (mặc định 600s), tối đa MAX_CONCURRENCY luồng song song (mặc định 5).

6. Nếu tôi muốn một yêu cầu cụ thể chỉ mình Claude thực hiện (không dùng team) thì cần làm gì?

Nói thẳng trong yêu cầu, ví dụ: "làm việc này một mình, đừng dùng Gemini worker". DISPATCH_MODE trong Multi_Agent.conf là cấu hình toàn cục áp cho mọi yêu cầu, không có cờ riêng theo từng lần hỏi — muốn khoá vĩnh viễn toàn hệ thống thì đặt DISPATCH_MODE=NEVER.

7. Sửa Multi_Agent.conf có cần khởi động lại MCP server hay phiên Claude Code không?

Không. File này được đọc lại từ đĩa mỗi lần gọi tool (dispatch_task/dispatch_batch), sửa xong lưu là có hiệu lực ngay từ lượt gọi tiếp theo.

Ngược lại, nếu sửa code (gemini_runner.py, worker_pool.py, mcp_gemini_server.py...) thì bắt buộc phải khởi động lại MCP server (khởi động lại phiên Claude Code / reload window IDE), vì đó là tiến trình stdio chạy sẵn không tự nạp lại code khi file đổi.

8. Vì sao một câu hỏi đơn giản như "OK" cũng tốn hơn 30.000 token?

Đây là chi phí cố định mỗi hội thoại mới: system prompt nội bộ của agy + tool schema + 2 file GEMINI.md/AGENTS.md ở gốc repo (hiện đồng bộ đầy đủ 136 dòng từ CLAUDE.md) — KHÔNG phải do --add-dir nạp toàn bộ workspace (cờ này chỉ cấp quyền đọc/ghi, agent tự đọc file khi cần qua tool call).

Đo thực tế: 32.193 input token cho prompt 1 dòng. Xem chi tiết bảng đo ở Tab 1, mục "Kinh Tế Token".

9. Trong cùng 1 task, gửi feedback nhiều lần có tốn lại toàn bộ chi phí cố định mỗi lần không?

Không tốn lại toàn bộ — gemini_send_feedback dùng lại đúng conversation_id của lần gọi trước (qua cờ --conversation của agy), nhờ đó phần lớn chi phí cố định được cache lại. Đo thực tế: lượt 2 trong cùng hội thoại tốn 35.964 input token nhưng 28.563 trong số đó là cache_read_tokens — đọc từ cache, rẻ hơn nhiều so với input hoàn toàn mới.

10. Worker hết quota giữa chừng thì task đang dở có bị mất không?

Không mất. File đã sửa (nếu có) vẫn giữ nguyên trên đĩa, bản backup gốc vẫn còn (chỉ dọn khi approve_task/rollback_task). Task chuyển trạng thái RATE_LIMITED — Claude có thể gọi lại gemini_send_feedback/gemini_dispatch_task cho đúng task_id đó sau khi quota hồi phục (WAIT) hoặc tự tiếp quản phần việc ngay (STOP).