career

Anthropic Claude 최신 소식 — API 버전 2026-10-21 전격 시행, temperature·top_p·top_k 파라미터 삭제 (2026.10.22)

📌 한줄 요약: 2026년 10월 21일(미국 태평양시간), 앤트로픽이 Claude API 버전 2026-10-21 을 배포했습니다. 2023년 6월(2023-06-01) 이후 3년 넘게 사실상 고정이던 버전이 교체된 것입니다. 핵심은 temperature·top_p·top_k 샘플링 파라미터의 완전 삭제입니다. 기본값이라도 보내면 400 에러가 납니다. 여기에 전 언어 SDK 메이저 버전 업(Python 2.0.0, TypeScript 1.0.0 등), ant CLI 2.0.0, 라이선스 MIT → Apache 2.0 전환까지 한꺼번에 묶였습니다. Claude API로 서비스나 사내 자동화를 돌리는 팀이라면 이번 주에 반드시 확인해야 하는 변경입니다.

지난 몇 달 Claude 쪽 소식은 신모델(Opus 5.5 → Sonnet 5.5 → Haiku 5.5)과 요금제, 에이전트 제품(Claude Duet)이 중심이었습니다. 이번 건은 결이 다릅니다. 화면에 보이지 않는, 그러나 코드가 깨지는 종류의 변화입니다. 모델이 좋아지는 뉴스는 구독자 입장에서 반가운 소식이지만, API 버전 교체는 운영 중인 파이프라인이 조용히 멈추는 뉴스입니다.

무슨 일이 있었나 → 가장 큰 변화(샘플링 파라미터 삭제) → 메시지 구조 변경 → Admin API 필드 개명 → 인증·SDK 구조 변경 → 왜 이렇게 바꿨나 → 영향(사용자/개발자) → 마이그레이션 체크리스트 → 전망 순서로 정리했습니다.

1. 무슨 일이 있었나 — 3년 만의 API 버전 교체

Anthropic 공식 문서 「Migrating to API version 2026-10-21」 대표 이미지 앤트로픽 공식 개발자 문서 「Migrating to API version 2026-10-21」 대표 이미지. (이미지 출처: platform.claude.com 공식 문서)

공식 릴리스 노트의 10월 21일 항목은 짧고 건조합니다. “API 버전 2026-10-21을 배포했다.” 그런데 그 한 줄이 뜻하는 무게는 작지 않습니다. Claude API의 anthropic-version 헤더가 2023-06-01에서 2026-10-21로 넘어간 것이기 때문입니다.

한 표로 정리하면 이렇습니다.

항목 내용
배포일 2026년 10월 21일(미국 태평양시간) / 한국시간 10월 22일
새 API 버전 2026-10-21 (이전 2023-06-01)
동시 배포 SDK Python 2.0.0, TypeScript 1.0.0, C# 13.0.0, Go 2.0.0, Java 3.0.0, PHP 1.0.0, Ruby 2.0.0, ant CLI 2.0.0
기본 헤더 새 SDK·CLI는 anthropic-version: 2026-10-21을 기본 전송 (Bedrock·Google Cloud 클라이언트 포함)
라이선스 SDK·CLI가 MIT → Apache License 2.0 으로 변경 (코드 수정 불필요, 의존성 라이선스 목록만 갱신)
Bedrock 제약 2026-10-21은 Claude 4.7 이후 모델에만 적용. 구모델은 기존 SDK 버전 유지 또는 기존 버전 헤더 유지
같은 날 추가 user profiles에 enforcement_status·enforcement_actions 필드 신설

표의 마지막 줄이 앞으로의 방향을 암시합니다. 같은 날 “우리 고객사의 최종 사용자 중 누가 제재·차단됐는지”를 API로 조회하는 필드가 추가됐습니다. 기술적 변경과 정책적 변경이 같이 움직이고 있다는 뜻입니다.

2. 가장 큰 변화 — temperature·top_p·top_k가 사라졌다

이번 버전에서 개발자가 가장 먼저 부딪히는 벽은 이겁니다.

“2026-10-21에서 temperature, top_p, top_k를 보내는 요청은 기본값이어도 400 에러를 반환합니다.”

그동안 관성적으로 넣어두던 코드가 그대로 있다면, 업그레이드하는 순간 모든 요청이 실패합니다. temperature=0으로 “같은 답이 나오게” 맞춰둔 사내 문서 분류기, 요약 파이프라인, 고객 응대 봇이 전부 여기에 해당합니다.

문서가 설명하는 동작은 이렇게 정리됩니다.

구분 2023-06-01 2026-10-21
파라미터 전송 허용 400 에러 (기본값 포함)
SDK 타입 3개 파라미터 존재 타입에서도 제거
CLI 플래그 존재 제거
실제 샘플링 지정값 반영 기본값(temperature 1.0)으로 샘플링

주의할 지점은 “그럼 대체 뭘 쓰면 되나”에 대한 답이 없다는 것입니다. 문서는 “이 효과를 대체하는 다른 설정은 없다(No other setting replaces it)“고 명시합니다. 즉 temperature를 낮춰 출력을 안정화하던 방식은 대체 수단 없이 사라집니다.

다만 영향 범위는 모델에 따라 갈립니다. 문서에 따르면 Claude 4.7 이후 모델은 이미 기본값만 받는 구조라서 체감 변화가 없습니다. 반면 Claude Sonnet 4.6 같은 구모델에서 temperature를 낮춰 쓰던 요청은 그 안정화 효과를 잃습니다. 이 경우 선택지는 두 가지입니다.

  1. 파라미터를 지우고 기본 동작을 받아들인다.
  2. 그 요청만 2023-06-01에 고정한다.

2번은 임시방편이지 해법이 아닙니다. 결국 모델을 올리고 파라미터를 버리는 방향으로 수렴할 수밖에 없습니다.

3. 메시지 구조 변경 — 조용히 400을 뱉는 두 가지

샘플링 파라미터만큼 눈에 띄지 않지만, 실제로 더 많은 코드를 건드리는 변경이 두 개 있습니다.

① assistant 메시지 안의 document 블록 → 400 문서 블록을 assistant 메시지에 직접 넣던 코드는 이제 거부됩니다. user 메시지로 옮겨야 합니다. 단, 웹 fetch 도구 결과처럼 다른 블록 안에 중첩된 문서는 계속 허용됩니다. 즉 “도구가 반환한 문서”는 되고, “내가 assistant 발화에 끼워 넣은 문서”는 안 됩니다.

② user 메시지 안의 citations → 400 text 블록에 비어 있지 않은 citations 배열을 달아 user 메시지로 보내면 400입니다. search_result 블록 안의 경우도 같습니다. 반면 assistant 메시지의 citations(이전 답변을 되돌려 보낼 때)와 문서·검색 결과의 "citations": {"enabled": true} 설정은 그대로 동작합니다.

두 변경의 공통점은 “모델이 만든 것”과 “내가 만든 것”을 구분한다는 점입니다. 출처 표시와 문서 첨부는 모델 출력 영역으로 좁히고, 사용자 입력에는 허용하지 않는 방향입니다. 프롬프트 인젝션 표면을 줄이려는 설계로 읽힙니다.

4. Admin API 필드 개명 — 대시보드가 비는 이유

관리자용 API를 직접 호출해 사내 대시보드를 만든 팀이라면 여기서 조용히 값이 null이 됩니다. 이전 필드명이 응답에서 완전히 빠지기 때문입니다.

엔드포인트 이전 이름 새 이름
RBAC 그룹 (생성·목록·조회·수정) roles role_ids
RBAC 그룹 구성원 (목록·추가) group_id rbac_group_id
RBAC 역할 (목록·조회) name display_name
조직·워크스페이스 rate limit group_type group.type
API 키 (목록·조회·수정) workspace_id scope
Analytics 사용량·비용 리포트 actor.email actor.email_address
Analytics 활동 요약 summaries data

API 키의 workspace_id는 특히 헷갈리는 부분입니다. 기존에는 Default 워크스페이스 키와 전체 워크스페이스 키가 모두 null 이라 둘을 구분할 수 없었습니다. 새 버전에서는 scope를 읽어야 합니다. 특정 워크스페이스에 묶인 키는 scope.workspace_id에 실제 ID가 들어가고, 전체 워크스페이스 키는 {"type": "organization"}이 됩니다. “null이면 Default”라고 가정한 코드는 반드시 수정해야 합니다.

참고로 group_type 쿼리 파라미터와 API 키 목록의 workspace_id 필터는 그대로 유지됩니다. 이름이 바뀐 것은 응답 필드 쪽입니다.

5. SDK 구조 변경 — 인증 헤더부터 타입까지

SDK 쪽은 “라이브러리를 새로 설치했다” 수준이 아니라 코드 구조를 손봐야 하는 변경이 섞여 있습니다.

Anthropic Claude Platform 공식 릴리스 노트 대표 이미지 앤트로픽 공식 「Claude Platform release notes」 대표 이미지. 10월 21일 항목에 API 버전 배포와 SDK 메이저 버전이 함께 기록돼 있습니다. (이미지 출처: platform.claude.com 공식 문서)

① API 키가 X-Api-Key → Authorization: Bearer SDK와 CLI가 키를 보내는 헤더가 바뀝니다. Claude API 자체는 두 헤더 모두 허용하므로 API를 직접 호출하는 코드는 문제없습니다. 문제는 중간에 프록시나 게이트웨이를 두고 X-Api-Key를 읽거나 주입하는 구조입니다. 이 경우 프록시가 키를 못 찾아 인증이 깨집니다. 해결책은 게이트웨이 쪽 헤더 처리를 Authorization으로 바꾸거나, HTTP 클라이언트의 auth 훅에서 X-Api-Key를 다시 붙이는 것입니다.

② Python 클라이언트는 자격증명을 하나만 받는다 api_key와 auth_token을 동시에 넘기면 ValueError 입니다. 게이트웨이용 토큰과 API용 키를 함께 쓰던 구성이라면, auth_token으로 토큰을 넘기고 default_headers에 X-Api-Key를 직접 설정하는 방식으로 바꿔야 합니다.

③ MessageParam이 역할별 유니온으로 분리 Python에서 MessageParam(role="user", content="...")처럼 타입을 호출하는 코드는 TypeError 가 납니다. 이제 UserMessageParam, AssistantMessageParam, SystemMessageParam으로 나뉘었고, 딕셔너리 리터럴({"role": "user", "content": "Hello"})은 그대로 동작합니다. 서브클래싱도 역할별 타입으로 바꿔야 합니다.

④ Text Completions API 제거 TypeScript·Go·Java·Ruby SDK와 CLI에서 레거시 Text Completions가 삭제됐습니다. ant completions create 명령도 사라졌고, ant messages create로 대체해야 합니다. 응답 텍스트 위치도 completion에서 content.0.text로 이동합니다.

⑤ 도구 러너의 클라이언트측 압축 제거 (TypeScript·Ruby) compactionControl 옵션과 관련 모듈이 빠졌습니다. 대신 서버측 압축(compact-2026-01-12 베타 + context_management)으로 옮겨갔습니다. 토큰 임계값은 최소 50,000 입니다.

⑥ 비베타 Models 메서드에서 betas 제거 client.models.list(betas=[...])는 이제 TypeError입니다. 베타 헤더가 필요하면 client.beta.models로 호출해야 합니다.

⑦ CLI에서 --api-key·--auth-token 플래그 삭제 이유는 명확합니다. “명령줄에 값이 있으면 셸 히스토리와 프로세스 목록에 노출되기 때문“입니다. 대신 ANTHROPIC_API_KEY 환경변수, --api-key-stdin, ant auth login을 쓰도록 안내합니다.

6. 왜 이렇게 바꿨나 — 세 가지 해석

공식 문서는 배경을 길게 설명하지 않습니다. 다만 변경 목록을 나열해 보면 방향이 읽힙니다.

첫째, “모델이 파라미터를 무시하는 시대”로 넘어갔다. 문서는 4.7 이후 모델이 이미 기본값만 받는다고 적습니다. 샘플링 제어를 프롬프트와 모델 설계 쪽으로 가져가고, API 표면에서는 걷어내는 흐름입니다. 개발자 입장에서는 제어권이 줄어드는 대신 API가 단순해지는 거래입니다.

둘째, 멀티테넌트 안전 집행이 제품 기능이 됐다. 10월 20일 user profiles가 나왔고, 21일에는 고객사가 자기 최종 사용자의 제재 상태를 조회하는 필드가 붙었습니다. 플랫폼·게이트웨이 사업자에게는 “우리 조직 전체가 정지되는” 리스크를 개별 사용자 단위로 격리할 수 있게 된 셈입니다. 동시에 앤트로픽이 고객의 최종 사용자를 직접 제재할 수 있는 통로가 열린 것이기도 합니다.

셋째, 라이선스가 MIT에서 Apache 2.0으로 갔다. 코드 변경은 필요 없지만, 특허 조항과 상표 조항이 명시적으로 들어오는 차이입니다. 대기업 의존성 심사에서 MIT보다 통과가 수월한 경우가 많습니다. 엔터프라이즈 도입을 겨냥한 정비로 볼 수 있습니다.

7. 영향 — 사용자와 개발자가 체감하는 지점

Claude 앱 사용자(비개발자) 이번 변경은 직접 영향이 거의 없습니다. claude.ai와 모바일 앱, Claude Code의 사용 경험은 그대로입니다. 다만 사내에서 Claude API를 붙여 만든 자동 분류·요약·번역 봇이 있다면, 그 봇이 어느 날 갑자기 응답을 멈출 수 있습니다. “AI로 업무 자동화를 돌리고 있는데 오늘부터 결과가 안 나온다”면 가장 먼저 API 버전을 확인해야 합니다.

개발자·운영자 영향은 네 갈래로 나뉩니다.

영역 체감 증상 확인할 것
요청 실패 모든 호출이 400 temperature·top_p·top_k 잔존 여부
인증 실패 401, 게이트웨이에서 차단 X-Api-Key 의존 프록시
대시보드 공백 값이 null Admin API 개명 필드, API 키 workspace_id
타입 에러 컴파일·타입체크 실패 MessageParam 호출, betas 인자, compactionControl

특히 Bedrock 경유 구성은 별도로 봐야 합니다. 2026-10-21이 Claude 4.7 이후 모델에만 적용되므로, 구모델을 쓰는 워크로드는 SDK만 올리면 오히려 깨질 수 있습니다. 문서가 안내하는 대로 구모델은 기존 버전을 유지하는 편이 안전합니다.

8. 마이그레이션 체크리스트

실무에서 순서를 잘못 잡으면 롤백이 어려워집니다. 문서의 권장 순서를 따라 정리하면 이렇습니다.

  1. 버전을 명시적으로 고정한다. SDK 없이 호출한다면 anthropic-version 헤더를 직접 지정. 지금 당장은 2023-06-01을 유지해도 됩니다.
  2. 코드 수정과 SDK 업그레이드를 한 릴리스로 묶는다. SDK만 먼저 올리면 요청이 새 버전으로 나가면서 수정 전 코드가 곧바로 400을 맞습니다.
  3. temperature류 파라미터를 전부 제거한다. 설정 파일, 환경변수, 프롬프트 템플릿까지 grep 대상입니다.
  4. assistant 메시지의 document, user 메시지의 citations를 정리한다.
  5. 프록시·게이트웨이의 인증 헤더 처리를 확인한다. Authorization으로 바꾸거나 X-Api-Key를 재주입.
  6. Admin API·Analytics 응답을 쓰는 대시보드를 새 필드명으로 바꾼다.
  7. 2026-10-21로 테스트한 뒤 배포한다. 운영과 스테이징의 버전이 갈리지 않게 주의.
  8. 의존성 라이선스 목록에 Apache 2.0을 반영한다. 사내 오픈소스 심사가 있다면 미리 공유.

한 줄로 요약하면 “SDK 업그레이드는 코드 수정과 동시에, 버전 헤더는 명시적으로” 입니다.

9. 전망 — 다음에 올 것

이번 릴리스에서 눈에 띄는 건 “정리”의 성격입니다. Text Completions 삭제, 클라이언트측 압축 제거, 샘플링 파라미터 삭제 — 모두 오래된 표면을 걷어내고 서버 쪽으로 기능을 옮기는 작업입니다. API 버전을 3년 만에 올렸다는 건, 앞으로 버전 교체 주기가 짧아질 수 있다는 신호로도 읽힙니다.

이어서 예상되는 흐름은 세 가지입니다.

  • 에이전트 실행 계층의 표준화. Managed Agents·세션·배포 관련 API가 계속 늘고 있어, “대화 API”보다 “작업 API” 쪽이 중심이 될 가능성이 큽니다.
  • 멀티테넌트 거버넌스 강화. user profiles와 제재 조회 필드가 붙은 이상, 사용량·비용·정책을 최종 사용자 단위로 집계하는 요구가 커집니다.
  • 구모델 지원 축소. Bedrock에서 신버전이 4.7 이후 모델로 제한된 것은, 모델 세대와 API 세대를 묶어 관리하겠다는 뜻으로 보입니다.

결국 이번 변경의 메시지는 단순합니다. “이제 파라미터로 답을 다듬지 말고, 모델과 프롬프트로 다루세요.” 오래된 설정을 그대로 두고 쓰던 자동화일수록 손댈 곳이 많아지는 시점입니다.

마무리 — 지금 해야 할 한 가지

API를 직접 쓰지 않더라도, 사내에 Claude API 기반 자동화가 있는지 한 번 확인해 보는 걸 권합니다. 담당자가 퇴사했거나 외주로 만든 봇이 temperature=0을 달고 돌고 있다면, 업그레이드 시점에 조용히 멈춥니다.

급하지 않다면 버전 헤더를 2023-06-01로 명시해 고정해 두고, 다음 스프린트에 SDK 업그레이드와 코드 수정을 한 커밋으로 묶는 방식이 가장 안전합니다. 반대로 신모델(4.7 이후)로 이미 넘어간 팀이라면, 샘플링 파라미터 제거는 오히려 코드가 깔끔해지는 기회입니다.

정리하자면 이렇습니다.

  • 지금 당장: temperature·top_p·top_k 사용처 검색, 버전 헤더 고정
  • 이번 주 안에: 프록시 인증 헤더, Admin API 필드명 점검
  • 다음 릴리스에: SDK 메이저 업그레이드 + 코드 수정 동시 배포

3년 만의 API 버전 교체는 한 번 지나가면 다시 오지 않는 정리 타이밍입니다. 미루면 미룰수록 구버전에 묶인 코드가 늘어납니다.