Hầu hết các API được thiết kế cho các nhà phát triển là con người, những người đọc tài liệu, xem ví dụ và debug bằng stack traces. Nhưng vào năm 2026, những đối tượng tiêu thụ API tăng trưởng nhanh nhất là các AI agent, và chúng tương tác với API theo cách rất khác biệt.
Đây là câu chuyện về cách chúng tôi thiết kế lại unified AI API của LemonData dựa trên một nguyên tắc đơn giản: đừng tỏ ra thông minh, hãy cung cấp thông tin. Kết quả là cái mà chúng tôi gọi là thiết kế API ưu tiên agent (agent-first API design), và nó đã giúp cắt giảm hơn 60% lượng token lãng phí của người dùng.
Thiết kế API Ưu tiên Agent là gì?
Thiết kế API ưu tiên agent có nghĩa là cấu trúc các phản hồi API của bạn, đặc biệt là các phản hồi lỗi, sao cho một AI agent có thể hiểu điều gì đã xảy ra và tự sửa lỗi mà không cần sự trợ giúp từ bên ngoài.
Lỗi API truyền thống:
{"error": {"message": "Model not found"}}
Lỗi API ưu tiên agent:
{
"error": {
"code": "model_not_found",
"message": "Model 'gpt5' not found",
"did_you_mean": "gpt-4o",
"suggestions": [{"id": "gpt-4o"}, {"id": "gpt-4o-mini"}],
"hint": "Use GET /v1/models to list all available models."
}
}
Sự khác biệt là gì? Với một API truyền thống, agent cần tìm kiếm trên web, tra cứu tài liệu, phân tích HTML và đoán. Với một API ưu tiên 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 gây khó khăn cho AI Agent
Hãy xem điều gì xảy ra khi một AI agent truy cập vào một bộ tổng hợp API điển hình lần đầu tiên:
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"error": {"message": "Model not found"}}
Agent: (tìm kiếm trên web cho "lemondata models list")
Agent: (truy cập một trang tài liệu, có thể là trang sai)
Agent: (phân tích HTML, tìm tên model)
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API: 200 ✓
Sáu bước. Nhiều yêu cầu mạng. Hàng trăm token bị lãng phí. Và đây là trường hợp thuận lợi nhất, khi agent đoán đúng URL tài liệu.
Với thiết kế ưu tiên agent:
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"did_you_mean": "gpt-4o", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API: 200 ✓
Hai bước. Không cần tìm kiếm web. Agent tự sửa lỗi chỉ từ phản hồi lỗi.
Nguyên tắc Cốt lõi: Sự thông minh nằm ở phía Model
Có một sự cám dỗ là xây dựng các API "thông minh": tự động sửa tên model, âm thầm điều hướng đến một model tương tự, thêm 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", bạn không biết ý định của nó là gì. Có thể nó đang thử nghiệm xem GPT-5 có tồn tại hay không. Có thể nó có giới hạn về ngân sách. Có thể nó cần một khả năng cụ thể. Việc tự động điều hướng sang gpt-4o sẽ âm thầm thay đổi chi phí, chất lượng đầu ra và các khả năng, tất cả đều diễn ra mà agent không hề hay biết.
Cách tiếp cận đúng đắn là báo lỗi nhanh và báo lỗi kèm thông tin. Hãy cung cấp cho agent tất cả dữ liệu. Hãy để nó tự quyết định.
Bốn Mô hình Thiết kế API Ưu tiên Agent
Mô hình 1: Không tìm thấy Model → Gợi ý xấp xỉ
{
"error": {
"code": "model_not_found",
"did_you_mean": "gpt-4-turbo",
"suggestions": [
{"id": "gpt-4o"},
{"id": "gpt-4o-mini"},
{"id": "claude-sonnet-4-5"}
],
"hint": "Did you mean 'gpt-4-turbo'? Use GET /v1/models to list all available models."
}
}
Trường did_you_mean sử dụng hệ thống phân giải ba lớp: ánh xạ alias 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 (edit distance) có giới hạn. Tất cả các ứng cử viên đều được xác thực so với danh sách model đang hoạt động, vì vậy chúng tôi không bao giờ gợi ý một model hiện đang ngoại tuyến.
Mô hình 2: Không đủ số dư → Các lựa chọn thay thế phù hợp ngân sách
{
"error": {
"code": "insufficient_balance",
"balance_usd": 0.12,
"estimated_cost_usd": 0.35,
"suggestions": [
{"id": "gpt-4o-mini", "estimated_cost_usd": 0.02},
{"id": "deepseek-chat", "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 nó đang có bao nhiêu, nó cần bao nhiêu và những model nào nó có thể chi trả. Agent có thể tự chủ hạ cấp xuống một model AI rẻ hơn mà không cần sự can thiệp của con người.
Mô hình 3: Tất cả các kênh đều lỗi → Các lựa chọn thay thế trực tiếp
{
"error": {
"code": "all_channels_failed",
"retryable": true,
"retry_after": 30,
"alternatives": [
{"id": "claude-sonnet-4-5", "status": "available"},
{"id": "gpt-4o", "status": "available"}
],
"hint": "All channels for 'claude-opus-4-6' temporarily unavailable. Retry in 30s or try an alternative."
}
}
Danh sách alternatives không phải là tĩnh. Đó là một truy vấn trực tiếp dựa trên dữ liệu tình trạng 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 ngay lúc này.
Mô hình 4: Bị giới hạn tốc độ → 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 cần phỏng đoán. Không cần exponential backoff bắt đầu từ các giá trị tùy ý. Agent biết chính xác thời gian chờ đợi. Để biết thêm về cách xử lý rate limits hiệu quả, hãy xem hướng dẫn rate limiting cho AI API 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ột model Claude, phản hồi sẽ bao gồm:
X-LemonData-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-LemonData-Native-Endpoint: /v1/messages
Chúng tôi đang nói với agent: "yêu cầu này đã thành công, nhưng có một cách tốt hơn." Agent có thể chuyển sang endpoint gốc trong lần gọi tiếp theo, để truy cập các tính năng như extended thinking và prompt caching vốn không có sẵn qua định dạng tương thích với OpenAI.
Chúng tôi đặt thông tin này trong headers, không phải trong body của phản hồi, vì body phải tuân theo đặc tả của OpenAI/Anthropic. Headers là điểm mở rộng an toàn.
Phản hồi /v1/models đóng vai trò như một "bí kíp" cho Agent
Chúng tôi đã thêm ba trường vào mỗi model trong phản hồi /v1/models:
category: chat model, image generator, video model, hoặc audio. Không còn phải đoán từ tên model.pricing_unit: theo token, theo ảnh, theo giây, hoặc theo yêu cầu. Cần thiết cho việc ước tính chi phí.cache_pricing: giá prompt cache của nhà cung cấp cộng với chiết khấu semantic cache của nền tảng.
Kết hợp với các trường hiện có (giá cả, khả năng, alias, token tối đa), một agent có thể đưa ra quyết định lựa chọn model đầy đủ thông tin chỉ từ một lần gọi API duy nhất.
llms.txt: Tài liệu đọc đầu tiên của Agent
Chúng tôi cung cấp một tệp llms.txt động tại api.lemondata.cc/llms.txt, một bản tóm tắt mà máy có thể đọc được về toàn bộ API. Nó bao gồm:
- Một template cho lần gọi đầu tiên với mã code mẫu
- Các tên model phổ biến (được tạo tự động từ dữ liệu sử dụng, không phải ghi cứng)
- Tất cả 12 endpoints kèm theo các tham số
- Các tham số lọc để khám phá model
Một agent đọc tệp này trước khi thực hiện cuộc gọi API đầu tiên sẽ có khả năng thực hiện đúng ngay từ lần đầu.
Dựa trên dữ liệu, không dựa trên kiến thức chủ quan
Mọi gợi ý trong hệ thống của chúng tôi đều đến từ dữ liệu thực tế. Bản đồ alias did_you_mean được khởi tạo từ 30 ngày dữ liệu 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 ý model được sắp xếp theo mô hình sử dụng thực tế. Các "tên model phổ biến" trong llms.txt được tạo ra từ cơ sở dữ liệu của chúng tôi.
Chúng tôi theo dõi mọi trường hợp không tìm thấy model trong một Redis sorted set. Khi một lỗi chính tả tích lũy đủ số lần truy cập, nó sẽ được đưa vào bản đồ alias. Khi một model ngoại tuyến, nó sẽ tự động biến mất khỏi tất cả các gợi ý. Hệ thống tự cải thiện chính nó.
Ràng buộc thiết kế giúp mọi thứ vận hành
Chúng tôi đặt ra một quy tắc: không thêm endpoint mới, không thêm SDK mới, không có thay đổi gây phá vỡ (breaking changes). Mọi thứ phải hoạt động 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 vẫn nhận được trải nghiệm giống như trước đây.
Ràng buộc này buộc chúng tôi phải chính xác về những thông tin thực sự giúp 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 áp dụng.
Cách áp dụng Thiết kế Ưu tiên Agent vào API của riêng bạn
Nếu bạn đang xây dựng các API mà AI agent sẽ tiêu thụ:
- Mọi lỗi đều phải có khả năng thực hiện hành động khắc phục. Bao gồm những gì đã sai, tại sao và phải làm gì tiếp theo.
- Gợi ý các lựa chọn thay thế, đừng tự động sửa lỗi. Hãy để agent đưa ra quyết định dựa trên thông tin.
- Sử dụng các trường có cấu trúc, không phải văn bản thuần túy.
did_you_meancó thể phân tích được; "Có phải bạn muốn nói..." trong một chuỗi ký tự thì không. - Căn cứ các gợi ý vào dữ liệu thực tế. Các mô hình sử dụng thực tế tốt hơn các danh sách được ghi cứng.
- Cung cấp khả năng khám phá mà máy có thể đọc được thông qua
llms.txt, đặc tả OpenAPI hoặc danh sách model có cấu trúc. - Duy trì khả năng 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 phá vỡ.
Bắt đầu từ đâu mà không cần viết lại mọi thứ
Hầu hết các đội ngũ không cần phải thiết kế lại toàn bộ API của họ trong một tuần.
Điểm bắt đầu thực tế thường nhỏ hơn:
- thêm một hoặc hai trường gợi ý mà máy có thể đọc được vào các lỗi có lưu lượng cao nhất của bạn
- làm cho
/v1/modelshoặc endpoint khám phá model tương đương trở nên phong phú và rõ ràng hơn - xuất bản một bản tóm tắt mà máy có thể đọc được như
llms.txt - kiểm tra toàn bộ quy trình với một agent client, không chỉ với curl
Nếu bạn đã đang vận hành thông qua một lớp gateway, hướng dẫn về unified AI gateway sẽ cho thấy tại sao lớp đ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 OpenAI trực tiếp, hướng dẫn di chuyển là nơi dễ dàng nhất để bắt đầu trước khi bạn thêm các hành vi thân thiện với agent hơn.
Câu hỏi thường gặp (FAQ)
Thiết kế API ưu tiên agent là gì?
Thiết kế API ưu tiên agent là một cách tiếp cận trong đó 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, cho phép các AI agent 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 bên ngoài.
Thiết kế ưu tiên agent khác với thiết kế ưu tiên nhà phát triển như thế nào?
Các API ưu tiên nhà phát triển tối ưu hóa cho khả năng đọc của con người: thông báo lỗi rõ ràng, tài liệu tốt, ví dụ hữu ích. Các API ưu tiên agent thêm các trường có cấu trúc (did_you_mean, suggestions, hint) mà máy có thể phân tích và thực hiện lập trình được.
Thiết kế ưu tiên agent có làm hỏng các client hiện có không?
Không. Các trường ưu tiên agent mang tính bổ sung, có nghĩa là các client hiện có có thể bỏ qua chúng và tiếp tục hoạt động mà không thay đổi.
LemonData triển khai thiết kế ưu tiên agent như thế nào?
Cổng unified AI API gateway của LemonData thêm các gợi ý lỗi có cấu trúc cho tất cả hơn 300 model. Mọi phản hồi lỗi đều bao gồm các gợi ý có thể thực hiện được và endpoint llms.txt cung cấp khả năng khám phá API mà máy có thể đọc được.
LemonData cung cấp quyền truy cập thống nhất vào hơn 300 model AI thông qua một API duy nhất. Dùng thử miễn phí để kiểm tra API ưu tiên agent với 1$ tín dụng khởi tạo.
