Agent của bạn hiếm khi thất bại vì model "ngu". Nó thất bại vì tool gọi API trả 429 mà không ai backoff, vì retry tạo hai đơn hàng, vì token bị nhúng vào prompt, vì endpoint đổi version mà không ai biết. Đó là lỗi backend, không phải lỗi prompt. Git và REST API là hai kỹ năng nền quyết định agent của bạn có sống được ngoài notebook hay không.
Mục lục
Cập nhật 2026
- MCP không thay REST. Spec
2026-07-28là bản stateless: bỏinitializehandshake và session ID, mỗi request mangprotocolVersionvà capabilities trong_meta; transport chỉ còn stdio và Streamable HTTP, HTTP+SSE đã deprecated. Nhưng MCP chỉ chuẩn hóa cách expose tool cho model; hợp đồng HTTP, authz và idempotency vẫn nằm ở tầng dịch vụ bên dưới. - Responses API là mặc định cho dự án mới. OpenAI khuyến nghị Responses cho mọi dự án mới; Astra và Sol chỉ tool-call được qua Responses. Chat Completions không còn là lựa chọn an toàn để dạy agent gọi tool.
- Auth của MCP là OAuth 2.1. Remote server dùng protected-resource metadata (RFC 9728), resource indicators (RFC 8707), PKCE và
iss(RFC 9207). Nếu bạn xây remote MCP server mà bỏ qua phần này, bạn đang mở một cửa sau có tên đẹp. - Model ID và giá đổi hàng tháng. Đừng hardcode một chuỗi model vào tool hay prompt. Pin phiên bản, ghi lại model đã dùng trong trace, và có đường lui khi provider đổi lịch giá.
Vì sao nhà phát triển agent cần kỹ năng backend thật
Một agent LLM có hai vai. Với người dùng, nó là một server: nhận request, giữ trạng thái, trả kết quả, chịu lỗi. Với hệ thống bên ngoài, nó là một client: gọi API, đọc response, thử lại, chịu rate limit. Cả hai vai đều là bài toán backend quen thuộc, chỉ khoác thêm lớp "model tự quyết định".
Điểm khác biệt quan trọng: model đề xuất hành động, nhưng code quyết định hành động đó có được phép chạy hay không. Nếu bạn để model tự quyết định cả việc retry, ngủ bao lâu, gọi endpoint nào, bạn đã giao quyền vận hành cho một hệ thống xác suất. Hãy giữ quyền đó trong code có thể review, test và log.
Kỹ năng backend còn quyết định chất lượng ngữ cảnh. Một tool trả về 500 KB JSON sẽ đốt context và tiền của bạn nhanh hơn mọi lỗi prompt. Một error message mơ hồ sẽ khiến model thử lại mù quáng. Thiết kế output của tool chính là thiết kế context của agent.
REST API: hợp đồng mà agent phải tôn trọng
REST không phải "gọi HTTP là xong". Nó là một hợp đồng về tài nguyên, phương thức, mã trạng thái và ngữ nghĩa lỗi. Agent là một client không đọc tài liệu kỹ như người, nên hợp đồng càng rõ thì agent càng ít bịa.
Tài nguyên, phương thức và mã trạng thái
GET an toàn và idempotent: gọi lại không đổi trạng thái server. PUT idempotent theo định nghĩa: gửi cùng body hai lần cho cùng kết quả. DELETE cũng idempotent. POST thì không: gọi hai lần có thể tạo hai bản ghi. PATCH không được bảo đảm idempotent. Agent cần biết điều này trước khi quyết định retry, không phải sau khi đã tạo trùng.
Mã trạng thái phải được xử lý theo lớp. 2xx là thành công, nhưng 202 nghĩa là "đã nhận, chưa xong" — agent phải poll hoặc chờ callback, không được coi là hoàn tất. 4xx là lỗi phía client: sửa request, không retry mù, trừ 408 và 429. 5xx có thể retry có kiểm soát. 409 là xung đột trạng thái, 422 thường là validation — hai lỗi này cần thông điệp đủ cụ thể để model sửa tham số.
Idempotency: thứ cứu bạn khỏi đơn hàng thứ hai
Timeout không có nghĩa là request thất bại. Request có thể đã thành công và response bị mất trên đường về. Nếu agent retry một POST tạo thanh toán mà không có idempotency key, bạn tạo hai giao dịch. Đây là lỗi phổ biến nhất khi biến một API thành tool.
Header Idempotency-Key là quy ước phổ biến ở nhiều API, không phải thuộc HTTP core — hãy đọc tài liệu của từng dịch vụ. Server nhận key, lưu kết quả của lần chạy đầu, và trả lại đúng kết quả đó cho các lần gửi lại cùng key. Key phải scope theo tenant và theo thao tác, có TTL, và nếu cùng key nhưng body khác thì trả 409 thay vì đoán ý. Phía agent, key nên sinh từ (run_id, step_id, tool_name) để retry trong cùng một bước dùng lại key, còn bước mới thì key mới.
Auth và quyền tối thiểu
API key dài hạn nhét trong biến môi trường là mức thấp nhất nên chấp nhận, và chỉ cho tool read-only. Với tool ghi, dùng token ngắn hạn, scope theo từng tool và từng tenant. Token được inject ở boundary — nơi code thực thi tool — không nằm trong context của model. Prompt injection không thể đọc thứ không tồn tại trong context.
Đừng cấp một token "admin" cho cả agent rồi trông chờ guardrail. OWASP LLM06 (Excessive Agency) mô tả đúng thất bại này: quá nhiều tool, quyền quá rộng, không có cổng phê duyệt. Sửa quyền trước khi thêm một model guardrail.
Rate limit, retry và backoff
429 kèm Retry-After là tín hiệu để code ngủ, không phải để model "thử lại sau". Dùng exponential backoff có jitter, giới hạn số lần thử, và chỉ retry thao tác idempotent hoặc có key. Không retry 400, 401, 403 — retry không sửa được lỗi quyền. Retry-After có thể là số giây hoặc HTTP-date; nếu code của bạn chỉ parse số, hãy nói rõ đó là giới hạn đã biết.
Rate limit còn là ngân sách. Mỗi tenant nên có quota riêng cho tool đắt tiền, và agent nên dừng bước thay vì xếp hàng vô hạn. Một hàng đợi retry không có trần là một cuộc tấn công từ chối dịch vụ do chính bạn gây ra.
Versioning và deprecation
Pin API version trong URL hoặc header, và ghi version đó vào trace cùng model ID. Khi provider thông báo deprecation, bạn cần biết tool nào đang gọi endpoint nào — điều này chỉ khả thi nếu request đi qua một lớp client chung thay vì mỗi tool tự gọi.
Với LLM API, versioning còn khó hơn: model ID, giá và tính năng tool-calling thay đổi theo tháng. Hãy coi model như một dependency có ngày hết hạn, có eval trước khi nâng, và có fallback đã test — không phải một chuỗi cố định trong config.
Git: quản lý thí nghiệm, không chỉ quản lý code
Một thay đổi hành vi agent thường là một diff gồm ba thứ: prompt, tool schema và code thực thi. Nếu chỉ commit code, bạn không thể tái tạo một lần chạy cũ, không biết prompt nào đi với schema nào, và không thể bisect khi chất lượng tụt.
Commit prompt và schema tool cùng nhau, kèm phiên bản eval set. Tag các mốc đã đo, ví dụ eval/2026-11-08-crm-v2, để sau này so sánh. Review diff prompt như review code: một câu thêm vào system prompt có thể đổi toàn bộ phân phối hành vi.
Đừng commit .env, token, log có PII hay dataset khách hàng. Dùng lock file cho dependency; dùng Git LFS cho artifact lớn như weight hay file dữ liệu — Git thường không hợp với file hàng GB. Và giữ một nhánh cho mỗi thí nghiệm, để rollback là thao tác một lệnh chứ không phải một buổi chiều.
git switch -c exp/tool-schema-v2
# sửa prompt + tool schema + eval cases
git add prompts/crm.md tools/crm_tool.py evals/crm_cases.jsonl
git commit -m "tool: bat buoc idempotency key, timeout 10s, loi co cau truc"
git tag eval/2026-11-08-crm-v2
git push origin exp/tool-schema-v2 --tags
Cho agent gọi API an toàn: một lớp client chung
Đừng để mỗi tool tự viết retry. Viết một lớp client nhỏ, có timeout, retry có trần, idempotency key và error envelope thống nhất. Model thấy lỗi đã được chuẩn hóa; code giữ các quyết định vận hành.
# File: tools/http_client.py
import os, random, time
import httpx
RETRYABLE = {429, 502, 503, 504}
def call_tool(path: str, *, idem_key: str, payload: dict | None = None,
timeout_s: float = 10.0, max_attempts: int = 3) -> dict:
base = os.environ["CRM_BASE_URL"] # .../api/v1
token = os.environ["CRM_TOKEN"] # token ngan han, scope crm:write
headers = {
"Authorization": f"Bearer {token}",
"Accept": "application/json",
"Idempotency-Key": idem_key, # quy uoc cua API, khong phai HTTP core
}
timeout = httpx.Timeout(timeout_s, connect=3.0)
with httpx.Client(timeout=timeout) as client:
for attempt in range(1, max_attempts + 1):
try:
r = client.post(base + path, json=payload, headers=headers)
except httpx.TimeoutException:
if attempt == max_attempts:
raise
time.sleep(min(2 ** attempt + random.random(), 8))
continue
if r.status_code in RETRYABLE:
if attempt == max_attempts:
r.raise_for_status()
# Retry-After co the la so giay hoac HTTP-date
wait = float(r.headers.get("Retry-After", 0) or 0)
time.sleep(max(wait, 2 ** attempt + random.random()))
continue
if r.status_code >= 400:
return {"ok": False, "status": r.status_code,
"error": r.text[:500], "retryable": False}
return {"ok": True, "status": r.status_code, "data": r.json()}
raise RuntimeError("unreachable")
Ba chi tiết trong code trên đáng chú ý. Thứ nhất, timeout là timeout tổng, không chỉ connect. Thứ hai, lỗi 4xx trả về retryable: False để model không thử lại vô ích. Thứ ba, output lỗi bị cắt — model không cần 2.000 token stack trace, nó cần mã lỗi và trường bị sai.
MCP và REST: không phải hoặc/hoặc
REST là hợp đồng giữa hai dịch vụ. MCP là giao thức để model client khám phá và gọi tool, resource, prompt. Chúng ở hai tầng khác nhau. Một MCP server có thể bọc một REST API, hoặc gọi thẳng database — nhưng nó không tự giải quyết authz, idempotency hay retry cho bạn.
| Câu hỏi | REST | MCP |
|---|---|---|
| Ai gọi | Service, script, agent runtime | Model client / agent host |
| Trạng thái | Tùy API; thường stateless | Stateless từ spec 2026-07-28 |
| Auth | API key, OAuth 2, mTLS tùy dịch vụ | OAuth 2.1 cho remote; env cho stdio |
| Retry/idempotency | Bạn thiết kế | Vẫn là việc của server bên dưới |
| Dùng khi | Tích hợp dịch vụ, endpoint nghiệp vụ | Expose tool cho nhiều client/model |
Kết luận thực dụng: học REST trước, vì mọi MCP server nghiêm túc đều phải giải quyết bài toán REST ở bên trong. Khi đã có một API ổn định, bọc nó thành MCP server là việc thêm một lớp giao diện — không phải việc thay thế nền tảng.
Checklist trước khi cho agent chạm production
- Mỗi tool có timeout, số lần retry tối đa và error envelope thống nhất.
- Mọi thao tác ghi có idempotency key; key sinh từ
(run_id, step_id, tool), không từ nội dung model bịa. - Token ngắn hạn, scope theo tool và tenant; không có secret trong prompt hay log.
- Endpoint và model ID được pin; trace ghi cả hai.
- Diff prompt + tool schema nằm trong cùng một commit, có tag eval.
Bài tiếp theo
Nếu bạn muốn đi sâu vào phần server của agent, đọc các kỹ năng phát triển backend cần thiết. Để thiết kế tool đúng chuẩn, xem thiết kế công cụ cho AI agent. Và khi đã có API, đọc MCP và spec mới trước khi bọc nó thành MCP server.
