Claude Platform Docs
모델 및 가격Claude Opus 5.5

Claude Opus 5.5 마이그레이션 가이드

이 마이그레이션 가이드를 통해 이전 Opus 모델 또는 Claude Sonnet 5에서 Claude Opus 5.5로 전환하세요. Claude Opus 5.5를 활성화하기 위한 안내에는 오류를 반환하는 요청 설정, 모든 응답의 사고 블록, 그리고 각 시작 모델별 체크리스트가 포함되어 있습니다.

Claude Code

Claude Code가 코드를 대신 마이그레이션하도록 하세요

/claude-api migrate 이 프로젝트를 claude-opus-5-5 모델로 마이그레이션해 줘

이 페이지에서는 Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 및 이전 Opus 모델, 또는 Claude Sonnet 5에서 Claude Opus 5.5로 전환하기 위한 코드 변경 사항을 나열합니다. 모든 독자는 Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항과 모든 응답에서 사고 처리하기를 읽어야 합니다. 그런 다음 현재 사용 중인 모델에 해당하는 섹션으로 이동하세요. 해당 섹션의 첫 문장에 적용되는 다른 섹션이 명시되어 있습니다. 마이그레이션 체크리스트에는 시작 모델별로 모든 변경 사항이 나열되어 있습니다.

Claude Opus 5.5는 Claude Opus 5보다 비용이 저렴합니다(입력/출력 토큰 100만 개당 $4 / $20 USD로, $5 / $25 USD와 비교됩니다. Claude 가격을 참조하세요). 기능 지원에 대해서는 Claude Opus 5.5의 새로운 기능을 참조하세요. 동작 차이와 모델별 프롬프팅 패턴에 대해서는 Claude Opus 5.5 프롬프팅을 참조하세요.

Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항

어떤 모델에서 전환하든, claude-opus-5-5에 대한 요청은 다음을 충족해야 합니다. 설정이 거부된다고 명시된 항목의 경우, API는 400 오류를 반환합니다.

  • 모델 ID: 날짜 접미사가 없는 고정 모델 ID인 claude-opus-5-5를 사용하세요. Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed), Microsoft Foundry에서는 해당 플랫폼의 모델 ID를 사용하세요. 사용 가능 여부를 참조하세요.
  • 사고: thinking 필드를 보내지 않거나, 이와 동일한 thinking: {"type": "adaptive"}를 보내세요. 적응형 사고는 항상 켜져 있습니다. thinking: {"type": "disabled"}와 수동 사고 예산(thinking: {"type": "enabled", "budget_tokens": N})은 거부됩니다. 사고에 대한 변경 전후 비교를 참조하세요.
  • 노력 수준: 사고 깊이는 이를 제어하는 유일한 요청 매개변수인 effort 매개변수로 제어하세요. 다섯 가지 수준(low, medium, high, xhigh, max)이 모두 지원되며, 기본값은 medium입니다. Claude Opus 5.5 권장 effort 수준을 참조하세요.
  • 도구 선택: tool_choice에 {"type": "auto"}(기본값) 또는 {"type": "none"}을 사용하세요. {"type": "any"} 또는 {"type": "tool", "name": "..."}로 도구 호출을 강제하면 거부됩니다. 도구 선택에 대한 변경 전후 비교를 참조하세요.
  • 샘플링 매개변수: temperature, top_p, top_k를 생략하세요. 모델의 동작을 안내하려면 프롬프팅을 사용하세요.
  • 프리필: messages를 미리 채운 assistant 턴으로 끝내지 마세요. 거부됩니다. 대신 구조화된 출력 또는 시스템 프롬프트 지침을 사용하세요.
  • 컴퓨터 사용: 컴퓨터 사용을 computer_toolset_20260801 도구 세트로 선언하세요. Amazon Bedrock에서는 computer_20251124도 작동합니다. 컴퓨터 사용 호환성 깨짐 변경 사항을 참조하세요.
  • 컨텍스트 윈도우: 컨텍스트 윈도우 베타 헤더가 필요하지 않습니다. 1M 토큰 컨텍스트 윈도우가 기본값이며, 이전 모델용으로 보낸 헤더는 효과가 없습니다.

다음 요청은 목록의 모든 항목을 충족합니다. 노력 수준이 설정되어 있고 thinking 필드가 없습니다. 예제에서 텍스트를 출력하는 경우, thinking 블록이 먼저 오기 때문에 텍스트 블록을 유형으로 찾습니다.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

for block in response.content:
    if block.type == "text":
        print(block.text)

모든 응답에서 사고 처리하기

사고는 모든 Claude Opus 5.5 요청에서 실행되므로, 모든 응답은 thinking 블록으로 시작할 수 있으며 max_tokens는 사고와 텍스트를 모두 포함합니다. 코드가 이미 사고를 켠 상태로 실행되고 있다면 항목 1~3은 이미 적용되어 있을 가능성이 높으므로 항목 4와 5를 확인하세요. 이전 모델에서 사고 없이 실행했다면 각 항목이 모두 변경 사항입니다.

  1. max_tokens는 사고와 텍스트를 모두 포함합니다: Claude Opus 4.8 및 이전 Opus 모델에서는 thinking 필드가 없는 요청이 사고 없이 실행됩니다. Claude Opus 5와 Claude Sonnet 5는 thinking: {"type": "disabled"}를 허용합니다. Claude Opus 5.5에서는 모든 요청이 적응형 사고로 실행됩니다. max_tokens는 여전히 전체 출력(사고와 응답 텍스트)에 대한 엄격한 한도이므로, 사고 없이 실행되던 워크로드에 대해서는 이를 다시 검토하세요. 사고 토큰은 사고 텍스트가 반환되지 않더라도 출력 토큰으로 청구되므로, 이러한 워크로드는 요청당 더 많은 출력 토큰을 생성할 수 있습니다. 비용 제어를 참조하세요. 사고에 사용하는 토큰을 줄이려면 노력 수준을 낮추세요. xhigh 또는 max 노력 수준으로 실행하는 경우, 모델이 사고하고 행동할 여유가 있도록 max_tokens를 크게 설정하세요. 64k 토큰에서 시작하여 조정하세요. 프롬프트가 사고 없이 실행되도록 조정되어 있었다면 사고가 비활성화된 상태를 위해 작성된 프롬프트를 참조하세요.

  2. 응답이 사고 블록으로 시작합니다: 응답은 첫 번째 text 블록 앞에 하나 이상의 thinking 블록으로 시작할 수 있습니다. content[0].text나 첫 번째 content_block_start 이벤트를 텍스트로 처리하는 스트림 핸들러처럼 위치로 응답을 읽는 코드는 이러한 응답에서 오작동합니다. 대신 type 필드로 콘텐츠 블록을 선택하세요. type이 "text"인 블록에서 text를 읽고, 스트림 이벤트를 처리할 때 블록 유형에 따라 분기하세요.

  3. 도구 사용 루프에서 사고 블록을 수정하지 않고 반환하세요: 도구 사용 루프를 실행하는 경우, 도구 결과를 반환할 때 각 어시스턴트 응답의 thinking 블록을 thinking 필드가 비어 있는 블록을 포함하여 완전하고 수정되지 않은 상태로 API에 다시 전달하세요. 콘텐츠 블록을 유형별로 필터링하거나 재구성하지 말고 받은 그대로 어시스턴트 메시지를 반환하세요. API는 편집되거나, 순서가 바뀌거나, 일부가 누락된 사고 블록을 400 오류로 거부합니다. 사고 블록 보존을 참조하세요.

  4. 사고 텍스트는 기본적으로 생략됩니다: thinking.display의 기본값은 "omitted"이므로, thinking 블록은 signature와 함께 빈 thinking 필드로 도착합니다. thinking 필드는 표시용 텍스트로만 취급하세요. 대신 읽을 수 있는 요약을 받으려면 thinking.display를 "summarized"로 설정하세요:

    thinking = {
    "type": "adaptive",
    "display": "summarized",
}

    제품이 사용자에게 추론 과정을 스트리밍하는 경우, 기본값에서는 출력이 시작되기 전에 긴 대기 시간으로 나타납니다. 사고 중에 진행 상황이 보이도록 하려면 display: "summarized"를 설정하세요. 사고 표시 제어를 참조하세요.

  5. 도구 호출 사이의 텍스트는 사고 블록으로 도착합니다: 모델이 도구 호출 사이에 작성하는 짧은 메모는 thinking 블록으로 반환되며, 기본 표시 설정에서는 비어 있습니다. 도구 호출 사이의 텍스트는 사고 블록으로 반환됩니다를 참조하세요.

시작 모델별 마이그레이션 체크리스트

그룹을 순서대로 진행하고 현재 모델이 명시된 그룹에서 멈추세요. 그 지점까지의 모든 항목이 적용됩니다. Claude Opus 5를 사용 중이라면 첫 번째 그룹이 전체 목록입니다. Claude Sonnet 5를 사용 중이라면 첫 번째 그룹과 마지막 그룹을 적용하세요.

모든 시작 모델

  • 모델 ID를 claude-opus-5-5로 업데이트하세요.
  • thinking: {"type": "disabled"}와 thinking: {"type": "enabled", ...}를 제거하고, 대신 effort 수준을 선택하세요.
  • effort를 명시적으로 설정하세요. Claude Opus 5의 기본값은 high이지만, 여기서는 기본값이 medium입니다.
  • tool_choice 유형 any와 tool을 auto와 엄격한 도구 사용 또는 구조화된 출력 조합으로 대체하세요.
  • 이전 컴퓨터 사용 도구 버전을 사용하는 경우, 대신 computer_toolset_20260801(베타 헤더 없음)을 선언하고 도구 세트에 맞게 에이전트 루프를 업데이트하세요. Amazon Bedrock에서는 computer_20251124도 작동합니다.
  • 라우터나 폴백이 대화를 Claude Opus 5.5에서 다른 모델로 옮길 수 있다면, 해당 모델은 Claude Opus 5.5의 사고 블록 없이 실행된다고 예상하세요(Claude API의 Claude Fable 5.1과 Claude Mythos 5.1은 예외로 이를 유지합니다). Claude Opus 5.5 자체는 Claude Opus 5, 이전 Opus, Sonnet, Haiku 모델의 사고를 읽으며, Claude API와 Claude Models on Google Cloud (Google managed)에서는 Claude Sonnet 5.5와 Claude Haiku 5.5의 사고도 읽지만, Claude Fable 또는 Claude Mythos 모델의 사고는 읽지 않습니다.
  • 콘텐츠 블록을 type으로 읽고, 도구 사용 루프에서 thinking 블록을 수정하지 않은 채 다시 전달하세요.
  • 인터페이스가 도구 호출 사이의 텍스트를 렌더링하는 경우, display: "updates"(베타) 또는 "summarized"를 설정하고 비어 있지 않은 thinking 블록을 렌더링하세요.
  • 코드가 대화 도중 이전 턴, system 프롬프트 또는 tools를 편집하는 경우, 보존된 사고를 따르세요.
  • stop_reason: "refusal"을 처리하고 폴백을 구성하세요.
  • 선택한 effort 수준에서 비용과 지연 시간의 기준을 다시 설정하세요.
  • 코드에서 사고를 비활성화했다면, 사고와 응답 텍스트를 모두 포함하는 max_tokens를 재검토하세요. xhigh 또는 max effort에서는 64k부터 시작하세요. 모든 응답에서 사고 처리하기를 참조하세요.

Claude Opus 4.8 이하

  • thinking 필드 없이 실행되던 워크로드를 검토하세요. Claude Opus 5.5에서는 사고와 함께 실행되며, 사고를 비활성화할 수 없습니다. 여전히 전체 출력(사고와 응답 텍스트)에 대한 엄격한 한도인 max_tokens를 다시 검토하고, 사고를 줄이고 싶은 곳에서는 effort를 낮추세요. 사고 토큰은 출력 토큰으로 청구되므로, 이러한 워크로드는 요청당 더 많은 출력 토큰을 생성할 수 있습니다.
  • thinking 필드를 파싱하는 코드가 이를 표시용 텍스트로만 취급하는지 확인하세요. 읽을 수 있는 요약을 받으려면 display: "summarized"를 설정하세요.
  • 캐싱 최소값에 가까운 프롬프트를 검토하세요. 512 토큰 이상의 프롬프트는 캐시 항목을 생성할 수 있습니다.
  • 조직에 Priority Tier 약정이 있는 경우, 용량을 별도로 계획하세요. Priority Tier는 Claude Opus 5.5에서 지원되지 않습니다.
  • xhigh 또는 max 노력 수준으로 실행하는 경우, 시작점으로 max_tokens를 최소 64k로 높이세요.
  • 에이전트 워크로드의 경우, 작업 예산(베타)과 대화 중 도구 변경(베타)을 고려하세요.

Claude Opus 4.7 이하

  • 이전 모델에 맞게 조정된 설정을 그대로 가져오지 말고, 자체 평가에서 노력 수준 스윕을 새로 실행하세요.
  • 컨텍스트 윈도우 베타 헤더를 모두 제거하세요.
  • 지침을 업데이트하기 위해 대화 기록을 재구성하는 경우, 프롬프트 캐시 적중을 유지하기 위해 대화 중 시스템 메시지로 전환하는 것을 고려하세요.
  • 중지 사유 처리 로직이 거부 시 stop_details를 읽는지 확인하세요.
  • Claude Opus 4.7이 거부하는 fast mode를 원한다면, Claude API 요청에 speed: "fast"를 설정하세요. Claude Opus 5.5에는 베타 헤더가 필요하지 않습니다.

Claude Opus 4.6 이하

  • 요청 페이로드에서 temperature, top_p, top_k를 제거하세요.
  • thinking: {"type": "enabled", "budget_tokens": N}을 thinking: {"type": "adaptive"}와 effort 매개변수의 조합으로 대체하거나, thinking 필드를 완전히 제거하세요. 적응형 사고는 항상 켜져 있습니다.
  • UI에 사고 내용을 표시하는 경우, 사고 요약을 명시적으로 선택하세요.
  • 업데이트된 토큰화에서 엔드투엔드 비용과 지연 시간을 다시 벤치마크하세요.
  • 압축 트리거를 포함하여 업데이트된 토큰화를 고려해 max_tokens를 다시 조정하세요.
  • 클라이언트 측 토큰 수 추정치를 다시 테스트하세요.
  • 애플리케이션이 이미지를 전송하는 경우, 고해상도 이미지 지원(전체 해상도 이미지당 최대 약 3배 더 많은 이미지 토큰)에 맞게 예산을 다시 책정하세요. 추가적인 충실도가 필요하지 않다면 전송하기 전에 다운샘플링하세요.
  • 모델에서 포인팅 또는 바운딩 박스 좌표를 사용하는 경우, 배율 변환을 모두 제거하세요. Claude Opus 4.7 이후 모델에서는 좌표가 실제 이미지 픽셀과 1:1입니다.
  • Claude Opus 4.7에서 시작된 동작 변경 사항을 검토하세요.
  • 제품이 정당한 보안 작업을 수행하는 경우, 사이버 콘텐츠에 대한 제한 완화를 위해 Cyber Verification Program에 신청하세요.

Claude Opus 4.5 이하

  • 어시스턴트 메시지 prefill을 모두 제거하세요. Claude Opus 4.6은 이미 이를 거부합니다.
  • 도구 호출 JSON 파싱이 표준 JSON 파서를 사용하는지 확인하세요.
  • client.beta.messages.create()에서 client.messages.create()로 이동하세요. 적응형 사고와 노력 수준에는 베타 네임스페이스가 필요하지 않습니다.
  • effort-2025-11-24 베타 헤더를 제거하세요(effort 매개변수에는 필요하지 않습니다).
  • fine-grained-tool-streaming-2025-05-14 베타 헤더를 제거하세요.
  • interleaved-thinking-2025-05-14 베타 헤더를 제거하세요(적응형 사고는 인터리브 사고를 자동으로 활성화합니다).
  • output_format을 output_config.format으로 마이그레이션하세요(해당하는 경우).

Claude 4.1 이하

  • 도구 버전을 업데이트하세요(text_editor_20250728, code_execution_20260521).
  • refusal 중지 사유를 처리하세요.
  • model_context_window_exceeded 중지 사유를 처리하세요.
  • 도구 문자열 매개변수의 후행 줄바꿈 처리를 확인하세요.
  • token-efficient-tools-2025-02-19 및 output-128k-2025-02-19 베타 헤더를 제거하세요.
  • 프롬프팅 모범 사례에 따라 프롬프트를 검토하고 업데이트하세요.

Claude Sonnet 5 전용

  • 지침을 업데이트하기 위해 대화 기록을 재구성하는 경우, 프롬프트 캐시 적중을 유지하기 위해 대화 중 시스템 메시지로 전환하는 것을 고려하세요.
  • 캐싱 최소값에 가까운 프롬프트를 검토하세요. 512 토큰 이상의 프롬프트는 캐시 항목을 생성할 수 있습니다.

Claude Opus 5에서 Claude Opus 5.5로 마이그레이션하기

먼저 Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항과 모든 응답에서 사고 처리하기를 진행하세요. 모든 시작 모델에는 이 섹션의 변경 사항이 필요합니다. 이는 Claude Opus 5.5가 거부하는 요청 설정과 이에 따른 응답 변경 사항입니다. 이 섹션의 체크리스트는 마이그레이션 체크리스트의 첫 번째 그룹입니다.

모델 이름 업데이트

model = "claude-opus-5"  # Before
model = "claude-opus-5-5"  # After

claude-opus-5-5는 날짜 접미사가 없는 고정 모델 ID로, claude-opus-5와 동일한 체계입니다. Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed), Microsoft Foundry에서는 해당 플랫폼의 모델 ID를 사용하세요. 가용성을 참조하세요.

호환성을 깨는 변경 사항

각 변경 사항은 Claude Opus 5.5의 새로운 기능의 호환성을 깨는 변경 사항에서 설명되어 있으며, 이 섹션에서는 각각에 대한 코드 변경을 제공합니다.

사고를 비활성화할 수 없음

thinking: {"type": "disabled"}와 thinking: {"type": "enabled", "budget_tokens": N}은 모두 400 오류("thinking.type.disabled" is not supported for this model. 또는 "thinking.type.enabled" is not supported for this model.)를 반환합니다. thinking 필드를 제거하고 노력 수준을 선택하세요. 토큰을 절약하기 위해 사고를 비활성화했던 경우에는 더 낮은 수준을 사용하세요. 그러면 응답이 thinking 블록으로 시작하므로, type으로 콘텐츠 블록을 선택하고 도구 결과와 함께 thinking 블록을 수정하지 않고 다시 전달하세요. 사고를 비활성화할 수 없음을 참조하세요.

변경 전. Claude Opus 5는 이 요청을 허용하지만, Claude Opus 5.5는 400 오류로 거부합니다:

client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "..."}],
)

변경 후:

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},  # thinking is always on; effort is the control
    messages=[{"role": "user", "content": "..."}],
)

강제 도구 사용이 지원되지 않음

tool_choice 유형 any와 tool은 토큰 카운팅 엔드포인트를 포함하여 400 오류(tool_choice: type "tool" and "any" are not supported for this model.)를 반환합니다. 엄격한 도구 사용 또는 구조화된 출력과 함께 auto를 사용하고, 도구가 적용되는 경우를 프롬프트에 명시하세요. Strict tool use는 JSON Schema의 일부만 허용하므로, strict: true를 추가하기 전에 각 도구의 input_schema를 확인하세요. 스키마의 모든 객체는 additionalProperties: false를 설정해야 합니다. JSON Schema 제한 사항을 참조하세요. 강제 도구 사용이 지원되지 않음을 참조하세요.

변경 전. Claude Opus 5는 이 요청을 허용하지만, Claude Opus 5.5는 400 오류로 거부합니다:

client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

변경 후:

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    # strict 도구 사용: 모든 호출이 도구의 input_schema와 일치합니다
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[
        {
            "role": "user",
            "content": "What's the weather in Paris? Use the get_weather tool.",
        }
    ],
)

사고 블록은 모델과 대화에 연결됨

Claude API에서 Claude Opus 5.5의 사고 블록을 읽는 모델은 Claude Fable 5.1과 Claude Mythos 5.1뿐이며, 다른 모델은 읽지 않습니다. 대화를 Claude Opus 5.5에서 다른 모델로 옮기는 라우터나 폴백은 해당 턴을 이 블록 없이 실행합니다. 반대 방향으로, Claude Opus 5.5는 Claude Opus 5와 이전 Opus, Sonnet, Haiku 모델의 사고 블록을 읽습니다. Claude API와 Claude Models on Google Cloud (Google managed)에서는 Claude Sonnet 5.5 및 Claude Haiku 5.5의 사고 블록도 읽습니다. 그러나 Claude Fable 또는 Claude Mythos 모델의 사고 블록은 읽지 않습니다. 블록이 유효한 상태로 유지되도록 대화를 “append-only”(추가 전용)로 유지하세요(대화 도중에 system 프롬프트, tools 또는 이전 메시지를 편집하지 마세요). Claude Code, claude.ai, Claude Managed Agents, Claude Agent SDK는 이미 이렇게 하고 있습니다. 2026년 8월 31일 00:00 UTC 당일 또는 그 이후에 생성된 계정에서는 Claude API 및 클라우드 플랫폼에서 이러한 편집 후 사고 블록을 재전송하면서 thinking.block_binding.prefix_mismatch_behavior를 설정하지 않은 요청이 400 오류를 받습니다. 추가 전용 통합의 경우 코드를 변경할 필요가 없습니다. 사고 블록은 모델과 대화에 연결됩니다 및 보존된 사고를 참조하세요.

일부 컴퓨터 사용 도구 버전은 지원되지 않습니다

Claude Opus 5.5는 computer_toolset_20260801 도구 세트를 통해 컴퓨터 사용을 지원합니다. Amazon Bedrock에서는 Claude Opus 5.5가 computer-use-2025-11-24 베타 헤더와 함께 computer_20251124 도구도 허용합니다. Claude Opus 5.5는 Claude API의 computer_20251124처럼 허용하지 않는 컴퓨터 사용 도구 버전에 대해 400 오류를 반환합니다. computer_20250124는 어떤 플랫폼에서도 허용하지 않습니다. Claude API에서 오류 메시지는 'claude-opus-5-5' does not support tool types: computer_20251124.로 시작하며, 이어서 모델이 허용하는 도구 유형을 나열합니다.

도구 세트를 사용하는 통합은 변경이 필요하지 않습니다. computer_20251124 통합을 도구 세트로 옮기려면 베타 헤더를 제거하고 name이나 디스플레이 크기 없이 computer_toolset_20260801 항목을 보내세요. 에이전트 루프에서는 한 턴의 모든 멤버 tool_use 블록을 처리하고 모든 결과에 toolset_name을 그대로 반환하세요. 액션은 input.action이 아니라 각 블록의 name에서 읽으세요. computer_20251124에서 마이그레이션에 에이전트 루프 변경 사항이 나열되어 있습니다.

변경 전. Claude Opus 5는 이 요청을 허용하지만, Claude Opus 5.5는 Claude API에서 400 오류와 함께 이를 거부합니다:

client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["computer-use-2025-11-24"],
    tools=[
        {
            "type": "computer_20251124",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
        }
    ],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

변경 후:

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    # 베타 헤더 없음. 도구 세트 항목은 이름이나 디스플레이 크기를 받지 않습니다
    tools=[{"type": "computer_toolset_20260801"}],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

도구 호출 사이의 텍스트는 사고 블록으로 반환됩니다

Claude Opus 5에서는 모델이 도구 호출 사이에 작성하는 텍스트가 text 블록으로 반환됩니다. Claude Opus 5.5에서는 Claude Fable 5.1에서와 마찬가지로, 그러한 설명이 진행 상황 업데이트 thinking 블록으로 반환되며, 각 도구 호출 앞에 최대 하나씩 옵니다. thinking.display의 기본값인 "omitted"에서는 이들의 thinking 필드가 비어 있습니다. 실패하는 요청은 없지만, 해당 텍스트를 진행 상황 업데이트로 사용자에게 스트리밍하는 애플리케이션은 도구 호출 사이에 아무것도 표시하지 않게 됩니다. 업데이트를 복원하려면 thinking 블록에서 이를 읽고 텍스트를 반환하는 display 값을 설정하세요. "updates"(베타, thinking-display-updates-2026-08-18 헤더)는 추론은 숨긴 채 진행 상황 업데이트를 반환하고, "summarized"는 둘 다 섞어서 반환합니다. 그런 다음 비어 있지 않은 각 thinking 블록을 그 뒤에 오는 tool_use 블록 앞에 렌더링하고, 나머지 어시스턴트 턴과 함께 블록을 변경하지 않고 다시 전달하세요. 사용자 대상 진행 상황 업데이트를 참조하세요.

안전 분류기와 폴백

Claude Opus 5.5는 stop_details 카테고리와 함께 stop_reason: "refusal"을 반환할 수 있습니다. 분류기는 Claude Opus 5보다 더 넓은 범위의 카테고리를 다루므로, "cyber"와 "reasoning_extraction" 외에도 "bio"와 같은 stop_details.category 값을 예상하세요. 거부 카테고리 표를 참조하세요. 거부를 처리하고 서버 측 폴백 또는 자체 재시도를 구성하세요(서버 측 폴백은 "reasoning_extraction"으로 거부된 요청을 재시도하지 않으며, 해당 거부는 그대로 반환됩니다). 거부와 폴백과 안전장치 거부를 참조하세요.

  1. 노력 수준 스윕을 다시 실행하세요. 노력 수준은 Claude Opus 5.5에서 유일한 사고 제어 수단이며, 기본값은 medium입니다(Claude Opus 5의 기본값은 high). 따라서 effort를 생략한 요청은 이제 medium으로 실행됩니다. 품질이 유지되는 곳에서는 수준을 낮추고, 가장 까다로운 작업에서는 수준을 높이세요. 노력 수준을 참조하세요.
  2. 모델별 프롬프트 지침을 재평가하세요. Claude Opus 5의 동작에 맞게 조정된 지침은 더 이상 필요하지 않을 수 있습니다. Claude Opus 5.5 프롬프팅을 참조하세요. 사고를 비활성화한 상태로 실행했다면 사고가 비활성화된 상태를 위해 작성된 프롬프트도 참조하세요.
  3. 프로덕션 트래픽을 전환하기 전에 개발 환경에서 테스트하세요.

Claude Opus 4.8에서 Claude Opus 5.5로 마이그레이션하기

먼저 Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항, 모든 응답에서 사고 처리하기, Claude Opus 5에서 Claude Opus 5.5로 마이그레이션하기를 진행하세요. 교체할 모델 ID로는 claude-opus-4-8을 사용하세요. 마지막 섹션은 Claude Opus 4.8의 코드에 그대로 적용됩니다. Claude Opus 4.8은 Claude Opus 5와 마찬가지로 다음과 같기 때문입니다:

  • thinking: {"type": "disabled"}, 강제 도구 선택, computer_20251124 도구를 허용합니다.
  • 도구 호출 사이의 텍스트를 text 블록으로 반환합니다.
  • 기본 노력 수준이 high입니다.

이 섹션에서는 Claude Opus 4.8과 Claude Opus 5 사이에 변경된 사항을 추가로 다룹니다. 체크리스트는 마이그레이션 체크리스트의 처음 두 그룹을 참조하세요.

변경 사항

  1. 사고를 생략한 요청에서도 사고가 실행됩니다: Claude Opus 4.8에서는 요청하지 않는 한 사고가 꺼져 있습니다. Claude Opus 5.5에서는 thinking 필드가 없는 요청도 사고와 함께 실행되므로, 모든 응답에서 사고 처리하기의 모든 항목이 해당 코드에 대한 변경 사항입니다. 코드가 thinking 필드를 보낸 적이 없다면, 사고에 대한 변경 전후에서 제거할 것은 없습니다.

  2. 더 낮은 프롬프트 캐싱 최소값: Claude Opus 5.5의 최소 캐시 가능 프롬프트 길이는 512 토큰으로, Claude Opus 4.8의 1,024 토큰에서 줄어들었습니다. Claude Opus 4.8에서 캐시하기에 너무 짧았던 프롬프트도 코드 변경 없이 캐시 항목을 생성할 수 있습니다. 모델별 최소값은 프롬프트 캐싱을 참조하세요.

  3. Priority Tier가 지원되지 않음: Priority Tier는 Claude Opus 5.5에서 지원되지 않지만, Claude Opus 4.8에서는 유지됩니다. 조직에 Priority Tier 약정이 있는 경우, 용량을 별도로 계획하세요.

다음은 필수는 아니지만 사용 경험을 개선해 줍니다:

  1. 작업 예산 고려(베타): 에이전트 워크로드의 경우, “task budget”(작업 예산)은 전체 에이전트 루프에서 사용할 수 있는 토큰 수를 모델에 알려줍니다. 작업 예산을 사용하려면 task-budgets-2026-03-13 베타 헤더가 필요합니다.

  2. 대화 중 도구 변경 고려(베타): “Mid-conversation tool changes”(대화 중 도구 변경)를 사용하면 이전 턴의 “prompt caching”(프롬프트 캐싱) 적중을 무효화하지 않고 대화 턴 사이에 도구를 추가하거나 제거할 수 있습니다. tools 배열 자체를 변경하면 캐시된 접두사가 무효화됩니다. Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed)에서는 inline-tools-2026-09-15 베타 헤더를 보내세요. mid-conversation-tool-changes-2026-07-01 헤더는 Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed)에서 참조로 도구 이름을 지정하는 변경에 대해 작동합니다.

Claude Opus 4.7에서 Claude Opus 5.5로 마이그레이션하기

먼저 Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항, 모든 응답에서 사고 처리하기, Claude Opus 5에서 Claude Opus 5.5로 마이그레이션하기, Claude Opus 4.8에서 Claude Opus 5.5로 마이그레이션하기를 진행하세요. 교체할 모델 ID로는 claude-opus-4-7을 사용하세요. 이 섹션들은 Claude Opus 4.7의 코드에 그대로 적용됩니다. Claude Opus 4.8과 마찬가지로 Claude Opus 4.7은 thinking: {"type": "disabled"}, 강제 도구 선택, computer_20251124 도구를 허용합니다. 기본 노력 수준은 high이며, 요청하지 않는 한 사고 없이 실행됩니다.

이 섹션에서는 Claude Opus 4.7 이후에 변경된 사항을 추가로 다룹니다. 코드가 Claude Opus 4.6 이하에 있다면, 이 섹션 다음에 Claude Opus 4.6 및 이전 Opus 모델에서 Claude Opus 5.5로 마이그레이션하기를 계속 진행하세요. 해당 섹션에서는 Claude Opus 4.7에서 적용된 호환성을 깨는 변경 사항을 추가로 다룹니다. 체크리스트는 마이그레이션 체크리스트의 처음 세 그룹을 참조하세요.

변경 사항

이 항목들 중 어느 것도 앞 섹션의 변경 사항에 호환성을 깨는 변경을 추가하지 않지만, 모델 ID를 교체한 후 확인해 볼 가치가 있습니다.

  1. “Effort”(노력) 수준 재조정: 각 effort 수준의 토큰 할당이 Claude Opus 4.7에 비해 Claude Opus 5.5에서 변경됩니다. 기본값은 medium이며, Claude Opus 4.7의 기본값은 high입니다. Claude Opus 4.7에 맞춰 조정된 설정을 그대로 가져오기보다는 자체 평가에서 effort를 새로 비교 테스트하세요. 노력 수준을 참조하세요.

  2. 1M 컨텍스트 윈도우가 기본값: Claude Opus 5.5는 베타 헤더 없이 기본적으로 전체 1M 토큰 “context window”(컨텍스트 윈도우)를 제공합니다. 이전 모델과의 호환성을 위해 클라이언트가 컨텍스트 윈도우 베타 헤더를 전달하고 있다면 이를 제거하세요.

  3. 대화 중 시스템 메시지: Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed)에서 Claude Opus 5.5는 messages 배열에서 사용자 턴 바로 다음에 오는 role: "system" 메시지를 허용합니다(배치 규칙 적용). 처음부터 적용되는 지침에는 최상위 system 필드를 사용하세요. Claude Opus 4.7은 messages에 포함된 role: "system"을 400 오류로 거부합니다. 지침을 업데이트하기 위해 전체 메시지 기록을 다시 구성하는 코드 경로를 유지 관리하고 있다면, 이를 단순화하고 이전 턴의 프롬프트 캐싱 적중을 유지할 수 있습니다.

  4. 거부 중지 세부 정보: 모델이 요청을 거부하면 Claude Opus 5.5는 refusal 중지 이유와 함께 거부 범주를 명시하는 stop_details 객체를 반환합니다. Claude Opus 4.7도 동일한 객체를 반환하므로, 이는 중지 이유 처리 로직이 아직 이 객체를 읽지 않는 경우에만 중요합니다. 베타 헤더는 필요하지 않으며, 옵트아웃할 수 없습니다. 중지 이유 처리 로직이 아직 이 객체를 읽지 않는다면 중지 이유 처리를 참조하세요. Claude Opus 5.5는 더 많은 범주에서 요청을 거부합니다. 안전 분류기 및 폴백을 참조하세요.

  5. 빠른 모드: Claude Opus 5.5는 Claude API에서 “fast mode”(빠른 모드)를 지원합니다. 빠른 모드는 Claude Opus 4.7에서는 사용할 수 없으며, speed: "fast"를 포함한 요청은 오류를 반환합니다. 요청에 speed: "fast"를 설정하세요. Claude Opus 5.5에는 베타 헤더가 필요하지 않습니다.

  6. 컴퓨터 사용 도구 세트 및 브라우저 사용 도구: Claude Opus 5.5는 “computer use”(컴퓨터 사용)를 computer_toolset_20260801 도구 세트로 지원하며, 웹 페이지 내 작업을 위한 “browser use tool”(브라우저 사용 도구)도 지원합니다. Claude Opus 4.7은 둘 다 지원하지 않습니다. computer_20251124 통합을 도구 세트로 옮기려면 컴퓨터 사용 호환성을 깨는 변경 사항을 참조하세요.

Claude Opus 4.6 및 이전 Opus 모델에서 Claude Opus 5.5로 마이그레이션

먼저 앞의 모든 섹션을 페이지 순서대로 진행하세요. 해당 섹션은 Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항, 모든 응답에서 사고 처리하기, 그리고 Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7에 대한 섹션입니다. 이 섹션들은 Claude Opus 4.6의 코드에 그대로 적용됩니다. Claude Opus 4.7과 마찬가지로 Claude Opus 4.6은 thinking: {"type": "disabled"}, 강제 도구 선택(forced tool choice), computer_20251124 도구를 허용합니다. 기본 노력 수준은 high이며, 요청하지 않는 한 사고 없이 실행됩니다. Claude Opus 4.5 및 이전 Opus 모델도 thinking: {"type": "disabled"}와 강제 도구 선택을 허용하고 요청하지 않는 한 사고 없이 실행되므로, 이 섹션들은 해당 모델에도 적용됩니다.

이 섹션은 Claude Opus 4.7에서 변경된 사항을 추가로 다루며, 교체할 모델 ID는 claude-opus-4-6입니다. 두 개의 하위 섹션은 Claude Opus 4.5 이하 및 Claude 4.1 이하를 사용하는 독자를 위해 그 이전에 변경된 사항을 추가로 다룹니다. 체크리스트는 마이그레이션 체크리스트에서 사용 중인 모델이 명시된 그룹까지 참조하세요.

호환성이 깨지는 변경 사항

  1. 확장 사고 제거: thinking: {"type": "enabled", "budget_tokens": N}은 Claude Opus 4.7 및 이후 모델에서 더 이상 지원되지 않으며 400 오류를 반환합니다. 적응형 사고(thinking: {"type": "adaptive"})로 전환하고 노력 수준 매개변수를 사용하여 사고 깊이를 제어하세요. Claude Opus 5.5에서는 적응형 사고가 항상 켜져 있습니다. thinking: {"type": "adaptive"}는 유효하며 thinking 필드를 완전히 생략하는 것과 동일합니다.

    이전(Claude Opus 4.6):

    client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "..."}],
)

    이후(Claude Opus 5.5), 모델 ID, thinking, output_config 줄이 다릅니다:

    client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

    적응형 사고는 프롬프트와 노력 수준 매개변수를 통해 조정할 수 있으며, 노력 수준 매개변수는 모델이 추론하는 양을 제어하는 방식으로서 사고 예산을 대체합니다. budget_tokens 값을 변환하는 대신 자체 평가에서 노력 수준 스윕(effort sweep)을 실행하세요. 노력 수준 표는 각 수준을 언제 사용해야 하는지 설명하며, Claude Opus 5.5에 권장되는 노력 수준은 이 모델에 대해 다룹니다.

  2. 샘플링 매개변수 제거: temperature, top_p, top_k를 생략하세요. Claude Opus 5.5에서 모델 동작을 안내하는 권장 방법은 프롬프팅입니다. 결정론적 출력을 위해 temperature = 0을 사용하고 있었다면, 이전 모델에서도 이것이 동일한 출력을 보장하지는 않았다는 점에 유의하세요.

  3. 기본적으로 사고 내용 생략: Claude Opus 4.7 및 이후 모델에서도 사고 블록은 여전히 응답 스트림에 나타나지만, 명시적으로 옵트인하지 않는 한 thinking 필드는 비어 있습니다. 이는 요약된 사고 텍스트를 반환하는 것이 기본값이었던 Claude Opus 4.6에서 조용히 변경된 사항입니다. 이를 복원하려면 모든 응답에서 사고 처리하기의 4번 항목을 참조하세요.

  4. 업데이트된 토큰 계산: Claude Opus 4.7은 새로운 토크나이저를 도입했으며, Claude Opus 5.5를 포함한 이후 Opus 모델도 이를 사용합니다. 이 토크나이저는 다양한 작업에서 성능 향상에 기여하며, Claude Opus 4.7 이전 모델과 비교하여 텍스트 처리 시 약 1배에서 1.35배의 토큰을 사용할 수 있습니다(콘텐츠에 따라 최대 약 35% 더 많음).

    /v1/messages/count_tokens는 Claude Opus 5.5에 대해 Claude Opus 4.6과 다른 토큰 수를 반환합니다. 토큰 효율성은 워크로드 형태에 따라 달라질 수 있습니다.

    압축(compaction) 트리거를 포함하여 추가 여유 공간을 확보하도록 max_tokens 매개변수를 업데이트하고, 클라이언트 측에서 토큰을 추정하거나 고정된 토큰 대 문자 비율을 가정하는 모든 코드 경로를 다시 테스트하세요. 확인하려면 토큰 계산 엔드포인트를 사용하세요. 프롬프트 조정, task_budget, effort는 비용 제어에 도움이 될 수 있지만, 이러한 제어 수단은 모델 지능과 상충될 수 있습니다.

  5. 프리필 제거(Claude Opus 4.6에서 이미 적용됨): Claude Opus 5.5를 포함한 Claude Opus 4.6 및 이후 Opus 모델에서는 어시스턴트 메시지를 프리필하면 400 오류가 반환되므로, 이는 Claude Opus 4.5 이하에서 마이그레이션하는 경우에만 변경 사항에 해당합니다. 대신 구조화된 출력이나 시스템 프롬프트 지침을 사용하세요.

동작 변경 사항

Claude Opus 4.7은 API 호환성을 깨뜨리지 않는, Claude Opus 4.6과의 동작상 차이를 도입했습니다. 다음 세 가지는 코드나 스캐폴딩에 영향을 줍니다:

  1. 에이전트 트레이스의 내장 진행 상황 업데이트: Claude Opus 4.7은 긴 에이전트 트레이스 전반에 걸쳐 사용자에게 더 규칙적이고 품질 높은 업데이트를 제공합니다. 중간 상태 메시지를 강제하기 위한 스캐폴딩("도구 호출 3회마다 진행 상황을 요약하세요")을 추가했다면 제거해 보세요. Claude Opus 5.5에서는 이러한 업데이트가 thinking 블록으로 전달되며, 기본 thinking.display에서는 비어 있습니다. 이를 받으려면 도구 호출 사이의 텍스트가 사고 블록으로 반환됨을 참조하세요. 길이와 내용을 조정하려면 사용자 대상 진행 상황 업데이트를 참조하세요.

  2. 실시간 사이버 보안 안전장치: 이 안전장치는 Claude Opus 4.7에서 새로 도입되었습니다. 금지되거나 고위험 주제와 관련된 요청은 거부로 이어질 수 있습니다. 침투 테스트, 취약점 연구, 레드팀과 같은 정당한 보안 작업의 경우, Cyber Verification Program에 신청하여 제한 완화를 요청하세요. 신청 경로는 Claude에 접근하는 방식에 따라 다릅니다.

  3. 고해상도 이미지 지원: Claude Opus 4.7은 고해상도 이미지를 지원하는 최초의 Claude 모델입니다. 최대 이미지 해상도는 긴 변 기준 2,576픽셀로, 이전 모델의 1,568픽셀에서 증가했습니다. 이를 통해 비전 중심 워크로드에서 성능이 향상되며, 특히 컴퓨터 사용, 스크린샷 이해, 문서 분석에 유용합니다.

    고해상도 지원은 자동으로 적용되며 베타 헤더나 클라이언트 측 옵트인이 필요하지 않습니다. 대비해야 할 두 가지 사항은 다음과 같습니다:

    • 전체 해상도 이미지는 이전 모델보다 최대 약 3배 많은 이미지 토큰을 사용할 수 있습니다(이전 상한인 약 1,600 토큰 대비 이미지당 최대 4,784 토큰). 이미지 중심 워크로드의 경우 max_tokens와 예상 비용을 다시 산정하거나, 추가 충실도가 필요하지 않다면 전송 전에 다운샘플링하세요.
    • Claude Opus 4.7에서는 모델이 반환하는 포인팅 및 바운딩 박스 좌표가 실제 이미지 픽셀과 1:1로 대응하므로 배율 변환이 필요하지 않습니다.

    자세한 내용은 Claude Opus 4.7의 고해상도 이미지 지원을 참조하세요.

프롬프트 측면의 차이점은 Claude Opus 5.5 프롬프팅 및 프롬프팅 모범 사례를 참조하세요.

Claude Opus 4.5 이하에서 마이그레이션

Claude Opus 4.5, Claude Opus 4.1 또는 그 이전 모델에서 Claude Opus 5.5로 직접 마이그레이션하는 경우, 이 페이지를 처음부터 읽으세요. 먼저 앞의 모든 섹션을 페이지 순서대로 진행하세요. 그런 다음 이 섹션 앞부분의 Claude Opus 4.6에서 마이그레이션할 때 호환성이 깨지는 변경 사항을 진행하세요. 그런 다음 Claude Opus 4.5와 Claude Opus 4.7 사이에 적용된 다음의 누적 변경 사항을 적용하세요. Claude Opus 4.1 이하를 사용 중이라면 이 하위 섹션 이후에 Claude 4.1 이하에서 마이그레이션을 계속 진행하세요.

호환성이 깨지는 변경 사항

  1. 프리필 제거는 Claude Opus 4.6에서 마이그레이션할 때 호환성이 깨지는 변경 사항에서 다룹니다.

  2. 도구 매개변수 따옴표 처리: Claude Opus 4.6 및 이후 모델은 도구 호출 인수에서 약간 다른 JSON 문자열 이스케이프를 생성할 수 있습니다(예: 유니코드 이스케이프 또는 슬래시 이스케이프의 다른 처리). 도구 호출 input을 JSON 파서 대신 원시 문자열로 파싱한다면 파싱 로직을 확인하세요. 표준 JSON 파서(json.loads() 또는 JSON.parse() 등)는 이러한 차이를 자동으로 처리합니다.

첫 번째 항목은 Claude Opus 5.5에서 필수이며, 나머지는 권장 사항입니다.

  1. 적응형 사고로 마이그레이션(필수): thinking: {"type": "enabled", "budget_tokens": N}은 Claude Opus 4.7 및 이후 모델에서 400 오류를 반환합니다. 변경 전후 예시는 Claude Opus 4.6에서 마이그레이션할 때 호환성이 깨지는 변경 사항의 1번 항목입니다. 이 마이그레이션에서는 또한 client.beta.messages.create()에서 client.messages.create()로 이동합니다. 적응형 사고와 노력 수준은 베타 SDK 네임스페이스나 베타 헤더가 필요하지 않습니다.

  2. 노력 수준 베타 헤더 제거: 노력 수준 매개변수는 베타 헤더가 필요하지 않습니다. 요청에서 effort-2025-11-24 베타를 제거하세요.

  3. 세분화된 도구 스트리밍 베타 헤더 제거: 세분화된 도구 스트리밍(fine-grained tool streaming)은 베타 헤더가 필요하지 않습니다. 요청에서 fine-grained-tool-streaming-2025-05-14 베타를 제거하세요.

  4. 인터리브드 사고 베타 헤더 제거: 적응형 사고를 사용하면 적응형 사고를 지원하는 모든 모델에서 인터리브드 사고(interleaved thinking)가 자동으로 적용됩니다. 요청에서 interleaved-thinking-2025-05-14 베타를 제거하세요.

  5. output_config.format으로 마이그레이션: 구조화된 출력을 사용하는 경우 output_format={...}을 output_config={"format": {...}}로 업데이트하세요. output_format 매개변수는 지원 중단되었으며 향후 제거될 예정입니다. 그래도 사용하려면 structured-outputs-2025-11-13 베타 헤더를 추가하세요. 이 헤더가 없으면 API는 400 오류를 반환합니다. Python SDK(v1.0 이상)는 client.beta.messages.create() 또는 count_tokens()에서 output_format={...}을 허용하지 않습니다. parse() 및 stream() 헬퍼의 output_format=Model 인수는 변경되지 않았습니다.

Claude 4.1 이하에서 마이그레이션

Claude Opus 4.1 이하 모델에서 Claude Opus 5.5로 직접 마이그레이션하는 경우, 먼저 Claude Opus 4.5 이하에서 마이그레이션의 모든 내용을 적용하세요. 해당 하위 섹션은 앞의 모든 섹션부터 시작하므로, 사실상 이 페이지를 처음부터 읽게 됩니다. 그런 다음 이 하위 섹션의 추가 변경 사항을 적용하세요.

추가적인 호환성이 깨지는 변경 사항

  1. 샘플링 매개변수 제거: 샘플링 매개변수 제거됨에서 다룹니다.

  2. 도구 버전 업데이트

    현재 도구 버전으로 업데이트하세요. undo_edit 명령을 사용하는 코드를 모두 제거하세요.

    # 변경 전
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]

# 변경 후
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
    • 텍스트 편집기: text_editor_20250728과 str_replace_based_edit_tool을 사용하세요. 자세한 내용은 텍스트 편집기 도구 문서를 참조하세요.
    • 코드 실행: code_execution_20260521로 업그레이드하세요. 마이그레이션 지침은 Code execution 도구 문서를 참조하세요.
    • 컴퓨터 사용: Claude Opus 5.5가 허용하지 않는 computer_20250124 대신 computer_toolset_20260801 도구 세트를 사용하세요. Amazon Bedrock에서는 computer_20251124도 작동합니다. 컴퓨터 사용 호환성 깨짐 변경 사항을 참조하세요.

  3. refusal 중지 이유 처리

    애플리케이션이 refusal 중지 이유를 처리하도록 업데이트하세요:

    response = client.messages.create(...)

if response.stop_reason == "refusal":
    # 거부 응답을 적절히 처리합니다
    pass

  4. model_context_window_exceeded 중지 이유 처리

    Claude 4.5 이상 모델은 요청된 max_tokens 제한이 아니라 컨텍스트 윈도우 한도에 도달하여 생성이 중지되면 model_context_window_exceeded 중지 이유를 반환합니다. 애플리케이션이 이 새로운 중지 이유를 처리하도록 업데이트하세요:

    response = client.messages.create(...)

if response.stop_reason == "model_context_window_exceeded":
    # context window(컨텍스트 윈도우) 한도를 적절히 처리합니다
    pass

  5. 도구 매개변수 처리 확인(후행 줄바꿈)

    Claude 4.5 이상 모델은 이전에는 제거되던 도구 호출 문자열 매개변수의 후행 줄바꿈을 보존합니다. 도구가 도구 호출 매개변수에 대한 정확한 문자열 일치에 의존한다면, 로직이 후행 줄바꿈을 올바르게 처리하는지 확인하세요.

  6. 동작 변경에 맞게 프롬프트 업데이트

    Claude 4 이상 모델은 더 간결하고 직접적인 커뮤니케이션 스타일을 가지며 명시적인 지시가 필요합니다. 최적화 지침은 프롬프팅 모범 사례를 검토하세요.

  • 베타 헤더: token-efficient-tools-2025-02-19와 output-128k-2025-02-19를 제거하세요. 모든 Claude 4 및 이후 모델에는 토큰 효율적인 도구 사용이 내장되어 있으며 이 헤더들은 아무런 효과가 없습니다.

Claude Sonnet 5에서 Claude Opus 5.5로 마이그레이션

Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항, 모든 응답에서 사고 처리하기, Claude Opus 5에서 Claude Opus 5.5로 마이그레이션을 진행하세요. 교체할 모델 ID로 claude-sonnet-5를 사용하세요. 마지막 섹션은 Claude Sonnet 5의 코드에 그대로 적용됩니다. Claude Sonnet 5는 Claude Opus 5와 마찬가지로 다음과 같기 때문입니다:

  • 기본적으로 사고가 켜진 상태로 실행되며 thinking: {"type": "disabled"}를 허용합니다. Claude Sonnet 5의 경우 모든 노력 수준에서 허용됩니다.
  • 강제 도구 선택과 computer_20251124 도구를 허용합니다.
  • 도구 호출 사이의 텍스트를 text 블록으로 반환합니다.
  • 기본 노력 수준은 high입니다.

수동 확장 사고, 샘플링 매개변수, 어시스턴트 prefill은 두 모델 모두에서 400 오류를 반환하므로 이 부분은 변경되지 않습니다. Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 섹션의 필수 변경 사항은 어느 것도 적용되지 않습니다.

변경된 사항

  1. 대화 중 시스템 메시지: Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed)에서 Claude Opus 5.5는 messages 배열에서 사용자 턴 바로 다음에 오는 role: "system" 메시지를 허용합니다(배치 규칙 적용). 이 기능은 Claude Sonnet 5에서는 사용할 수 없습니다. 지침을 업데이트하기 위해 전체 메시지 기록을 다시 구성하는 코드 경로를 유지 관리하고 있다면, 이를 단순화하고 이전 턴의 프롬프트 캐싱 적중을 유지할 수 있습니다.

  2. 더 낮은 프롬프트 캐싱 최소값: Claude Opus 5.5에서 캐시 가능한 최소 프롬프트 길이는 512 토큰으로, Claude Sonnet 5의 1,024 토큰에서 낮아졌습니다. Claude Sonnet 5에서 캐시하기에 너무 짧았던 프롬프트도 코드 변경 없이 캐시 항목을 생성할 수 있습니다. 모델별 최소값은 프롬프트 캐싱을 참조하세요.

이 페이지가 도움이 되었나요?