Xử lý khi agent treo hoặc đi sai hướng
Khi agent lặp vô nghĩa, đi sai hướng hoặc kẹt ở trạng thái executing, trang này hướng dẫn dừng an toàn, chẩn đoán qua log và diff rồi chọn hướng xử lý phù hợp.
Đối tượng: member (dừng agent) và admin (xử lý sâu) khi agent lặp vô nghĩa, đi sai hướng, hoặc kẹt. Điều kiện: bạn là
membertrở lên của Space chứa task; xử lý tay trong worktree cần quyền vào máy chạy server (liên hệ sysadmin).
Quyết định nhanh
Dừng và chẩn đoán
- Dừng agent: nút Stop Agent trên UI, hoặc:
curl -X POST http://<host>/api/tasks/<taskId>/stop
Trả task với agentStatus: failed. Chưa có agent nào chạy → 409 {"error": "no running agent for this task"}.
Process CLI bị kill, worktree giữ nguyên.
- Xem agent đã làm gì: tab Event Stream (toàn bộ log), tab Changes (diff hiện tại), hoặc:
curl 'http://<host>/api/tasks/<taskId>/events?limit=100'
curl http://<host>/api/tasks/<taskId>/status
status cho biết ngay task đang planning / executing / complete / failed và agent có thực sự
đang chạy (isRunning) hay chỉ là trạng thái kẹt trên DB.
- Xem diff trực tiếp từ worktree (khi UI chưa kịp hiện):
curl http://<host>/api/tasks/<taskId>/diff
Trả {"diff","files","additions","deletions"} đọc từ worktree (rơi về repo khi chưa có worktree).
Chọn hướng đi
| Tình huống | Cách xử lý |
|---|---|
| Agent đi đúng hướng nhưng thiếu | Tab Follow-up → gửi tin nhắn bổ sung, không cần restart |
| Agent đi sai hoàn toàn | Stop → sửa description cho rõ hơn → Run lại |
| Muốn giữ code nhưng đổi cách tiếp cận | Stop → nhờ admin Request Changes với ghi chú → rework trên cùng worktree |
| Worktree đã bẩn không cứu được | POST /api/tasks/:id/cleanup-worktree → Run lại từ đầu |
Task kẹt ở executing dù đã stop | Lease 30s tự hết hạn; hoặc restart server để kích hoạt orphan recovery (sysadmin) |
Dọn worktree bẩn (trả {"success": true}; chưa có worktree → 400 {"error": "no worktree to clean up"}):
curl -X POST http://<host>/api/tasks/<taskId>/cleanup-worktree
cleanup-worktree xoá bản checkout cách ly của task. Chỉ dùng khi đã xem diff và chắc không cần giữ.
Muốn giữ hướng đi hiện tại thì Stop (không dọn) rồi Follow-up hoặc Request Changes.
- Timeout mặc định 60 phút (
AGENT_TIMEOUT_MS), override 1–240 phút ở cấp task (timeoutMinutes). Hết giờ, agent bị kill và task ghi Activity timeout. - Bấm Run/Stop dồn dập có thể gặp
429(rate limit vài giây) — đợi rồi kiểm trastatus, đừng bấm tiếp. - Quá 3 vòng rework task tự vào
needs-human. Lúc này làm tay trong worktree:
docker exec -it agentjira_server sh -c 'cd <worktreePath> && git log --oneline -5 && git status'
Vì sao task kẹt tự hồi phục
Yêu cầu chạy được ghi durable trước khi agent khởi động (dispatch lease 30 giây):
server crash giữa chừng, cụm boot recovery quét task còn planning/executing,
đưa về idle kèm Activity system_recovery, worktree giữ nguyên — bạn chỉ cần bấm Run lại.
Sweeper 15 giây nhặt tiếp các run còn dang dở mà agent không còn chạy. Không mất việc, không cần xoá task.
Gặp lỗi? Xem Xử lý sự cố.