API 팀이 필드 이름을 customer_name에서 customer_full_name으로 변경했습니다. 이들은 변경 사항을 공지하고 문서를 업데이트했으며, 사람이 관리하는 모든 클라이언트는 풀 리퀘스트를 받았습니다. 하지만 에이전트는 아무것도 받지 못했습니다. 아무도 이를 클라이언트로 생각하지 않았기 때문입니다. 에이전트는 계속해서 이전 필드를 전송했고, API는 요청을 수락하고 알 수 없는 키를 무시했으며, 2주 동안 에이전트가 생성한 모든 레코드에는 이름이 비어 있었습니다.
에이전트는 변경 사항을 가장 알아차리기 어렵고, 문제점을 가장 쉽게 덮어버리는 API 소비자입니다. 인간 클라이언트는 예외를 발생시키지만, 에이전트는 200 응답을 읽고 호출이 성공했다고 판단한 후 다음 단계로 넘어갑니다. 때로는 성공처럼 보이는 방식으로 문제를 즉흥적으로 해결하기도 합니다.
이 가이드는 에이전트가 API 변화에 왜 유독 취약한지, 일반적인 클라이언트에게는 문제를 일으키지 않지만 에이전트를 망가뜨리는 변경 사항은 무엇인지, 버전을 고정하고 감지하는 방법, 그리고 실행 전에 CI에서 변화를 포착하는 방법을 다룹니다. 운영 환경에서 AI 에이전트가 고장나는 이유에 대한 저희의 게시물은 실패 모드를 다루며, 이 게시물은 코드베이스 외부에서 발생하는 실패 모드를 다룹니다.
Apidog가 여기서 중요한 이유는 감지가 사양(spec) 문제이기 때문입니다. API 정의의 이전 버전과 현재 버전을 가지고 있다면, 그 차이는 기계적으로 파악할 수 있습니다.
에이전트가 클라이언트보다 변화를 덜 감지하는 이유
네 가지 특성이 좋지 않게 결합합니다.
묵시적 허용. 대부분의 API는 요청 본문의 알 수 없는 필드를 무시합니다. 필드 이름이 변경되면 새로운 필드는 없고 이전 필드는 폐기되며, 200 응답이 나갑니다. 아무런 예외도 발생하지 않습니다.
즉흥적인 처리. 응답에 값이 누락된 경우, 모델은 종종 멈추기보다는 그럴듯한 대체 값으로 계속 진행합니다. 이는 대화에서는 유용한 행동이지만, API를 대상으로 할 때는 위험한 행동입니다.
프롬프트의 설명. 에이전트 도구 설명은 API에 대한 가정을 텍스트로 인코딩합니다. API가 변경되면 설명이 미묘하게 틀어지고, 잘못된 설명은 코드 개입 없이도 잘못된 호출을 생성합니다. 도구 스키마 설계에 대한 저희 게시물에서 해당 텍스트에 얼마나 많은 동작이 의존하는지 다룹니다.
컴파일러 없음. 타입이 지정된 클라이언트는 필드가 사라지면 빌드 시간에 오류가 발생합니다. 에이전트의 계약은 JSON 스키마와 산문에 기반하며, 호출이 실패하기 전까지는 아무도 이를 확인하지 않거나, 더 나쁜 경우, 조용히 실패하지 않을 때까지도 확인하지 않습니다.
결론적으로, 일반적인 클라이언트에게는 안전한 변경 사항이라도 에이전트에게는 항상 안전하지 않을 수 있으므로, 별도로 분류해야 합니다.
실제로 에이전트를 망가뜨리는 변경 사항
일반적인 추가적 변경 대 파괴적 변경 분할은 여전히 적용되지만, 에이전트는 중간 범주를 추가합니다.
모두에게 진정으로 파괴적인 변경. 엔드포인트 제거, 필드 제거, 필드 이름 변경, 유형 변경, 선택적 매개변수를 필수 매개변수로 변경, URL 변경. 에이전트도 여기서 고장나지만, 더 조용히 발생합니다.
타입이 지정된 클라이언트에게는 안전하지만, 에이전트에게는 위험한 변경 사항:
- 새로운 필수 필드. 기존 호출자는 모두 고장나지만, 에이전트는 유효성 검사 오류를 통해 값을 발명하여 수정하려고 시도할 수 있습니다. 이는 심각한 실패보다 더 나쁩니다.
- 새로운 열거형 값. 일반 클라이언트는 처리하지 못하는 값을 무시합니다. 에이전트는 익숙하지 않은 값에 대해 추론하고 제품이 의도하지 않은 결론을 내릴 수 있습니다.
- 강화된 유효성 검사 규칙. 이전에 모든 문자열을 허용했던 필드가 이제 특정 패턴을 요구합니다. 에이전트는 실패를 통해서만 패턴을 배울 수 있으며, 이것이 바로 AI 에이전트를 위한 API 오류 설계에 대한 저희 게시물에서 다루었듯이 규칙이 오류 메시지에 속해야 하는 이유입니다.
- 기본값 변경. 페이지네이션 기본값이 100에서 20으로 떨어지고, 제한(limit)을 전혀 보내지 않던 에이전트는 이제 데이터의 5분의 1만 보고 완전한 것처럼 보고합니다.
- 문서 재작성. 동작 변경은 전혀 없지만, OpenAPI 사양을 에이전트 도구로 변환하는 저희 가이드에서처럼 도구가 사양에서 생성된 경우, 설명 텍스트가 변경되어 도구 선택이 바뀔 수 있습니다.
에이전트에게도 안전한 변경 사항. 선택적 필드 추가, 엔드포인트 추가, 기존 기본값을 유지한 채 선택적 매개변수 추가, 유효성 검사 완화.
중간 목록은 주의해야 할 사항입니다. 표준 변경 검토에서는 아무것도 표시되지 않기 때문입니다.
항상 버전을 고정하세요
첫 번째 방어책은 묵시적으로 움직이는 것을 거부하는 것입니다.
API가 제공하는 메커니즘(경로 세그먼트, 헤더, 계정 수준 고정 등)이 무엇이든 간에 모든 요청에 명시적인 버전을 보냅니다. GitHub의 API 버전 관리 문서는 날짜 헤더를 사용하고, Stripe는 명시적인 업그레이드 단계를 통해 계정별 버전을 고정합니다. 둘 다 동일한 속성을 제공합니다. 즉, 사용자가 결정하기 전까지는 아무것도 변경되지 않습니다.
DEFAULT_HEADERS = {
"X-API-Version": "2026-06-01",
"User-Agent": "billing-agent/1.4 (+https://example.com/agents)",
}
User-Agent는 버전 고정만큼 중요합니다. API 제공자가 호출자에게 사용 중단(deprecation)에 대해 경고해야 할 때, 그들은 트래픽을 살펴봅니다. 자신을 식별하는 에이전트는 이메일을 받지만, 기본 라이브러리 문자열을 보내는 에이전트는 받지 못합니다.
API를 소유하고 있다면, 버전을 발행하고 유지하십시오. 최고의 API 버전 관리 전략에 대한 저희 가이드는 옵션을 다루고, Apidog에서 API 버전 관리는 여러 버전을 동시에 유지하는 방법을 다룹니다.
버전 관리가 전혀 없는 타사 API의 경우, 가능한 것을 고정하십시오. 즉, 구축에 사용한 응답 형태를 기록하고 확인하십시오. 이것이 다음 섹션의 내용입니다.
실행 전에 변화를 감지하세요
고정은 시간을 벌어줍니다. 하지만 궁극적인 업그레이드를 막지는 못하며, 버전 관리 없이 변경되는 API에는 아무런 도움이 되지 않습니다. 그러므로 감지해야 합니다.
정기적으로 사양(spec)을 비교합니다. 제공자가 OpenAPI 문서를 발행한다면, 매일 가져와서 도구를 생성했던 사본과 비교하십시오. 필드 제거, 유형 변경, 요구 사항 추가, 열거형 확장, 설명 편집 등을 확인합니다. Apidog에서는 가져온 정의를 프로젝트에 유지하고 버전 간에 무엇이 변경되었는지 확인할 수 있어 "무언가 변경되었는지" 여부가 조사가 아닌 보고서로 전환됩니다.
호출하는 엔드포인트에 대해 계약 테스트를 수행합니다. 에이전트가 가진 각 도구에 대해 알려진 정상 요청을 보내고 응답 형태를 검증합니다. 즉, 필수 필드가 있는지, 유형이 올바른지, 열거형 값이 예상 범위 내에 있는지 확인합니다. 이는 사양을 전혀 발행하지 않는 API(대부분이 그렇습니다)의 변화를 감지합니다. API 계약 테스트 가이드는 패턴을 다루고, 양방향 계약 테스트는 양쪽에서 실행하는 방법을 다룹니다.
런타임에 형태를 검증합니다. 예상 스키마에 대해 도구 래퍼 내에서 응답을 검증하고, 예상치 못한 것이 나타나면 경고를 기록합니다. 이는 마지막 방어선이며, 아무도 공지하지 않은 변경 사항을 포착하는 방법입니다.
def check_shape(tool_name, payload, expected):
missing = [f for f in expected["required"] if f not in payload]
extra = [f for f in payload if f not in expected["properties"]]
if missing:
log.error("api_drift", tool=tool_name, missing=missing)
raise ApiDriftError(f"{tool_name}: missing fields {missing}")
if extra:
log.warning("api_new_fields", tool=tool_name, fields=extra)
return payload
누락된 필드는 실패로 처리하고, 추가된 필드는 경고합니다. 필수 필드가 누락되면 에이전트가 불완전한 데이터로 작업하게 될 것이므로, 이는 멈춰야 할 가치가 있는 실패입니다. 새 필드는 일반적으로 추가적이며 실행을 방해하지 않고 알아두는 것이 좋습니다. 둘 다 에이전트 도구 호출 추적에 대한 저희 게시물에 설명된 추적 기록으로 보냅니다.
스키마뿐만 아니라 동작도 관찰합니다. 일부 변화는 형태 확인으로는 보이지 않습니다. 예를 들어, 기본값이 변경되거나, 속도 제한이 강화되거나, 응답이 느려지는 경우입니다. 완료된 작업당 호출 수, 엔드포인트당 재시도율, 도구당 평균 응답 크기를 추적합니다. 이들 중 어느 하나라도 급격한 변화가 있다면, 일반적으로 상위 시스템에서 무언가 변경되었음을 의미합니다.
에이전트를 고장내지 않고 업그레이드하기
새 버전으로 이동할 때는 이를 에이전트의 변경 사항으로 취급해야 합니다. 실제로 그러하기 때문입니다.
도구를 수동으로 편집하기보다는 다시 생성하여 설명과 스키마가 함께 움직이도록 합니다. 그런 다음 생성된 도구 정의의 차이점을 읽어보십시오. 이 차이점은 실제 파급 효과이며, API 변경 로그가 암시하는 것보다 작거나 클 수 있습니다.
새 버전의 목업(mock)을 대상으로 에이전트를 실행한 후 실제 환경에 연결하십시오. 이는 가장 가치 있는 단계이자 가장 자주 건너뛰는 단계입니다. 운영 환경 대신 목업을 대상으로 에이전트 실행하기에 대한 저희 게시물에 따라, 새 사양으로 구축된 목업을 사용하면 새 형태에 대해 전체 작업 스위트를 위험 없이 실행할 수 있습니다.
선택 스위트를 다시 실행하십시오. 설명 변경은 모델이 선택하는 도구를 바꿀 수 있으며, 이러한 회귀는 스키마 차이점으로는 보이지 않습니다. 비결정적 에이전트 테스트하기에 대한 저희 가이드에서처럼, 고정된 프롬프트 세트에 대한 도구 선택을 검증하십시오.
이전 버전이 여전히 고정되어 준비된 상태에서 플래그를 통해 트래픽 일부에 배포하십시오. 하루 동안 동일한 네 가지 숫자를 관찰하십시오. 에이전트 회귀는 불만이 제기되기 한참 전에 작업당 더 많은 호출과 더 많은 재시도로 나타납니다.
운영 환경까지 도달한 세 가지 변화
이름이 변경된 필드. 서론에 나온 이야기입니다. 모든 호출에 200 응답, 모든 레코드에 빈 이름. 2주 후 보고서를 읽던 사람에 의해 발견되었습니다. 응답에 대한 런타임 형태 검사는 첫 번째 호출에서 이를 잡아냈을 것입니다. 에이전트가 읽으려고 했던 필드가 사라졌기 때문입니다.
강화된 페이지네이션 기본값. 한 제공자가 기본 페이지 크기를 100에서 20으로 줄였습니다. 에이전트는 limit을 전혀 보내지 않았기 때문에 20개의 레코드만 보고 이를 완전한 세트로 요약하기 시작했습니다. 오류는 발생하지 않았습니다. 요약은 단순히 틀렸고, 자신감 있는 어조로 읽혔습니다. 해결책은 명시적인 limit을 보내는 한 줄짜리 코드였고, 더 넓은 교훈은 다음과 같습니다. 기본값에 의존하면 다른 사람의 결정에 대한 암묵적인 의존성을 갖게 됩니다.
새로운 열거형 값. 결제 API에 status: "disputed"가 추가되었습니다. 타입이 지정된 클라이언트는 이를 무시했습니다. 에이전트는 이에 대해 추론하고, 이의 제기된 청구를 환불로 간주하여, 실제와 다른 결산된 장부를 보고했습니다. 명시적인 열거형 유효성 검사는 모델이 이를 해석하도록 두는 대신 익숙하지 않은 값에 대해 예외를 발생시켰을 것입니다.
패턴은 다음과 같습니다. 각 변경 사항은 공지되었고, 제공자의 자체 분류에 따르면 각 변경 사항은 추가적이거나 사소한 것이었지만, 에이전트에게는 각각 파괴적이었습니다. 그 간극이 바로 설계의 대상입니다.
사용 중단을 작업 항목으로 다루세요
제공자는 일반적으로 경고를 보냅니다. 경고는 변경 로그, 이메일 또는 응답의 Deprecation 헤더로 도착하며, 이들 중 어느 것도 에이전트를 유지 관리하는 사람에게 도달하기 쉽지 않습니다.
이를 일반적인 작업 대기열에 연결하십시오. Deprecation 헤더와 Sunset 헤더는 모두 표준화되어 있으므로, 일반적인 검사가 모든 제공자에 걸쳐 작동합니다. 나타날 때 기록하고, 수천 번째 발견이 아닌 첫 발견 시 경고합니다. 오늘날 호출의 3%에 나타나는 헤더는 서비스 중단 날짜에 완전한 서비스 중단이 됩니다.
또한 인벤토리를 유지하십시오. 어떤 에이전트, 어떤 제공자, 어떤 버전, 어떤 엔드포인트, 그리고 누가 소유하고 있는지. 파일에 열 줄만 있으면 충분합니다. 사용 중단 공지가 도착했을 때, "이것이 우리에게 영향을 미치는가"라는 질문은 검색 작업에 오후를 보내는 것이 아니라 1분 안에 답해야 합니다.
변화는 작업이므로 소유자를 지정하세요
감지는 대기열을 생성합니다. 사양 차이점, 실패한 계약 테스트, 처음으로 발견된 사용 중단 헤더. 각각은 마감 기한이 있는 작은 작업이며, 실패 모드는 서비스 중단 날짜가 올 때까지 아무도 소유하지 않는 채로 채널에 머물러 있는 것입니다.
팀이 이미 작업을 추적하는 곳에 두십시오. 배포된 서비스가 아닌 코딩 런타임으로 에이전트가 실행되는 경우, 이를 관리하는 플랫폼이 루프를 닫을 수 있습니다. Sharkly는 에이전트 또는 크루에 작업을 할당하고 목표, 실행 추적, 검토를 한 곳에 유지하여 "결제 API가 이 엔드포인트를 사용 중단했습니다"가 스레드의 메시지가 아닌 결과와 함께 할당된 작업이 되도록 합니다. 무엇을 사용하든 규칙은 동일합니다. 소유자가 없는 변화 경고는 서비스 중단되는 날 다시 만나게 될 사용 중단입니다.
체크리스트
- 모든 요청은 명시적인 API 버전과 식별 가능한
User-Agent를 보냅니다. - 타사 사양 문서는 정기적으로 가져와서 비교됩니다.
- 에이전트가 호출할 수 있는 모든 도구는 응답 형태를 검증하는 계약 테스트를 가지고 있습니다.
- 도구 래퍼는 런타임에 응답을 검증합니다. 누락된 것은 실패 처리, 새로운 것은 경고 처리합니다.
- 엔드포인트별 동작 메트릭이 추적되어 조용한 변화가 드러나도록 합니다.
- 버전 업그레이드는 도구를 수동으로 편집하는 대신 재생성합니다.
- 새 버전의 목업에 대해 작업 스위트와 선택 스위트 모두 먼저 실행됩니다.
- 롤아웃은 플래그가 지정되고 되돌릴 수 있으며, 이전 버전은 여전히 고정되어 있습니다.
API 팀은 계속해서 변경 사항을 출시할 것이며, 이는 괜찮습니다. 필요한 것은 에이전트가 변화를 알아차리는 클라이언트가 되도록 하는 것이며, 이를 위해서는 버전 고정, 계약 테스트 및 런타임 형태 확인이 필요합니다. Apidog 다운로드를 통해 사양을 비교하고 라이브 실행에 도달하기 전에 다음 버전을 목업하십시오.
자주 묻는 질문
타사 사양의 변경 사항을 얼마나 자주 확인해야 하나요? 대부분의 경우 매일이면 충분하며, 자동화하기 쉽습니다. 게시된 사양이 없는 API의 경우, 외부에서 동일한 변화를 감지하므로 대신 CI에서 실행되는 계약 테스트에 의존하십시오.
항상 가장 오래된 작동 버전으로 고정해야 하나요? 아닙니다. 업그레이드가 의도적으로 이루어지도록 고정하고, 정해진 일정에 따라 업그레이드하십시오. 제거될 때까지 이전 버전을 고수하는 것은 계획된 변경을 비상 상황으로 만듭니다.
변경 후에도 에이전트가 잘 작동한다면요? 가정하기보다는 확인하십시오. 위험한 결과는 이름이 변경된 필드가 조용히 삭제되는 것과 같이 여전히 200을 반환하는 경우입니다. 형태 검증은 성공적인 실행으로는 알 수 없는 것을 알려줍니다.
에이전트를 위해 자체 API의 버전 관리를 다르게 해야 하나요? 다르게 할 필요는 없지만, 더 엄격하게 해야 합니다. 새로운 필수 필드, 새로운 열거형 값, 변경된 기본값을 타입이 지정된 클라이언트에게는 추가적일지라도 에이전트 소비자에게는 파괴적인 것으로 취급하고, 동일한 방식으로 공지하십시오.
어떤 에이전트가 어떤 엔드포인트를 호출하는지 어떻게 알 수 있나요? 추적 기록을 통해 알 수 있습니다. 실행당 도구 이름과 엔드포인트는 종속성 맵을 제공하며, 사용 중단으로 누가 영향을 받는지 정확히 알려줍니다. 에이전트 도구 호출 추적에 대한 저희 게시물에서 기록 형태를 다룹니다.
에이전트가 변경된 API에 스스로 적응할 수 있나요? 때로는 가능하지만, 이에 의존해서는 안 됩니다. 누락된 필드를 즉흥적으로 처리하는 모델은 아무런 문제가 발생하지 않았다는 신호 없이 그럴듯한 출력을 생성합니다. 대신 시끄럽게 실패하고 도구를 수정하십시오.