API 버전 2026-10-21로 마이그레이션

이 가이드는 API 버전 2023-06-01에서 2026-10-21로 이전하기 위한 코드 변경 사항을 나열합니다. 업그레이드 단계에서 수행할 작업을 순서대로 설명합니다.

업그레이드 단계

1. 1

   2026-10-21로 전환

   SDK를 사용하는 경우, 요청은 해당 SDK의 메이저 버전이 출시되었을 때 최신이었던 API 버전을 사용합니다. 사용하는 언어에 표시된 버전은 2026-10-21을 사용하는 첫 번째 버전이므로 해당 버전으로 업그레이드하세요. SDK 없이 API를 호출하는 경우 anthropic-version 헤더를 2026-10-21로 설정하세요.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   anthropic 패키지를 버전 2.0.0으로 업그레이드하세요.

   업그레이드는 다음 단계의 수정 사항과 함께 릴리스하세요.

2. 2

   호환성이 깨지는 변경 사항에 맞게 코드 업데이트

   호환성이 깨지는 변경 사항을 검토하고, 영향을 받는 각 항목에 맞게 코드를 업데이트하세요. 또한 새 SDK 또는 CLI 버전에 필요한 코드 변경도 적용하세요.

3. 3

   2026-10-21에 대해 테스트

   릴리스하기 전에 2026-10-21에 대해 통합을 테스트하세요.

호환성이 깨지는 변경 사항

Messages API

이 변경 사항은 Messages API(POST /v1/messages)에 대한 요청, 토큰 카운팅, 그리고 2026-10-21로 생성된 Message Batch의 각 요청에 적용됩니다.

assistant 메시지의 document 블록은 오류를 반환합니다

assistant 메시지에 document 블록을 직접 보내는 경우 영향을 받습니다.

2026-10-21에서는 assistant 메시지에 document 블록을 직접 배치한 요청이 400 오류를 반환합니다. 대신 user 메시지로 문서를 보내세요. Claude가 반환한 웹 페치 도구 결과처럼 다른 블록 안에 중첩된 문서는 여전히 허용됩니다.

user 메시지의 citations는 오류를 반환합니다

search_result 블록 내부를 포함하여 user 메시지의 text 블록에 citations를 보내는 경우 영향을 받습니다.

2026-10-21에서는 user 메시지에 비어 있지 않은 citations 배열이 있는 text 블록을 보내는 요청이 400 오류를 반환합니다. 해당 블록에서 citations를 제거하세요. 다시 보내는 Claude의 이전 응답과 같이 assistant 메시지의 text 블록에 있는 citations는 여전히 허용되며, 문서와 검색 결과의 "citations": {"enabled": true} 설정도 마찬가지입니다.

샘플링 매개변수가 제거되었습니다

Messages 요청 또는 Message Batch 요청에서 temperature, top_p 또는 top_k를 보내는 경우 영향을 받습니다.

2026-10-21에서는 temperature, top_p 또는 top_k를 보내는 요청이 매개변수의 기본값이더라도 400 오류를 반환합니다.

요청에서 세 매개변수를 제거하세요.

최신 메이저 버전부터 SDK와 CLI에는 더 이상 이 세 매개변수가 없습니다.

이러한 매개변수가 없으면 요청은 temperature 1.0을 포함한 기본값으로 샘플링하며, 이는 이 매개변수를 생략한 2023-06-01 요청과 동일합니다. Claude 4.7 이상 모델처럼 이미 기본값만 허용하는 모델은 이전과 같이 샘플링합니다. Claude Sonnet 4.6처럼 다른 값을 허용하는 모델에서는 더 일관된 출력을 위해 temperature를 낮춘 요청이 그 효과를 잃게 됩니다. 이를 대체하는 다른 설정은 없습니다. 요청이 기본값이 아닌 값에 의존하는 경우, 매개변수 전송을 중단하거나 해당 요청을 2023-06-01에 유지하세요.

Admin API 및 Claude Enterprise Analytics API

코드가 다음 표에 있는 Admin API 또는 Claude Enterprise Analytics API 응답 필드를 읽는 경우 영향을 받습니다.

2026-10-21에서는 Admin API와 Claude Enterprise Analytics API의 응답에 이름이 변경된 필드의 이전 이름이 더 이상 포함되지 않습니다. 대신 새 이름을 사용하세요.

Admin API:

Claude Enterprise Analytics API:

속도 제한 목록 엔드포인트의 group_type 쿼리 매개변수와 API 키 목록 엔드포인트의 workspace_id 필터는 변경되지 않았습니다.

API 키의 workspace_id

코드가 API 키의 workspace_id를 읽는 경우 영향을 받습니다.

2023-06-01에서 API 키의 workspace_id는 키가 바인딩된 워크스페이스의 ID이며, Default Workspace에 바인딩된 키와 하나의 워크스페이스에 바인딩되지 않은 키(모든 워크스페이스 키)의 경우 null입니다.

2026-10-21에서는 workspace_id가 제거되었습니다. 대신 scope를 읽으세요. Default Workspace를 포함하여 워크스페이스에 바인딩된 키의 경우 scope.workspace_id는 해당 워크스페이스의 실제 ID이며, 모든 워크스페이스 키는 workspace_id 없이 {"type": "organization"}의 scope를 가집니다.

코드가 null인 workspace_id를 Default Workspace로 처리했다면, 대신 scope.workspace_id를 Default Workspace의 ID와 비교하세요. 해당 ID를 찾으려면 include_default=true로 List Workspaces를 호출하고 이름이 "Default"인 워크스페이스를 가져오세요.

SDK 및 CLI 변경 사항

이전 SDK 및 CLI 버전은 모든 요청에 anthropic-version: 2023-06-01을 보냈습니다. 2026-10-21로 전환에 있는 버전은 2026-10-21을 보냅니다. 호환성이 깨지는 변경 사항의 변경 사항도 이들에 적용됩니다. 제거된 매개변수와 이전 필드 이름은 SDK의 타입과 CLI의 플래그 및 출력에서도 사라졌습니다.

Amazon Bedrock 및 Google Cloud의 API 버전

Google Cloud's Agent Platform용 SDK 클라이언트는 헤더 대신 요청 본문에 버전을 지정합니다. 이전 버전이 vertex-2023-10-16을 보냈던 곳에 anthropic_version: 2026-10-21을 보내며, anthropic-version 헤더는 보내지 않습니다.

Amazon Bedrock 클라이언트도 마찬가지입니다. 이전 버전이 bedrock-2023-05-31을 보냈던 곳에 anthropic_version: 2026-10-21을 보내며, anthropic-version 헤더는 보내지 않습니다. Claude Opus 4.7보다 오래된 모델은 아직 Bedrock에서 API 버전 2026-10-21을 지원하지 않으며, 이를 지정한 요청은 400 오류를 받을 수 있습니다. 이러한 모델 중 하나를 사용하는 경우 당분간 이전 SDK 버전을 유지하거나, 업그레이드한 후 bedrock-2023-05-31을 직접 보내세요.

MessageParam은 역할별로 하나의 타입을 가진 유니온입니다

이전 버전에서 MessageParam은 모든 역할에 대한 하나의 타입이었습니다. 이제 각 역할은 고유한 타입을 가집니다: UserMessageParam, AssistantMessageParam, SystemMessageParam. BetaMessageParam도 같은 방식으로 BetaUserMessageParam, BetaAssistantMessageParam, BetaSystemMessageParam으로 분리됩니다. SDK가 보내는 요청은 이전과 동일한 필드와 값을 가집니다.

# 변경 전
message = MessageParam(role="user", content="Hello")

# 변경 후
message: MessageParam = {"role": "user", "content": "Hello"}

# 변경 전
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    return {"role": role, "content": text}


# 변경 후
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
    if role == "user":
        return {"role": "user", "content": text}
    return {"role": "assistant", "content": text}

값이 하나뿐인 enum은 상수가 됩니다

이 변경은 C#, Go, Java, PHP, Ruby SDK와 CLI 플래그 하나에 영향을 줍니다. 이전 버전에서는 하나의 값만 가질 수 있는 필수 필드가 멤버가 하나뿐인 자체 enum 타입을 가졌습니다. 이제 이러한 필드는 상수이며, 해당 enum 타입은 제거되었습니다. SDK가 보내고 읽는 JSON은 동일합니다.

도구 러너에서 클라이언트 측 압축이 제거되었습니다

이 변경은 TypeScript 및 Ruby SDK에 영향을 줍니다. 도구 러너의 클라이언트 측 "compaction"(압축)은 제거되었으며, 대신 클라이언트의 추가 요청 없이 API 내부에서 대화를 요약하는 서버 측 압축을 사용합니다.

// 변경 전
const runner = client.beta.messages.toolRunner({
  // ...
  compactionControl: { enabled: true, contextTokenThreshold: 100_000 }
});

// 변경 후
const runner = client.beta.messages.toolRunner({
  // ...
  betas: ["compact-2026-01-12"],
  context_management: {
    edits: [{ type: "compact_20260112", trigger: { type: "input_tokens", value: 100_000 } }]
  }
});

트리거 임계값은 최소 50,000 토큰이어야 합니다. 다른 옵션(pause_after_compaction, 사용자 지정 instructions)은 압축을 참조하세요.

Text Completions가 제거되었습니다

레거시 Text Completions API가 TypeScript, Go, Java, Ruby SDK와 CLI에서 제거되었습니다. 최신 모델과 기능은 이를 지원하지 않습니다. 대신 Messages API를 사용하세요.

# 변경 전
ant completions create \
  --model "$MODEL" \
  --max-tokens-to-sample 1024 \
  --prompt $'\n\nHuman: Hello, Claude\n\nAssistant:'

# 변경 후
ant messages create \
  --model "$MODEL" \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

베타가 아닌 Models 메서드에서 betas가 제거되었습니다

베타가 아닌 Models 메서드는 더 이상 betas를 받지 않으며, ant models 명령은 더 이상 --beta를 받지 않습니다. 베타 헤더를 보내려면 client.beta.models에서 같은 메서드를 호출하거나, CLI에서 ant beta:models를 사용하세요. SDK에서 이러한 메서드는 BetaModelInfo를 반환하며, 베타가 아닌 메서드는 ModelInfo를 반환합니다.

# 변경 전
page = client.models.list(betas=[beta])

# 변경 후
page = client.beta.models.list(betas=[beta])

API 키는 Authorization: Bearer로 전송됩니다

SDK와 CLI는 API 키를 X-Api-Key 헤더 대신 Authorization: Bearer <key>로 전송하므로, X-Api-Key를 읽거나 설정하는 프록시 또는 게이트웨이는 Authorization을 사용하도록 변경하거나 키를 직접 X-Api-Key로 보내세요. Claude API는 두 헤더 중 어느 쪽의 키든 허용하므로, API와 직접 통신하는 프로그램은 변경할 필요가 없습니다.

# Before
X-Api-Key: <key>

# After
Authorization: Bearer <key>

프록시 또는 게이트웨이가 X-Api-Key를 읽는 경우

import httpx2
from anthropic import Anthropic, DefaultHttpxClient


def send_x_api_key(request: httpx2.Request) -> httpx2.Request:
    if request.headers.get("Authorization") == f"Bearer {api_key}":
        del request.headers["Authorization"]
        request.headers["X-Api-Key"] = api_key
    return request


client = Anthropic(api_key=api_key, http_client=DefaultHttpxClient(auth=send_x_api_key))

요청에서 X-Api-Key를 설정하거나 제거한 경우

이 변경은 Python, TypeScript, Go, PHP, Ruby SDK에 영향을 줍니다.

요청이 인증 토큰만 보내도록 X-Api-Key를 제거했다면, 해당 코드를 변경하는 대신 삭제하세요. Authorization을 제거하면 토큰이 제거되기 때문입니다. 클라이언트는 하나의 자격 증명을 보유하므로 그것이 토큰인지 확인하세요: 코드에서 아무것도 전달하지 않고 ANTHROPIC_API_KEY와 ANTHROPIC_AUTH_TOKEN이 모두 설정되어 있으면 클라이언트는 키를 사용합니다.

클라이언트는 하나의 자격 증명을 보유합니다

이제 API 키와 인증 토큰이 하나의 헤더를 공유하므로, SDK 클라이언트는 하나의 자격 증명을 보유합니다. 코드에서 아무것도 전달하지 않으면 자격 증명 우선순위 순서를 따릅니다.

client = Anthropic(api_key=key, auth_token=token)

# 이전: `X-Api-Key: <key>` 및 `Authorization: Bearer <token>`을 함께 전송했습니다
# 이후: `ValueError`를 발생시킵니다

하나의 SDK 또는 CLI의 변경 사항

이 변경 사항들은 각각 하나의 SDK 또는 CLI에 영향을 줍니다.

# 변경 전
ant --api-key "$KEY" models list

# 변경 후, 환경 변수에서 가져오기
export ANTHROPIC_API_KEY="$KEY"
ant models list

# 변경 후, 시크릿 관리자에서 가져오기
op read op://vault/anthropic/api-key | ant --api-key-stdin models list

라이선스는 Apache 2.0입니다

이 버전부터 SDK와 CLI는 Apache License, Version 2.0에 따라 라이선스가 부여됩니다. 이전 버전은 MIT License로 유지됩니다. 코드 변경은 필요하지 않습니다. 의존성의 라이선스를 추적하고 있다면 해당 항목을 업데이트하세요.

• TypeScript: 플랫폼 패키지(@anthropic-ai/bedrock-sdk, @anthropic-ai/vertex-sdk, @anthropic-ai/foundry-sdk, @anthropic-ai/aws-sdk, @anthropic-ai/google-cloud-sdk)는 각자의 1.0.0 릴리스에서 라이선스가 변경됩니다.
• C#: 다른 패키지(Anthropic.Bedrock, Anthropic.Vertex, Anthropic.Foundry, Anthropic.Aws, Anthropic.GoogleCloud, Anthropic.Mcp)는 각자의 1.0.0 릴리스에서 라이선스가 변경됩니다.
• Java: 이 변경은 모든 com.anthropic 아티팩트에 적용됩니다.