# Bản đồ agent harness: AI agent thật sự hoạt động thế nào

[Systems, Mapped](https://homus.dev/speakers/systems-mapped) · [Systems, Mapped](https://homus.dev/orgs/systems-mapped)

> Vẽ agent harness thành bản đồ: loop, tools, context engineering, subagents, skills, sandbox, agent chạy dài, build một harness 150 dòng Python và cách đo.

Topics: Agents, Coding Agents, Context Engineering

Canonical: https://homus.dev/talks/agent-harnesses-mapped-how-ai-agents-actually-work

## 1. Tấm bản đồ hôm nay: agent harness

Người dẫn mở đầu bằng ý tưởng lấy một khái niệm trong software engineering và vẽ nó thành một tấm bản đồ. Tấm bản đồ lần này là agent harness (video đăng ngày 11/10/2026).

Người dẫn giải thích, theo video đăng ngày 11/10/2026: các coding agent như Claude Code, Codex và Cursor được làm từ hai thứ. Thứ nhất là một AI model. Thứ hai là phần software bọc quanh model, phần cho phép model đọc file, chạy lệnh và tiếp tục làm việc cho tới khi xong việc. Phần software đó chính là harness, và đó là chủ đề của cả video.

Đối tượng là các developer đang dùng coding agent và muốn biết bên trong thật sự đang diễn ra chuyện gì, hoặc những người muốn tự build một cái. Người xem không cần nền tảng machine learning nào cả (video đăng ngày 11/10/2026).

Rồi người dẫn trình bày lộ trình. Trước hết là harness thật ra là gì, và nó khác framework ở chỗ nào. Tiếp theo là các bộ phận cốt lõi của nó: loop, tools, context, planning và safety. Sau đó là những agent chạy hàng giờ hoặc hàng ngày. Cuối cùng, người dẫn sẽ build một harness từ đầu, đi một vòng qua các lựa chọn mã nguồn mở, và học cách đo xem một harness có tốt hay không. Nhưng trước hết là câu hỏi: vì sao harness lại quan trọng đến thế (video đăng ngày 11/10/2026)?

Lộ trình người dẫn đưa ra ở đầu video, vẽ lại thành một tuyến tàu theo đúng thứ tự các phần sẽ đi qua.

## 2. Cùng một model, hai kết quả khác nhau

Người dẫn nói có một điều kỳ lạ về AI agent. Lấy một model, cùng bộ weight, cùng giá mỗi token. Đặt nó vào hai chương trình khác nhau và giao cho cả hai cùng một coding task. Một bên làm xong. Bên kia đi lạc, chạy vòng vòng, rồi bỏ cuộc (video đăng ngày 11/10/2026).

![Hai vòng tròn harness quanh cùng một model: Program A về đích Task done, Program B dừng ở Stalled](https://homus.dev/photos/VhTtnolEiSw-0143.jpg)

Program A và Program B dùng cùng một model, chỉ khác phần harness bao quanh (khung đứt nét màu cam): một bên tới "Task done", bên kia "Stalled". Bên dưới là các ví dụ người dẫn nêu trong video đăng ngày 11/10/2026: Claude Code, Codex, Cursor và "any coding agent".

Theo người dẫn, chuyện này không phải giả định. Theo video đăng ngày 11/10/2026, trong năm 2026, trước khi video ra, LangChain đã đưa coding agent của họ từ khoảng hạng 30 lên top 5 trên một benchmark tên là Terminal-Bench. Họ không đổi model chút nào. Họ đổi mọi thứ xung quanh model. Một workshop paper tại ICML năm 2026 cũng đi tới cùng kết luận đó: phần code bao quanh model quan trọng xấp xỉ bằng chính model.

Phần code đó có một cái tên: agent harness. Người dẫn nói rằng nếu bạn đã dùng Claude Code, Codex, Cursor hay bất kỳ coding agent nào khác, bạn đã dùng một harness. Và một khi nhìn thấy các bộ phận của nó, bạn có thể tinh chỉnh nó, sửa nó, hoặc build cái của riêng mình. Vậy thì bắt đầu vẽ bản đồ (video đăng ngày 11/10/2026).

## 3. Model không phải là agent

Bắt đầu từ việc một model thật ra là gì. Theo người dẫn (video đăng ngày 11/10/2026), một large language model là một hàm số: text đi vào, text đi ra. Nó không có bộ nhớ giữa các lần gọi. Nó không mở được file, không chạy được lệnh, không xem được giờ. Mỗi lần gọi nó, bạn gửi cho nó mọi thứ nó cần biết, và nó gửi lại một câu trả lời. Rồi nó quên sạch.

Vậy làm sao thứ đó trở thành một cái gì đó sửa được bug trong repo của bạn? Người dẫn dẫn lại định nghĩa mà theo lời người dẫn là gọn gàng nhất, của Simon Willison: một agent là một model chạy tools trong một vòng lặp để đạt một mục tiêu. Ba ý: tools, một loop, và một goal (video đăng ngày 11/10/2026).

Model không tự làm được việc nào trong ba việc đó. Nó chỉ có thể yêu cầu. Phải có một thứ khác chạy vòng lặp, thực thi tools, và theo dõi xem mình đang ở đâu. Thứ đó chính là harness. Agent bằng model cộng harness (video đăng ngày 11/10/2026).

LangChain nói thẳng: nếu bạn không phải là model, bạn là harness. Các prompt, các tool, bộ nhớ, các bước kiểm tra an toàn, phần code quyết định khi nào dừng. Tất cả đều là harness (video đăng ngày 11/10/2026).

![Phép so sánh của Philipp Schmid: Model là CPU, Context window là RAM, Harness là hệ điều hành, Agent là ứng dụng](https://homus.dev/photos/VhTtnolEiSw-0303.jpg)

Phép so sánh của Philipp Schmid trên màn hình: Model là CPU (sức xử lý thô), Context window là RAM (nhanh, nhỏ, bị xoá mỗi lần), Harness là hệ điều hành (quyết định cái gì được nạp, được chạy, được chạm vào ổ đĩa), Agent là ứng dụng bạn thật sự dùng.

Philipp Schmid dùng một phép so sánh với máy tính mà người dẫn khuyên nên giữ trong đầu suốt phần còn lại của video. Model là CPU, sức xử lý thô. Context window là RAM: nhanh, nhỏ, và bị xoá mỗi lần. Harness là hệ điều hành: nó quyết định cái gì được nạp vào bộ nhớ, cái gì được chạy, và cái gì được phép chạm vào ổ đĩa. Còn agent là ứng dụng mà bạn thật sự sử dụng (video đăng ngày 11/10/2026).

Trên tấm bản đồ, model chỉ là một ga duy nhất. Mọi thứ khác được vẽ trong video, mọi tuyến và mọi ga khác, đều là harness (video đăng ngày 11/10/2026).

## 4. Harness, framework và runtime

Trước khi đi vào bên trong, người dẫn dành một chút cho chuyện tên gọi, vì lĩnh vực này có rất nhiều cái tên chồng lên nhau. Harrison Chase của LangChain đã vẽ một bức tranh ba tầng hữu ích, và người dẫn vẽ lại nó thành ba tuyến (video đăng ngày 11/10/2026).

Dưới cùng là **runtime**. Việc của nó là giữ cho agent sống: lưu trạng thái, chạy tiếp sau khi crash, stream output, và tạm dừng để chờ một con người. LangGraph và Temporal nằm ở tầng này. Một runtime không quan tâm agent của bạn làm gì. Nó chỉ quan tâm agent tiếp tục chạy (video đăng ngày 11/10/2026).

Ở giữa là **framework**. Nó cho bạn các khối xây dựng: một cách gọi model, định nghĩa tool, và kết nối các agent với nhau. LangChain, OpenAI Agents SDK, Google ADK và CrewAI nằm ở đây. Một framework đưa bạn các bộ phận, nhưng bạn vẫn là người quyết định chúng khớp với nhau thế nào (video đăng ngày 11/10/2026).

![Ba tuyến Harness, Framework, Runtime; tuyến Harness sáng lên với Deep Agents và Claude Agent SDK](https://homus.dev/photos/VhTtnolEiSw-0403.jpg)

Ba tầng vẽ thành ba tuyến: Runtime (LangGraph, Temporal, "keeps the agent alive"), Framework (LangChain, OpenAI Agents SDK, Google ADK, CrewAI, "gives you the parts"), và Harness, nơi Deep Agents và Claude Agent SDK được đánh dấu là "harnesses you build on". Cách xếp tầng theo video đăng ngày 11/10/2026.

Trên cùng là **harness**. Nó là loại "batteries included": các prompt, tools, planning, một file system và việc quản lý context đều đã được quyết định sẵn cho bạn. Theo cách xếp của người dẫn (video đăng ngày 11/10/2026), Deep Agents của LangChain và Claude Agent SDK của Anthropic là những harness để bạn build lên trên. Claude Code, Codex và Gemini CLI là những harness có thêm một giao diện người dùng ở trên.

Người dẫn kể rằng Anthropic thật ra đã đổi tên Claude Code SDK thành Claude Agent SDK vì chính lý do này: harness bên trong Claude Code hoá ra hữu ích để build bất kỳ agent nào (theo video đăng ngày 11/10/2026).

Bản thân Chase nói ranh giới giữa các tầng là mờ, và người dẫn cho rằng ông nói đúng. Một quy tắc ngón tay cái hữu ích: nếu nó quyết định agent của bạn hành xử thế nào theo mặc định, nó là một phần của harness (video đăng ngày 11/10/2026).

Còn một phân biệt nữa, của Birgitta Böckeler trên trang của Martin Fowler. Có harness đi kèm sẵn với công cụ, như system prompt và các tool có sẵn. Và có harness mà bạn build quanh nó: các file quy tắc của bạn, test của bạn, linter của bạn. Khi người ta nói "harness engineering", họ thường muốn nói tới loại thứ hai. Video này nói về cả hai (video đăng ngày 11/10/2026).

## 5. Agent loop: trái tim của mọi harness

Ở trung tâm của mọi harness là một vòng lặp. Trên bản đồ, đó là tuyến vòng tròn màu đỏ, và theo người dẫn (video đăng ngày 11/10/2026), mọi agent bạn từng dùng đều đang chạy một phiên bản nào đó của nó. Người dẫn viết nó ra một lần, thật chậm.

Bạn gõ một yêu cầu. Harness không chỉ gửi mỗi câu chữ của bạn tới model. Nó dựng một prompt: một system prompt chứa các chỉ dẫn của nó, các quy tắc về những gì được phép, file chỉ dẫn của project bạn, thông tin về môi trường như thư mục làm việc hiện tại của bạn, định nghĩa của mọi tool mà model được dùng, rồi tới cuộc hội thoại tính đến lúc đó, kết thúc bằng tin nhắn của bạn (video đăng ngày 11/10/2026).

![Ga Build prompt trên vòng Agent loop, với các thành phần của prompt: Your message, History, Tool definitions, Environment, AGENTS.md, Rules, System prompt](https://homus.dev/photos/VhTtnolEiSw-0523.jpg)

Ga "Build prompt": khối Instructions (System prompt, AGENTS.md, Your task) đổ vào vòng "Agent loop, repeats until no tool call". Phía trên là các lớp của prompt: System prompt, Rules, AGENTS.md, Environment, Tool definitions, History và Your message. Mô tả loop theo video đăng ngày 11/10/2026.

Sau đó harness gọi model. Nhớ rằng model chỉ là text vào, text ra. Nhưng theo người dẫn (video đăng ngày 11/10/2026), các model thời nay được train để trả lời theo một cách đặc biệt khi chúng muốn hành động. Thay vì text thường, chúng trả về một tool call: một yêu cầu có cấu trúc, gồm tên tool và các tham số của nó.

Ví dụ, model có thể nói: gọi `read_file` với path là `app.js`. Model chưa đọc gì cả, nó mới chỉ yêu cầu. Một câu trả lời thậm chí có thể chứa nhiều tool call cùng lúc (video đăng ngày 11/10/2026).

Đến lúc này harness tiếp quản. Nó kiểm tra xem lời gọi đó có được phép không, chạy tool, và ghi lại output. Nếu tool lỗi, thì thông báo lỗi trở thành output. Người dẫn nhấn mạnh điều này quan trọng và sẽ quay lại nó sau. Kết quả được đưa trở lại cuộc hội thoại, ghép với đúng lời gọi đã yêu cầu nó thông qua một ID. Rồi, không cần chờ bạn, harness gọi model lần nữa với lịch sử dài hơn. Model đọc kết quả và quyết định bước tiếp theo: một tool call khác, hoặc một câu trả lời (video đăng ngày 11/10/2026).

Đọc một file, tìm một hàm, sửa nó, chạy test, đọc lỗi test, sửa lại. Mỗi vòng là một lần gọi model. Vòng lặp kết thúc khi model trả lời bằng text thường mà không có tool call nào. Đó là tín hiệu cho thấy model nghĩ nó đã xong (video đăng ngày 11/10/2026).

Theo người dẫn (video đăng ngày 11/10/2026), một harness tốt còn có phanh của riêng nó: số bước tối đa, một ngân sách, và cách xử lý lỗi cũng như các lần model từ chối, để một model đang bối rối không thể quay vòng mãi mãi.

Thêm một chi tiết mà người dẫn nói là rất quan trọng trong thực tế. Lịch sử chỉ dài thêm ở phía cuối. Mọi thứ phía trước giữ nguyên y hệt từ lần gọi này sang lần gọi sau. Điều đó cho phép nhà cung cấp model cache phần đầu của prompt, nên mỗi vòng mới rẻ hơn và nhanh hơn (theo video đăng ngày 11/10/2026). Người dẫn dặn hãy nhớ điều này, vì nó định hình rất nhiều quyết định thiết kế harness.

## 6. Tools: cách model chạm vào thế giới

Tools là cách model chạm vào thế giới, nên người dẫn nhìn cận cảnh một tool. Một tool có bốn phần: một cái tên, một đoạn mô tả, một schema cho input, và hàm thật sự được chạy (video đăng ngày 11/10/2026).

Điểm bất ngờ là model không bao giờ nhìn thấy hàm đó. Nó chỉ thấy tên, mô tả và schema. Theo người dẫn (video đăng ngày 11/10/2026), ba thứ đó là toàn bộ giao diện người dùng mà model có.

![Thẻ A tool với name read_file, description, input schema path string, và function mà model không bao giờ thấy](https://homus.dev/photos/VhTtnolEiSw-0723.jpg)

Thẻ "A tool": name `read_file`, description, input schema `{ "path": string }` nằm trong vùng "the model sees"; phần function `def read_file(path): ...` nằm trong khung "the model never sees". Đoạn mô tả đang được viết lại thành "Read a UTF-8 text file. Use before editing.", kèm lời khuyên "explain it like you would to a new hire" (video đăng ngày 11/10/2026).

Lời khuyên của Anthropic là viết mô tả tool theo cách bạn giải thích công cụ đó cho một nhân viên mới. Nói nó làm gì, khi nào nên dùng, và các input có nghĩa là gì. Dùng tên tham số rõ ràng. Theo người dẫn, một chỗ mơ hồ mà con người sẽ nhún vai bỏ qua lại biến thành một phỏng đoán sai với model (video đăng ngày 11/10/2026).

Khi một tool lỗi, harness không nên crash. Nó gửi lỗi về cho model như kết quả của tool và đánh dấu đó là lỗi. Một thông báo lỗi tốt thì cụ thể và nói cho model biết nên làm gì tiếp theo. Theo người dẫn (video đăng ngày 11/10/2026), các model giỏi bất ngờ ở việc đọc một thông báo lỗi và tự sửa ở lần thử kế tiếp. Trên màn hình là ví dụ "Error: no such file src/app.js" kèm gợi ý "Did you mean app.js?", với ghi chú `is_error: true` rồi model tự sửa.

Nhiều tool hơn không có nghĩa là tốt hơn. Mỗi định nghĩa tool chiếm chỗ trong prompt, và các tool chồng chéo nhau làm model bối rối không biết chọn cái nào. Philipp Schmid ghi lại rằng Vercel đã bỏ 80% số tool của agent của họ và được ít bước hơn, phản hồi nhanh hơn (người dẫn dẫn lại trong video đăng ngày 11/10/2026). Ít tool hơn, mỗi tool một việc rõ ràng.

Điều tương tự áp dụng cho những gì tool trả về. Hãy đưa cho model kết quả nhiều tín hiệu: phân trang, lọc, cắt bớt, và khi cắt bớt thì nói cho model biết cách xin ít dữ liệu hơn. Anthropic cũng khuyên làm cho lỗi khó xảy ra: khi đường dẫn file tương đối liên tục gây lỗi, họ đổi tool để bắt buộc dùng đường dẫn tuyệt đối (theo người dẫn, video đăng ngày 11/10/2026).

Còn có một lựa chọn cấp tiến hơn. Theo người dẫn (video đăng ngày 11/10/2026), project mini-swe-agent chỉ đưa cho model đúng một tool: một bash shell. Mọi thứ, từ đọc file, sửa file đến chạy test, đều diễn ra qua lệnh shell. Phần code agent của nó khoảng 100 dòng, và nó làm tốt trên các coding benchmark thật.

Cuối cùng, tools không nhất thiết phải nằm bên trong harness. Model Context Protocol, MCP, là một chuẩn để cắm các tool bên ngoài vào bất kỳ harness nào: issue tracker của bạn, một database, một trình duyệt. Theo người dẫn (video đăng ngày 11/10/2026), MCP được quản lý bởi Agentic AI Foundation thuộc Linux Foundation, và gần như mọi harness được nhắc tới trong video đều hỗ trợ nó.

## 7. Context engineering: quyết định model nhìn thấy gì

Mỗi vòng của loop gửi toàn bộ lịch sử trở lại cho model. Lịch sử đó nằm trong context window, tức mọi thứ model có thể nhìn thấy ở lần gọi này. Context window có một giới hạn cứng, và theo người dẫn (video đăng ngày 11/10/2026), từ rất lâu trước khi chạm tới giới hạn đó đã có một vấn đề mềm hơn.

Anthropic mô tả context window như một "attention budget": càng nhồi nhiều token vào, model càng khó dùng tốt từng token một. Một số người gọi hiện tượng này là context rot. Người dẫn nói: một context lộn xộn làm một model thông minh hành xử ngớ ngẩn (video đăng ngày 11/10/2026). Vì vậy, một phần lớn công việc của harness là quyết định cái gì được đưa vào window và cái gì phải ở ngoài. Đó là context engineering.

Người dẫn đưa ra năm kỹ thuật chính, theo video đăng ngày 11/10/2026:

- **Giới hạn output của tool.** Một lệnh duy nhất có thể in ra hàng nghìn dòng. Theo người dẫn và màn hình (video đăng ngày 11/10/2026), Claude Code mặc định giới hạn phản hồi của tool ở 25.000 token. Phần còn lại bị cắt, kèm một ghi chú nói rằng nó đã bị cắt.

- **Dọn kết quả tool cũ.** Khi model đã dùng xong nội dung một file, toàn bộ văn bản đó không cần ở lại mãi (theo video đăng ngày 11/10/2026). Harness có thể thay nó bằng một placeholder ngắn.

- **Compaction.** Khi context gần đầy, harness yêu cầu model tóm tắt cuộc hội thoại tới lúc đó: mục tiêu, các quyết định, những gì đã xong và những gì còn lại. Rồi nó mở một window mới chỉ với bản tóm tắt đó. Theo người dẫn (video đăng ngày 11/10/2026), đây là mẹo phổ biến nhất trong các phiên dài, và cũng rủi ro nhất, vì bất cứ thứ gì bản tóm tắt bỏ sót là mất luôn.

- **Just-in-time retrieval.** Thay vì nhồi nguyên file vào prompt ngay từ đầu, giữ các tham chiếu nhẹ như đường dẫn file, và để agent tự nạp thứ nó cần bằng các tool search và read khi cần. Theo người dẫn (video đăng ngày 11/10/2026), đây là cách các coding agent khám phá những repo lớn mà không bị chìm.

- **Bộ nhớ bên ngoài window.** Agent ghi chú vào file, một danh sách to-do, một progress log, rồi đọc lại sau (theo video đăng ngày 11/10/2026). Context window là RAM, file system là ổ đĩa.

![Context window đầy các khối call và result, dòng chữ Claude Code caps tool responses at 25,000 tokens by default, và năm kỹ thuật](https://homus.dev/photos/VhTtnolEiSw-0943.jpg)

Kỹ thuật thứ nhất, "Cap output": dòng "Claude Code caps tool responses at 25,000 tokens by default" (theo video đăng ngày 11/10/2026), một nhãn "first 200 lines + truncated", và context window đầy các khối call/result trước vạch "hard limit". Bên dưới là năm kỹ thuật: Cap output, Clear old results, Compact, Just in time, Memory files.

File chỉ dẫn, như `AGENTS.md` hay `CLAUDE.md`, theo người dẫn hoạt động tốt khi nó là một tấm bản đồ ngắn. Người dẫn kể OpenAI giữ file của họ ở khoảng 100 dòng, trỏ tới các tài liệu sâu hơn thay vì chứa mọi thứ (theo video đăng ngày 11/10/2026).

Một bài học cuối từ đội làm Manus, theo người dẫn (video đăng ngày 11/10/2026) và blog của Manus (đọc ngày 26/10/2026). Agent của họ đọc khoảng 100 token cho mỗi token nó viết ra, nên chi phí input là tất cả, và input được cache rẻ hơn 10 lần đối với họ (theo video đăng ngày 11/10/2026). Để giữ cho cache hoạt động: giữ phần đầu prompt ổn định, chỉ append, không bao giờ sửa các tin nhắn cũ, và không thêm hay bớt tool giữa chừng một task. Theo người dẫn, họ đã build lại agent framework của mình bốn lần để học những bài học như thế này.

## 8. Plans, subagents và skills

Với các task dài, theo người dẫn (video đăng ngày 11/10/2026), model bị trôi. Chúng giải phần thú vị rồi quên phần còn lại. Cách sửa đơn giản là một planning tool: model viết ra một danh sách to-do và cập nhật nó trong lúc làm.

Nghe thì tầm thường, nhưng đội làm Manus giải thích vì sao nó có tác dụng: mỗi lần model viết lại danh sách, mục tiêu được dời xuống cuối context, đúng chỗ mà sự chú ý của model mạnh nhất. Bản plan liên tục tự nhắc lại chính nó. Trên màn hình là một file `todo.md` với bốn mục "find the bug", "write a test", "fix it", "run all tests", kèm dòng "Each rewrite puts the goal at the end of the context, where the model pays most attention" (video đăng ngày 11/10/2026).

Ý thứ hai là subagent. Giả sử agent cần tìm xem việc xác thực (authentication) diễn ra ở đâu trong một codebase lớn. Việc tìm đó có thể phải đọc hàng chục file. Nếu tất cả diễn ra trong context chính, window sẽ đầy rác. Thay vào đó, harness khởi động một subagent: một agent mới với context window sạch của riêng nó. Nó làm phần khám phá lộn xộn và chỉ trả về một bản tóm tắt ngắn, theo người dẫn thường khoảng một hoặc hai nghìn token (video đăng ngày 11/10/2026).

Agent chính có được câu trả lời mà không phải gánh mớ lộn xộn. Theo người dẫn (video đăng ngày 11/10/2026), subagent cũng có thể chạy song song, làm cho việc nghiên cứu rộng hoặc các task nhiều phần nhanh hơn nhiều. Cái giá là chúng không chia sẻ bộ nhớ với nhau, nên agent chính phải đưa cho mỗi subagent một bản brief rõ ràng, đầy đủ.

Ý thứ ba là skills. Theo người dẫn (video đăng ngày 11/10/2026), một skill là một folder chứa chỉ dẫn, và đôi khi cả script, cho một loại task: làm một bảng tính, làm theo checklist review của một team, deploy một service. Lúc bắt đầu, harness chỉ nạp tên và một dòng mô tả của từng skill.

![Danh sách skill spreadsheets, code-review, deploy, brand-voice, data-report, với SKILL.md của spreadsheets mở ra](https://homus.dev/photos/VhTtnolEiSw-1243.jpg)

"Skills: only the name and one line load up front": năm skill ví dụ (spreadsheets, code-review, deploy, brand-voice, data-report), mỗi skill chỉ có tên và một dòng. Skill spreadsheets được mở ra thành `SKILL.md` với ba bước "Read the template", "Fill the rows", "Check the formulas" cộng thư mục `scripts/`. Cách nạp theo mô tả trong video đăng ngày 11/10/2026.

Phần chỉ dẫn đầy đủ chỉ được nạp khi task cần tới. Cách này gọi là progressive disclosure, và theo người dẫn (video đăng ngày 11/10/2026), nó cho phép một agent biết về hàng trăm khả năng mà không phải trả giá cho tất cả chúng trong mọi prompt.

Theo người dẫn (video đăng ngày 11/10/2026), Agent Skills bắt đầu từ Anthropic rồi trở thành một chuẩn mở, được nhiều harness hỗ trợ, trong đó có Codex, Gemini CLI, OpenCode và goose; tuyến "Agent Skills: an open standard" trên màn hình còn có thêm Copilot và Cursor. Mẹo tương tự cũng được dùng cho các tool MCP: nạp tên trước, và chỉ nạp định nghĩa đầy đủ khi cần.

## 9. Permissions, sandbox và prompt injection

Một agent chạy được lệnh shell trên máy bạn thì cũng có thể xoá file của bạn, làm lộ key của bạn, hoặc push lên production. Vì vậy, theo người dẫn (video đăng ngày 11/10/2026), mọi harness nghiêm túc đều đặt các lớp kiểm soát giữa yêu cầu của model và thế giới thật.

Lớp kiểm soát thứ nhất là permissions. Harness có thể hỏi bạn trước mọi hành động, cho phép một danh sách lệnh an toàn như chạy test hay đọc file, hoặc chạy tự do. Theo người dẫn (video đăng ngày 11/10/2026), các harness tốt còn tạo checkpoint để bạn có thể tua lại nếu agent đi sai.

Lớp kiểm soát thứ hai là sandbox. Các lệnh của agent chạy trong một không gian cách ly. Nó chỉ được ghi bên trong folder project của bạn và chỉ được truy cập các website đã được duyệt. Theo người dẫn (video đăng ngày 11/10/2026), Claude Code dựng lớp này trên các tính năng của hệ điều hành: bubblewrap trên Linux và Seatbelt trên macOS.

![Agent đi qua đèn Permission check vào Sandbox gồm project folder, run tests, approved sites; ~/.ssh và unknown-site.com nằm ngoài; ô 84% fewer permission prompts](https://homus.dev/photos/VhTtnolEiSw-1403.jpg)

Agent đi qua đèn tín hiệu "Permission check" vào Sandbox chỉ gồm project folder, run tests và approved sites; `~/.ssh` và unknown-site.com nằm ngoài hàng rào. Góc trái là "Credentials, kept outside the sandbox", góc phải là con số "84% fewer permission prompts", dòng dưới ghi "bubblewrap on Linux, Seatbelt on macOS" (video đăng ngày 11/10/2026).

Theo người dẫn (video đăng ngày 11/10/2026) và bài viết của Anthropic về sandboxing trong Claude Code (đọc ngày 26/10/2026), Anthropic thấy sandbox làm giảm 84% số lần hỏi xin quyền, vì bên trong hàng rào thì ít hành động hơn hẳn cần một con người duyệt. Theo người dẫn (video đăng ngày 11/10/2026), một số harness còn đi xa hơn: giữ credentials hoàn toàn bên ngoài sandbox, để ngay cả một agent đã bị chiếm quyền cũng không đọc được chúng.

Giờ tới vấn đề mà người dẫn gọi là khó nhất: prompt injection. Tools mang text từ bên ngoài vào context: một trang web, một README, một comment trong issue. Text đó có thể chứa chỉ dẫn do kẻ tấn công viết. Model đọc nó và có thể làm theo, vì với một model, chỉ dẫn và dữ liệu đều chỉ là text (theo video đăng ngày 11/10/2026).

Simon Willison gọi tổ hợp nguy hiểm này là "lethal trifecta": một agent có quyền truy cập dữ liệu riêng tư, tiếp xúc với nội dung không đáng tin, và có một đường để gửi dữ liệu ra ngoài. Có đủ cả ba, kẻ tấn công có thể đánh cắp dữ liệu của bạn (video đăng ngày 11/10/2026).

Theo người dẫn (video đăng ngày 11/10/2026), cách phòng thủ đáng tin cậy không phải là một bộ lọc thông minh hơn, vì bộ lọc sẽ bị vượt qua. Nó nằm ở thiết kế: loại bỏ một trong ba yếu tố, hoặc bắt buộc con người duyệt mọi việc hệ trọng một khi nội dung không đáng tin đã vào context.

Permissions, sandbox và xử lý cẩn thận các input không đáng tin. Trên bản đồ, đó là các đèn tín hiệu và hàng rào. Người dẫn nói chúng không làm agent thông minh hơn. Chúng làm cho sai lầm của agent không gây hậu quả không thể cứu vãn (video đăng ngày 11/10/2026).

## 10. Agent chạy hàng giờ, hàng ngày

Mọi thứ nói tới đây đều gói gọn trong một phiên. Nhưng còn những việc mất hàng giờ hay hàng ngày thì sao? Theo người dẫn (video đăng ngày 11/10/2026), không context window nào chứa nổi chúng, kể cả khi có compaction.

Vì thế, theo người dẫn (video đăng ngày 11/10/2026), những harness mới nhất xử lý việc dài như làm theo ca: nhiều phiên riêng biệt, mỗi phiên tiếp tục từ chỗ phiên trước để lại. Anthropic đã viết về việc build đúng kiểu này, và họ bắt đầu bằng cách liệt kê agent thất bại thế nào trong các việc dài. Chúng tuyên bố thắng quá sớm. Chúng đánh dấu một feature là xong mà không thật sự test nó. Và chúng hết context giữa chừng một thay đổi, để lại một mớ lộn xộn cho phiên sau.

Cách sửa của Anthropic, theo người dẫn (video đăng ngày 11/10/2026) và bài viết của Anthropic về harness cho agent chạy dài (đọc ngày 26/10/2026), bắt đầu bằng một phiên đặc biệt đầu tiên: một initializer agent. Nó viết một script để dựng môi trường, một file progress, và một danh sách feature đầy đủ trong đó mọi feature lúc đầu đều được đánh dấu là failing. Rồi nó tạo git commit đầu tiên.

Mỗi phiên sau đó đi theo một quy trình cố định. Đọc git log và file progress. Chạy một test nhanh để chắc chắn không có gì bị hỏng. Chọn một feature, build nó, rồi test nó từ đầu đến cuối như một người dùng sẽ làm. Commit, cập nhật file progress, và để lại code sạch cho ca sau. Người dẫn nói: nó không có gì khéo léo cả. Nó là việc một team kỹ sư có kỷ luật vẫn làm.

Trong một bài viết sau đó, theo người dẫn (video đăng ngày 11/10/2026), Anthropic chia công việc cho ba vai: một planner viết spec, một generator build, và một evaluator test app đang chạy trong một trình duyệt thật như một người dùng.

![Ba ga Planner, Generator, Evaluator; hai ô so sánh 20 min about $9 single agent và 6 hours about $200 full harness](https://homus.dev/photos/VhTtnolEiSw-1623.jpg)

Ba vai Planner ("writes the spec"), Generator ("builds"), Evaluator ("tests the running app", kèm một cửa sổ app có nút click). Bên dưới là phép so sánh Anthropic công bố, theo video đăng ngày 11/10/2026: "20 min, about $9" cho single agent và "6 hours, about $200" cho full harness với kết quả tốt hơn hẳn.

Trong một phép so sánh (theo người dẫn, video đăng ngày 11/10/2026), một agent đơn lẻ làm xong trong 20 phút với khoảng 9 đô, trong khi full harness chạy sáu tiếng và tốn khoảng 200 đô. Kết quả của full harness tốt hơn hẳn. Harness chạy dài đổi chi phí lấy chất lượng.

Và đây là bài học mà người dẫn gọi là quan trọng nhất của chương này: mỗi bộ phận của harness mã hoá một giả định về việc model không tự làm được. Theo người dẫn (video đăng ngày 11/10/2026), Anthropic từng cần reset context định kỳ, vì một model trở nên "lo lắng" khi gần chạm giới hạn và vội vàng kết thúc. Một model sau đó không còn làm thế nữa, nên họ bỏ các lần reset.

Model tiến bộ, giả định hết hạn, và theo người dẫn (video đăng ngày 11/10/2026), những người build harness giỏi thường xuyên kiểm tra xem từng bộ phận còn cần thiết không, rồi xoá những gì không còn cần.

## 11. Build một harness từ đầu trong khoảng 150 dòng Python

Lý thuyết thế là đủ. Người dẫn build một harness bằng Python, khoảng 150 dòng, và mỗi bước thêm một tuyến lên bản đồ. Cách làm theo bài hướng dẫn "How to Build an Agent" của Thorsten Ball, mà người dẫn gọi là xuất sắc, và theo project mini-swe-agent (video đăng ngày 11/10/2026).

**Bước 1, chat loop.** Đọc thứ bạn gõ, thêm nó vào một danh sách tin nhắn, gửi cả danh sách đó tới model, in câu trả lời ra, lặp lại. Để ý rằng mỗi lần đều gửi toàn bộ danh sách. API không nhớ gì cả, nên harness phải nhớ (theo video đăng ngày 11/10/2026).

**Bước 2, một tool.** Định nghĩa `read_file` với tên, mô tả và schema, rồi truyền nó cho model ở mọi lần gọi. Giữ thêm một dictionary ánh xạ từ tên tool sang hàm Python. Nếu model yêu cầu một tool không tồn tại, trả về một kết quả lỗi thay vì crash (video đăng ngày 11/10/2026).

**Bước 3, khép vòng lặp.** Khi model trả lời bằng một tool call, chạy hàm đó, bọc output trong một tool result có cùng ID với lời gọi, thêm nó vào danh sách tin nhắn, và gọi model lần nữa mà không chờ người dùng. Người dẫn nói đây là khoảnh khắc chatbot trở thành agent (video đăng ngày 11/10/2026).

**Bước 4, điều kiện dừng.** Nếu câu trả lời không có tool call, lượt đó xong. Đặt thêm giới hạn số bước và xử lý các cách khác mà một câu trả lời có thể kết thúc, như hết output token. Theo người dẫn (video đăng ngày 11/10/2026), không có bước này thì một model bối rối có thể lặp mãi và đốt sạch ngân sách của bạn.

**Bước 5, tools thật.** Liệt kê file. Sửa một file bằng cách thay một chuỗi chính xác bằng chuỗi mới. Và chạy một lệnh bash. Theo người dẫn (video đăng ngày 11/10/2026), chỉ với những tool này, agent đã có thể khám phá một project, sửa code và chạy test, và đó là phần lớn những gì một coding agent làm.

**Bước 6, chỉ dẫn.** Một system prompt nói cho model biết việc của nó và cách hành xử, cộng với file `AGENTS.md` của project nếu có, chứa lệnh build, lệnh test và quy tắc style (video đăng ngày 11/10/2026).

**Bước 7, ngân sách context.** Cắt bớt mọi output của tool dài quá vài nghìn ký tự, và báo cho model biết là đã cắt. Khi lịch sử gần chạm giới hạn, yêu cầu model tóm tắt rồi tiếp tục từ bản tóm tắt đó (video đăng ngày 11/10/2026).

**Bước 8, an toàn.** Hỏi trước khi chạy lệnh shell, trừ khi lệnh nằm trong một danh sách an toàn ngắn, và chạy bash bên trong một container thay vì trực tiếp trên máy bạn. Theo người dẫn (video đăng ngày 11/10/2026), trong mini-swe-agent thay đổi đó đúng nghĩa đen là đổi một lời gọi subprocess thành một lệnh Docker exec.

**Bước 9, plan và giao việc.** Thêm một tool to-do để model theo dõi plan của nó, và một tool subagent khởi động một agent mới với danh sách tin nhắn riêng và chỉ trả về câu trả lời cuối cùng (video đăng ngày 11/10/2026).

**Bước 10, log và eval.** Lưu mọi tin nhắn vào một file log để bạn đọc được chính xác chuyện gì đã xảy ra. Rồi viết năm task nhỏ có kiểm tra tự động và chạy chúng mỗi khi bạn sửa harness. Lúc đó bạn mới biết một thay đổi có thật sự giúp ích hay không (video đăng ngày 11/10/2026).

![Mười bước build harness bên trái và file agent.py ở bước 10 khoảng 150 dòng bên phải với code log và TASKS](https://homus.dev/photos/VhTtnolEiSw-1923.jpg)

Mười bước dưới dạng một tuyến tàu (Chat loop tới Logs and evals) và file `agent.py` ở "step 10 · ~150 lines": đoạn ghi mọi tin nhắn vào `logs/{run_id}.jsonl` và vòng chạy năm task nhỏ, mỗi task kèm một lệnh kiểm tra (video đăng ngày 11/10/2026).

Đoạn code bước 10 trên màn hình:

```
log = open(f"logs/{run_id}.jsonl", "a")
log.write(json.dumps(msg) + "\n")     # every message

TASKS = [("fix the failing test", "pytest -q"), ...]
for task, check in TASKS:              # five small tasks
run_agent([user_msg(task)])
print(task, passed(check))
```

Người dẫn kết luận: đó là một harness thật. Nó nhỏ, nhưng theo người dẫn (video đăng ngày 11/10/2026), mỗi bộ phận trong đó là một bộ phận bạn sẽ tìm thấy trong Claude Code, Codex hay OpenCode. Chỉ là những harness đó cẩn thận hơn nhiều với từng bộ phận.

## 12. Bức tranh harness mã nguồn mở

Bạn không bắt buộc phải tự build. Theo người dẫn (video đăng ngày 11/10/2026), có những harness mã nguồn mở rất tốt, và cái phù hợp tuỳ vào việc bạn muốn làm gì. Người dẫn đi qua bốn tuyến.

**Tuyến Learn.** Nếu bạn muốn học harness hoạt động thế nào, hãy đọc những cái nhỏ. Theo người dẫn (video đăng ngày 11/10/2026): mini-swe-agent có khoảng 100 dòng code agent với bash là tool duy nhất. Pi của Mario Zechner được cố ý làm tối giản và dễ hack. smolagents của Hugging Face giữ phần lõi dưới 1.000 dòng, và agent của nó viết hành động dưới dạng code Python. Còn Deep Agents của LangChain trình bày mỗi bộ phận chuẩn của harness, gồm planning, file system, subagents và summarization, thành một mảnh riêng mà bạn đọc được.

**Tuyến Embed.** Nếu bạn muốn đặt một agent vào bên trong sản phẩm của mình, hãy dùng một SDK. Theo người dẫn (video đăng ngày 11/10/2026), OpenAI Agents SDK làm việc với nhiều nhà cung cấp model. Strands Agents của AWS và Pydantic AI gọn gàng và không phụ thuộc model (model-agnostic). Google ADK hợp với Google Cloud. Nếu bạn muốn chính harness của Claude Code dưới dạng một thư viện, có Claude Agent SDK, nhưng người dẫn lưu ý nó theo điều khoản thương mại của Anthropic chứ không phải một giấy phép mã nguồn mở, và nó được build cho các model Claude (theo video đăng ngày 11/10/2026).

![Bốn tuyến Learn, Embed, Use daily, Run locally với tên các harness mã nguồn mở trên từng tuyến](https://homus.dev/photos/VhTtnolEiSw-2103.jpg)

Bốn tuyến của bức tranh mã nguồn mở, theo video đăng ngày 11/10/2026: Learn (mini-swe-agent, Pi, smolagents, Deep Agents), Embed (OpenAI Agents SDK, Strands Agents, Pydantic AI, Google ADK, Claude Agent SDK với nhãn "commercial terms"), Use daily (opencode, Codex CLI, Gemini CLI, Cline "in VS Code", Aider, goose, OpenHands "self-host for a team"), và tuyến Run locally đang sáng lên.

**Tuyến Use daily.** Nếu bạn chỉ muốn một coding agent tốt để dùng ngay, theo người dẫn (video đăng ngày 11/10/2026) có những lựa chọn mã nguồn mở mạnh: OpenCode, Codex CLI của OpenAI, Gemini CLI của Google, Cline bên trong VS Code, Aider trong terminal, goose, và OpenHands nếu bạn muốn chạy agent cho cả một team trên server của chính mình.

**Tuyến Run locally.** Và nếu bạn muốn chạy trên model local vì quyền riêng tư hay chi phí, theo người dẫn (video đăng ngày 11/10/2026) nhiều harness trong số này hỗ trợ việc đó. Codex có tuỳ chọn dùng model local qua Ollama, còn goose, Cline, smolagents, Pydantic AI và Strands đều làm việc được với model chạy local.

Người dẫn gọi tin tốt nhất là các harness đang hội tụ về những chuẩn chung, theo video đăng ngày 11/10/2026: MCP cho tools; `AGENTS.md` cho chỉ dẫn của project, mà theo người dẫn và màn hình đang được hàng chục nghìn project mã nguồn mở dùng; Agent Skills để đóng gói know-how; và Agent Client Protocol, cho phép các code editor nói chuyện với bất kỳ agent nào. Tools, chỉ dẫn và skills của bạn ngày càng mang đi được, nên bạn có thể đổi harness mà không phải làm lại từ đầu.

## 13. Đo xem harness có tốt không, và tấm bản đồ đầy đủ

Câu hỏi cuối cùng: làm sao biết harness của bạn có tốt không? Theo người dẫn (video đăng ngày 11/10/2026), các benchmark công khai là điểm khởi đầu. SWE-bench Verified là 500 GitHub issue thật đã được các developer kiểm tra. Bản sửa của agent phải làm cho các test đang fail chuyển sang pass mà không làm hỏng thứ gì khác. Terminal-Bench thử agent trên các task thật trong terminal. Người dẫn nói đây chính là nơi các kết quả "cùng model, khác harness" xuất hiện.

Nhưng theo người dẫn, benchmark hữu ích nhất là benchmark của chính bạn. Lời khuyên của Anthropic, theo người dẫn (video đăng ngày 11/10/2026) và bài "Demystifying evals for AI agents" (đọc ngày 26/10/2026), là bắt đầu với 20 đến 50 task lấy từ các lần thất bại thật. Chấm kết quả bằng code, như chạy test, ở bất cứ đâu có thể. Chạy mỗi task vài lần trong một môi trường mới, vì agent không làm cùng một việc mỗi lần chạy. Và rồi đọc các bản ghi phiên chạy. Người dẫn nói bạn sẽ học được từ 10 bản ghi nhiều hơn từ bất kỳ điểm số nào (video đăng ngày 11/10/2026).

![Thư mục evals với bốn mục và bảng năm task chạy năm lần với kết quả xanh đỏ khác nhau](https://homus.dev/photos/VhTtnolEiSw-2223.jpg)

"The most useful benchmark is your own": thư mục `evals/` với bốn mục: 20 đến 50 task lấy từ các lần thất bại thật, chấm bằng code (chạy test), chạy vài lần mỗi lần một môi trường mới, và đọc lại bản ghi các phiên chạy, và một lưới năm task chạy năm lần cho kết quả xanh/đỏ khác nhau, nhãn "agents vary run to run" (video đăng ngày 11/10/2026).

Rồi người dẫn trải ra toàn bộ tấm bản đồ. Một model chỉ biết đọc và viết text. Một vòng lặp liên tục gọi nó. Tools để nó hành động. Context engineering quyết định nó nhìn thấy gì. Plans, subagents và skills để giữ cho việc dài đi đúng hướng. Permissions và sandbox để sai lầm không gây hậu quả không thể cứu vãn. Và các phiên chuyển giao cho nhau với những việc kéo dài nhiều ngày (video đăng ngày 11/10/2026).

Người dẫn nhắc lại ý quan trọng nhất: harness là thứ tạm thời. Theo người dẫn (video đăng ngày 11/10/2026), mỗi bộ phận của nó tồn tại vì một điều mà các model của thời điểm đó chưa tự làm được. Khi model tiến bộ, các phần của harness biến mất và những phần mới xuất hiện cho các bài toán khó hơn. Tấm bản đồ liên tục thay đổi. Và giờ thì bạn đã biết cách đọc nó.

## Nguồn và liên kết

- Tên gốc: Agent Harnesses, Mapped: How AI Agents Actually Work
- Sự kiện: [YouTube](https://homus.dev/events/youtube)
- Video gốc: [https://www.youtube.com/watch?v=VhTtnolEiSw](https://www.youtube.com/watch?v=VhTtnolEiSw)

- Kênh YouTube Systems, Mapped (Systems, Mapped): [youtube.com/channel/UCv1aVG9d2-OH9EAVWA5tJlw](https://www.youtube.com/channel/UCv1aVG9d2-OH9EAVWA5tJlw)

- Thorsten Ball, "How to Build an Agent": hướng dẫn build một code-editing agent trong dưới 400 dòng code (đọc ngày 26/10/2026): [ampcode.com/how-to-build-an-agent](https://ampcode.com/how-to-build-an-agent)

- mini-swe-agent: README mô tả khoảng 100 dòng Python cho agent class, không có tool nào ngoài bash, chạy lệnh bằng `subprocess.run` (đọc ngày 26/10/2026): [github.com/SWE-agent/mini-swe-agent](https://github.com/SWE-agent/mini-swe-agent)

- Anthropic, "Effective context engineering for AI agents": "attention budget" và context rot (đọc ngày 26/10/2026): [anthropic.com/engineering/effective-context-engineering-for-ai-agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)

- Anthropic, "Writing effective tools for agents": viết mô tả tool như mô tả cho một người mới vào team (đọc ngày 26/10/2026): [anthropic.com/engineering/writing-tools-for-agents](https://www.anthropic.com/engineering/writing-tools-for-agents)

- Anthropic, "Effective harnesses for long-running agents": initializer agent và danh sách feature đánh dấu failing (đọc ngày 26/10/2026): [anthropic.com/engineering/effective-harnesses-for-long-running-agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)

- Anthropic, "Demystifying evals for AI agents": bắt đầu với 20-50 task (đọc ngày 26/10/2026): [anthropic.com/engineering/demystifying-evals-for-ai-agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)

- Anthropic, sandboxing trong Claude Code: giảm 84% số lần hỏi quyền trong sử dụng nội bộ, dựng trên bubblewrap và Seatbelt (đọc ngày 26/10/2026): [anthropic.com/engineering/claude-code-sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing)

- Simon Willison, "The lethal trifecta for AI agents: private data, untrusted content, and external communication" (đọc ngày 26/10/2026): [simonwillison.net/2025/Jun/16/the-lethal-trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/)

- Birgitta Böckeler trên trang của Martin Fowler, "Harness engineering" (đọc ngày 26/10/2026): [martinfowler.com/articles/harness-engineering.html](https://martinfowler.com/articles/harness-engineering.html)

- Philipp Schmid, "Agent harness": phép so sánh Model là CPU, Context Window là RAM, Harness là hệ điều hành, và ví dụ Vercel bỏ 80% tool (đọc ngày 26/10/2026): [philschmid.de/agent-harness-2026](https://www.philschmid.de/agent-harness-2026)

- LangChain, "The anatomy of an agent harness": "Agent = Model + Harness" và việc đưa coding agent từ Top 30 lên Top 5 trên Terminal Bench 2.0 chỉ bằng cách đổi harness (đọc ngày 26/10/2026): [langchain.com/blog/the-anatomy-of-an-agent-harness](https://langchain.com/blog/the-anatomy-of-an-agent-harness)

- Manus, "Context Engineering for AI Agents: Lessons from Building Manus": tỉ lệ input/output khoảng 100:1, chênh lệch giá 10 lần với input được cache, todo.md để nhắc lại mục tiêu, build lại framework bốn lần (đọc ngày 26/10/2026): [manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)

- Pi (pi-mono) của Mario Zechner (đọc ngày 26/10/2026): [github.com/badlogic/pi-mono](https://github.com/badlogic/pi-mono)

- AGENTS.md (đọc ngày 26/10/2026): [agents.md](https://agents.md/)

- Agent Skills: định dạng mở, mỗi skill là một folder chứa file SKILL.md, nạp theo progressive disclosure (đọc ngày 26/10/2026): [agentskills.io](https://agentskills.io/)

- Model Context Protocol (đọc ngày 26/10/2026): [modelcontextprotocol.io](https://modelcontextprotocol.io)

- Agent Client Protocol (đọc ngày 26/10/2026): [agentclientprotocol.com](https://agentclientprotocol.com/)

Nguồn: https://homus.dev/talks/agent-harnesses-mapped-how-ai-agents-actually-work · cập nhật 2026-10-26