AI Agents & Agentic AI
Trang chủ / Module 2
🔁 Module 2 / 16 · 1 tuần

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.

Agent LoopHarnessStop reason
📌 Vì sao module này quan trọng

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ầnLà gìBạn kiểm soát bằng
ModelNhận toàn bộ context, sinh ra văn bản và/hoặc yêu cầu gọi toolChọn model, mức effort, system prompt
ToolsCá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áiSystem 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:

  1. Thu thập ngữ cảnh — đọc file, tìm kiếm, truy vấn dữ liệu để hiểu tình hình.
  2. Hành động — sửa file, gọi API, viết báo cáo.
  3. Kiểm chứng — chạy test, đọc lại kết quả, so với yêu cầu.
  4. 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ĩaHarness làm gì
tool_useModel muốn gọi một hay nhiều toolThực thi, trả tool_result, gọi tiếp
end_turnModel cho rằng đã xong (hoặc cần hỏi lại người dùng)Trả kết quả cuối
max_tokensOutput bị cắt vì chạm giới hạnKhô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_turnTool phía server (web search...) cần thêm lượtGửi lại nguyên lịch sử để tiếp tục
refusalModel từ chối vì lý do an toànDừ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.content vào lịch sử. Nếu chỉ giữ phần text, bạn đánh rơi khối tool_use (request sau sẽ lỗi) và khối suy nghĩ (model mất mạch lập luận).
  • Mọi tool_use phải có đúng một tool_result cùng tool_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_steps nằ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ạnChống lạiCách đặt
Số bước tối đaVò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ềnChi 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ậmTimeout cho từng tool và cho cả phiên
Kích thước kết quả toolMột kết quả 500KB nuốt hết contextCắt bớt có thông báo rõ ("đã cắt, dùng tham số offset để đọc tiếp")
Phát hiện lặpGọi cùng tool cùng tham số nhiều lầnBăm (tên + tham số); lần thứ 3 thì chèn nhắc nhở hoặc dừng
⚠️ Đừng giao giới hạn cho prompt

"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

Viết agent CLI tối giản với 3 tool

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

✅ 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