UseAgent

Hướng dẫn thao tác

Một goal ngắn.
Cả đội cùng nhớ.

UseAgent là bộ não supervisor và giao thức file-first để nhiều agent cùng làm việc trong một repository mà không giẫm scope của nhau.

Mô hình dễ nhớ

Người dùng → UseAgent supervisor → các worker → report/evidence → supervisor → người dùng.

Bắt đầu trong 5 bước

  1. Đặt control plane.

    Đưa `tools/useagent.py`, `.agents/skills/`, `knowledge/`, `work/`, `AGENTS.md` và config vào root project.

  2. Khởi tạo và kiểm tra.

    Chạy python tools/useagent.py init, sau đó python tools/useagent.py validate.

  3. Đăng ký runtime thật.

    Mỗi Codex, Claude Code hoặc Antigravity session cần id riêng, capability và scope không chồng lấn.

  4. Gửi goal nhẹ cho supervisor.

    Nêu đích đến, agent hiện có và giới hạn. Supervisor tự tạo roadmap, DAG, task và prompt.

  5. Chạy cycle.

    Supervisor tạo mailbox/prompt; worker pull assignment, sửa đúng scope rồi report bằng CLI.

Codex, Claude Code và Antigravity

Ba runtime này không cần adapter riêng. Điều kiện là đều mở cùng repository, đọc được Markdown, chạy được CLI và tôn trọng assignment.

python tools/useagent.py agent register
--id claude-web --role worker
--scope src/frontend --capability web

Trong Codex dùng $useagent cho supervisor và $useagent-worker cho worker. Claude Code chạy tại đúng local checkout. Antigravity tạo Project trỏ vào đúng thư mục, ưu tiên shared-folder mode cho thiết lập đơn giản.

Chu trình autopilot hữu hạn

python tools/useagent.py supervisor cycle --run-qa
python tools/useagent.py worker pull --agent <id>
python tools/useagent.py task report <task-id> ...

Supervisor đọc report ở cycle kế tiếp, kiểm acceptance, chạy QA, tạo debug task khi fail, cập nhật knowledge và ghi checkpoint. Chu trình dừng khi goal mơ hồ, thiếu quyền, scope conflict, lỗi lặp lại hoặc cần deploy/secret/DNS.

Tự động nhận task

Nếu runtime có CLI hoặc adapter local, bạn có thể cấu hình runner argv một lần. Runner nhận {assignment_path}, đọc assignment, làm việc và gọi task report; UseAgent tự lưu evidence và tạo failed report nếu runner thoát mà không report.

python tools/useagent.py worker run --agent <id> --max-tasks 1 --wait-seconds 300

Mặc định không có runner và không tự chạy process ngoài. Codex, Claude Code và Antigravity dùng adapter riêng, còn giao thức mailbox/report vẫn giống nhau.

Bạn chỉ cần xem các file này

01work/SUPERVISOR_REPORT.md

Sức khỏe dự án và next action hiện tại.

02work/checkpoints/

Điểm resume sau mỗi bounded cycle.

03work/completed/COMPLETED.md

Danh sách worker handover đã báo hoàn tất.

04work/evidence/

Log test, review và QA có thể lặp lại.

Đọc hướng dẫn English chi tiết