Thiết kế API ưu tiên Agent: Cách xây dựng các API mà AI Agents thực sự hiểu được

Hầu hết các API được xây dựng cho các lập trình viên là con người, những người đọc tài liệu, duyệt qua các ví dụ và gỡ lỗi bằng stack trace. Vào năm 2026, một phần ngày càng lớn lưu lượng truy cập API đến từ các AI agent, và chúng không tương tác với API theo cách con người vẫn làm.

Đây là cách chúng tôi thiết kế lại API AI thống nhất của TokenLab dựa trên một nguyên tắc: đừng cố tỏ ra thông minh, hãy cung cấp thông tin. Chúng tôi gọi kết quả này là thiết kế API ưu tiên AI agent (agent-first API design), và nó đã giúp người dùng của chúng tôi cắt giảm hơn 60% lượng token lãng phí.

Những điểm chính

• Thiết kế API ưu tiên AI agent bổ sung các gợi ý có cấu trúc, máy có thể đọc được vào các phản hồi lỗi để các AI agent có thể tự sửa lỗi mà không cần tìm kiếm trên web hay sự trợ giúp của con người.
• Đưa ra các lựa chọn thay thế, đừng tự động sửa lỗi. Các trường như did_you_mean, suggestions và retryable cho phép các agent đưa ra quyết định sáng suốt thay vì để quyết định đó bị áp đặt.
• Mọi gợi ý đều dựa trên dữ liệu thực tế (production data), vì vậy các mô hình ngoại tuyến hoặc đã lỗi thời sẽ không bao giờ xuất hiện trong danh sách đề xuất.
• Các trường gợi ý mang tính bổ sung và tương thích ngược, vì vậy các client tương thích với OpenAI hiện có vẫn hoạt động bình thường mà không cần thay đổi.

Thiết kế API ưu tiên AI Agent là gì?

Thiết kế API ưu tiên AI agent nghĩa là cấu trúc các phản hồi của bạn, đặc biệt là các phản hồi lỗi, để một AI agent có thể hiểu điều gì đã xảy ra và khắc phục nó mà không cần rời khỏi cuộc hội thoại.

Lỗi API truyền thống:

{"error": {"message": "Model not found"}}

Lỗi API ưu tiên AI agent:

{
  "error": {
    "code": "model_not_found",
    "message": "Model 'gpt5.5' not found",
    "did_you_mean": "gpt-5.5",
    "suggestions": [{"id": "gpt-5.5"}, {"id": "gemini-3.5-flash"}],
    "hint": "Use GET /v1/models to list all available models."
  }
}

Với API truyền thống, agent phải tìm kiếm trên web, tìm tài liệu, phân tích HTML và đoán. Với API ưu tiên AI agent, nó tự sửa lỗi chỉ trong một bước.

Tại sao các API truyền thống lại thất bại với AI Agent

Hãy xem điều gì xảy ra khi một agent truy cập vào một trình tổng hợp API điển hình lần đầu tiên:

Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API:   400 {"error": {"message": "Model not found"}}
Agent: (tìm kiếm trên web "tokenlab models list")
Agent: (lấy một trang tài liệu, có thể là sai trang)
Agent: (phân tích HTML, tìm tên mô hình)
Agent: POST /v1/chat/completions {"model": "gpt-5.5"}
API:   200 ✓

Sáu bước, nhiều yêu cầu mạng, hàng trăm token bị lãng phí. Và đó là trường hợp thuận lợi, khi agent tình cờ đoán đúng URL tài liệu.

Với thiết kế ưu tiên AI agent:

Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API:   400 {"did_you_mean": "gpt-5.5", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-5.5"}
API:   200 ✓

Hai bước, không cần tìm kiếm trên web. Agent tự sửa lỗi chỉ từ phản hồi lỗi.

Nguyên tắc cốt lõi: Trí thông minh nằm ở phía mô hình

Cám dỗ lớn nhất là xây dựng các API "thông minh" có khả năng tự động sửa tên mô hình, âm thầm định tuyến lại đến thứ gì đó tương tự, hoặc gắn thêm một công cụ gợi ý. Chúng tôi đã từ chối tất cả những điều đó.

Khi một agent gửi model: "gpt5.5", bạn không thực sự biết ý định của nó. Có thể nó đang kiểm tra xem có bản phát hành GPT mới hơn không. Có thể nó có giới hạn ngân sách chặt chẽ. Có thể nó cần một khả năng cụ thể mà chỉ một mô hình hỗ trợ. Việc tự động định tuyến đến gpt-5.5 sẽ âm thầm thay đổi chi phí, chất lượng và khả năng, và agent sẽ không bao giờ biết điều đó đã xảy ra.

Cách tốt hơn là thất bại nhanh và thất bại một cách đầy đủ thông tin. Hãy cung cấp cho agent tất cả dữ liệu và để nó tự quyết định.

Bốn mô hình thiết kế API ưu tiên AI Agent

Mô hình 1: Model Not Found → Gợi ý mờ (Fuzzy Suggestions)

{
  "error": {
    "code": "model_not_found",
    "did_you_mean": "gpt-5.5",
    "suggestions": [
      {"id": "gpt-5.5"},
      {"id": "gemini-3.5-flash"},
      {"id": "claude-sonnet-5"}
    ],
    "hint": "Did you mean 'gpt-5.5'? Use GET /v1/models to list all available models."
  }
}

did_you_mean sử dụng giải pháp ba lớp: ánh xạ bí danh tĩnh từ dữ liệu thực tế, khớp chuỗi chuẩn hóa và khoảng cách chỉnh sửa có giới hạn. Mỗi ứng viên đều được kiểm tra với danh sách mô hình trực tuyến, vì vậy chúng tôi không bao giờ gợi ý một mô hình hiện đang ngoại tuyến.

Mô hình 2: Insufficient Balance → Các lựa chọn thay thế theo ngân sách

{
  "error": {
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gemini-3.5-flash", "estimated_cost_usd": 0.02},
      {"id": "deepseek-v4-flash", "estimated_cost_usd": 0.01}
    ],
    "hint": "Insufficient balance. Try a cheaper model or top up."
  }
}

Thay vì chỉ nói "không đủ tiền", chúng tôi cho agent biết chính xác số dư hiện có, số tiền cần thiết và những mô hình nào nó có thể chi trả ngay bây giờ. Agent có thể tự động hạ cấp xuống một mô hình AI rẻ hơn mà không cần sự can thiệp của con người. Hãy xác minh giá mỗi mô hình hiện tại trên danh mục mô hình TokenLab trước khi đặt cứng các ngưỡng chi phí.

Mô hình 3: All Channels Failed → Các lựa chọn thay thế trực tuyến

{
  "error": {
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-5", "status": "available"},
      {"id": "gpt-5.5", "status": "available"}
    ],
    "hint": "All channels for 'claude-opus-4-8' temporarily unavailable. Retry in 30s or try an alternative."
  }
}

Danh sách alternatives không tĩnh. Đó là một truy vấn trực tiếp vào dữ liệu sức khỏe kênh của chúng tôi, vì vậy agent nhận được thông tin thời gian thực về những gì thực sự đang hoạt động, thay vì một danh sách dự phòng cứng nhắc có thể đã lỗi thời.

Mô hình 4: Rate Limited → Thời gian thử lại chính xác

{
  "error": {
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "limit": "1000/min",
    "remaining": 0,
    "hint": "Rate limited. Retry after 8s."
  }
}

Không đoán, không cần exponential backoff bắt đầu từ một giá trị tùy ý. Agent biết chính xác thời gian chờ. Để biết thêm về cách xử lý giới hạn tốc độ hiệu quả, hãy xem hướng dẫn giới hạn tốc độ API AI của chúng tôi.

Các phản hồi thành công cũng mang theo gợi ý

Khi một agent gọi /v1/chat/completions với mô hình Claude, phản hồi bao gồm:

X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages

Chúng tôi đang nói với agent rằng: điều này đã hoạt động, nhưng có cách tốt hơn. Nó có thể chuyển sang endpoint gốc trong lần gọi tiếp theo và tận dụng các tính năng như extended thinking và prompt caching vốn không được hiển thị thông qua định dạng tương thích với OpenAI.

Các gợi ý này nằm trong header, không phải body phản hồi, vì body phải tuân thủ chính xác đặc tả của OpenAI hoặc Anthropic. Header là điểm mở rộng an toàn mà không làm hỏng bất kỳ logic phân tích cú pháp hiện có nào.

Phản hồi /v1/models như một bảng cheat sheet cho Agent

Chúng tôi đã thêm ba trường vào mỗi mục mô hình trong phản hồi /v1/models:

• category: mô hình chat, trình tạo ảnh, mô hình video hoặc âm thanh. Không còn phải đoán từ tên gọi.
• pricing_unit: mỗi token, mỗi ảnh, mỗi giây hoặc mỗi yêu cầu. Cần thiết cho bất kỳ ước tính chi phí thực tế nào.
• cache_pricing: giá prompt cache thượng nguồn cộng với chiết khấu cache ngữ nghĩa của nền tảng.

Kết hợp với các trường hiện có (giá cả, khả năng, bí danh, max token), một agent có thể đưa ra lựa chọn mô hình hoàn toàn sáng suốt từ một lần gọi API duy nhất. Bạn có thể xem danh mục trực tuyến đầy đủ trong danh mục mô hình TokenLab (quan sát ngày 2026-07-07), hiện liệt kê hơn 300 mô hình trên các danh mục chat, ảnh, video và âm thanh, bao gồm các tùy chọn tiên phong hiện nay như Claude Sonnet 5, GPT-5.5 và Gemini 3.5 Flash. Hãy xác minh giá cả và tình trạng sẵn có hiện tại trên trang đó thay vì giả định các số liệu trong bài viết này là hiện tại.

llms.txt: Lần đọc đầu tiên của Agent

Chúng tôi cung cấp một tệp llms.txt động tại api.tokenlab.sh/llms.txt, một bản tổng quan về toàn bộ API mà máy có thể đọc được. Nó bao gồm:

• Mẫu gọi lần đầu với mã hoạt động
• Tên mô hình phổ biến, được tự động tạo từ dữ liệu sử dụng thay vì đặt cứng
• Tất cả 12 endpoint với các tham số
• Các tham số lọc để khám phá mô hình

Một agent đọc tệp này trước lần gọi API đầu tiên sẽ có khả năng thực hiện yêu cầu đúng ngay từ lần thử đầu tiên cao hơn nhiều.

Dựa trên dữ liệu, không phải dựa trên kiến thức

Mọi gợi ý trong hệ thống đều đến từ dữ liệu thực tế. Bản đồ bí danh did_you_mean được tạo từ 30 ngày lỗi model_not_found thực tế trong nhật ký yêu cầu của chúng tôi. Các gợi ý mô hình được sắp xếp theo mức độ sử dụng thực tế. Danh sách "tên mô hình phổ biến" trong llms.txt được tạo từ cơ sở dữ liệu của chúng tôi, không phải duy trì thủ công.

Chúng tôi theo dõi mọi lỗi mô hình trong một tập hợp Redis đã sắp xếp. Khi một lỗi chính tả tích lũy đủ lượt truy cập, nó sẽ được đưa vào bản đồ bí danh. Khi một mô hình ngoại tuyến, nó sẽ tự động bị loại khỏi mọi danh sách gợi ý. Hệ thống tự điều chỉnh theo thời gian thay vì trở nên lỗi thời, điều này rất quan trọng khi các bản phát hành mô hình mới như GPT-5.5, Claude Sonnet 5 và Gemini 3.5 Flash ra mắt trên các mốc thời gian chồng chéo.

Ràng buộc thiết kế giúp nó hoạt động

Chúng tôi đặt ra một quy tắc: không endpoint mới, không SDK mới, không thay đổi gây lỗi (breaking changes). Mọi thứ phải nằm gọn trong định dạng lỗi tương thích với OpenAI hiện có. Các trường mới là tùy chọn, vì vậy bất kỳ client nào bỏ qua chúng đều có trải nghiệm giống hệt như trước đây.

Ràng buộc đó buộc chúng tôi phải chính xác về những gì thực sự giúp một agent tự sửa lỗi, thay vì xây dựng các API mới phức tạp mà không ai muốn áp dụng.

Cách áp dụng thiết kế ưu tiên AI Agent vào API của riêng bạn

Nếu bạn đang xây dựng các API mà các AI agent sẽ tiêu thụ:

1. Làm cho mọi lỗi đều có thể hành động được. Nêu rõ điều gì đã sai, tại sao và phải làm gì tiếp theo.
2. Đưa ra các lựa chọn thay thế thay vì tự động sửa lỗi. Hãy để agent đưa ra quyết định sáng suốt.
3. Sử dụng các trường có cấu trúc, không phải văn xuôi. did_you_mean là thứ có thể phân tích cú pháp; "did you mean..." bị chôn vùi trong một câu thì không.
4. Dựa trên dữ liệu thực tế. Các mẫu sử dụng thực tế tốt hơn một danh sách cứng nhắc bị lỗi thời.
5. Cung cấp khả năng khám phá máy có thể đọc được thông qua llms.txt, đặc tả OpenAPI hoặc danh sách mô hình có cấu trúc.
6. Giữ tính tương thích ngược. Các trường gợi ý mới nên mang tính bổ sung, không bao giờ gây lỗi.

Bắt đầu từ đâu mà không cần viết lại mọi thứ

Hầu hết các nhóm không cần phải thiết kế lại toàn bộ API của họ trong một tuần. Một điểm khởi đầu nhỏ hơn vẫn hoạt động tốt:

1. Thêm một hoặc hai trường gợi ý máy có thể đọc được vào các lỗi có khối lượng lớn nhất của bạn.
2. Làm cho /v1/models hoặc endpoint khám phá tương đương của bạn trở nên phong phú và rõ ràng hơn.
3. Xuất bản một bản tổng quan máy có thể đọc được, chẳng hạn như llms.txt.
4. Kiểm tra toàn bộ vòng lặp với một client agent thực tế, không chỉ là curl.

Nếu bạn đã vận hành thông qua một lớp gateway, hướng dẫn về gateway AI thống nhất giải thích lý do tại sao mặt phẳng điều khiển đó lại quan trọng. Nếu bạn vẫn đang sử dụng tích hợp tương thích với OpenAI trực tiếp, hướng dẫn di chuyển là nơi dễ nhất để bắt đầu trước khi thêm các hành vi thân thiện với agent.

Câu hỏi thường gặp (FAQ)

Thiết kế API ưu tiên AI agent là gì?

Đó là một phương pháp mà các phản hồi lỗi bao gồm các gợi ý có cấu trúc, máy có thể đọc được (các trường như did_you_mean, suggestions và hint) để các AI agent có thể tự sửa lỗi mà không cần sự can thiệp của con người hoặc tra cứu tài liệu.

Thiết kế ưu tiên AI agent khác với thiết kế API ưu tiên lập trình viên như thế nào?

Các API ưu tiên lập trình viên tối ưu hóa cho khả năng đọc của con người: thông báo rõ ràng, tài liệu tốt, ví dụ hữu ích. Các API ưu tiên AI agent bổ sung các trường có cấu trúc trên nền tảng đó để máy móc có thể phân tích lỗi và hành động theo lập trình, mà không cần đọc bất cứ thứ gì.

Thiết kế ưu tiên AI agent có làm hỏng các client hiện có không?

Không. Các trường mang tính bổ sung. Các client hiện có không tìm kiếm did_you_mean hoặc suggestions sẽ chỉ đơn giản là bỏ qua chúng và tiếp tục hoạt động chính xác như trước đây.

---

TokenLab cung cấp quyền truy cập thống nhất vào hơn 300 mô hình AI, bao gồm các mô hình tiên phong hiện nay như GPT-5.5, Claude Sonnet 5 và Gemini 3.5 Flash, thông qua một API duy nhất được liệt kê trong danh mục mô hình. Bắt đầu miễn phí để kiểm tra API ưu tiên AI agent với $1 tín dụng khởi đầu.