Agent 1 — Harness Engineering: Dựng AI Agent thực chiến

Vì sao "harness" quan trọng hơn cả model

Khi một AI agent thất bại trong thực tế, 9/10 trường hợp thủ phạm không phải model mà là lớp bao quanh nó. Cùng một claude-opus-4-8, hai đội khác nhau cho ra hai kết quả cách biệt một trời một vực — chênh lệch nằm ở harness.

Harness (khung/giàn giáo) là toàn bộ hạ tầng phần mềm bao quanh lời gọi model để biến nó từ "trả lời một câu" thành "hoàn thành một nhiệm vụ nhiều bước". Nếu model là bộ não, thì harness là giác quan, tay chân, trí nhớ và kỷ luật:

• Vòng lặp tác tử (agentic loop): gọi model → model chọn hành động → thực thi → quan sát kết quả → lặp lại cho tới khi xong.
• Tools: cửa để agent tác động ra thế giới (chạy SQL, đọc file, gọi API, tìm kiếm).
• Quản lý ngữ cảnh (context engineering): nạp đúng thông tin vào cửa sổ context, nén/tóm tắt khi đầy.
• Bộ nhớ: scratchpad ngắn hạn + memory dài hạn (file/vector).
• Kiểm chứng (verification): agent tự kiểm hoặc bị agent khác phản biện trước khi chốt.
• Quyền & an toàn: chặn hành động nguy hiểm — sống còn với ngân hàng.

"Harness engineering" chính là kỹ năng thiết kế các thành phần này. Các benchmark như SWE-bench cho thấy: đổi harness (cùng model) thường tạo cách biệt điểm số lớn hơn cả việc nâng đời model. Đầu tư vào harness là đầu tư có đòn bẩy cao nhất.

Giải phẫu một harness

Trước khi code, hãy có mô hình tư duy đúng về vòng đời một lượt agent:

Điểm mấu chốt: model không tự chạy vòng lặp — chính code của bạn (harness) mới đọc stop_reason, thực thi tool, nối kết quả trở lại và quyết định khi nào dừng. Đó là lý do harness là kỹ thuật phần mềm, không phải prompt engineering.

7 kỹ năng cốt lõi khi xây agent

Ba kỹ năng bị xem nhẹ nhất nhưng tạo khác biệt lớn nhất là thiết kế tool, kiểm chứng và eval. Một tool tốt giống một hàm API tốt: rõ ràng, khó dùng sai, báo lỗi giúp người gọi tự sửa. Chi tiết về tool & agent xem Tools & Agents; về guardrail chống prompt injection xem LLMOps — Security & Injection.

Single-agent hay Multi-agent?

Câu hỏi quan trọng nhất — và câu trả lời mặc định là single-agent.

Theo Anthropic công bố (bài Building a multi-agent research system), hệ multi-agent của họ vượt single-agent khoảng ~90% trên bộ eval nghiên cứu nội bộ, nhưng tiêu tốn ~15× token so với một phiên chat thường; và biến số giải thích phần lớn hiệu năng chính là lượng token bỏ ra. Thông điệp rút ra:

• Multi-agent không làm mọi thứ tốt hơn — nó đánh đổi token lấy độ bao phủ/song song.
• Chỉ dùng khi nhiệm vụ chia nhỏ độc lập được (nghiên cứu nhiều nguồn, rà soát nhiều chiều, migrate nhiều file) và giá trị đầu ra biện minh cho chi phí.
• Với tác vụ tuyến tính (một pipeline tuần tự), multi-agent thường chỉ thêm độ trễ và lỗi.

Mẫu kiến trúc multi-agent thực dụng

Mẫu phổ biến và dễ vận hành nhất là orchestrator–worker (điều phối viên fan-out cho các worker chạy song song rồi tổng hợp):

Vài mẫu bổ trợ nên nằm trong "hộp đồ nghề":

• Pipeline: mỗi item đi qua nhiều stage độc lập, không rào chắn giữa các stage → tối ưu thời gian tường (wall-clock).
• Adversarial verify: mỗi phát hiện được N agent cố phản bác; chỉ giữ lại nếu sống sót → diệt kết quả "nghe hợp lý nhưng sai".
• Judge panel: sinh nhiều lời giải từ các góc khác nhau, cho các judge chấm điểm độc lập rồi tổng hợp từ bản thắng.
• Loop-until-dry: với khám phá không biết trước số lượng (tìm bug, rà lỗi), lặp tới khi K vòng liên tiếp không ra gì mới.

Repo & công cụ nên dùng

Chọn theo nhu cầu, đừng chọn theo độ nổi tiếng. Bắt đầu mỏng nhất có thể.

Lời khuyên thực chiến: tự viết vòng lặp trần bằng SDK cho agent đầu tiên (bạn sẽ hiểu tường tận cơ chế), chỉ chuyển sang framework khi độ phức tạp điều phối thực sự vượt sức tự quản. Framework giấu đi vòng lặp — tiện khi bạn đã hiểu, nguy hiểm khi bạn chưa.

Quickstart: dựng agent chạy được ngay

Dưới đây là toàn bộ một harness tối giản nhưng đúng chuẩn — vòng lặp tác tử với một tool. Mã minh hoạ (Python, Anthropic SDK); đây chính là "hạt nhân" mà mọi framework mở rộng ra.

# pip install anthropic
from anthropic import Anthropic

client = Anthropic()  # đọc ANTHROPIC_API_KEY từ môi trường

# 1) Định nghĩa tool: tên rõ, schema chặt, mô tả để MODEL hiểu khi nào dùng
tools = [{
    "name": "run_sql",
    "description": "Chạy MỘT câu SELECT chỉ-đọc trên read-replica kho dữ liệu, trả bảng kết quả.",
    "input_schema": {
        "type": "object",
        "properties": {"query": {"type": "string", "description": "Câu SQL SELECT hợp lệ"}},
        "required": ["query"],
    },
}]

def run_sql(query: str) -> str:
    # Thực thi trên READ-REPLICA + allowlist chỉ SELECT (guardrail an toàn)
    # ... trả về kết quả dạng text; nếu lỗi, trả THÔNG BÁO GIÚP MODEL TỰ SỬA
    return "chi_nhanh | du_no\nHN | 8420\nHCM | 7910"

# 2) Vòng lặp tác tử — chính là HARNESS
messages = [{"role": "user", "content": "Top 5 chi nhánh dư nợ cao nhất, kèm nhận xét ngắn."}]
for _ in range(8):  # ngân sách bước: chống loop vô hạn
    resp = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=2048,
        thinking={"type": "adaptive"},   # để model tự cân nhắc độ sâu suy luận
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})  # giữ nguyên block (kể cả thinking)
    if resp.stop_reason != "tool_use":
        break
    results = []
    for block in resp.content:
        if block.type == "tool_use":
            out = run_sql(**block.input)          # thực thi
            results.append({"type": "tool_result",
                            "tool_use_id": block.id,
                            "content": out})       # quan sát → nối lại
    messages.append({"role": "user", "content": results})

print(resp.content[-1].text)

Ba điều khiến đoạn này là harness thật chứ không phải demo: (1) ngân sách bước chặn loop vô hạn; (2) tool chạy trên read-replica + allowlist SELECT — agent không thể phá dữ liệu; (3) giữ nguyên resp.content khi nối lại để không làm hỏng chuỗi suy luận. Từ hạt nhân này, nâng lên multi-agent chỉ là: cho tool spawn_worker gọi lại chính hàm trên với nhiệm vụ con, rồi orchestrator tổng hợp.

Muốn đưa lên production, bổ sung theo thứ tự ưu tiên: eval bộ test cố định → trace/observability → guardrail injection → nén context. Xem thêm LLM — Production, LLMOps — Đánh giá & chống ảo giác và LLMOps — Tổng quan.

Use case thực tế

Bối cảnh: Khối Dữ liệu NCB cần một "trợ lý phân tích" cho cán bộ nghiệp vụ hỏi số liệu bằng tiếng Việt tự nhiên, thay vì chờ đội DE viết SQL (mỗi yêu cầu trung bình chờ ~1,5 ngày).

Harness single-agent (giai đoạn 1): vòng lặp như trên với 3 tool — run_sql (read-replica, allowlist SELECT), get_schema (trả cấu trúc bảng), make_chart. Guardrail: chặn mọi DDL/DML, giới hạn 10.000 dòng, log toàn bộ query để kiểm toán. Kết quả pilot 4 tuần: ~68% câu hỏi được trả lời tự phục vụ ngay, thời gian chờ từ ~1,5 ngày xuống ~2 phút; các câu còn lại (mơ hồ/nhạy cảm) chuyển human-in-the-loop.

Nâng lên multi-agent (giai đoạn 2) — rà soát báo cáo tháng: một orchestrator fan-out 5 worker, mỗi worker kiểm một chiều (khớp tổng, ngoại lệ, so kỳ trước, quy tắc NHNN, chất lượng dữ liệu — xem Data Quality), rồi một verifier phản biện từng phát hiện. Chi phí token gấp nhiều lần một lượt chat, nhưng bắt được ~3× số sai lệch so với rà soát single-agent nhờ các góc nhìn độc lập — hoàn toàn xứng đáng cho một quy trình kiểm soát rủi ro.

Bài học: bắt đầu bằng single-agent để học miền và dựng eval; chỉ mở multi-agent ở đúng chỗ nhiệm vụ chia được và giá trị cao. Không có bộ eval đo tỉ lệ đúng, đừng đưa agent chạm vào số liệu thật.

Ghi nhớ

• Harness > model. Cùng một model, harness quyết định agent là sản phẩm hay chỉ là demo. Đây là kỹ thuật phần mềm, không phải prompt.
• Vòng lặp do code của bạn điều khiển: đọc stop_reason, thực thi tool, nối kết quả, quyết định dừng.
• 7 kỹ năng cốt lõi: thiết kế tool, context engineering, điều khiển vòng lặp, memory, kiểm chứng, quyền & an toàn, eval & observability. Ba đòn bẩy lớn nhất: tool tốt, verify, eval.
• Mặc định single-agent. Multi-agent đổi nhiều token lấy độ bao phủ/song song (~15× token cho ~90% cải thiện theo Anthropic) — chỉ dùng khi nhiệm vụ chia được và giá trị cao.
• Mẫu multi-agent nền tảng: orchestrator–worker; bổ trợ bằng pipeline, adversarial verify, judge panel, loop-until-dry.
• Repo khởi đầu: anthropic-cookbook + SDK để học vòng lặp trần; lên framework (LangGraph/CrewAI/…) chỉ khi điều phối vượt sức tự quản; luôn kèm eval (promptfoo/inspect_ai) và trace (langfuse/phoenix).
• Ngân hàng: read-replica + allowlist + human-in-the-loop + log kiểm toán là điều kiện tối thiểu trước khi agent chạm số liệu thật.