Bài 2 — Thiết lập môi trường & khung agent triage

Mục tiêu bài này: dựng một agent triage tối thiểu chạy được, nhận vào một bug report thô và trả về JSON có cấu trúc. Ta ưu tiên đơn giản, chạy được ngay, sau đó mới nâng cấp.

Kiến trúc tối thiểu

[Bug report] -> [Prompt + Rubric] -> [LLM] -> [JSON parser + validate] -> [Kết quả triage]
                         ^                                    |
                         +----- retry nếu JSON hỏng ----------+

Bốn thành phần: system prompt (chứa rubric), schema output, lớp gọi LLM, và lớp validate/retry.

Các bước thiết lập

• Tạo project và cài SDK LLM bạn dùng, đặt API key vào biến môi trường (không hardcode).

mkdir triage-agent && cd triage-agent
python -m venv .venv && source .venv/bin/activate
pip install anthropic pydantic
export ANTHROPIC_API_KEY=sk-...   # không commit key

• Định nghĩa schema bằng Pydantic để ép kiểu và validate output:

from pydantic import BaseModel, Field
from typing import Literal, List

class Triage(BaseModel):
    severity: Literal["S1","S2","S3","S4"]
    priority: Literal["P0","P1","P2","P3"]
    component: str
    status: Literal["triaged","needs_info","duplicate"]
    missing: List[str] = Field(default_factory=list)
    next_action: str
    rationale: str

• Viết system prompt nhúng rubric severity từ Bài 1 và YÊU CẦU trả JSON đúng schema. Luôn kèm câu: "Nếu thiếu repro steps/env, đặt status=needs_info và liệt kê vào missing".

• Gọi LLM và parse:

import json, anthropic
client = anthropic.Anthropic()

def triage(report: str) -> Triage:
    msg = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        system=SYSTEM_PROMPT,   # chứa rubric + yêu cầu JSON
        messages=[{"role":"user","content":report}],
    )
    raw = msg.content[0].text
    return Triage.model_validate_json(_extract_json(raw))

• Thêm validate + retry: nếu model_validate_json ném lỗi, gửi lại kèm thông báo lỗi để LLM tự sửa (tối đa 2 lần), tránh vòng lặp vô hạn.

Khung tư duy: "contract-first"

Định nghĩa hợp đồng đầu ra (schema) TRƯỚC, prompt chỉ là cách đạt hợp đồng đó. Khi output là JSON có kiểu, bạn cắm được vào bất kỳ hệ thống nào (Jira, Slack, GitHub) mà không sửa lõi.

Checklist trước khi chạy thật

[ ] API key nằm trong biến môi trường, không trong code
[ ] Schema có Literal cho các trường phân loại (không để free-text)
[ ] Có hàm extract JSON chịu được text thừa quanh JSON
[ ] Có retry giới hạn khi JSON hỏng
[ ] Có timeout cho lời gọi LLM
[ ] Log lại input + output thô để audit

Sai lầm thường gặp

• Không validate output, tin thẳng chuỗi LLM trả về → khi model trả thêm lời dẫn ("Đây là kết quả:...") thì json.loads vỡ.
• Retry không giới hạn → khi model kẹt, agent quay vô hạn, đốt token.
• Hardcode API key hoặc commit lên git.
• Để severity/component là free-text → downstream không lọc/định tuyến được.
• Không đặt timeout → một request treo làm nghẽn cả hàng đợi triage.

Bài 3 sẽ đi sâu vào việc dạy agent tái hiện bug — bước quan trọng nhất để phân biệt bug thật với báo cáo sai.