AI 에이전트를 위한 API 설계: Idempotency, 기계가 읽을 수 있는 오류 처리 및 202 응답 + Webhooks

대부분의 API는 두 명의 소비자(consumer)를 위해 설계되었습니다. 바로 문서를 읽는 사람과 한 번 코드를 작성한 사람이었습니다. 하지만 AI 에이전트는 그렇지 않습니다. 에이전트는 기계가 읽을 수 있는 설명으로부터 런타임에 엔드포인트를 발견하고, 필드 이름을 패턴 매칭하여 인수를 채우며, 무언가 실패하면 자동으로 재시도하고, 아무도 각 단계를 지켜보지 않아도 다섯 개의 호출을 연결(chain)합니다. 인간에게는 단순히 사용 가능한 API가 에이전트에게는 자주 '잘못 사용될' 수 있으며, 이 오용은 중복 청구 또는 삭제된 기록을 생성할 때까지 성공처럼 보입니다.

좋은 소식은 다음과 같습니다. API를 에이전트 친화적으로 만드는 속성들은 인간 통합자(integrator)에게 도움이 되는 성숙한 API 설계 관행과 동일합니다. 이 글에서는 구체적인 요청 및 응답 형태와 함께 가장 중요한 여섯 가지 사항을 다룹니다.

1. 모든 변경(mutating) 요청은 Idempotent해야 한다 (멱등성)

에이전트는 여러분의 호출을 재시도할 것입니다. 연결이 끊겼거나, 작업 중간에 컨텍스트 창이 압축되었거나, 사용자가 '다시 시도'라고 말했기 때문에 재시도합니다. 만약 POST /charges가 재시도될 때 두 번째 청구를 생성한다면, 에이전트는 결국 하나를 만들 것입니다.

모든 non-GET 작업에는 멱등성 키(idempotency key)를 받아 처리하고 그 결과를 영속화해야 합니다:

POST /v1/refunds HTTP/1.1
Idempotency-Key: ord_8821.refund.2026-10-14.01
Content-Type: application/json
...

첫 번째 요청은 정상적으로 처리됩니다. 동일한 키로 재전송(replay)하면, 원래 성공했든 알려진 방식으로 실패했든 저장된 응답이 반환됩니다. 키는 인증된 클라이언트별로 범위가 지정되어야 하며 문서화된 기간 내에 만료되어야 합니다 (24시간은 일반적인 최소 기준입니다). 이 내용을 작업 설명서에 명시적으로 문서화하세요. 멱등성 키를 아는 에이전트는 스스로 안정적인 키를 생성할 것입니다.

2. 오류는 산문(prose)이 아니라 데이터여야 한다

인간은

세 가지 정보가 에이전트가 다음으로 무엇을 할지 결정하며, 이 세 가지 모두 기계가 읽을 수 있는 본문에 포함되어야 합니다:

• 재시도 가능 여부(Is it retryable)? 불리언 값은 상태 코드 범위에서 추론하는 것보다 훨씬 효과적입니다.
• 언제(When)? 429 및 503의 경우, 추측하기보다는 Retry-After 초를 준수해야 합니다.
• 어떤 인수가 잘못되었는가?(Which argument was wrong?) 필드 수준 오류는 에이전트가 스스로 수정하고 재프롬프트(re-prompt)할 수 있게 하지만, 일반적인 400 응답은 추측하도록 강요합니다.

전체 표준 및 OpenAPI 모델링은 REST error responses in 2026: RFC 9457 Problem Details에서 다루고 있습니다.

3. 장기 작업은 요청을 차단하지 않아야 한다 (Long work never blocks a request)

에이전트는 참을성이 없는 스케줄러와 같습니다: 호출에 45초가 걸리면, 스택의 무언가가 타임아웃되어 재시도할 것입니다. 장기 실행 작업은 즉시 작업을 처리하는 핸들(job handle)과 함께 반환되어야 합니다. 202 Accepted 패턴과 상태 엔드포인트가 에이전트에게 가장 친화적인 형태입니다:

HTTP/1.1 202 Accepted
Location: /v1/jobs/job_4f2a
Retry-After: 5
...

{ "job_id": "job_4f2a", "status": "succeeded", "result_url": "/v1/reports/rpt_91" }

4. 스키마는 엄격하고 명시적이며 컴포넌트를 재사용해야 한다 (Schemas are strict, explicit, and reuse components)

에이전트는 양식을 작성합니다. 에이전트는 양식이 허용하는 만큼 정확하게 작동합니다:

• 요청 본문에는 `

동일한 스키마를 기반으로 생성된 MCP 도구의 경우, 엄격성이 복합적으로 작용합니다: 도구의 입력 스키마가 곧 OpenAPI 스키마이므로 드리프트할 두 번째 설명이 없습니다.

5. 페이지네이션과 이름은 의도적으로 지루하다

영리한 URL과 커서 형식은 사람(링크를 클릭하는)에게는 비용이 들지 않지만, 에이전트(이를 구성하는)에게는 상당한 비용을 초래합니다. 두 가지 규칙이 있습니다:

• 모든 컬렉션은 불변의 페이지네이션 엔벨로프와 불투명한 커서, 그리고 명확한 중단 조건을 반환해야 하며, 무한 배열을 절대 반환해서는 안 됩니다. 자세한 내용은 커서 대 오프셋 페이지네이션: OpenAPI 사양에 무엇을 넣어야 하는가를 참조하세요.
• 작업 동작은 메서드를 따라야 합니다. GET은 절대 변경하지 않으며, DELETE는 Idempotent(멱등성)하고, PUT은 대체하며, PATCH는 업데이트합니다. 에이전트는 HTTP 의미론에서 의도를 추론하므로, 여기서 그들을 놀라게 하는 것은 최악의 유형의 버그를 유발하는데, 이는 호출 자체가 '작동'하기 때문입니다.

6. 모양뿐만 아니라 동작을 설명하라

필드를 나열하는 것만을 담은 OpenAPI 문서는 에이전트가 볼 수 없는 규칙들을 추론하도록 내버려 둡니다. 설명에는 결정을 변경하는 운영적 사실들이 포함되어야 합니다:

paths:
  /v1/orders:
    post:
...

사이드 이펙트, 시간 창(time windows), 등급별 속도 제한(rate limits per tier), 그리고 순서 보장(

이것이 바로 스펙 기반(spec-driven), 로컬 우선(local-first) API 워크스페이스의 핵심 아이디어입니다. 코드가 존재하기 전에 AI의 도움을 받아 계약(contract)을 설계하고, 그로부터 문서(docs), 목업(mocks), 테스트(tests), 그리고 MCP 도구들을 파생시키는 것입니다. 이 흐름은 온라인 데모에서 시도해 볼 수 있으며, 동일한 계약에 대한 테스트 측면은 REST API를 위한 시나리오 테스트에 설명되어 있습니다.