Giải phẫu một Agent — Tự viết Agent Loop từ đầu
Bốn thành phần của mọi agent, vòng lặp thu thập ngữ cảnh → hành động → kiểm chứng, và code một harness hoàn chỉnh không dùng framework.
Mọi framework agent — LangGraph, Claude Agent SDK, OpenAI Agents SDK — đều bọc quanh cùng một vòng lặp dài chưa tới 50 dòng code. Nếu bạn chưa tự viết vòng lặp đó, mọi thứ framework làm sẽ là phép thuật, và khi agent hỏng (nó sẽ hỏng) bạn không biết nhìn vào đâu. Module này bóc trần vòng lặp, để từ đây về sau mỗi khái niệm mới (memory, subagent, guardrail) đều có một chỗ cụ thể trong code mà bạn hình dung được.
🎯 Mục tiêu học tập
- Mô tả 4 thành phần của agent: model, tools, vòng lặp (harness), và context/trạng thái
- Tự viết một agent loop hoàn chỉnh: gọi model, thực thi tool, trả kết quả, xử lý lỗi, dừng đúng lúc
- Xử lý đúng mọi stop_reason và đặt các giới hạn cứng (số bước, token, thời gian)
- Hiểu vì sao lịch sử message chính là 'trạng thái' của agent và hệ quả của điều đó
Bốn thành phần của mọi agent
| Thành phần | Là gì | Bạn kiểm soát bằng |
|---|---|---|
| Model | Nhận toàn bộ context, sinh ra văn bản và/hoặc yêu cầu gọi tool | Chọn model, mức effort, system prompt |
| Tools | Các hàm model được phép yêu cầu gọi; mỗi tool có tên, mô tả, schema tham số | Thiết kế tool (Module 3) |
| Vòng lặp (harness) | Code của bạn: gửi request, chạy tool, nối kết quả vào lịch sử, lặp | Điều kiện dừng, xử lý lỗi, quyền hạn |
| Context / trạng thái | System prompt + lịch sử message + kết quả tool tích luỹ | Context engineering (Module 4), memory (Module 7) |
Điểm then chốt hay bị hiểu sai: model không tự chạy tool. Model chỉ sinh ra một khối
dữ liệu có cấu trúc nói "tôi muốn gọi search_orders với tham số này". Chính harness của bạn
quyết định có chạy không, chạy thế nào, rồi đưa kết quả trở lại. Mọi cơ chế an toàn (duyệt, sandbox, giới
hạn) đều sống ở harness — vì đó là nơi duy nhất bạn có quyền kiểm soát tuyệt đối.
Vòng lặp: thu thập ngữ cảnh → hành động → kiểm chứng
Agent giỏi (và con người giỏi) làm việc theo cùng một nhịp:
- Thu thập ngữ cảnh — đọc file, tìm kiếm, truy vấn dữ liệu để hiểu tình hình.
- Hành động — sửa file, gọi API, viết báo cáo.
- Kiểm chứng — chạy test, đọc lại kết quả, so với yêu cầu.
- Lặp lại cho đến khi kiểm chứng đạt, rồi báo cáo.
Về mặt giao thức, mỗi vòng là một request tới API. Model trả về một stop_reason cho biết
vì sao nó dừng sinh:
| stop_reason | Ý nghĩa | Harness làm gì |
|---|---|---|
tool_use | Model muốn gọi một hay nhiều tool | Thực thi, trả tool_result, gọi tiếp |
end_turn | Model cho rằng đã xong (hoặc cần hỏi lại người dùng) | Trả kết quả cuối |
max_tokens | Output bị cắt vì chạm giới hạn | Không được chạy tool call dở dang; tăng giới hạn hoặc yêu cầu tiếp tục |
pause_turn | Tool phía server (web search...) cần thêm lượt | Gửi lại nguyên lịch sử để tiếp tục |
refusal | Model từ chối vì lý do an toàn | Dừng, báo người dùng; không thử lại y nguyên |
Code: agent loop hoàn chỉnh không dùng framework
import anthropic
client = anthropic.Anthropic()
# --- 1. Tools: mỗi tool = hàm Python + schema mô tả cho model ---
def search_orders(customer_email: str) -> str:
rows = db.query("SELECT id, status, total FROM orders WHERE email = %s", customer_email)
return str(rows) if rows else "Không tìm thấy đơn hàng nào cho email này."
def get_order_detail(order_id: str) -> str:
...
TOOL_FUNCS = {"search_orders": search_orders, "get_order_detail": get_order_detail}
TOOLS = [
{
"name": "search_orders",
"description": "Tìm tất cả đơn hàng của một khách theo email. Trả về id, trạng thái, tổng tiền. "
"Dùng khi khách hỏi về đơn hàng mà chưa cung cấp mã đơn.",
"input_schema": {
"type": "object",
"properties": {"customer_email": {"type": "string", "description": "Email khách đã đăng ký"}},
"required": ["customer_email"],
},
},
# ... get_order_detail tương tự
]
# --- 2. Vòng lặp ---
def run_agent(user_input: str, max_steps: int = 20) -> str:
messages = [{"role": "user", "content": user_input}]
for step in range(max_steps):
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
system="Bạn là trợ lý chăm sóc khách hàng của cửa hàng ABC. ...",
tools=TOOLS,
messages=messages,
)
# Luôn nối NGUYÊN response.content (kể cả khối thinking/tool_use), không chỉ phần text
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason == "end_turn":
return "".join(b.text for b in response.content if b.type == "text")
if response.stop_reason in ("max_tokens", "refusal"):
return f"Agent dừng sớm: {response.stop_reason}"
if response.stop_reason == "pause_turn":
continue
# stop_reason == "tool_use": chạy MỌI tool được yêu cầu, gom kết quả vào MỘT message
results = []
for block in response.content:
if block.type != "tool_use":
continue
try:
output = TOOL_FUNCS[block.name](**block.input)
results.append({"type": "tool_result", "tool_use_id": block.id, "content": output})
except Exception as e:
results.append({"type": "tool_result", "tool_use_id": block.id,
"content": f"Lỗi: {e}", "is_error": True})
messages.append({"role": "user", "content": results})
return "Đã chạm giới hạn số bước — dừng để tránh chi phí bùng nổ."
Năm chi tiết nhỏ trong đoạn code trên quyết định agent chạy ổn hay hỏng âm thầm:
- Nối nguyên
response.contentvào lịch sử. Nếu chỉ giữ phần text, bạn đánh rơi khốitool_use(request sau sẽ lỗi) và khối suy nghĩ (model mất mạch lập luận). - Mọi
tool_usephải có đúng mộttool_resultcùngtool_use_id, kể cả khi tool lỗi. - Kết quả của các tool gọi song song nằm trong cùng một message. Tách ra nhiều message sẽ vô tình dạy model thôi gọi song song.
- Lỗi tool là dữ liệu, không phải exception: trả về với
is_errorđể model đọc, hiểu, và tự sửa (đổi tham số, thử tool khác). - Giới hạn cứng
max_stepsnằm ở code, không nằm ở prompt.
Bản rút gọn với Tool Runner của SDK
Khi đã hiểu vòng lặp, bạn không cần viết lại nó mỗi lần. SDK có sẵn helper lo phần lặp; bạn chỉ viết hàm tool, schema được sinh từ chữ ký hàm và docstring:
import anthropic
from anthropic import beta_tool
client = anthropic.Anthropic()
@beta_tool
def search_orders(customer_email: str) -> str:
'''Tìm tất cả đơn hàng của một khách theo email.
Args:
customer_email: Email khách đã đăng ký.
'''
...
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=16000,
tools=[search_orders],
messages=[{"role": "user", "content": "Đơn của tôi (an@example.com) tới đâu rồi?"}],
)
for message in runner: # mỗi vòng lặp yield một message của model
print(message.stop_reason)
Lời khuyên: viết tay vòng lặp một lần để hiểu (bài tập bên dưới), rồi dùng helper/SDK cho công việc thật, chỉ quay lại vòng lặp tay khi cần kiểu điều khiển mà helper không cho.
Lịch sử message chính là trạng thái
API của model là stateless: mỗi request bạn gửi lại toàn bộ lịch sử. Hệ quả:
- Muốn lưu/khôi phục agent → lưu danh sách
messages(đây chính là thứ "checkpointing" của các framework làm — Module 7). - Chi phí mỗi bước tăng dần vì lịch sử dài ra; bước thứ 30 gửi lại cả 29 bước trước. Prompt caching (Module 4) là thứ khiến điều này chấp nhận được.
- Agent chỉ "biết" những gì nằm trong lịch sử. Nếu bạn cắt bớt một kết quả tool, với model nó chưa từng tồn tại.
- Lịch sử nên chỉ được nối thêm (append-only). Sửa các lượt cũ vừa phá cache, vừa có thể làm hỏng các khối suy nghĩ model cần đọc lại.
Các giới hạn cứng mọi harness phải có
| Giới hạn | Chống lại | Cách đặt |
|---|---|---|
| Số bước tối đa | Vòng lặp vô hạn | Đếm trong code; khi chạm, yêu cầu model tóm tắt tiến độ rồi dừng |
| Ngân sách token/tiền | Chi phí bùng nổ | Cộng dồn response.usage mỗi bước, dừng khi vượt |
| Thời gian (wall-clock) | Treo vì tool chậm | Timeout cho từng tool và cho cả phiên |
| Kích thước kết quả tool | Một kết quả 500KB nuốt hết context | Cắt bớt có thông báo rõ ("đã cắt, dùng tham số offset để đọc tiếp") |
| Phát hiện lặp | Gọi cùng tool cùng tham số nhiều lần | Băm (tên + tham số); lần thứ 3 thì chèn nhắc nhở hoặc dừng |
"Không được gọi
quá 10 tool" trong system prompt là một lời đề nghị. if step >= 10: break là một sự đảm
bảo. Mọi thứ liên quan đến tiền và an toàn phải được thực thi bằng code.
🏋️ Bài tập thực hành
Không dùng framework, viết một agent dòng lệnh có 3 tool: list_files(dir),
read_file(path), run_python(code) (chạy trong thư mục tạm). Yêu cầu: (1) vòng lặp
xử lý đủ 5 stop_reason; (2) lỗi tool trả về dưới dạng is_error; (3) giới hạn số bước và tổng
token; (4) in ra mỗi bước: tool nào được gọi, tham số gì, kết quả dài bao nhiêu ký tự. Giao cho nó nhiệm vụ
"tìm file CSV lớn nhất trong thư mục này và cho tôi biết 3 cột có nhiều giá trị thiếu nhất", rồi đọc lại toàn
bộ log để thấy agent tự quyết định trình tự như thế nào. Sau đó viết lại bằng Tool Runner và so sánh số dòng.
📚 Tài nguyên học tập
-
Claude Docs — Tool use overviewCơ chế tool use và vòng lặp agent ở mức APIDocs
-
Anthropic — Building agents with the Claude Agent SDKVòng lặp gather context → act → verify trong một harness thực tếBài viết
-
Thorsten Ball — How to Build an AgentXây coding agent tối giản từng bước, cho thấy vòng lặp đơn giản đến mức nàoBài viết
-
12-Factor AgentsCác nguyên tắc kỹ thuật phần mềm áp dụng cho agent: làm chủ prompt, context, luồng điều khiểnRepo
✅ Tự đánh giá hoàn thành
- Vẽ lại được vòng lặp agent và chỉ ra chỗ model quyết định, chỗ code quyết định
- Tự viết được agent loop xử lý đủ các stop_reason mà không nhìn tài liệu
- Giải thích được vì sao phải nối nguyên response.content và gom tool_result vào một message
- Agent của mình có đủ giới hạn cứng: số bước, token, timeout, kích thước kết quả tool