Agent-First API Design: AI 에이전트가 실제로 이해할 수 있는 API를 구축하는 방법

대부분의 API는 문서를 읽고, 예제를 살펴보고, 스택 트레이스로 디버깅하는 인간 개발자를 위해 구축됩니다. 2026년 현재, API 트래픽의 상당 부분이 AI 에이전트로부터 발생하고 있으며, 이들은 인간과 동일한 방식으로 API와 상호작용하지 않습니다.

이것이 바로 우리가 TokenLab의 통합 AI API를 한 가지 원칙을 중심으로 재설계한 이유입니다. "똑똑하게 보이려 하지 말고, 정보를 제공하라"는 것입니다. 우리는 이 결과를 Agent-First API 설계라고 부르며, 이를 통해 사용자들의 낭비되는 토큰을 60% 이상 절감했습니다.

핵심 요약

• Agent-First API 설계는 에러 응답에 구조화된 기계 판독 가능 힌트를 추가하여, AI 에이전트가 웹 검색이나 인간의 도움 없이 스스로 수정할 수 있도록 합니다.
• 자동 수정 대신 대안을 제시하세요. did_you_mean, suggestions, retryable과 같은 필드를 통해 에이전트가 대신 결정되는 것이 아니라 정보에 입각한 결정을 내릴 수 있게 합니다.
• 모든 제안은 프로덕션 데이터를 기반으로 하므로, 오프라인 상태이거나 지원이 중단된 모델은 후보 목록에 나타나지 않습니다.
• 힌트 필드는 추가적이며 하위 호환성을 유지하므로, 기존의 OpenAI 호환 클라이언트는 변경 없이 계속 작동합니다.

Agent-First API 설계란 무엇인가?

Agent-First API 설계란 응답, 특히 에러 응답을 구조화하여 AI 에이전트가 무엇이 잘못되었는지 이해하고 대화 흐름을 벗어나지 않고 수정할 수 있도록 하는 것을 의미합니다.

기존의 API 에러:

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

Agent-First API 에러:

{
  "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."
  }
}

기존 API를 사용하면 에이전트는 웹을 검색하고, 문서를 찾고, HTML을 파싱하고, 추측해야 합니다. Agent-First API를 사용하면 한 단계 만에 스스로 수정합니다.

기존 API가 AI 에이전트에게 실패하는 이유

에이전트가 일반적인 API 애그리게이터에 처음 접속할 때 어떤 일이 벌어지는지 확인해 보세요:

Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API:   400 {"error": {"message": "Model not found"}}
Agent: (searches the web for "tokenlab 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-5.5"}
API:   200 ✓

6단계, 여러 번의 네트워크 요청, 수백 개의 낭비된 토큰이 발생합니다. 이것은 에이전트가 운 좋게 올바른 문서 URL을 추측했을 때의 '해피 패스'일 뿐입니다.

Agent-First 설계의 경우:

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 ✓

2단계, 웹 검색 제로. 에이전트는 에러 응답만으로 스스로 수정했습니다.

핵심 원칙: 지능은 모델 측에 머물러야 한다

모델 이름을 자동으로 수정하거나, 조용히 유사한 모델로 라우팅하거나, 추천 엔진을 덧붙이는 "똑똑한" API를 만들고 싶은 유혹이 생깁니다. 우리는 그 모든 것을 거부했습니다.

에이전트가 model: "gpt5.5"를 보낼 때, 여러분은 그 의도를 정확히 알 수 없습니다. 어쩌면 더 새로운 GPT 릴리스가 있는지 확인하는 중일 수도 있고, 엄격한 예산 제약이 있을 수도 있으며, 특정 모델만 지원하는 기능을 필요로 할 수도 있습니다. gpt-5.5로 자동 라우팅하면 비용, 품질, 기능이 조용히 변경되며 에이전트는 무슨 일이 일어났는지 결코 알 수 없습니다.

더 나은 방법은 빠르게 실패하고 유익하게 실패하는 것입니다. 에이전트에게 모든 데이터를 제공하고 스스로 결정하게 하세요.

4가지 Agent-First API 설계 패턴

패턴 1: 모델을 찾을 수 없음 → 퍼지 제안(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은 3단계 해상도를 사용합니다: 프로덕션 데이터의 정적 별칭 매핑, 정규화된 문자열 일치, 제한된 편집 거리(edit distance). 모든 후보는 실시간 모델 목록과 대조되므로 현재 오프라인 상태인 모델은 절대 제안하지 않습니다.

패턴 2: 잔액 부족 → 예산 인식 대안

{
  "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."
  }
}

단순히 "잔액 부족"이라고 말하는 대신, 에이전트에게 현재 잔액, 필요한 비용, 지금 바로 사용할 수 있는 저렴한 모델을 정확히 알려줍니다. 에이전트는 인간의 개입 없이 자율적으로 더 저렴한 AI 모델로 다운그레이드할 수 있습니다. 비용 임계값을 하드코딩하기 전에 TokenLab 모델 디렉토리에서 현재 모델별 가격을 확인하세요.

패턴 3: 모든 채널 실패 → 실시간 대안

{
  "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."
  }
}

alternatives 목록은 정적이지 않습니다. 이는 채널 상태 데이터에 대한 실시간 쿼리이므로, 에이전트는 오래된 하드코딩된 폴백 목록이 아니라 현재 실제로 작동 중인 것에 대한 실시간 정보를 얻습니다.

패턴 4: 속도 제한 → 정확한 재시도 타이밍

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

추측도, 임의의 값에서 시작하는 지수 백오프도 없습니다. 에이전트는 정확한 대기 시간을 알고 있습니다. 속도 제한을 잘 처리하는 방법에 대한 자세한 내용은 AI API 속도 제한 가이드를 참조하세요.

성공 응답에도 힌트가 포함된다

에이전트가 Claude 모델로 /v1/chat/completions를 호출하면, 응답에는 다음이 포함됩니다:

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

우리는 에이전트에게 "이것은 성공했지만, 더 좋은 방법이 있다"고 알려주는 것입니다. 에이전트는 다음 호출에서 네이티브 엔드포인트로 전환하여 OpenAI 호환 형식에서는 노출되지 않는 확장된 사고(extended thinking) 및 프롬프트 캐싱과 같은 기능을 사용할 수 있습니다.

이러한 힌트는 응답 본문이 아닌 헤더에 존재합니다. 본문은 OpenAI 또는 Anthropic 사양을 정확히 따라야 하기 때문입니다. 헤더는 기존 파싱 로직을 깨뜨리지 않는 안전한 확장 지점입니다.

에이전트의 치트 시트로서의 /v1/models 응답

우리는 /v1/models 응답의 모든 모델 항목에 세 가지 필드를 추가했습니다:

• category: 채팅 모델, 이미지 생성기, 비디오 모델 또는 오디오. 이름으로 추측할 필요가 없습니다.
• pricing_unit: 토큰당, 이미지당, 초당 또는 요청당. 실제 비용 추정에 필요합니다.
• cache_pricing: 업스트림 프롬프트 캐시 가격과 플랫폼의 시맨틱 캐시 할인.

기존 필드(가격, 기능, 별칭, 최대 토큰)와 결합하여, 에이전트는 단일 API 호출로 완전히 정보에 입각한 모델 선택을 할 수 있습니다. 전체 실시간 카탈로그는 TokenLab 모델 디렉토리(2026-07-07 관측)에서 볼 수 있으며, 현재 Claude Sonnet 5, GPT-5.5, Gemini 3.5 Flash와 같은 최신 프론티어 옵션을 포함하여 채팅, 이미지, 비디오, 오디오 카테고리에 걸쳐 300개 이상의 모델이 나열되어 있습니다. 이 기사의 수치가 현재와 다를 수 있으므로 해당 페이지에서 현재 가격과 가용성을 확인하세요.

llms.txt: 에이전트의 첫 번째 읽기 자료

우리는 api.tokenlab.sh/llms.txt에서 전체 API에 대한 기계 판독 가능한 개요인 동적 llms.txt를 제공합니다. 여기에는 다음이 포함됩니다:

• 작동하는 코드가 포함된 첫 호출 템플릿
• 하드코딩이 아닌 사용 데이터에서 자동 생성된 일반적인 모델 이름
• 매개변수가 포함된 12개의 모든 엔드포인트
• 모델 발견을 위한 필터 매개변수

첫 번째 API 호출 전에 이 파일을 읽는 에이전트는 첫 시도에서 요청을 성공시킬 확률이 훨씬 높습니다.

지식 기반이 아닌 데이터 기반

시스템의 모든 제안은 프로덕션 데이터에서 나옵니다. did_you_mean 별칭 맵은 요청 로그의 30일간의 실제 model_not_found 에러에서 생성되었습니다. 모델 제안은 실제 사용량에 따라 정렬됩니다. llms.txt의 "일반적인 모델 이름" 목록은 수동으로 유지 관리되는 것이 아니라 데이터베이스에서 생성됩니다.

우리는 모든 모델 누락을 Redis 정렬 세트에서 추적합니다. 오타가 충분한 히트를 기록하면 별칭 맵으로 승격됩니다. 모델이 오프라인 상태가 되면 모든 제안 목록에서 자동으로 제외됩니다. 시스템은 시간이 지남에 따라 스스로 조정되며, 이는 GPT-5.5, Claude Sonnet 5, Gemini 3.5 Flash와 같은 새로운 모델 릴리스가 겹치는 일정으로 출시될 때 중요합니다.

성공을 이끈 설계 제약

우리는 한 가지 규칙을 정했습니다: 새로운 엔드포인트, 새로운 SDK, 하위 호환성을 깨는 변경은 없음. 모든 것은 기존의 OpenAI 호환 에러 형식 내에 맞아야 했습니다. 새로운 필드는 선택 사항이므로 이를 무시하는 클라이언트는 이전과 정확히 동일한 경험을 얻습니다.

그 제약은 아무도 채택하려 하지 않을 복잡한 새 API를 만드는 대신, 에이전트가 스스로 수정하는 데 실제로 무엇이 도움이 되는지에 대한 정밀함을 강요했습니다.

자신의 API에 Agent-First 설계를 적용하는 방법

AI 에이전트가 소비할 API를 구축하고 있다면:

1. 모든 에러를 실행 가능하게 만드세요. 무엇이 잘못되었는지, 왜 그런지, 다음에 무엇을 해야 하는지 명시하세요.
2. 자동 수정 대신 대안을 제시하세요. 에이전트가 정보에 입각한 결정을 내리게 하세요.
3. 산문이 아닌 구조화된 필드를 사용하세요. did_you_mean은 파싱 가능하지만, 문장 속에 묻힌 "did you mean..."은 그렇지 않습니다.
4. 실제 데이터에 기반한 제안을 하세요. 프로덕션 사용 패턴이 오래된 하드코딩 목록보다 낫습니다.
5. llms.txt, OpenAPI 사양 또는 구조화된 모델 목록을 통해 기계 판독 가능한 발견 기능을 제공하세요.
6. 하위 호환성을 유지하세요. 새로운 힌트 필드는 추가적이어야 하며, 절대 기존 기능을 깨뜨려선 안 됩니다.

모든 것을 다시 쓰지 않고 시작하는 방법

대부분의 팀은 일주일 만에 전체 API를 재설계할 필요가 없습니다. 더 작은 시작점이 효과적입니다:

1. 가장 볼륨이 큰 에러에 하나 또는 두 개의 기계 판독 가능한 힌트 필드를 추가하세요.
2. /v1/models 또는 이와 동등한 발견 엔드포인트를 더 풍부하고 명시적으로 만드세요.
3. llms.txt와 같은 기계 판독 가능한 개요를 하나 게시하세요.
4. curl뿐만 아니라 실제 에이전트 클라이언트로 전체 루프를 테스트하세요.

이미 게이트웨이 계층을 통해 운영 중이라면 통합 AI 게이트웨이 가이드에서 왜 해당 제어 평면이 중요한지 설명합니다. 여전히 직접적인 OpenAI 호환 통합을 사용 중이라면, 에이전트 친화적인 동작을 계층화하기 전에 마이그레이션 가이드가 시작하기 가장 쉬운 곳입니다.

FAQ

Agent-First API 설계란 무엇인가요?

에러 응답에 구조화된 기계 판독 가능한 힌트(did_you_mean, suggestions, hint와 같은 필드)를 포함하여 AI 에이전트가 인간의 개입이나 문서 조회 없이 스스로 수정할 수 있도록 하는 접근 방식입니다.

Agent-First는 개발자 우선(Developer-First) API 설계와 어떻게 다른가요?

개발자 우선 API는 인간의 가독성(명확한 메시지, 좋은 문서, 유용한 예제)을 최적화합니다. Agent-First API는 그 위에 구조화된 필드를 추가하여 기계가 에러를 파싱하고 프로그래밍 방식으로 조치를 취할 수 있도록 합니다.

Agent-First 설계가 기존 클라이언트를 깨뜨리나요?

아니요. 필드는 추가적인 것입니다. did_you_mean이나 suggestions를 찾지 않는 기존 클라이언트는 단순히 이를 무시하고 이전과 정확히 동일하게 작동합니다.

---

TokenLab은 모델 디렉토리에 나열된 단일 API를 통해 GPT-5.5, Claude Sonnet 5, Gemini 3.5 Flash와 같은 최신 프론티어 모델을 포함한 300개 이상의 AI 모델에 대한 통합 액세스를 제공합니다. 무료로 시작하기를 통해 $1의 시작 크레딧으로 Agent-First API를 테스트해 보세요.