AI Agent Roadmap: Thiết Kế Công Cụ cho AI Agent – Đầu vào, Đầu ra và Xử lý Lỗi

Một tool cho agent là một API viết cho client không đọc code, không đọc tài liệu, và sẽ bịa tham số nếu mô tả không đủ rõ. Nếu một lập trình viên mới đọc description mà vẫn hiểu sai, model cũng sẽ hiểu sai — chỉ khác là model không hỏi lại. Bài này đi qua schema, naming, idempotency, timeout, phân loại lỗi, giới hạn output, quyền và approval gate, cùng các quy ước MCP đang áp dụng năm 2026.

Cập nhật 2026: MCP đã stateless, lỗi vẫn là chuyện cũ

  • MCP spec 2026-07-28 bỏ handshake initialize và Mcp-Session-Id. Mỗi request mang protocolVersion và clientCapabilities trong _meta; server cung cấp server/discover. State giữa các lần gọi đi qua handle do server cấp và truyền như tham số tool.
  • Transport chỉ còn stdio và Streamable HTTP; HTTP+SSE đã deprecated và SSE resumability bị bỏ. Auth dùng OAuth 2.1 với RFC 9728, RFC 8707, PKCE; Dynamic Client Registration đã deprecated, ưu tiên Client ID Metadata Documents; stdio dùng credential từ môi trường.
  • SDK MCP hiện tại: Python mcp 2.3.0, TypeScript 1.32.2, .NET 2.4.0. Major khác nhau, nên đừng copy snippet giữa các SDK mà không kiểm tra API.
  • OWASP LLM Top 10 vẫn xếp Improper Output Handling (LLM05) và Excessive Agency (LLM06) trong nhóm lỗi agent phổ biến nhất: quá nhiều tool, quyền quá rộng, không có cổng duyệt.

Tool là API cho client ngẫu nhiên

Client này có ba đặc điểm. Nó không đọc code nguồn. Nó chỉ thấy tên, mô tả và schema. Và nó sẽ gọi tool theo xác suất, không theo hợp đồng. Vì thế mọi thứ quan trọng phải nằm trong schema hoặc trong mô tả, theo cách kiểm tra được. Đừng giấu quy tắc trong tài liệu nội bộ, và đừng dựa vào việc model “sẽ hiểu ý”.

Schema: bề mặt nhỏ, kiểu rõ, đơn vị tường minh

Một schema tốt có ít tham số, kiểu cụ thể, và không có any. Ưu tiên enum thay vì chuỗi tự do; dùng ISO 8601 cho thời gian; ghi đơn vị ngay trong tên trường (amount_cents, duration_seconds, size_bytes); tách tiền tệ khỏi số tiền; và thêm tenant hoặc scope nếu tool chạy đa khách hàng.

Đừng đặt mọi thứ là bắt buộc. Trường bắt buộc là trường model phải bịa khi thiếu dữ liệu. Chỉ bắt buộc thứ tool không thể chạy nếu thiếu; còn lại để optional với mô tả rõ. Nếu một tham số có thể suy ra an toàn ở server, hãy suy ra ở server thay vì hỏi model.

{
  "name": "refund_order",
  "description": "Hoàn tiền một phần hoặc toàn bộ đơn hàng đã thanh toán. Dùng khi khách yêu cầu hoàn tiền và đơn còn trong hạn 30 ngày. Không dùng để hủy đơn chưa thanh toán. Đây là hành động không đảo ngược và cần approval.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "description": "ID đơn hàng, dạng ORD-..."},
      "amount_cents": {"type": "integer", "minimum": 1, "description": "Số tiền hoàn, đơn vị cent"},
      "currency": {"type": "string", "enum": ["VND", "USD"]},
      "reason": {"type": "string", "enum": ["damaged", "late", "wrong_item", "other"]},
      "idempotency_key": {"type": "string", "description": "Khóa do caller sinh, bắt buộc để retry an toàn"}
    },
    "required": ["order_id", "amount_cents", "currency", "reason", "idempotency_key"]
  }
}

Ba chi tiết trong schema này đáng chú ý. amount_cents là số nguyên, không phải số thực, để tránh sai số tiền. reason là enum, để model không tự sáng tác lý do. idempotency_key nằm trong schema, không nằm ngoài, để model luôn truyền nó và runtime luôn kiểm tra nó.

Naming và description: nói khi nào dùng, khi nào không

Tên tool nên là động từ + danh từ: refund_order, search_docs, create_calendar_event. Tránh utility, process, handle, manage — những tên không nói được hành động. Một tool làm một việc; nếu một tool có tham số action với mười giá trị, model sẽ chọn sai action thường xuyên hơn là chọn đúng mười tool riêng.

Description phải trả lời năm câu: làm gì, khi nào dùng, khi nào không dùng, có side effect gì, trả về hình dạng gì. Câu “khi nào không dùng” là câu hay bị bỏ nhất và cũng hữu ích nhất: nó ngăn model dùng tool A cho việc của tool B. Nếu tool không đảo ngược được, nói rõ trong description và trong schema, đừng chỉ ghi trong tài liệu.

Idempotency: retry an toàn không phải may mắn

Mọi tool có side effect nên nhận idempotency key từ caller. Server lưu ánh xạ (tool, key) tới kết quả đã thực hiện, và trả lại kết quả đó khi cùng key đến lần hai. Cửa sổ lưu phải dài hơn cửa sổ retry, và key phải do caller sinh từ (task_id, step_id, tool_call_id) để hai lần chạy khác nhau không vô tình ghi đè nhau.

Idempotency không thay thế approval, và approval không thay thế idempotency. Một approval được duyệt hai lần vẫn có thể tạo hai lần hoàn tiền nếu tool không có key. Ngược lại, một key đúng vẫn có thể hoàn tiền nhầm người nếu approval không kiểm tra tham số. Hai cơ chế bảo vệ hai thứ khác nhau.

Trước khi retry một tool có side effect, hãy reconcile: đọc trạng thái thật từ hệ thống đích xem hành động đã xảy ra chưa. Retry mù sau timeout là cách tạo side effect trùng. Nếu không đọc được trạng thái, đừng retry; escalate.

Timeout: đặt ở đâu và cắt cái gì

Cần ba loại thời gian: connect timeout, read timeout, và deadline tổng của cả task. Deadline tổng là thứ agent phải biết, vì nó quyết định có kịp thử phương án B hay không. Một tool không nhận deadline sẽ chạy đến khi hệ thống đích trả lời, kể cả khi task đã hết hạn từ lâu.

Khi timeout, phải hủy được việc đang chạy nếu SDK hỗ trợ; nếu không, ít nhất đừng gửi thêm request mới. Sau deadline, retry chỉ làm tăng tải và che giấu sự cố. Ghi timeout vào error body với cùng cấu trúc như lỗi khác, để agent không phải đoán.

Phân loại lỗi: retryable hay không, và agent nên làm gì

Nhóm Retry? Hành vi đúng
Validation Không Sửa tham số; trả field lỗi và gợi ý
Auth / permission Không Refresh một lần, rồi escalate; không lặp
Not found / conflict Không Reconcile trạng thái, đổi tham số hoặc dừng
Rate limit (429) Có Tôn trọng Retry-After, backoff có jitter
Transient (5xx, timeout) Có, nếu idempotent Backoff, cap số lần, reconcile trước
Partial success Không mù Đọc phần đã làm, bù phần thiếu

Mọi lỗi nên có cùng một hình dạng: code, message, retryable, field nếu là validation, hint nếu có cách sửa, và request_id để tra log. Message phải viết cho model đọc: ngắn, cụ thể, không lộ stack trace, không lộ bí mật. “Thiếu order_id” tốt hơn “Invalid request payload”; “Đơn đã hoàn tiền trước đó, dùng key cũ để lấy kết quả” tốt hơn “Conflict”.

Ba lỗi không bao giờ retry: 400, 401, 403. Retry 401 vô tình biến một lỗi quyền thành vòng lặp đăng nhập. Retry 400 chỉ đốt token. Retry 403 có thể là dấu hiệu tấn công hoặc cấu hình sai, không phải sự cố tạm thời.

Output: giới hạn trước khi vào context

Output tool đi thẳng vào context và tính tiền như input. Một API trả 5 MB JSON sẽ làm agent mất context, chậm và đắt, trong khi model chỉ cần ba trường. Giới hạn ở phía server: trả ít trường, phân trang bằng cursor, cắt bớt kèm cờ truncated, và không bao giờ dump HTML thô.

Cấu trúc output nên ổn định giữa các lần gọi. Nếu tool có nhiều loại kết quả, thêm trường phân biệt và schema riêng cho từng loại. Đừng trả về “đôi khi là object, đôi khi là string”; model sẽ parse sai và bạn sẽ đi tìm lỗi ở prompt trong khi lỗi nằm ở tool.

Kết quả dài nên được tóm tắt kèm con trỏ tới bản đầy đủ, không phải nhét toàn bộ. Và mọi output tool phải được coi là dữ liệu không tin cậy: nó có thể chứa chỉ dẫn injection. Gắn nhãn nguồn, không cho output thay đổi policy, và không đưa output vào planner nếu planner có quyền rộng.

Quyền và approval gate

Scope tối thiểu theo tool, không theo agent. Một agent không nên có một token vạn năng cho mọi tool; mỗi tool nên có scope riêng, thời hạn ngắn, gắn với tenant và task. Secret không nằm trong context; inject token ngắn hạn ở biên, xoay vòng, và che trong log.

Approval gate bắt buộc cho tiền, ghi production, export dữ liệu, đổi quyền tài khoản. Gate phải log ai duyệt, tham số nào được duyệt, và quyết định gì. Duyệt một lần không có nghĩa là duyệt mọi tham số tương tự; nếu tham số đổi, phải duyệt lại. Egress cũng là quyền: allowlist đích đến, chặn cloud metadata, tách mạng build và mạng chạy.

Quy ước MCP: tool không còn là hàm nội bộ

Nếu tool được expose qua MCP, thiết kế phải theo spec 2026-07-28. Server không giữ session; mỗi request tự mang metadata. State giữa các lần gọi phải là handle do server cấp, truyền như tham số, không phải biến ẩn trong bộ nhớ server. Điều này ảnh hưởng trực tiếp đến thiết kế tool: tool cần state phải có tham số handle, và handle phải có thời hạn.

Phân biệt primitive: tools là hành động, resources là dữ liệu đọc, prompts là template. Đừng nhét mọi thứ vào tools. Với auth, dùng OAuth 2.1 và scope theo tool; đừng dựa vào session. Với registry, nhớ rằng registry chính thức vẫn ở trạng thái preview và dữ liệu có thể reset — đừng coi nó là nguồn sự thật duy nhất cho production.

Code: một tool có idempotency, deadline và lỗi có cấu trúc

# File: tools/refund.py — stdlib; gateway là client nội bộ của bạn
import time, uuid

class ToolError(Exception):
    def __init__(self, code: str, message: str, retryable: bool,
                 field: str | None = None, hint: str | None = None) -> None:
        super().__init__(message)
        self.code = code
        self.message = message
        self.retryable = retryable
        self.field = field
        self.hint = hint

class IdempotencyStore:
    def __init__(self) -> None:
        self._done: dict[str, dict] = {}
    def get(self, key: str) -> dict | None:
        return self._done.get(key)
    def put(self, key: str, value: dict) -> None:
        self._done[key] = value

def refund_order(order_id: str, amount_cents: int, currency: str, reason: str,
                 idempotency_key: str, store: IdempotencyStore, gateway,
                 deadline: float) -> dict:
    if amount_cents <= 0:
        raise ToolError("VALIDATION", "amount_cents phải lớn hơn 0", False, "amount_cents")
    if time.monotonic() >= deadline:
        raise ToolError("DEADLINE", "Task đã hết thời gian", False, hint="escalate")
    cached = store.get(idempotency_key)
    if cached is not None:
        return cached
    try:
        result = gateway.refund(order_id=order_id, amount_cents=amount_cents,
                                currency=currency, reason=reason,
                                timeout_s=max(1.0, deadline - time.monotonic()))
    except TimeoutError as exc:
        raise ToolError("TRANSIENT", "Gateway timeout", True,
                        hint="reconcile trước khi retry") from exc
    except gateway.AuthError as exc:
        raise ToolError("AUTH", "Token không hợp lệ hoặc hết quyền", False) from exc
    payload = {"status": "ok", "refund_id": result.refund_id,
               "amount_cents": amount_cents, "request_id": str(uuid.uuid4())}
    store.put(idempotency_key, payload)
    return payload

Điểm đáng chú ý: kiểm tra deadline trước khi gọi, không sau. Lưu kết quả sau khi gateway trả về, trước khi trả cho agent. Và timeout được map thành TRANSIENT với hint reconcile, không phải retry mù. Trong production, store phải là Redis hoặc database có TTL, không phải dict trong bộ nhớ; dict ở đây chỉ để minh họa hình dạng.

Kiểm thử tool: lỗi mới là hợp đồng

Test tool không phải test happy path. Cần sáu nhóm: schema validation với tham số thiếu và sai kiểu; error injection cho từng nhóm lỗi; timeout và deadline; replay cùng idempotency key; permission denial; và output vượt giới hạn. Thêm một nhóm thứ bảy: output chứa văn bản injection, để chắc rằng agent coi nó là dữ liệu chứ không phải chỉ thị.

Ở tầng agent, đo tool-call accuracy — tên, tham số, thứ tự — chứ không chỉ task success. Một task có thể thành công nhờ model tự bịa kết quả sau khi gọi sai tool. promptfoo 0.125.1 và DeepEval 4.3.3 phù hợp cho regression ở tầng này; còn test tool thuần nên chạy bằng unit test thông thường, không cần LLM.

Nhìn sang 2027

MCP stateless sẽ ổn định và registry trưởng thành hơn, nhưng bài toán thiết kế tool không đổi: schema rõ, lỗi có phân loại, side effect có idempotency, quyền tối thiểu, và approval cho hành động không đảo ngược. Điều đang tăng là mức độ chuẩn hóa: tool contract sẽ được test như API contract, còn approval và egress sẽ thành phần bắt buộc của mọi agent platform, không phải phụ lục bảo mật.

Checklist

  • Một tool một việc; tên là động từ + danh từ; description nói cả when-not.
  • Schema ít trường, enum thay chuỗi tự do, đơn vị nằm trong tên trường.
  • Mọi side effect nhận idempotency key; reconcile trước khi retry.
  • Lỗi có code, retryable, field, hint, request_id; không retry 400/401/403.
  • Output có cap, cursor và cờ truncated; coi output là dữ liệu không tin cậy.
  • Scope theo tool, token ngắn hạn, approval gate cho tiền và ghi production.
  • Test lỗi, timeout, replay và permission denial, không chỉ happy path.

Đọc tiếp: xây dựng công cụ AI tốt hơn, function calling với OpenAI và Gemini, Model Context Protocol, và Git và REST API cho nhà phát triển agent.