Trả lời ngắn: Harness là phần code và quy trình bao quanh model để biến một yêu cầu thành lượt chạy có kiểm soát. Nó cấp dữ liệu/tool, kiểm quyền, lưu tiến độ và quyết định rõ khi nào hoàn tất hoặc dừng.

Đọc xong, bạn sẽ hiểu:

  • Tám lớp cơ bản của một AI harness.
  • Một run đi từ request đến outcome và audit thế nào.
  • Khi nào cần router, MCP hoặc multi-agent.
  • Cách điền Harness Canvas trước khi viết code.

Lưu ý giáo dục: Framework này là bản đồ tư duy, không bảo đảm hệ thống đúng hoặc an toàn. Ví dụ chỉ dùng FAQ và tool giả; production cần kiểm thử, bảo mật, privacy, vận hành và yêu cầu chuyên ngành phù hợp.

1. Framework Harness Engineering là gì? Ghép các mảnh thành một hệ

a. Model là động cơ, harness là hệ vận hành

Từ bài #21 đến #29, bạn đã gặp kiến trúc agent, tool calling, function calling, MCP, routing, multi-agent, guardrail và retry. Harness Engineering ghép các mảnh đó thành lớp vận hành quanh model: nhận việc, chuẩn hóa context, cấp capability, giữ state, kiểm hành động, xử lý lỗi và chứng minh outcome.

Một model giỏi vẫn có thể dùng nhầm tool, mất context, lặp side effect hoặc kết thúc khi chưa đạt yêu cầu. Tương tự, động cơ mạnh không tự tạo đường ray, tín hiệu và phanh. Harness quyết định model được chạy ở đâu, quan sát gì và khi nào phải dừng.

Hình 1 — Tám lớp giúp tách trách nhiệm; không một prompt phải gánh toàn bộ hệ thống.

b. Run và contract là hai đơn vị nền

Run FAQ-01 lưu câu hỏi, nguồn D1, trạng thái VERIFYING, budget 1 tool call và kết quả cuối. Contract của bước retrieve quy định input là query; output là danh sách evidence ID hoặc error.

Một run là phiên xử lý từ request đến outcome, error hoặc stop. Run có ID, user/tenant, policy version, budget, state và trace. Nó không đồng nghĩa một model call; một run có thể gồm nhiều call, tool result và approval.

Contract là quy ước giữa hai phần hệ thống. Công cụ tra đơn nhận order_id, trả trạng thái hoặc mã lỗi, và ghi ai xử lý khi dữ liệu thiếu. Tương tự, bộ định tuyến trả đường đi kèm độ tin cậy; bộ kiểm tra trả kết quả đạt hay lỗi kèm lý do. Quy ước rõ giúp thay AI hoặc công cụ mà không phải viết lại toàn hệ thống.

c. Framework không phải framework phần mềm

Bài này không bắt bạn chọn SDK. Cùng một Harness Canvas có thể triển khai bằng code thuần, workflow engine hoặc agent framework. Công cụ thay đổi nhanh; goal, quyền, state, exit condition và eval vẫn phải trả lời được.

OpenAI mô tả agent qua model, tools và instructions, đồng thời nhấn mạnh mỗi orchestration cần một run loop và exit condition. Họ khuyến nghị bắt đầu single-agent rồi chỉ tăng độ phức tạp khi cần. OpenAI — A practical guide to building AI agents

2. Tám lớp của một AI harness dễ kiểm soát

a. Goal/interface và context

  1. Goal & interface: xác định job, user, input, output, success, non-goal và quyền yêu cầu. “Trả lời FAQ có evidence ID” rõ hơn “hãy hỗ trợ khách hàng”.
  2. Context: chọn system instruction, conversation, retrieval, memory và metadata. Gắn provenance, freshness, token budget; coi web, file và tool output là dữ liệu chưa tin cậy.

Hai lớp này trả lời “làm gì” và “biết gì”. Context nhiều không tự tốt; context đúng, đủ và có nguồn mới giúp model quyết định.

b. Model/routing và tools/MCP

  1. Model & routing: chọn model theo độ khó, cost/latency; router chỉ xuất hiện khi nhiều intent hoặc model cần đường xử lý khác. Có default và fallback, không route vòng.
  2. Tools & MCP: tool công bố capability bằng tên, mô tả, schema và error contract. MCP chuẩn hóa kết nối host–client–server, nhưng host vẫn quản lifecycle, connection permission và security boundary. MCP — Architecture

Capability là khả năng đọc hoặc hành động, không phải quyền tự động. Tool có send_email không có nghĩa mọi user hoặc agent đều được gửi.

c. Orchestration và guardrails

  1. Orchestration: định nghĩa thứ tự, route, handoff, owner, shared state, aggregation và exit condition. Bắt đầu một agent; chỉ thêm workers khi task thực sự chia độc lập.
  2. Guardrails: kiểm input, context, model output, tool parameters và action. Authorization ở ngoài model; hành động high-risk cần approval, least privilege và fail closed.

d. Reliability/state và observability/evals

  1. Reliability & state: timeout, error envelope, retry budget, idempotency, checkpoint, resume, fallback và stop reason. State có schema và một owner cho mỗi artifact.
  2. Observability, evals & human: log/trace/metric cho run; eval đo outcome lẫn đường đi; human nhận escalation với đủ context và evidence.

Nếu thiếu lớp 8 — observability, eval và đường chuyển người — đội chỉ thấy final answer mà không biết run đã đi qua đâu. Họ không thấy model gọi tool nào, tốn bao nhiêu, guardrail block gì hoặc lỗi tập trung ở route nào.

3. Một run đi xuyên harness như thế nào?

a. Lifecycle chín bước

Với FAQ assistant giả, một run có thể đi qua:

  1. Request: nhận câu hỏi và run ID.
  2. Validate: kiểm schema, scope và quyền.
  3. Context: retrieve D1–D4, gắn evidence ID.
  4. Decide: model chọn trả lời hoặc hỏi lại.
  5. Tool: gọi capability read-only nếu cần.
  6. Observe: chuẩn hóa result/error vào state.
  7. Verify: kiểm schema, citation và policy.
  8. Outcome: trả answer, partial, escalate hoặc stop.
  9. Audit: ghi trace tối thiểu, metric và eval sample.

Hình 2 — Lifecycle có cổng verify, approval và error/stop; không phải đường thẳng luôn thành công.

b. Nhánh approval và error

Nếu assistant chỉ trả text có evidence, risk thấp. Nếu sau này có tool sửa ticket, action gate phải kiểm user, resource, reversibility và approval. Guardrail block hoặc permission fail đi thẳng stop/escalate, không retry như lỗi mạng.

Nếu retrieval timeout, reliability layer áp retry budget. Nếu output thiếu evidence ID, repair một lần rồi validate lại. Mọi nhánh cập nhật state và reason; không để model tự tuyên bố thành công.

c. Done rule phải đo được

Done không phải “model nói đã xong”. Run chỉ done khi output đúng schema, mỗi claim được nguồn tương ứng hỗ trợ, evidence ID tồn tại, policy pass và không vượt budget. Không tìm thấy nguồn thì outcome hợp lệ là unknown, không bịa cho đủ.

Mỗi layer nên có owner: content team sở hữu policy, platform team sở hữu tool contract, product sở hữu success metric, security sở hữu control, operations sở hữu incident path. Owner mơ hồ khiến lỗi rơi giữa các nhóm.

4. Chọn độ phức tạp và tránh over-engineering

a. Complexity ladder bốn mức

  • Mức 0 — Deterministic: rule, template, search; không cần model quyết workflow.
  • Mức 1 — Single call/structured output: model chuyển đổi hoặc phân loại, không tool loop.
  • Mức 2 — Single agent + tools: một run loop, vài capability rõ, guardrail và state.
  • Mức 3 — Router/multi-agent: nhiều domain hoặc subtask độc lập, có handoff và aggregation.

Chọn mức thấp nhất đạt eval. Anthropic cũng phân biệt workflow định trước với agent tự quyết và khuyên tìm giải pháp đơn giản, composable trước khi thêm autonomy. Anthropic — Building effective agents

b. Bốn dấu hiệu đang xây quá tay

  • Có router nhưng chỉ một route thật sự hoạt động.
  • Có nhiều agent chỉ đổi tên prompt, cùng context và cùng tool.
  • Dùng MCP cho một function nội bộ cố định nhưng không cần boundary/reuse.
  • Có memory dài hạn trước khi có schema, retention và eval retrieval.

Mỗi lớp mới thêm latency, cost, failure mode và công sức quan sát. Sơ đồ đẹp không phải bằng chứng cần kiến trúc phức tạp.

c. Gate để nâng một mức

Chỉ nâng mức khi baseline không đạt target và biết nguyên nhân. Router cần confusion matrix theo intent; multi-agent cần chứng minh task độc lập và lợi ích vượt coordination cost; memory cần test recall/precision; action tool cần threat model và approval path.

Ghi decision record: vấn đề, bằng chứng eval, thay đổi, metric kỳ vọng và rollback. Nếu metric không cải thiện, quay lại mức đơn giản hơn.

5. Bài tập 20 phút: điền Harness Canvas

a. Case FAQ giả

Dùng bốn đoạn D1–D4 và 10 câu hỏi mẫu bên dưới; hai câu cố ý không có nguồn. Chạy bằng giấy rồi đối chiếu expected evidence IDs/unknown. Assistant chỉ dùng retrieve_fake_docs, không web, account hoặc API thật. Mục tiêu: answer ngắn, claim có evidence ID; thiếu nguồn thì nói unknown.

b. Mẫu đối chiếu: Harness Canvas đã điền

Lớp Mẫu điền
Goal/I-O FAQ có evidence; JSON answer, evidence_ids
Context Chỉ D1–D4, mỗi đoạn có ID và version
Model/router Một model; chưa có bằng chứng cần router
Tools/MCP retrieve_fake_docs, read-only; chưa cần MCP
Orchestration Retrieve → answer → verify → stop
Guardrails Scope-only; no source thì unknown
Reliability/state 1 schema repair; run ID, budget, stop reason
Eval/human 10 câu; owner duyệt claim thiếu evidence

Hình 3 — Canvas một trang buộc mỗi capability gắn với contract, control, bằng chứng và owner.

c. Acceptance gate trước code

Bạn chỉ chuyển sang prototype khi trả lời được: success đo bằng gì, source nào được dùng, tool nào được phép, error nào retry, ai duyệt unknown/high-risk, run dừng khi nào và log nào chứng minh outcome.

Sau đó xây Mức 0 hoặc 1 trước. Chạy mười eval cases, ghi failure taxonomy rồi mới quyết định có cần tool loop, router hay multi-agent.

6. Tổng kết Phase 3: model là động cơ, harness là hệ vận hành

a. Năm ý chính

  • Harness Engineering thiết kế hệ vận hành quanh model, không chỉ viết prompt.
  • Tám lớp tách goal/context, model/routing, tools/MCP, orchestration, guardrails, reliability/state và eval/operations.
  • Một run cần contract, state, budget, exit condition, audit và owner.
  • Chọn complexity thấp nhất đạt eval; chỉ thêm router/multi-agent khi có bằng chứng.
  • Harness Canvas giúp thiết kế control và acceptance gate trước code.

b. Câu hỏi tự kiểm tra

  • Model khác harness ở đâu?
  • MCP có tự cấp quyền tool cho model không?
  • Khi nào nên thêm router hoặc multi-agent?
  • Done rule của FAQ assistant là gì?

c. Gợi ý đáp án

Xem gợi ý câu 1Model tạo quyết định; harness cấp context/tool, kiểm quyền, state, lỗi, outcome và vận hành run. → Xem mục 1.
Xem gợi ý câu 2Không. MCP công bố/trao đổi capability; host và hệ authorization vẫn quyết quyền. → Xem mục 2.
Xem gợi ý câu 3Khi baseline thấp hơn target và eval chỉ ra intent/subtask thật sự cần tách. → Xem mục 4.
Xem gợi ý câu 4Output đúng schema, claim có evidence, policy pass, trong budget; thiếu nguồn trả unknown. → Xem mục 3.

d. Thuật ngữ cần nhớ

Thuật ngữ Giải thích ngắn
Harness Engineering Thiết kế lớp vận hành quanh model.
Run Một phiên từ request đến outcome/stop.
Contract Quy ước input, output, quyền, lỗi và owner.
Orchestration Điều phối route, bước, handoff và exit.
Capability Khả năng data/action do tool công bố.
State Trạng thái có schema của run.
Observability Log, trace và metric của hành vi hệ.
Eval Bộ thử đo outcome và đường đi.
Complexity ladder Mức deterministic đến multi-agent.
Harness Canvas Bản thiết kế một trang cho hệ.

e. Nguồn tham khảo

f. Học tiếp gì?

Xem lại Error Handling & Retry #29 nếu chưa rõ failure contract và retry budget. Bài tiếp theo mở PHASE 4 — AGENTIC LOOP với Agentic AI là gì? #31: khi nào model thật sự tự điều khiển nhiều bước thay vì chỉ chạy một workflow cố định?

Nhắc lại giáo dục: Harness là hệ thống sống; phải tiếp tục eval, monitor, review quyền và học từ incident sau khi phát hành.