Bài 5 — Tích hợp CI: biến agent thành một check trong pipeline

Để agent thành một phần đáng tin của quy trình, nó phải chạy tự động, ổn định và có trạng thái rõ ràng trong pipeline. Bài này biến script review thành một CI check đúng nghĩa: chạy trên mỗi PR, báo pass/fail, không làm vỡ pipeline khi lỗi hạ tầng.

1. Đặt agent đúng vị trí trong pipeline

Thứ tự khuyến nghị: lint → test → agent review. Lý do: nếu lint/test đã đỏ, PR còn sẽ đổi; chạy agent lúc đó tốn token vô ích. Cho agent chạy sau, hoặc song song nhưng chỉ block khi lint/test xanh.

jobs:
  agent-review:
    needs: [lint, test]   # chạy sau khi lint & test xong
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: pip install -r agent/requirements.txt
      - run: python agent/review.py
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}

2. Báo trạng thái qua Checks API

Agent nên tạo một check run để hiện kết quả gọn trên PR:

POST /repos/{o}/{r}/check-runs
{
  "name": "agent-review",
  "head_sha": "<sha>",
  "status": "completed",
  "conclusion": "neutral",   // giai đoạn đầu: neutral, không block
  "output": {
    "title": "3 nhận xét (1 high)",
    "summary": "Xem inline comments để biết chi tiết."
  }
}

Giai đoạn đầu để conclusion: neutral (hiện kết quả nhưng không chặn). Khi đủ tin cậy, chuyển sang failure khi có lỗi high (xem Bài 7).

3. Fail-safe: lỗi agent không được làm vỡ pipeline

LLM có thể timeout, hết quota, hoặc trả JSON hỏng. Nguyên tắc: lỗi hạ tầng của agent → thoát mã 0 (không chặn), ghi log rõ ràng. Đừng để dev bị kẹt merge chỉ vì API LLM chập chờn.

try:
    run_review()
except LLMError as e:
    log.warning(f"Agent bỏ qua do lỗi hạ tầng: {e}")
    post_check(conclusion="neutral", summary="Agent tạm bỏ qua (lỗi hạ tầng).")
    sys.exit(0)   # KHÔNG chặn merge vì lỗi của chính agent

Các bước tích hợp

• Đặt job agent-review với needs: [lint, test].
• Cài dependencies và chạy review.py với secrets từ CI.
• Tạo check run báo số lượng + mức nghiêm trọng.
• Bọc toàn bộ trong try/except: lỗi hạ tầng → neutral + exit 0.
• Thêm cache dependencies để job nhanh; đặt timeout job (vd 5 phút).
• Ghi log token dùng để theo dõi chi phí (Bài 8).

Checklist "CI-ready"

• [ ] Chạy tự động trên opened và synchronize.
• [ ] Có timeout để không treo runner.
• [ ] Lỗi agent không chặn merge (fail-safe).
• [ ] Bỏ qua PR quá lớn / PR của bot / file trong ignore_paths.
• [ ] Log rõ: đã review file nào, tốn bao nhiêu token.

Sai lầm thường gặp

• Để lỗi LLM làm đỏ pipeline. Dev sẽ ghét agent ngay lập tức. Fail-safe là bắt buộc.
• Chạy agent trước lint/test. Lãng phí token cho code còn sẽ sửa. Đặt sau.
• Không đặt timeout. Một lần LLM treo có thể giữ runner nhiều phút. Luôn giới hạn.
• Chạy lại full review mỗi push nhỏ. Cân nhắc chỉ review file thay đổi so với lần chạy trước để tiết kiệm.
• Không loại PR của bot/dependabot. Agent review PR bump version là vô nghĩa và tốn tiền; lọc theo tác giả.

Ví dụ: lọc PR không đáng review

def should_review(pr):
    if pr["user"]["login"] in BOT_AUTHORS:      # dependabot, renovate...
        return False
    if pr["draft"]:                              # PR nháp, bỏ qua
        return False
    if pr["changed_files"] > cfg["max_files"]:   # quá lớn
        return False
    if pr["title"].startswith("[skip-agent]"):   # dev chủ động bỏ qua
        return False
    return True

Mỗi PR bị lọc là token tiết kiệm được. Cho dev một cờ chủ động ([skip-agent]) tôn trọng quyền kiểm soát của họ và giảm khó chịu.

Đo thời gian và chi phí ngay trong CI

Ghi lại thời gian chạy và token dùng vào output của check để đội thấy được "giá" mỗi lần review:

post_check(conclusion="neutral",
           summary=f"Review {n_files} file trong {elapsed:.1f}s, ~{tokens} tokens.")

Số liệu này chính là đầu vào cho việc tối ưu chi phí ở Bài 8. Không đo thì không tối ưu được.

Agent giờ là một check ổn định trong CI. Bài 6 tập trung vào vấn đề quan trọng nhất để agent được tin dùng: giảm false positive.