AI Agent Roadmap: Xây dựng Agent AI Từ Khởi Đầu Chỉ Với API LLM

Một framework agent che đi bốn thứ: vòng lặp, lược đồ tool, ngân sách, và cách ghi lại những gì đã xảy ra. Khi tự viết một agent bằng HTTP thuần, bạn buộc phải quyết định cả bốn. Bài này đi qua một agent tối thiểu chạy được chỉ với thư viện chuẩn của Python, rồi mở rộng dần các phần mà production thực sự cần: state, allowlist, retry, budget, logging và phê duyệt của con người.

Cập nhật 2026.

  • OpenAI khuyến nghị Responses cho dự án mới; Chat Completions vẫn chạy nhưng từ GPT-5.4 không gọi tool được trừ khi reasoning_effort là none. Astra và Sol bắt buộc dùng Responses nếu có tool.
  • Token suy luận được tính như output, nên ngân sách của agent phải tính cả phần “nghĩ”, không chỉ câu trả lời.
  • Prompt cache giúp phần prefix lặp lại rẻ hơn, nhưng chỉ khi prefix ổn định; chèn thời gian hoặc ID ngẫu nhiên vào system prompt sẽ phá cache.
  • Retry đúng là retry có điều kiện: tôn trọng 429 và Retry-After, không retry 400/401/403, và chỉ retry thao tác idempotent.

Sáu thành phần, không phải một “agent”

Bỏ tên thương hiệu đi, một agent là sáu thứ ghép lại:

  • State: danh sách message và các biến phụ (task id, số bước, chi phí).
  • Model client: một hàm gửi HTTP, có timeout và retry.
  • Tool registry: ánh xạ tên tool tới hàm thật, kèm JSON Schema cho tham số.
  • Loop: gọi model, đọc tool call, thực thi, nối kết quả, lặp.
  • Budgets: số bước, token, thời gian, và phát hiện lặp.
  • Telemetry: log từng bước, usage, quyết định phê duyệt.
user -> [state] -> LLM -> tool_calls? --không--> final answer
                 |                |
                 |                +--có--> executor (allowlist + schema)
                 |                              |
                 +<--------- tool result ------+

Điểm dễ hiểu sai nhất là state. messages không phải bộ nhớ của agent; nó chỉ là hình chiếu mà bạn gửi cho model ở lượt này. Bộ nhớ thật là của bạn: lịch sử đầy đủ, kết quả tool, quyết định phê duyệt, và các biến kiểm soát. Nếu chỉ giữ messages, bạn sẽ mất dấu khi cần nén, khi retry, hoặc khi kiểm toán.

Điểm thứ hai: kết quả tool là dữ liệu không đáng tin. Nó có thể chứa chỉ dẫn độc hại (prompt injection gián tiếp) hoặc JSON sai. Hãy đưa nó vào context như bằng chứng có nhãn, không phải như mệnh lệnh. Nội dung tool không được phép ghi đè system prompt.

Gọi API bằng HTTP thuần

Đoạn mã dưới đây dùng urllib của thư viện chuẩn, nên không cần cài SDK. Nó giả định một endpoint tương thích Chat Completions. Nếu bạn dùng GPT-6 Astra hoặc Sol, hãy chuyển phần gọi sang Responses; hợp đồng vòng lặp giữ nguyên, chỉ lược đồ request/response thay đổi theo tài liệu.

# File: agent.py — agent tối thiểu, chỉ dùng thư viện chuẩn
import hashlib, json, os, random, sys, time
import urllib.error, urllib.request

BASE = os.environ.get("LLM_BASE_URL", "https://api.openai.com/v1")
MODEL = os.environ["LLM_MODEL"]
KEY = os.environ["LLM_API_KEY"]

MAX_STEPS = 8
MAX_TOKENS = 40_000
MAX_SECONDS = 90

def post(path, body, tries=4):
    for attempt in range(tries):
        req = urllib.request.Request(
            BASE + path,
            data=json.dumps(body).encode("utf-8"),
            headers={
                "Authorization": "Bearer " + KEY,
                "Content-Type": "application/json",
            },
        )
        try:
            with urllib.request.urlopen(req, timeout=60) as r:
                return json.loads(r.read())
        except urllib.error.HTTPError as e:
            if e.code in (400, 401, 403):
                raise                      # lỗi của bạn, retry không giúp
            wait = float(e.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait + random.random())  # backoff có jitter
    raise RuntimeError("LLM API thất bại sau khi retry")

Hàm post là toàn bộ tầng vận chuyển. Ba quyết định trong đó rất quan trọng: timeout hữu hạn, retry chỉ cho 429/5xx, và đọc Retry-After thay vì đoán. Với 400 do schema sai, retry chỉ làm bạn trả tiền nhiều lần cho cùng một lỗi.

Tool registry và JSON Schema

Registry là allowlist. Tên tool do model trả về không bao giờ được dùng để tra hàm tùy ý hay gọi eval. Mỗi tool có schema tham số; schema vừa là hợp đồng cho model, vừa là thứ bạn validate trước khi chạy.

def now_utc():
    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())

def count_words(text):
    return str(len(text.split()))

TOOLS = {
    "now_utc": {
        "fn": now_utc,
        "schema": {
            "type": "function",
            "function": {
                "name": "now_utc",
                "description": "Trả về thời gian UTC hiện tại.",
                "parameters": {"type": "object", "properties": {}},
            },
        },
    },
    "count_words": {
        "fn": count_words,
        "schema": {
            "type": "function",
            "function": {
                "name": "count_words",
                "description": "Đếm số từ trong một đoạn văn bản.",
                "parameters": {
                    "type": "object",
                    "properties": {"text": {"type": "string"}},
                    "required": ["text"],
                },
            },
        },
    },
}

Tool đọc-only như hai tool trên không cần phê duyệt. Tool có tác động bên ngoài — gửi email, ghi database, chuyển tiền — phải nằm trong một tập REQUIRES_APPROVAL và đi qua cổng phê duyệt trước khi thực thi. Việc thiết kế tên, mô tả và kiểu lỗi của tool được bàn kỹ ở bài Thiết kế công cụ cho AI Agent.

Vòng lặp đầy đủ

SYSTEM = (
    "Bạn là agent. Dùng tool khi cần dữ kiện hoặc tính toán. "
    "Khi đã đủ thông tin, trả lời cuối cùng bằng tiếng Việt, không gọi tool nữa."
)

def run(task, approve=lambda name, args: True):
    messages = [
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": task},
    ]
    seen = set()
    started = time.monotonic()
    spent = 0

    for step in range(1, MAX_STEPS + 1):
        data = post("/chat/completions", {
            "model": MODEL,
            "messages": messages,
            "tools": [t["schema"] for t in TOOLS.values()],
            "tool_choice": "auto",
            "max_tokens": 800,
        })

        msg = data["choices"][0]["message"]
        spent += data.get("usage", {}).get("total_tokens", 0)
        calls = msg.get("tool_calls") or []

        assistant = {"role": "assistant", "content": msg.get("content") or ""}
        if calls:
            assistant["tool_calls"] = calls
        messages.append(assistant)

        print(json.dumps({
            "step": step,
            "calls": [c["function"]["name"] for c in calls],
            "usage": data.get("usage"),
        }, ensure_ascii=False), file=sys.stderr)

        if not calls:
            return msg.get("content", "")

        for call in calls:
            name = call["function"]["name"]
            try:
                args = json.loads(call["function"]["arguments"] or "{}")
            except json.JSONDecodeError:
                args = {}

            digest = hashlib.sha256(
                (name + json.dumps(args, sort_keys=True)).encode()
            ).hexdigest()

            if name not in TOOLS:
                out = "ERROR: tool không tồn tại trong allowlist"
            elif digest in seen:
                out = "STOP: lời gọi giống hệt đã được thực hiện"
            elif not approve(name, args):
                out = "DENIED: người dùng từ chối hành động này"
            else:
                seen.add(digest)
                try:
                    out = TOOLS[name]["fn"](**args)
                except Exception as e:
                    out = "ERROR: " + type(e).__name__

            messages.append({
                "role": "tool",
                "tool_call_id": call["id"],
                "content": str(out),
            })

        if spent > MAX_TOKENS or time.monotonic() - started > MAX_SECONDS:
            raise TimeoutError("vượt ngân sách token hoặc thời gian")

    raise RuntimeError("vượt ngân sách số bước")

Vòng lặp có bốn điều kiện dừng thật: model không còn tool call, số bước, ngân sách token, và thời gian. Điều kiện thứ năm là phát hiện lặp bằng băm tên tool cộng tham số. Nếu thiếu nó, một model bị kẹt sẽ gọi cùng một tool với cùng tham số cho đến khi hết context.

Thứ tự kiểm tra cũng quan trọng: allowlist trước, rồi lặp, rồi phê duyệt, cuối cùng mới thực thi. Đừng đảo thứ tự và đừng gọi tool trước khi validate tham số. Trong production, hãy validate bằng JSON Schema thật thay vì tin vào việc model tuân thủ mô tả.

Một chi tiết nhỏ nhưng ảnh hưởng lớn tới độ ổn định: lỗi tool phải được trả về cho model dưới dạng có cấu trúc, không phải stack trace. Một chuỗi như “ERROR: thiếu trường ‘text’” giúp model sửa lời gọi ở bước sau; một stack trace 20 dòng vừa làm phình context vừa có thể lộ đường dẫn nội bộ. Tương tự, hãy cắt kết quả tool quá dài trước khi đưa vào context: model không cần toàn bộ trang web, chỉ cần phần liên quan. Đặt giới hạn ký tự cho mỗi kết quả tool và ghi lại việc cắt trong log để không mất khả năng truy vết.

Năm lỗi làm agent chết

Triệu chứng Nguyên nhân thường gặp Cách sửa
Lặp vô hạn Không có max steps hoặc không phát hiện lặp Đặt cả hai, và trả lỗi có cấu trúc cho model
Tool không tồn tại Model bịa tên hoặc schema mô tả mơ hồ Allowlist, mô tả tool rõ, trả “unknown tool” thay vì đoán
JSON sai Model bọc markdown hoặc cắt chuỗi Parse có thử/sai, và yêu cầu schema chặt
Chi phí tăng vọt Mỗi bước gửi lại toàn bộ lịch sử, reasoning bật cao Đặt budget, giữ prefix ổn định, hạ effort
Hành động nguy hiểm Tool có quyền rộng, không có cổng duyệt Tách quyền, phê duyệt, và sandbox

Lỗi thứ tư thường bị đánh giá thấp. Một vòng lặp 8 bước gửi lại system prompt và tool schema 8 lần. Nếu prefix ổn định, phần lặp này đọc từ cache với giá thấp hơn nhiều; nếu bạn chèn ngày giờ hoặc một ID vào system prompt, cache vô hiệu và bạn trả giá đầy đủ cho mọi bước. Hãy đặt nội dung biến động ở cuối, sau phần tĩnh.

Log dạng JSON line đủ để debug một task, nhưng chưa đủ để phân tích hàng loạt. Hãy thêm một trace id cho mỗi task, một span cho mỗi bước, và ghi các trường ổn định: tên tool, hash của tham số, độ trễ, số token vào/ra. Nhờ vậy bạn có thể trả lời “task nào tốn nhất”, “tool nào hay lỗi”, và “bước nào lặp”. OTel GenAI vẫn ở trạng thái Development, tên thuộc tính còn thay đổi, nên nếu dùng OTel hãy pin phiên bản semconv thay vì giả định ổn định.

Retry, idempotency và phê duyệt

Retry tầng LLM và retry tầng tool là hai chuyện khác nhau. Với LLM, retry một request bị 429 là an toàn vì nó không tạo ra tác động bên ngoài. Với tool, retry có thể gửi hai email hoặc trừ tiền hai lần. Vì vậy mọi tool có tác động phải nhận một idempotency key, và kết quả phải được đối soát trước khi thử lại.

Cổng phê duyệt của con người không phải một hộp thoại “OK”. Nó cần ghi lại ai duyệt, duyệt hành động nào, với tham số gì, và quyết định lúc nào. Bản thân phê duyệt không bảo vệ khỏi việc chạy lại cùng hành động; nó chỉ là một lớp kiểm soát. Hãy kết hợp với idempotency và audit log.

Với agent đọc-only, bạn có thể bỏ qua phê duyệt để giảm ma sát. Với agent có quyền ghi, hãy mặc định phê duyệt và chỉ tự động hóa sau khi eval chứng minh an toàn trong một phạm vi hẹp. Việc gọi tool có cấu trúc và các lỗi thường gặp của API được trình bày ở bài Triển khai Function Calling với OpenAI và Gemini.

Khi nào nên chuyển sang framework

Ba dấu hiệu cho thấy tự viết không còn rẻ: bạn cần persistence qua nhiều process, bạn cần streaming và interrupt giữa chừng, hoặc bạn cần nhiều agent phối hợp với state chia sẻ. Lúc đó, các abstraction như checkpoint, session, handoff đã được giải quyết bởi framework và tự viết lại là tiêu tiền vào thứ không phải lợi thế của bạn.

Ngược lại, nếu agent của bạn chỉ có vài tool, chạy trong một process, vài nghìn task mỗi ngày, thì khoảng 100 dòng như trên dễ hiểu hơn mọi framework. Bạn kiểm soát được retry, chi phí, và log; không có lớp abstraction nào che mất lỗi thật.

Checklist

  • Đặt LLM_MODEL, base URL và key qua biến môi trường; không hard-code.
  • Allowlist tool, validate tham số theo JSON Schema trước khi chạy.
  • Bốn ngân sách: bước, token, thời gian, và phát hiện lặp.
  • Log mỗi bước dưới dạng JSON line, kèm usage và tên tool.
  • Phê duyệt cho mọi hành động không thể hoàn tác; ghi lại người duyệt.
  • Giữ prefix prompt ổn định để cache có tác dụng.

Đọc tiếp: Kiểm thử Agent AI: Unit, Tích hợp và Con người trong Vòng lặp và Đánh giá Agent AI bằng LangSmith, Ragas và DeepEval.