Agent harness là gì? Ví dụ, flowchart và các harness phổ biến 2026

Năm 2023 mọi người nói prompt engineering. Năm 2025–26, team ship agent thật nói nhiều hơn về harness engineering.

Công thức ngắn:

Agent = Model + Harness

Model sinh token. Harness nối model với thế giới: vòng lặp, tool, quyền, sandbox, context, verify, và chỗ người xen vào (HITL).

Dành cho: apply AI / fullstack — người build chatbox, coding agent, agent nội bộ — không phải researcher train model.

Ý chính: Đổi model mỗi tuần ít khi cứu được agent hỏng. Đổi harness (tools + verify + permissions) mới cứu.

Liên quan: MCP · Skill · Subagent · Learn → AI Roadmap (phase Agents + harness).

---

1 · Harness không phải “framework agent”

Nhiều người nhầm harness với LangChain / LangGraph. Thực tế (kể cả khảo sát source ~11 coding harness sản xuất năm 2026): hầu hết runtime tự viết async loop, ít ai import “agent framework” chung.

Martin Fowler / Thoughtworks gọi phần bạn cấu hình quanh coding agent là outer harness: guides (lái trước) + sensors (sửa sau).

---

2 · Flowchart 1 — vòng đời một bước agent

Đây là xương sống hầu hết coding agent (Claude Code, Cursor, Codex, OpenHands…):

                    ┌─────────────┐
                    │  User goal  │
                    └──────┬──────┘
                           ▼
              ┌────────────────────────┐
              │  Context pack          │
              │  system + rules +      │
              │  skills + file/RAG     │
              └────────────┬───────────┘
                           ▼
 syn ┌──────────────────┐
 │   │  LLM decide      │◄──────────────────────────┐
 │   │  (think / act)   │                           │
 │   └────────┬─────────┘                           │
 │            │                                     │
 │     ┌──────┴──────┐                              │
 │     ▼             ▼                              │
 │  Text reply    Tool call                         │
 │     │             │                              │
 │     │             ▼                              │
 │     │      ┌──────────────┐                      │
 │     │      │  Permission  │──deny──► explain     │
 │     │      │  allowlist   │                      │
 │     │      └──────┬───────┘                      │
 │     │             ▼                              │
 │     │      ┌──────────────┐                      │
 │     │      │  Sandbox /   │                      │
 │     │      │  workspace   │                      │
 │     │      └──────┬───────┘                      │
 │     │             ▼                              │
 │     │      ┌──────────────┐                      │
 │     │      │  Execute     │                      │
 │     │      │  (fs/shell)  │                      │
 │     │      └──────┬───────┘                      │
 │     │             ▼                              │
 │     │      ┌──────────────┐     fail             │
 │     │      │  Verify      │─────────────┐        │
 │     │      │  lint/test   │             │        │
 │     │      └──────┬───────┘             │        │
 │     │          ok │                     ▼        │
 │     │             │              tool result     │
 │     ▼             └───────────────────► append ──┘
 │  Done / HITL ask human
 └──

Đọc flowchart: “Done” không phải model tự tuyên bố xong — verify (test/lint/script) hoặc HITL mới là cổng.

---

3 · Bảy khối harness (bản tối thiểu → bản xịn)

Từ giải phẫu coding harness thực chiến:

Apply AI SME: đủ 1–6. Điểm 7 chỉ khi team hoặc product agent platform.

---

4 · Ví dụ 1 — Support chatbox (không phải coding agent)

Goal: widget trả lời FAQ shop, escalate khi không chắc.

User message
    │
    ▼
[Input guard] ── PII / injection? ──► refuse / sanitize
    │
    ▼
[Retrieve] FAQ chunks (RAG) + order policy
    │
    ▼
[LLM] draft answer + confidence
    │
    ├── confidence thấp ──► [HITL / human queue]
    │
    ▼
[Output guard] no fake price / no legal claim
    │
    ▼
Reply + log trace (Langfuse-style)

Harness ở đây: guard + RAG + HITL + trace — không phải “prompt hay”. Model đổi được; các khối kia là sản phẩm bạn bán.

---

5 · Ví dụ 2 — Mini coding agent (đúng phase Roadmap harness)

Goal: “Sửa bug X trong repo, chạy test rồi mới báo Done.”

Goal: fix failing test auth.spec.ts
    │
    ▼
[Skill: ship-check] nạp playbook
    │
    ▼
Agent: read failing test + source
    │
    ▼
Agent: edit files (allowlist src/** only)
    │
    ▼
Harness hook: pnpm test auth.spec.ts
    │
    ├── fail ──► append output ──► agent retry (max 3)
    │
    ▼
pass → summarize diff → human merge

Không có hook test = agent hay ảo giác Done. Đó là lý do Flo-style diagram luôn vẽ Agent Sandboxes + Evaluation.

---

6 · Guides vs sensors (outer harness)

Theo tư duy Thoughtworks (guides / sensors):

Luật vàng: sensor computational chạy mỗi lần agent sửa file (rẻ). Sensor inferential để PR / nightly (đắt).

Steering loop của người:

1. Agent mắc lỗi lặp →
2. Viết guide ngắn hoặc sensor tự bắt →
3. Lần sau ít cần review tay hơn.

---

7 · Các harness phổ biến hiện nay (2026)

Bảng “dùng cảm nhận sản phẩm”, không phải benchmark lab:

Nhận xét chéo (từ giải phẫu source cộng đồng): skills và MCP đang phổ biến; retrieval trong coding harness thường deterministic (grep/path), không phải nhồi vector mọi thứ.

---

8 · Flowchart 2 — chọn harness nào (apply AI)

Bạn cần gì?
    │
    ├── Sửa code trong repo hàng ngày
    │       └── Cursor hoặc Claude Code / Codex
    │             + outer harness (rules + tests)
    │
    ├── Agent cho khách (chatbox / RAG / tools)
    │       └── Tự build harness mỏng:
    │             allowlist tools + HITL + eval 30 case
    │
    ├── Team corp muốn “ChatGPT nội bộ”
    │       └── Platform (Open WebUI / Dify / custom)
    │             + audit + quota + tool registry
    │
    └── Nghiên cứu / benchmark agent
            └── OpenHands / SWE-agent stack

Đừng clone full diagram Flo (multi-frontier + RL) nếu team = 1 người. Clone pattern: sandbox + tools + eval.

---

9 · Checklist harness tối thiểu (ship tuần này)

Copy vào Notion / HARNESS.md:

1. Goal rõ — 1 câu Done (vd. “test X xanh”).
2. Allowlist tools — read; write src/**; shell chỉ pnpm test / lint.
3. Sandbox — không đụng .env, không rm -rf /.
4. Verify hook — fail test = chưa Done.
5. HITL — merge, deploy, gửi email khách = hỏi người.
6. Trace — log tool call + token (dù chỉ file JSON).
7. Eval nhỏ — 10–30 golden case; chạy lại khi đổi prompt/skill.
8. 1–3 Skills — playbook lặp (review, ship-check, incident).

Đó đúng tinh thần Phase 4–5 trên AI Roadmap của site này.

---

10 · Anti-pattern

1. Chỉ thêm model mạnh hơn khi fail thật ra là thiếu test hook.
2. MCP đầy settings nhưng không có skill/playbook → tay nhiều, não loạn.
3. Trust “agent nói Done” không chạy verify.
4. Sandbox = laptop thật với quyền admin.
5. Eval = cảm giác (“hôm nay trả lời ổn”) — không có golden set.
6. Outer harness 50 trang — agent không đọc hết; guide phải ngắn, sensor phải chạy được.

---

Kết

Harness không phải buzzword thay prompt. Nó là kỷ luật sản phẩm: model không đáng tin một mình; bạn bọc nó bằng quyền, môi trường, và cổng chất lượng.

Nếu chỉ nhớ 3 dòng:

1. Agent = Model + Harness.
2. Done = verify (hoặc HITL), không phải lời model.
3. Outer harness (rules/skills/tests) là chỗ apply AI kiểm soát được khi model đổi hàng tháng.

---

Bước tiếp: mở Roadmap phase “Agents + harness”, làm project mini coding agent + hook test. Một demo repo thuyết phục khách hơn một slide architecture.