에이전트 우선 API 디자인: AI 에이전트가 실제로 이해할 수 있는 API를 구축하는 방법
대부분의 API는 문서를 읽고, 예제를 탐색하며, 스택 트레이스로 디버깅하는 인간 개발자를 위해 설계되었습니다. 하지만 2026년에는 가장 빠르게 성장하는 API 소비자는 인간이 아닌 AI 에이전트입니다. 그리고 이들은 API와 매우 다르게 상호작용합니다.
이것은 우리가 LemonData의 통합 AI API를 하나의 단순한 원칙, 즉 "똑똑해지려 하지 말고 정보를 제공하라"를 중심으로 재설계한 이야기입니다. 그 결과가 바로 우리가 에이전트 우선(agent-first) API 디자인이라 부르는 것이며, 이를 통해 사용자들의 낭비되는 token을 60% 이상 줄였습니다.
에이전트 우선 API 디자인이란?
에이전트 우선 API 디자인이란 AI 에이전트가 무엇이 잘못되었는지 이해하고 외부의 도움 없이 스스로 수정할 수 있도록 API 응답, 특히 에러 응답을 구조화하는 것을 의미합니다.
전통적인 API 에러:
{"error": {"message": "Model not found"}}
에이전트 우선 API 에러:
{
"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."
}
}
차이점이 무엇일까요? 전통적인 API를 사용하면 에이전트는 웹을 검색하고, 문서를 찾고, HTML을 파싱하고, 추측해야 합니다. 에이전트 우선 API를 사용하면 단 한 단계 만에 스스로 수정합니다.
전통적인 API가 AI 에이전트에게 실패하는 이유
AI 에이전트가 일반적인 API 애그리게이터를 처음 접했을 때 어떤 일이 벌어지는지 살펴보세요:
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"error": {"message": "Model not found"}}
Agent: (searches the web for "lemondata models list")
Agent: (fetches a docs page, maybe the wrong one)
Agent: (parses HTML, finds a model name)
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API: 200 ✓
6단계입니다. 여러 번의 네트워크 요청. 수백 개의 낭비되는 token. 그리고 이것은 에이전트가 올바른 문서 URL을 추측해낸 운 좋은 경우입니다.
에이전트 우선 디자인을 적용하면:
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 ✓
2단계입니다. 웹 검색은 필요 없습니다. 에이전트는 에러 응답만으로 스스로 수정했습니다.
핵심 원칙: 지능은 모델 측에 머물러야 합니다
모델 이름을 자동 수정하거나, 유사한 모델로 조용히 라우팅하거나, 추천 엔진을 추가하는 등 "똑똑한" API를 만들고 싶은 유혹이 생깁니다. 우리는 이 모든 것을 거부했습니다.
에이전트가 model: "gpt5"를 보낼 때, 그 의도를 알 수 없습니다. GPT-5가 존재하는지 테스트하는 것일 수도 있고, 예산 제약이 있을 수도 있으며, 특정 기능이 필요할 수도 있습니다. gpt-4o로 자동 라우팅하면 에이전트가 모르는 사이에 비용, 출력 품질, 기능이 조용히 변경될 것입니다.
올바른 조치는 빠르게 실패하고 정보를 풍부하게 제공하는 것입니다. 에이전트에게 모든 데이터를 제공하고, 에이전트가 결정하게 하세요.
네 가지 에이전트 우선 API 디자인 패턴
패턴 1: 모델을 찾을 수 없음 → 퍼지(Fuzzy) 제안
{
"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."
}
}
did_you_mean 필드는 세 가지 레이어의 해결 방식을 사용합니다: 정적 별칭 매핑(추측이 아닌 실제 운영 데이터 기반), 정규화된 문자열 매칭, 그리고 제한된 편집 거리(edit distance). 모든 후보는 실시간 모델 목록에 대해 검증됩니다. 현재 오프라인 상태인 모델은 절대 제안하지 않습니다.
패턴 2: 잔액 부족 → 예산 인식 대안
{
"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."
}
}
단순히 "돈이 부족하다"고 말하는 대신, 에이전트에게 현재 잔액이 얼마인지, 얼마가 필요한지, 그리고 지불 가능한 모델이 무엇인지 정확히 알려줍니다. 에이전트는 인간의 개입 없이 자율적으로 더 저렴한 AI 모델로 다운그레이드할 수 있습니다.
패턴 3: 모든 채널 실패 → 실시간 대안
{
"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."
}
}
alternatives 목록은 정적이지 않습니다. 이는 채널 상태 데이터에 대한 실시간 쿼리입니다. 에이전트는 현재 실제로 작동 중인 모델에 대한 실시간 정보를 얻습니다.
패턴 4: 속도 제한(Rate Limited) → 정확한 재시도 타이밍
{
"error": {
"code": "rate_limit_exceeded",
"retryable": true,
"retry_after": 8,
"limit": "1000/min",
"remaining": 0,
"hint": "Rate limited. Retry after 8s."
}
}
추측할 필요가 없습니다. 임의의 값에서 시작하는 지수 백오프(exponential backoff)도 필요 없습니다. 에이전트는 정확한 대기 시간을 압니다. 속도 제한을 효과적으로 처리하는 방법에 대한 자세한 내용은 AI API 속도 제한 가이드를 참조하세요.
성공 응답에도 힌트가 포함됩니다
에이전트가 Claude 모델로 /v1/chat/completions를 호출하면 응답에 다음이 포함됩니다:
X-LemonData-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-LemonData-Native-Endpoint: /v1/messages
우리는 에이전트에게 "성공했지만, 더 좋은 방법이 있다"고 말해줍니다. 에이전트는 다음 호출에서 네이티브 엔드포인트로 전환하여, OpenAI 호환 형식에서는 사용할 수 없는 확장 사고(extended thinking)나 프롬프트 캐싱(prompt caching) 같은 기능을 활용할 수 있습니다.
본문은 OpenAI/Anthropic 사양을 따르기 때문에, 이 정보를 응답 본문이 아닌 헤더에 넣었습니다. 헤더는 안전한 확장 포인트입니다.
에이전트 치트 시트로서의 /v1/models 응답
우리는 /v1/models 응답의 모든 모델에 세 가지 필드를 추가했습니다:
category— 채팅 모델, 이미지 생성기, 비디오 모델, 아니면 오디오? 더 이상 이름으로 추측할 필요가 없습니다.pricing_unit— token당, 이미지당, 초당, 요청당. 비용 추정에 필수적입니다.cache_pricing— 업스트림 프롬프트 캐시 가격 및 플랫폼 시맨틱 캐시 할인.
기존 필드(가격, 기능, 별칭, 최대 token)와 결합하여, 에이전트는 단 한 번의 API 호출로 충분한 정보를 바탕으로 모델 선택 결정을 내릴 수 있습니다.
llms.txt: 에이전트가 가장 먼저 읽는 것
우리는 api.lemondata.cc/llms.txt에서 동적 llms.txt를 제공합니다. 이는 전체 API에 대한 기계 판독 가능한 개요입니다. 여기에는 다음이 포함됩니다:
- 작동하는 코드가 포함된 첫 호출 템플릿
- 일반적인 모델 이름(하드코딩이 아닌 사용 데이터에서 자동 생성)
- 파라미터가 포함된 모든 12개 엔드포인트
- 모델 검색을 위한 필터 파라미터
첫 API 호출 전에 이 파일을 읽는 에이전트는 첫 시도에 성공할 가능성이 높습니다.
지식이 아닌 데이터 기반
우리 시스템의 모든 제안은 실제 운영 데이터에서 나옵니다. did_you_mean 별칭 맵은 요청 로그에 기록된 30일간의 실제 model_not_found 에러를 기반으로 생성되었습니다. 모델 제안은 실제 사용 패턴에 따라 정렬됩니다. llms.txt의 "일반적인 모델 이름"은 우리 데이터베이스에서 생성됩니다.
우리는 Redis 정렬 집합(sorted set)에 모든 모델 미스(miss)를 추적합니다. 오타가 충분히 누적되면 별칭 맵으로 승격됩니다. 모델이 오프라인이 되면 모든 제안에서 자동으로 사라집니다. 시스템이 스스로 개선되는 것입니다.
이를 가능하게 만든 설계 제약
우리는 한 가지 규칙을 세웠습니다: 새로운 엔드포인트 없음, 새로운 SDK 없음, 하위 호환성을 깨는 변경 없음. 모든 것이 기존의 OpenAI 호환 에러 형식 내에서 작동해야 했습니다. 새로운 필드는 선택 사항이며, 이를 무시하는 클라이언트는 이전과 동일한 경험을 하게 됩니다.
이 제약 덕분에 아무도 채택하지 않을 정교하고 새로운 API를 만드는 대신, 에이전트가 스스로 수정하는 데 실제로 도움이 되는 정보가 무엇인지 정확히 파악하는 데 집중할 수 있었습니다.
자신의 API에 에이전트 우선 디자인을 적용하는 방법
AI 에이전트가 소비할 API를 구축하고 있다면:
- 모든 에러는 조치 가능해야 합니다 — 무엇이 잘못되었는지, 왜 그런지, 다음에 무엇을 해야 하는지 포함하세요.
- 자동 수정하지 말고 대안을 제시하세요 — 에이전트가 충분한 정보를 바탕으로 결정하게 하세요.
- 산문(prose)이 아닌 구조화된 필드를 사용하세요 —
did_you_mean은 파싱 가능하지만, 문자열 내의 "Did you mean..."은 그렇지 않습니다. - 실제 데이터를 기반으로 제안하세요 — 실제 운영 사용 패턴이 하드코딩된 목록보다 낫습니다.
- 기계 판독 가능한 검색 기능을 제공하세요 —
llms.txt, OpenAPI 사양, 또는 구조화된 모델 목록을 활용하세요. - 하위 호환성을 유지하세요 — 새로운 힌트 필드는 항상 추가적이어야 하며, 기존 기능을 깨뜨려서는 안 됩니다.
FAQ
에이전트 우선 API 디자인이란 무엇인가요?
에이전트 우선 API 디자인은 에러 응답에 구조화되고 기계 판독 가능한 힌트를 포함하여, AI 에이전트가 인간의 개입이나 외부 문서 조회 없이 스스로 수정할 수 있도록 하는 접근 방식입니다.
에이전트 우선은 개발자 우선 API 디자인과 어떻게 다른가요?
개발자 우선 API는 명확한 에러 메시지, 좋은 문서, 유용한 예제 등 인간의 가독성에 최적화되어 있습니다. 에이전트 우선 API는 기계가 프로그래밍 방식으로 파싱하고 조치할 수 있는 구조화된 필드(did_you_mean, suggestions, hint)를 추가합니다.
에이전트 우선 디자인이 기존 클라이언트를 중단시키나요?
아니요. 에이전트 우선 필드는 JSON 응답에 추가되는 필드일 뿐입니다. 이를 모르는 클라이언트는 단순히 무시합니다. 기존 통합은 변경 없이 계속 작동합니다.
LemonData는 에이전트 우선 디자인을 어떻게 구현하나요?
LemonData의 통합 AI API 게이트웨이는 300개 이상의 모든 모델에 구조화된 에러 힌트를 추가합니다. 모든 에러 응답에는 조치 가능한 제안이 포함되며, llms.txt 엔드포인트는 기계 판독 가능한 API 검색 기능을 제공합니다.
LemonData는 단일 API를 통해 300개 이상의 AI 모델에 대한 통합 액세스를 제공합니다. lemondata.cc에서 에이전트 우선 API를 사용해 보세요.
