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이며, Claude Opus 5는 $5 / $25입니다. 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, Google Cloud, Microsoft Foundry에서는 해당 플랫폼의 모델 ID를 사용하세요. 가용성을 참조하세요.
• 사고: thinking 필드를 보내지 않거나, 이와 동일한 thinking: {"type": "adaptive"}를 보내세요. adaptive thinking(적응형 사고)은 항상 켜져 있습니다. thinking: {"type": "disabled"}와 수동 사고 예산(thinking: {"type": "enabled", "budget_tokens": N})은 거부됩니다. 사고 설정의 변경 전후 비교를 참조하세요.
• Effort: 사고 깊이는 이를 제어하는 유일한 요청 매개변수인 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를 미리 채운 어시스턴트 턴으로 끝내지 마세요. 이는 거부됩니다. 대신 structured outputs(구조화된 출력) 또는 시스템 프롬프트 지침을 사용하세요. Amazon Bedrock에서는 Claude Opus 5.5에 구조화된 출력을 사용할 수 없으므로, 시스템 프롬프트 지침을 사용하세요.
• 컴퓨터 사용: Claude API와 Google Cloud에서는 컴퓨터 사용을 computer_toolset_20260801 도구 세트로 선언하세요. 해당 플랫폼에서는 이전 computer_20251124 도구가 거부됩니다. 컴퓨터 사용 관련 호환성이 깨지는 변경 사항을 참조하세요.
• 컨텍스트 윈도우: 컨텍스트 윈도우 베타 헤더가 필요하지 않습니다. 1M 토큰 컨텍스트 윈도우가 기본값이며, 이전 모델용으로 보낸 헤더는 아무런 효과가 없습니다.

다음 요청은 목록의 모든 항목을 충족합니다. effort가 설정되어 있고 thinking 필드가 없습니다. 텍스트를 출력하는 SDK 탭은 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는 여전히 사고와 응답 텍스트를 합한 전체 출력에 대한 엄격한 제한이므로, 사고 없이 실행되던 워크로드에서는 이 값을 다시 검토하세요. 사고 토큰은 사고 텍스트가 반환되지 않더라도 출력 토큰으로 청구되므로, 이러한 워크로드는 요청당 더 많은 출력 토큰을 생성할 수 있습니다. 비용 제어를 참조하세요. 사고에 사용하는 토큰을 줄이려면 effort 수준을 낮추세요. xhigh 또는 max effort로 실행하는 경우 모델이 사고하고 행동할 여유를 갖도록 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"로 설정하세요:

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   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를 명시적으로 설정하세요. 기본값은 medium이며, Claude Opus 5의 기본값은 high입니다.
• tool_choice 유형 any와 tool을 auto와 엄격한 도구 사용 또는 구조화된 출력의 조합으로 대체하거나, Amazon Bedrock에서는 auto만으로 대체하세요.
• Claude API 또는 Google Cloud에서 컴퓨터 사용을 사용하는 경우, computer_20251124 대신 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와 Google Cloud에서는 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 약정이 있다면 용량을 별도로 계획하세요. Claude Opus 5.5에서는 Priority Tier가 지원되지 않습니다.
• xhigh 또는 max effort로 실행하는 경우, 시작점으로 max_tokens를 최소 64k로 높이세요.
• 에이전트 워크로드의 경우 작업 예산(베타)과 대화 중간 도구 변경(베타)을 고려하세요.

Claude Opus 4.7 이하

• 이전 모델에 맞게 조정된 설정을 그대로 가져오지 말고, 자체 평가에서 effort 스윕을 새로 실행하세요.
• 컨텍스트 윈도우 베타 헤더를 모두 제거하세요.
• 지침을 업데이트하기 위해 대화 기록을 재구성하는 경우, 프롬프트 캐시 적중을 유지하기 위해 대화 중간 시스템 메시지로 전환하는 것을 고려하세요.
• 중지 사유 처리 코드가 거부 시 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 이하

• 어시스턴트 메시지 프리필을 모두 제거하세요. Claude Opus 4.6에서 이미 거부됩니다.
• 도구 호출 JSON 파싱에 표준 JSON 파서를 사용하는지 확인하세요.
• client.beta.messages.create()에서 client.messages.create()로 이전하세요. 적응형 사고와 effort에는 베타 네임스페이스가 필요하지 않습니다.
• 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, Google Cloud 및 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 필드를 제거하고 effort 수준을 선택하세요. 토큰을 절약하기 위해 사고를 비활성화했던 경우에는 더 낮은 수준을 사용하세요. 그러면 응답이 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를 사용하고, 도구가 적용되는 경우를 프롬프트에 명시하세요. 엄격한 도구 사용은 JSON Schema의 하위 집합을 허용하므로, strict: true를 추가하기 전에 각 도구의 input_schema를 확인하세요. 스키마의 모든 객체는 additionalProperties: false를 설정해야 합니다. JSON Schema 제한 사항을 참조하세요. Amazon Bedrock에서는 엄격한 도구 사용을 포함한 구조화된 출력을 Claude Opus 5.5에서 사용할 수 없습니다. 해당 플랫폼에서는 strict 없이 auto를 보내고, 도구가 적용되는 경우를 프롬프트에 명시하며, 코드에서 도구 입력을 검증하세요. 강제 도구 사용은 지원되지 않음을 참조하세요.

변경 전. 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 tool use(엄격한 도구 사용): 모든 호출이 도구의 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 Fable 5.1과 Claude Mythos 5.1이 Claude Opus 5.5의 사고 블록을 읽으며, 다른 모델은 읽지 않습니다. 대화를 Claude Opus 5.5에서 다른 모델로 옮기는 라우터나 폴백은 해당 턴을 사고 블록 없이 실행합니다. 반대 방향으로, Claude Opus 5.5는 Claude Opus 5, 이전 Opus, Sonnet, Haiku 모델, 그리고 Claude API와 Google Cloud에서는 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는 이미 그렇게 하고 있습니다. 적용 방식은 모든 플랫폼에서 Claude Fable 5.1과 동일합니다. 2026년 8월 31일 00:00 UTC 이후에 생성된 계정의 경우, 이러한 편집 후 사고 블록을 재전송하면 기본적으로 400 오류가 반환됩니다. 추가 전용 통합에는 코드 변경이 필요하지 않습니다. 사고 블록이 모델 및 대화에 연결됨과 보존된 사고를 참조하세요.

computer_20251124 컴퓨터 사용 도구는 Claude API 및 Google Cloud에서 지원되지 않음

Claude API 및 Google Cloud에서 유형이 computer_20251124인 tools 항목은 400 오류('claude-opus-5-5' does not support tool types: computer_20251124.와 그 뒤에 모델이 허용하는 도구 유형)를 반환합니다. 대신 computer_toolset_20260801 도구 세트를 선언하세요: 베타 헤더를 제거하고 name이나 디스플레이 크기 없이 항목을 전송하세요. 에이전트 루프에서는 멤버 tool_use 블록(액션은 input.action이 아니라 블록의 name입니다)을 턴당 여러 개 처리하고, 모든 결과에 toolset_name을 그대로 반환하세요. 요청 변경 사항은 아래에 나와 있으며, 에이전트 루프 변경 사항은 computer_20251124에서 마이그레이션에 나열되어 있습니다. Amazon Bedrock에서는 이전 computer_20251124 도구가 Claude Opus 5에서와 마찬가지로 Claude Opus 5.5에서도 계속 작동하므로 변경이 필요하지 않습니다. 다른 플랫폼의 경우 컴퓨터 사용 도구의 호환성 섹션을 참조하세요. Claude API 및 Google Cloud에서 computer_20251124 컴퓨터 사용 도구는 지원되지 않음을 참조하세요.

변경 전. Claude Opus 5는 이 요청을 허용하지만, Claude API와 Google Cloud에서 Claude Opus 5.5는 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,
    # beta 헤더가 필요 없으며, toolset 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
    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. effort 스윕을 다시 실행하세요. Effort는 Claude Opus 5.5에서 유일한 사고 제어 수단이며, 기본값이 Claude Opus 5의 high와 달리 medium이므로 effort를 생략한 요청은 이제 medium으로 실행됩니다. 품질이 유지되는 경우에는 수준을 낮추고, 가장 까다로운 작업에는 수준을 높이세요. Effort를 참조하세요.
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 블록으로 반환합니다.
• 기본 effort가 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-budgets-2026-03-13 베타 헤더가 필요합니다.

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

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.7은 Claude Opus 4.8과 마찬가지로 thinking: {"type": "disabled"}, 강제 도구 선택, computer_20251124 도구를 허용합니다. 기본 effort는 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 수준 재조정: Claude Opus 5.5에서는 Claude Opus 4.7과 비교하여 각 effort 수준에 할당되는 토큰이 달라집니다. 기본값은 medium이며, Claude Opus 4.7의 기본값은 high입니다. Claude Opus 4.7에 맞게 조정된 설정을 그대로 가져오지 말고, 자체 평가에서 effort 스윕을 새로 실행하세요. Effort를 참조하세요.

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

3. 대화 중간 시스템 메시지: Claude API, Amazon Bedrock, Google Cloud에서 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. Fast mode: Claude Opus 5.5는 Claude API에서 fast mode를 지원합니다. Fast mode는 Claude Opus 4.7에서는 사용할 수 없으며, speed: "fast"가 포함된 요청은 오류를 반환합니다. 요청에 speed: "fast"를 설정하세요. Claude Opus 5.5에는 베타 헤더가 필요하지 않습니다.

6. 컴퓨터 사용 도구 세트 및 브라우저 사용 도구: Claude API와 Google Cloud에서 Claude Opus 5.5는 computer_toolset_20260801 도구 세트 형태의 컴퓨터 사용과 웹페이지 내 작업을 위한 브라우저 사용 도구를 지원합니다. Claude Opus 4.7은 둘 다 지원하지 않습니다. 해당 플랫폼에서 Claude Opus 5.5는 이전 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.6은 Claude Opus 4.7과 마찬가지로 thinking: {"type": "disabled"}, 강제 도구 선택, computer_20251124 도구를 허용합니다. 기본 effort는 high이며, 요청하지 않는 한 사고 없이 실행됩니다. Claude Opus 4.5 및 이전 Opus 모델도 thinking: {"type": "disabled"}와 강제 도구 선택을 허용하고 요청하지 않는 한 사고 없이 실행되므로, 이 섹션들은 해당 모델에도 적용됩니다.

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

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

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

   이전 (Claude Opus 4.6):

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   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 줄이 달라집니다:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   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": "..."}],
   )

   적응형 사고는 프롬프팅과 effort 매개변수를 통해 조정할 수 있습니다. effort 매개변수는 모델의 추론량을 제어하는 방법으로서 "thinking budget"(사고 예산)을 대체합니다. budget_tokens 값을 그대로 변환하기보다는 자체 평가(eval)에서 effort 스윕을 실행하세요. effort 수준 표는 각 수준을 언제 사용해야 하는지 설명하며, Claude Opus 5.5 권장 effort 수준에서 이 모델을 다룹니다.

2. 샘플링 매개변수 제거: Claude Opus 5.5를 포함한 Claude Opus 4.7 이상 모델에서 temperature, top_p, top_k를 기본값이 아닌 값으로 설정하면 400 오류가 반환됩니다. Python SDK(v1.0 이상)는 이 매개변수들을 정의하지 않으며, 이를 전달하면 TypeError가 발생합니다. 가장 안전한 마이그레이션 방법은 요청 페이로드에서 이 매개변수들을 완전히 생략하는 것입니다. Claude Opus 5.5에서 모델 동작을 안내하는 권장 방법은 프롬프팅입니다. 결정론적 출력을 위해 temperature = 0을 사용하고 있었다면, 이전 모델에서도 이 설정이 동일한 출력을 보장한 적은 없다는 점에 유의하세요.

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

4. 토큰 계산 방식 업데이트: Claude Opus 4.7은 새로운 "tokenizer"(토크나이저)를 도입했으며, 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 이하에서 마이그레이션하는 경우에만 변경 사항입니다. 대신 구조화된 출력 또는 시스템 프롬프트 지침을 사용하세요. Amazon Bedrock에서는 Claude Opus 5.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픽셀에서 증가했습니다. 이를 통해 비전 중심 워크로드에서 성능이 향상되며, 특히 "computer use"(컴퓨터 사용), 스크린샷 이해, 문서 분석에 유용합니다.

   고해상도 지원은 자동이며 베타 헤더나 클라이언트 측 옵트인이 필요하지 않습니다. 계획해야 할 두 가지 사항:

   • 전체 해상도 이미지는 이전 모델보다 최대 약 3배 더 많은 이미지 토큰을 사용할 수 있습니다(이미지당 최대 4,784 토큰, 이전 상한인 이미지당 약 1,600 토큰과 비교). 이미지 중심 워크로드에 대해 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()로 이동합니다. 적응형 사고와 effort는 베타 SDK 네임스페이스나 베타 헤더가 필요하지 않습니다.

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

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

4. 인터리브 사고 베타 헤더 제거: 적응형 사고를 사용하면 적응형 사고를 지원하는 모든 모델에서 인터리브 사고가 자동으로 적용됩니다. 요청에서 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 명령을 사용하는 코드를 모두 제거하세요.

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   # 변경 전
   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로 업그레이드하세요. 마이그레이션 지침은 코드 실행 도구 문서를 참조하세요.
   • 컴퓨터 사용: Claude API와 Google Cloud에서 Claude Opus 5.5는 컴퓨터 사용을 computer_toolset_20260801 도구 세트로만 허용하며, 이전의 computer_20250124 및 computer_20251124 도구는 해당 플랫폼에서 거부됩니다. 컴퓨터 사용 관련 호환성이 깨지는 변경 사항을 참조하세요.

3. refusal 중지 사유 처리

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

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   response = client.messages.create(...)
   
   if response.stop_reason == "refusal":
       # 거부를 적절히 처리합니다
       pass

4. model_context_window_exceeded 중지 사유 처리

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

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   response = client.messages.create(...)
   
   if response.stop_reason == "model_context_window_exceeded":
       # 컨텍스트 윈도우 한도를 적절히 처리합니다
       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의 경우 모든 effort 수준에서 허용).
• 강제 도구 선택과 computer_20251124 도구를 허용합니다.
• 도구 호출 사이의 텍스트를 text 블록으로 반환합니다.
• 기본 effort가 high입니다.

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

변경된 사항

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

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