클로드 API(Claude API), 새 버전과 개발 도구에서 호환 규격 변경

API 버전은 프로그램이 어떤 형식으로 정보를 주고받는지를 정하는 약속이다. 앤트로픽은 같은 버전 안에서는 기존 입력·출력 항목을 유지한다는 정책을 두고 있다. 다만 선택 입력이나 새로운 응답 값이 추가될 수 있고 오류 조건도 바뀔 수 있어, 같은 버전을 쓰면 응답이 영원히 완전히 고정된다는 뜻은 아니다. 이번에는 버전 날짜 자체를 바꾸면서 기존 항목을 제거하는 변경을 묶었다.

개발 도구는 이 약속을 프로그램 언어별로 다루기 쉽게 만든다. 공식 SDK는 답변을 조금씩 받는 스트리밍, 실패한 요청의 재시도, 오류 처리 등을 지원한다. 별도의 명령줄 도구는 터미널과 자동 실행 작업에서 API를 부르는 데 쓰인다. 공식 안내는 이 도구들을 에이전트의 실행 과정까지 관리하는 상위 제품과 구분한다. 따라서 이번 개편의 직접 대상은 클로드 호출 코드를 작성하거나 유지하는 개발자다.

메시지 요청에서 눈에 띄는 변경은 답변의 선택 폭을 조절하던 temperature, top_p, top_k 세 항목의 제거다. 새 규격에서는 기본값을 넣어 보내도 요청 형식 오류인 400 오류가 난다. 이전에 다른 값을 허용하던 모델에서 낮은 temperature로 출력 변동을 줄였다면 그 효과도 사라지며, 전환 문서는 이를 대신하는 설정이 없다고 설명한다. 새 버전을 쓰는 것과 과거 설정의 동작을 보존하는 것이 항상 같은 선택은 아니다.

대화 자료를 보내는 방식도 더 엄격해진다. AI 답변 역할의 메시지에 문서 블록을 직접 넣거나, 사용자 메시지의 텍스트에 비어 있지 않은 인용 목록을 넣으면 새 규격이 거부한다. 반면 AI가 돌려준 도구 결과 안에 문서가 들어 있거나, 이전 AI 답변의 인용 정보를 다시 보내는 경우는 허용된다. 문서와 인용 기능을 없앤 변경이 아니라, 어느 역할의 메시지에 어떤 자료를 넣을지 구분한 것이다.

관리·분석용 응답도 영향을 받는다. 공식 버전 기록은 권한 그룹의 역할 목록, API 키가 속한 범위, 사용자별 이용·비용 보고서의 이메일 항목 등에 새 이름을 적용한다고 명시한다. 응답 내용을 읽는 기업의 관리 프로그램에는 모델을 호출하는 부분 외의 수정도 생길 수 있다는 의미다. 특히 새 규격에서 사라진 이름을 계속 찾는 코드는 정보가 있어도 이전 방식으로 꺼내지 못한다.

21일 공개 기록에는 파이썬(Python) SDK 2.0.0과 타입스크립트(TypeScript) SDK 1.0.0을 비롯한 일곱 언어의 새 주요 버전이 올라왔다. 명령줄 도구의 첫 전환 버전은 2.0.0이다. 이 번호들은 새 API 규격을 기본으로 사용하기 시작한 버전을 가리킨다. 현재 도구 안내에 표시되는 후속 버전 번호와 첫 공개 번호를 구분해야 하며, 라이선스 변경도 새 버전부터 적용된다.

API 규격과 개발 도구를 따로 봐야 하는 이유는 공식 버전 정책에도 드러난다. SDK의 주요 버전마다 기본 API 버전이 정해지고, API 버전이 바뀔 때 SDK도 새 주요 버전을 낸다. 따라서 라이브러리 업데이트는 설치 파일만 바꾸는 일이 아니라 서비스가 서버와 주고받는 약속을 바꾸는 계기가 된다. 이번 공개의 실질적인 변화는 새 기능의 숫자보다 기존 서비스의 요청·응답 처리에 명확한 전환 경계가 생겼다는 점이다.