Tạo task và chạy agent

Với điều kiện bạn đã là member của Space, trang này hướng dẫn tạo task thủ công cùng cách chạy, theo dõi và dừng agent để công việc chuyển sang Review đúng quy trình.

Đối tượng: developer trực tiếp biến yêu cầu thành task và giao cho agent. Role kỹ thuật: Board member — tạo/sửa task, chạy/dừng agent, apply plan, ghi Wiki draft; không approve/merge. Điều kiện: đã có Space và bạn đã là member trở lên (nếu 403 mọi thứ, xem Xử lý sự cố).

Ranh giới quan trọng nhất: "làm" (member) tách khỏi "duyệt" (admin). Nút Approve bị chặn với bạn là đúng thiết kế.

Màn hình liên quan

Màn hình	Bạn làm gì ở đây
Board View (màn hình chính)	New Task (phím N), tìm kiếm, filter chips, kéo-thả 4 cột; panel Agent bên phải (3 tab Event Stream / Changes / Follow-up)
Tree View	Xem cây epic → story → task sau Apply Plan; kiểm tra quan hệ blocks
Review View	Chỉ xem (không duyệt): biết task mình đang ở tầng thẩm định nào

Vòng đời task qua agent

Agent xong không tự done: server chuyển task sang cột review với reviewState = peer-review, chờ Reviewer Agent rồi chờ người ở human-gate. Chi tiết các tầng: Máy trạng thái task.

Tạo task thủ công & chạy agent

Hai đường làm cùng một việc — chọn tab bạn cần, không phải đọc cả hai.

Qua giao diện

1. Bấm New Task (phím N) và điền:

   • title (tối đa 200 ký tự), và description càng cụ thể càng tốt (tối đa 5000 ký tự) — agent chỉ biết những gì bạn viết cộng với .board/wiki/**;
   • type (task / bug / story / epic), priority, agentType (CLI sẽ thực thi);
   • repoPath (kế thừa từ Space, override được), baseBranch (thường main);
   • useWorktree — bật: agent làm việc trên bản checkout cách ly, không phá code bạn đang viết dở.
   • timeoutMinutes (tùy chọn, 1–240; trống thì lấy mặc định 60 phút của server).
   • Images (tùy chọn): kéo-thả ảnh vào task — tối đa 10 ảnh, mỗi ảnh ≤ 10MB, chỉ nhận PNG / JPEG / GIF / WebP / SVG. Dùng để đưa ảnh chụp lỗi hoặc mockup vào ngữ cảnh của agent.

2. Kéo task sang In Progress → bấm Start Agent (POST /api/tasks/:id/run).

   Ô "Auto-run" trong hộp thoại tạo task

   Tick Auto-run thì agent chạy ngay sau khi tạo, khỏi phải kéo rồi bấm. Nhưng server chỉ thực sự chạy khi task được tạo sẵn ở cột in-progress — tạo ở backlog (mặc định) mà tick Auto-run thì không có gì chạy, và cũng không có thông báo lỗi nào.

3. Theo dõi panel bên phải: dòng thinking, lệnh terminal, file sửa đổi (tab Changes cho diff đang hình thành).

4. Cần bổ sung yêu cầu giữa lúc agent chạy? Tab Follow-up → gửi tin nhắn (POST /api/tasks/:id/message) — không cần restart.

5. Agent xong → task tự chuyển sang Review với reviewState = peer-review. Việc của bạn tới đây là xong — chờ approver.

Muốn dừng giữa đường: Stop Agent (POST /api/tasks/:id/stop). Worktree được giữ nguyên để bạn kiểm tra.

Qua API

Tạo task (trả 201 với task mới, agentStatus: idle, columnId: backlog):

curl -X POST http://<host>/api/tasks \
  -H 'Content-Type: application/json' \
  -d '{
    "projectId": "<spaceId>",
    "title": "Thêm retry cho webhook VNPay",
    "description": "Bổ sung retry 3 lần với backoff khi VNPay timeout. Non-goals: không chạm module hoàn tiền.",
    "type": "task",
    "priority": "high",
    "baseBranch": "main",
    "useWorktree": true,
    "timeoutMinutes": 60
  }'

{
  "id": "3f2a1c9e-…",
  "projectId": "<spaceId>",
  "title": "Thêm retry cho webhook VNPay",
  "columnId": "backlog",
  "agentStatus": "idle",
  "useWorktree": true
}

Chạy agent (trả task với agentStatus: planning, columnId: in-progress):

curl -X POST http://<host>/api/tasks/<taskId>/run

Nhắn bổ sung khi agent đang chạy (trả {"success": true}):

curl -X POST http://<host>/api/tasks/<taskId>/message \
  -H 'Content-Type: application/json' \
  -d '{"message": "Nhớ thêm unit test cho nhánh timeout"}'

Dừng agent, xem trạng thái nhẹ, đọc event stream:

curl -X POST http://<host>/api/tasks/<taskId>/stop
curl http://<host>/api/tasks/<taskId>/status
curl 'http://<host>/api/tasks/<taskId>/events?limit=50'

GET /:id/status trả đúng shape {"id","agentStatus","agentType","columnId","isRunning"}. GET /:id/events lọc được bằng ?since=<timestamp>&limit=<n>.

Danh sách endpoint đầy đủ kèm quyền tối thiểu: API hay dùng.

Lỗi hay gặp khi chạy agent

Bạn làm	Kết quả	Làm gì tiếp
Chạy task còn blocker chưa done	400 Cannot run task: blocked by unresolved tasks: […]	Xong blocker rồi chạy lại — Dependency gating
Bấm Run khi agent đang chạy	409 agent already running for this task	Đợi, hoặc Stop trước
Bấm Run dồn hai lần	409 run already claimed hoặc 429 too many requests	Đợi vài giây rồi kiểm GET /:id/status
Kéo tay sang done khi chưa approve	400 Task cannot move to done: Human approval is required for this Space.	Đi qua bước Approve — Human Gate

Bảng đầy đủ mọi mã lỗi kèm thông điệp gốc: Mã lỗi API.

@mention sinh subtask từ comment

1. Mở tab Comments trong panel Agent → gõ @persona <việc cần làm>, ví dụ @qa kiểm tra đăng nhập hết hạn token.
2. Gửi comment → mỗi @persona thành 1 subtask con (parentId là task hiện tại), tối đa 5 subtask/comment.
3. Subtask mới nằm ở Backlog, idle — chỉ sinh task, không sinh run. Bạn tự Start Agent sau.
4. Mở subtask bằng chip dưới comment ([mã] tiêu đề @persona).

Mention rớt (không sinh subtask) khi thuộc 1 trong 6 trường hợp — lý do hiện ngay dưới comment (@handle — lý do):

Trường hợp	Lý do hiển thị
Nằm trong quote (>) hoặc code block (``` / `)	inside a quote or code block
Handle lạ (không thuộc persona của Space + agent_profiles)	not a known persona
Trùng (cùng persona + cùng việc đã nhận ở trên)	same request already above
Vượt quá 5 subtask trong 1 comment	over the per-comment limit
Chỉ dẫn ngắn hơn 5 ký tự (ví dụ @qa ok)	no instruction to act on
Task cha đã ở tầng sâu nhất (tối đa 3 tầng)	cả lô rớt: this task is already at the deepest level

Cả lô ghi trong 1 transaction (createSubtaskBatch): lỗi giữa lô → rollback, 0 subtask được ghi. Gửi trùng (retry mạng, double-click Send) không nhân đôi nhờ externalKey băm từ nội dung comment (idempotency). Tiêu đề subtask cắt ở 120 ký tự (mô tả giữ nguyên cả comment để đọc đủ ngữ cảnh).

Chỉ comment của human mới sinh subtask

Comment của agent không sinh (chống loop agent tự nhân task). Tính năng mặc định OFF — operator bật bằng AGENTBOARD_MENTION_SUBTASK=1 rồi restart server. Persona ghi lên subtask là handle bạn gõ; cột persona chuẩn hoá về 1 trong 5 persona Space, lạ quá thì về coder.

Viết mô tả task cho agent làm tốt

Chất lượng đầu ra tỉ lệ thuận với chất lượng description:

• Liệt kê acceptance criteria cụ thể, kiểm chứng được (agent và Reviewer Agent đối chiếu từng tiêu chí).
• Thêm mục non-goals — những gì agent không được chạm (file, module, hành vi).
• Đừng copy-paste convention code vào mô tả: tri thức Wiki đã được bơm tự động vào .board/wiki/**. Xem Wiki hai chiều.

Việc bạn KHÔNG làm được ở trang này (và vì sao)

Bạn thử	Kết quả	Vì sao
Approve / Request Changes	403	Cần admin và human thật — service token cũng 403 vì phân giải về system
Kéo task bị block sang in-progress khi blocker chưa done	bị chặn kèm thông báo	Dependency gating bảo vệ bạn khỏi code trên nền cũ

Checklist tự xác minh

• Tạo task với useWorktree bật, chạy agent, thấy stream realtime và diff ở tab Changes.
• Dùng Follow-up nhắn bổ sung giữa chừng; biết Stop giữ nguyên worktree.
• Mô tả task có acceptance criteria cụ thể + non-goals.
• Gõ @qa <việc> trong Comments → subtask con xuất hiện ở Backlog (idle, không tự chạy); mention sai hiện lý do dưới comment.
• Gọi GET /api/tasks/<id>/status thấy đúng 5 trường id/agentStatus/agentType/columnId/isRunning.

Gặp lỗi? Xem Xử lý sự cố.

Đi tiếp: AI Planner — ý tưởng thành cây Epic/Task · Khi agent treo / đi sai hướng · Task không chạy / agent treo?