Claude Sonnet 5.5로 마이그레이션하기

이 가이드는 Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Sonnet 4, Claude 3.7 Sonnet 또는 Claude Haiku 4.5에서 Claude Sonnet 5.5로 옮길 때 필요한 코드 변경 사항을 정리합니다. 처음 두 섹션을 읽은 다음, 현재 모델에 해당하는 섹션까지 이어서 읽으세요. 마이그레이션 체크리스트에는 시작 모델별로 모든 변경 사항이 정리되어 있습니다.

Claude Sonnet 5.5의 가격은 Claude Sonnet 5와 같습니다. Claude 가격을 참조하세요. "context window"(컨텍스트 윈도우)와 출력 한도는 Claude Sonnet 5.5 모델 페이지를 참조하세요. 기능과 프롬프팅에 대해서는 Claude Sonnet 5.5의 새로운 기능과 Claude Sonnet 5.5 프롬프팅을 참조하세요.

Claude Sonnet 5.5에 요청 보내기

이 요청은 작성된 그대로 Claude Sonnet 5.5에서 작동합니다. 이 요청은 "effort level"(노력 수준)을 설정하며, SDK 탭의 예제는 블록 유형별로 응답을 읽습니다. 400 오류를 반환하는 다섯 가지 설정은 포함하지 않습니다. 해당 설정은 사고 예산, 샘플링 매개변수, 어시스턴트 prefill, 강제 도구 선택, thinking: {"type": "disabled"}입니다.

client = anthropic.Anthropic()

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

print(f"Stop reason: {response.stop_reason}")
for block in response.content:
    if block.type == "text":
        print(block.text)

기본적으로 사고가 실행됩니다

Claude Sonnet 5.5에서는 thinking 필드가 없는 요청도 thinking: {"type": "adaptive"}를 보낸 요청과 마찬가지로 "adaptive thinking"(적응형 사고)으로 실행됩니다. Claude Sonnet 4.6 및 이전 모델과 Claude Haiku 4.5에서는 같은 요청이 사고 없이 실행되었습니다. "up-front thinking"(사전 사고) 없이 계속 실행하려면 사전 사고 끄기를 참조하세요.

응답에서 사고 처리하기

사고 없이 실행되던 코드는 아래 세 항목을 모두 적용해야 합니다. Claude Sonnet 5용 코드에는 처음 두 항목이 이미 반영되어 있을 가능성이 높습니다.

• 콘텐츠 블록을 type으로 구분해 읽으세요. 응답이 thinking 블록으로 시작할 수 있으므로, content[0].text를 읽는 코드는 제대로 작동하지 않습니다.
• 도구 사용 루프에서는 빈 블록을 포함해 thinking 블록을 변경하지 말고 그대로 다시 전달하세요. 사고 블록 보존을 참조하세요.
• max_tokens를 다시 검토하세요. 이 값에는 사고와 텍스트가 모두 포함되며, 사고 토큰은 출력 토큰으로 청구됩니다. 비용 제어를 참조하세요.

사고 텍스트는 기본적으로 생략됩니다. thinking 블록은 빈 thinking 필드와 signature만 담아 반환됩니다. 읽을 수 있는 요약을 받으려면 display: "summarized"를 설정하세요. 이 값은 Claude Sonnet 4.6 및 이전 모델과 Claude Haiku 4.5의 기본값입니다. 사고 표시 제어를 참조하세요.

사전 사고 끄기

Claude Sonnet 5.5에서 사전 사고를 끄려면 thinking: {"type": "between_tools"}를 보내세요. 이 값이 가장 낮은 사고 설정입니다. 이 설정에서도 도구 호출 사이의 진행 상황 업데이트는 요약 텍스트가 담긴 thinking 블록으로 반환됩니다. 도구를 사용하지 않으면 응답에는 텍스트만 포함됩니다. Claude Sonnet 5에서는 thinking: {"type": "disabled"}로 사고를 끄며, 그 이전 모델은 기본적으로 사고 없이 실행됩니다. Claude Sonnet 5.5에서 disabled를 보내면 400 invalid_request_error가 반환됩니다.

"thinking.type.disabled" is not supported for this model. Use "thinking.type.between_tools" for the lowest thinking setting, or "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

between_tools는 Claude Sonnet 5.5를 제공하는 모든 플랫폼에서 베타 헤더 없이 작동합니다. 이 설정은 low, medium, high 노력 수준에서만 허용되며, xhigh 또는 max에서는 400 오류를 반환합니다. 이 수준에서 실행하려면 적응형 사고를 사용하세요. 즉, thinking 필드를 생략하거나 thinking: {"type": "adaptive"}를 보내면 됩니다. between_tools에는 다른 필드를 함께 지정할 수 없으며, display, budget_tokens 또는 block_binding을 함께 보내면 400 오류가 반환됩니다. "server-side fallback"(서버 측 폴백)을 사용하는 경우, Claude Sonnet 5로 폴백된 between_tools 요청은 Claude Sonnet 5에서 thinking: {"type": "disabled"}로 실행됩니다.

between_tools를 사용하면 대화 도중에 노력 수준을 바꿀 수 없습니다. 현재 적용 중인 수준과 다른 메시지별 output_config.effort를 보내면 400 오류가 반환됩니다. 턴마다 노력 수준을 다르게 하려면 적응형 사고를 사용하세요. 프롬프팅 지침은 사전 사고 없이 실행하기를 참조하세요.

between_tools가 정의되지 않은 SDK 버전에서는 Python 및 TypeScript 예제가 타입 검사를 통과하지 못합니다. SDK를 업데이트하거나, C#, Go, Java 예제처럼 값을 원시 JSON으로 전달하세요.

이전 (Claude Sonnet 5):

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

이후 (Claude Sonnet 5.5):

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "between_tools"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

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

아래 그룹을 위에서부터 차례로 적용하고, 사용 중인 모델이 제목에 포함된 그룹까지 적용한 뒤 멈추세요. Claude Haiku 4.5에서 옮기는 경우에는 "Claude Sonnet 4 이하"를 제외한 모든 그룹을 적용하고, 마지막으로 "Claude Haiku 4.5 전용"을 적용하세요.

모든 시작 모델

• 모델 ID를 claude-sonnet-5-5로 변경하세요.
• 콘텐츠 블록을 type으로 읽고, thinking 블록을 변경 없이 다시 전달하세요.
• 사전 사고 없이 계속 실행하려면 high effort 이하에서 가장 낮은 사고 설정을 보내세요.
• 강제 도구 사용을 auto와 strict 도구로(Amazon Bedrock에서는 auto만으로) 대체하세요.
• 대화를 추가 전용(append-only)으로 유지하세요.
• Claude API와 Google Cloud에서는 fine-grained-tool-streaming-2025-05-14 베타 헤더 없이 컴퓨터 사용을 툴셋으로 옮기세요.
• 어드바이저 도구를 지원되는 어드바이저와 함께 사용하고, 암호화된 조언을 예상하세요.
• 도구 호출 사이의 텍스트를 thinking 블록에서 읽으세요.
• 거부를 처리하고 폴백을 구성하세요.
• effort 스윕을 다시 실행하고 비용 기준선을 다시 설정하세요.

Claude Sonnet 4.6 이하

• thinking 필드가 없는 요청에서도 사고가 실행된다는 점에 대비하고, max_tokens를 다시 검토하세요.
• 사고 예산을 노력 수준으로 대체하세요.
• 기본값이 아닌 temperature, top_p, top_k 값을 제거하세요.
• 사고 텍스트를 표시하는 경우 display: "summarized"를 설정하세요.
• 토큰 수를 다시 계산하고 이미지 토큰 예산을 다시 책정하세요.

Claude Sonnet 4.5 이하

• 어시스턴트 prefill을 다른 방식으로 대체하세요.
• 도구 호출 입력은 표준 JSON 파서로 파싱하세요.
• Amazon Bedrock에서는 컴퓨터 사용 도구를 computer_20250124에서 computer_20251124로 옮기세요.
• output_config.effort를 명시적으로 설정하세요.
• 컨텍스트 윈도우 관련 베타 헤더를 모두 제거하세요.
• interleaved-thinking-2025-05-14를 제거하고, fine-grained-tool-streaming-2025-05-14를 eager_input_streaming으로 대체하세요.
• output_format을 output_config.format으로 옮기세요.

Claude Sonnet 4 이하

• 도구 버전을 text_editor_20250728 및 code_execution_20260521로 업데이트하세요.
• refusal 및 model_context_window_exceeded 중지 이유를 처리하세요.
• 도구의 문자열 매개변수에 후행 줄바꿈이 있는지 확인하세요.
• token-efficient-tools-2025-02-19 및 output-128k-2025-02-19를 제거하세요.
• 프롬프트를 검토하세요.

Claude Haiku 4.5 전용

• claude-haiku-4-5-20251001 또는 해당 별칭을 새 모델 ID로 바꾸세요.
• 더 높은 토큰당 가격을 기준으로 비용 기준선을 다시 설정하세요.
• Claude Haiku 4.5에서는 너무 짧아 캐시되지 않았던 프롬프트를 검토하세요.

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

이 섹션의 변경 사항은 모든 시작 모델에 적용됩니다. 모델 ID를 날짜 접미사가 없는 claude-sonnet-5-5로 바꾸세요. 다른 플랫폼에서는 가용성에 나열된 ID를 사용하세요.

강제 도구 사용은 지원되지 않습니다

이 페이지에서 다루는 이전 모델은 모두 any 또는 tool 유형의 tool_choice를 허용합니다. Claude Sonnet 5.5는 토큰 카운팅 엔드포인트를 포함한 모든 요청에서 두 유형을 모두 400 오류로 거부합니다.

tool_choice: type "tool" and "any" are not supported for this model.

tool_choice: {"type": "auto"}를 보내고, 도구 입력이 스키마와 일치하도록 도구에 strict: true를 표시하세요. 이 경우 모델이 도구를 호출하지 않고 답변할 수 있으므로, 언제 도구를 사용해야 하는지 프롬프트에 명시하세요. Strict 도구 사용은 JSON Schema의 일부만 지원하며, 모든 객체에 additionalProperties: false가 필요합니다. JSON Schema 제한 사항을 참조하세요. Amazon Bedrock에서는 strict 도구 사용을 포함하는 구조화된 출력을 Claude Sonnet 5.5에서 사용할 수 없습니다. 그곳에서는 strict 없이 auto를 보내고, 언제 도구를 호출해야 하는지 프롬프트에 명시하며, 코드에서 도구 입력을 검증하세요.

이전 (Claude Sonnet 5):

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

이후 (Claude Sonnet 5.5):

client.messages.create(
    model="claude-sonnet-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.",
        }
    ],
)

이 예제에서는 목록의 모든 도구를 strict로 지정합니다. 하나의 요청에는 strict 도구를 최대 20개까지 포함할 수 있으며, MCP, 컴퓨터 사용, 브라우저 사용 툴셋 항목에는 strict를 지정할 수 없습니다. 도구 목록이 길다면 필요한 도구에만 지정하세요.

사고 블록은 모델과 대화에 연결됩니다

Claude Sonnet 5.5는 Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 및 그 이전 모델의 사고 블록을 읽을 수 있습니다. 반면 Claude Opus 5, Claude Opus 5.5, 그리고 모든 Claude Fable 및 Claude Mythos 모델의 블록은 읽지 못합니다. API는 모델이 읽을 수 없는 블록을 제거합니다. 이 경우에도 요청은 200을 반환하며, 제거된 블록에는 요금이 청구되지 않습니다. 대화 도중 모델 전환하기를 참조하세요.

또한 Claude Sonnet 5.5의 각 사고 블록에는 그 블록 이전까지의 대화 내용에 대한 서명이 포함됩니다. 2026년 8월 31일 00:00 UTC 이후에 생성된 계정의 경우, Claude API, Amazon Bedrock, Google Cloud에서 API가 이 서명 검증을 기본적으로 적용합니다. 이러한 계정에서는 이전 대화 기록을 수정한 뒤 블록을 다시 보내는 요청이 400 오류를 반환합니다. 대화는 추가 전용으로 유지하고, 지침이나 도구를 바꿀 때는 대화 중간 시스템 메시지를 사용하세요. Claude Sonnet 5.5가 생성한 사고 블록은 해당 블록을 생성한 계정이나 그 계정에 연결된 계정에서만 사용할 수 있습니다. 보존된 사고를 참조하세요.

Claude API와 Google Cloud에서는 컴퓨터 사용에 툴셋이 필요합니다

Claude API와 Google Cloud에서 Claude Sonnet 5.5는 computer_toolset_20260801 툴셋을 통해서만 컴퓨터 사용을 지원하며, 이 플랫폼에서 computer_20251124를 보내면 400 오류가 반환됩니다. computer_20250124는 어떤 플랫폼에서도 Claude Sonnet 5.5에서 사용할 수 없습니다. 아래 표에서 현재 보내는 버전을 찾으세요.

fine-grained-tool-streaming-2025-05-14 베타 헤더를 보내고 있다면 툴셋으로 옮길 때 제거하세요. 이 헤더를 툴셋 항목과 함께 보내면 400 오류가 반환됩니다. 대신 필요한 각 도구에 eager_input_streaming: true를 설정하세요.

이미 툴셋을 보내는 코드는 변경할 필요가 없습니다. 요청과 에이전트 루프의 변경 사항은 computer_20251124에서 마이그레이션하기를 참조하세요. 다른 플랫폼에 대해서는 호환성을 참조하세요.

어드바이저 도구에서 사용할 수 있는 어드바이저가 줄었습니다

어드바이저 도구를 사용할 때 Claude Sonnet 5.5 실행자(executor)에는 Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5, Claude Fable 5.1, Claude Mythos 5, Claude Mythos 5.1 중 하나를 어드바이저로 지정해야 합니다. Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6을 어드바이저로 지정하면 400 오류가 반환됩니다. 조언은 advisor_redacted_result 블록에 암호화되어 반환되므로, 응답에서 조언 텍스트를 읽을 수 없습니다. 모델 호환성을 참조하세요.

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

Claude Sonnet 5.5에서는 모델이 도구 호출 사이에 작성하는 메모 중 한두 문장보다 긴 것은 진행 상황 업데이트 thinking 블록으로 반환되며, 기본 display 설정에서는 내용이 비어 있습니다. 이보다 짧은 메모는 계속 text로 반환됩니다. Claude Sonnet 5 및 이전 모델에서는 도구 호출 사이의 모든 텍스트가 text 블록으로 반환됩니다. 이 변경으로 요청이 실패하지는 않지만, 이러한 메모를 표시하던 인터페이스에는 더 이상 메모가 나타나지 않습니다.

적응형 사고를 사용할 때 업데이트만 받으려면 display를 "updates"(베타, thinking-display-updates-2026-08-18 헤더 필요)로 설정하고, 추론과 함께 받으려면 "summarized"로 설정하세요. 내용이 있는 각 thinking 블록은 바로 뒤에 오는 tool_use 블록보다 먼저 렌더링하세요. between_tools를 사용하면 display를 설정하지 않아도 텍스트가 반환됩니다. 사용자 대상 진행 상황 업데이트를 참조하세요.

안전 분류기와 폴백

Claude Sonnet 5.5는 Claude Sonnet 5보다 더 많은 범주에서 요청을 거절합니다. 거절된 요청은 stop_reason: "refusal"을 반환하며, stop_details에 다음 범주 중 하나가 표시될 수 있습니다.

• "cyber": 멀웨어나 익스플로잇 개발처럼 사이버 피해로 이어질 수 있는 요청입니다.
• "bio": 위험한 실험 방법처럼 생물학적 피해로 이어질 수 있는 요청입니다.
• "frontier_llm": 경쟁 AI 모델 개발에 도움이 될 수 있는 요청입니다.
• "reasoning_extraction": 모델의 내부 추론을 응답 텍스트에 그대로 재현하도록 요구하는 요청입니다.
• "general_harms": 그 밖의 사용 정책 영역에 해당하는 요청입니다. 무해한 작업도 이 범주로 분류될 수 있습니다.

서버 측 폴백(fallbacks: "default", 베타, Claude API 전용)은 "cyber" 및 "frontier_llm" 범주로 거절된 요청을 Claude Sonnet 5에서 다시 시도합니다. "bio", "reasoning_extraction", "general_harms" 범주로 거절된 요청은 다시 시도하지 않습니다. 거부 및 폴백과 거부에 대한 요금 청구 방식을 참조하세요.

Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Haiku 4.5에서 옮기는 코드에는 실시간 사이버 보호 장치가 새로 적용됩니다. 정당한 보안 작업을 수행하는 경우 Cyber Verification Program에 신청하세요.

기타 변경 사항

• "Prompt caching"(프롬프트 캐싱): 캐시할 수 있는 최소 프롬프트 길이가 Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5의 1,024 토큰에서 512 토큰으로 줄었습니다. 프롬프트 캐싱을 참조하세요.
• 새로운 기능: 대화 중간 시스템 메시지, 대화 중간 도구 변경, 메시지별 노력 수준에 대해서는 Claude Sonnet 5.5의 새로운 기능을 참조하세요. 단, between_tools를 사용하면 대화 도중에 노력 수준을 바꿀 수 없습니다.

권장 변경 사항

노력 수준 스윕을 다시 실행하세요. Claude Sonnet 5.5에는 low, medium, high, xhigh, max의 다섯 가지 노력 수준이 있으며, Claude API의 기본값은 high입니다. 각 수준이 재보정되었으므로, 같은 수준이라도 Claude Sonnet 5와 같은 양의 사고를 생성하지는 않습니다. 에이전트형 워크로드나 "latency"(지연 시간)에 민감한 워크로드가 아니라면 high에서 시작하세요. 에이전트형 코딩과 다단계 도구 사용에서는 요구 사항이 명확한 작업은 medium에서 시작하고, 더 어렵거나 긴 작업은 high로 올리세요. 채팅처럼 지연 시간에 민감한 작업은 medium 또는 low에서 시작하세요. 수준은 output_config.effort에서 설정합니다. Claude Sonnet 5.5 권장 노력 수준을 참조하세요. 그런 다음 Claude Sonnet 5.5 프롬프팅을 기준으로 모델별 프롬프트 지침을 다시 평가하세요.

Claude Sonnet 4.6 및 이전 Sonnet 모델에서 Claude Sonnet 5.5로 마이그레이션하기

먼저 앞의 모든 섹션을 적용하세요. 이때 모델 ID는 claude-sonnet-4-6을 바꾸면 됩니다. 그런 다음 아래 변경 사항을 적용하세요. Claude Sonnet 4.5 이하에서 옮기는 경우에는 이어지는 하위 섹션도 계속 적용하세요.

호환성을 깨는 변경 사항

사고를 지정하지 않은 요청에서도 사고가 실행됩니다. 기본적으로 사고가 실행됩니다와 사전 사고 끄기를 참조하세요.

사고 예산을 지정하면 오류가 반환됩니다. Claude Sonnet 4.6은 thinking: {"type": "enabled", "budget_tokens": N}을 지원 중단된 설정으로 허용하며, Claude Sonnet 4.5와 Claude Haiku 4.5는 모든 사고에 이 설정을 사용합니다. Claude Sonnet 5.5에서는 이 설정이 400 오류를 반환합니다.

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

예산을 제거하고 노력 수준을 설정하세요. 예산과 노력 수준 사이에는 정해진 대응 관계가 없으므로, 두세 가지 수준에서 평가를 실행해 보세요.

이전 (Claude Sonnet 4.6):

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

이후 (Claude Sonnet 5.5):

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

샘플링 매개변수를 지정하면 오류가 반환됩니다. Claude Sonnet 4.6 및 이전 모델과 Claude Haiku 4.5는 temperature, top_p, top_k를 허용합니다. Claude Sonnet 5.5에서는 이 매개변수에 기본값이 아닌 값을 지정하면 400 오류가 반환되므로, 해당 매개변수를 제거하세요.

사고 텍스트는 기본적으로 생략됩니다. 응답에서 사고 처리하기를 참조하세요.

기타 변경 사항

• 토큰 수 약 30% 증가: Claude Sonnet 5.5는 Claude Sonnet 5와 같은 토크나이저를 사용합니다. 따라서 같은 텍스트라도 Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Haiku 4.5보다 토큰이 약 30% 더 많이 생성되며, 정확한 비율은 콘텐츠에 따라 다릅니다. 토큰 카운팅으로 토큰 수를 다시 계산하고, max_tokens와 비용을 다시 검토하세요.
• 노력 수준: xhigh가 새로 추가되었고, 각 수준이 재보정되었습니다. 권장 변경 사항을 참조하세요.
• 이미지: Claude Sonnet 5.5는 고해상도 이미지 등급을 사용하며, 긴 변 기준 최대 2576픽셀, 이미지당 최대 4,784개의 시각 토큰을 지원합니다. Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Haiku 4.5의 한도는 1568픽셀, 1,568 토큰입니다. 예를 들어 2000×1500 이미지는 Claude Sonnet 5.5에서 약 2.5배 많은 토큰을 사용합니다. 해상도 및 토큰 비용을 참조하세요.

Claude Sonnet 4.5 이하에서 마이그레이션하기

Claude Sonnet 4.5, Claude Sonnet 4 또는 Claude 3.7 Sonnet에서 옮기는 경우, 먼저 앞의 모든 섹션을 적용한 다음 아래 변경 사항을 적용하세요.

Prefill을 사용하면 오류가 반환됩니다. Claude Sonnet 5.5는 Claude Sonnet 4.6 및 Claude Sonnet 5와 마찬가지로, 마지막 어시스턴트 턴을 미리 채운 요청을 400 오류로 거부합니다. Claude Sonnet 4.5, Claude Haiku 4.5 및 그 이전 모델은 이러한 요청을 허용합니다. 오류 메시지는 다음과 같습니다.

This model does not support assistant message prefill. The conversation must end with a user message.

각 prefill은 원래 용도에 따라 다음과 같이 대체하세요.

• 출력 형식: 구조화된 출력을 사용하세요. 분류 작업에는 enum 필드가 있는 도구를 사용할 수 있습니다.
• 서두 생략: 시스템 프롬프트에서 바로 답변하도록 요청하세요.
• 불필요한 거부 방지: 대개 사용자 메시지에 명확한 지침을 넣는 것으로 충분합니다.
• 이어서 작성: 사용자 메시지로 옮기세요. 예: "이전 응답이 중단되었으며 [previous_response](으)로 끝났습니다. 중단된 부분부터 이어서 작성하세요."
• 컨텍스트 리마인더: 사용자 턴에 넣으세요.

도구 입력 이스케이프. 도구 호출 인수의 이스케이프 방식이 이전과 다를 수 있습니다. input은 표준 JSON 파서로 파싱하세요.

컴퓨터 사용. Claude Sonnet 5.5에서는 computer_20250124를 사용할 수 없습니다. 컴퓨터 사용 표를 참조하세요.

노력 수준. Claude Sonnet 4.5에는 effort 매개변수가 없습니다. 권장 변경 사항에 설명된 대로 노력 수준을 명시적으로 설정하세요.

컨텍스트 및 출력. Claude Sonnet 5.5는 베타 헤더 없이도 더 큰 컨텍스트 윈도우와 더 높은 출력 한도를 제공합니다. 모델 페이지를 참조하세요. 컨텍스트 윈도우 관련 베타 헤더는 모두 제거하세요.

베타 헤더. 적응형 사고는 도구 호출 사이에 자동으로 사고를 끼워 넣으므로 interleaved-thinking-2025-05-14를 제거하세요. fine-grained-tool-streaming-2025-05-14는 필요한 각 도구에 eager_input_streaming: true를 설정하는 방식으로 대체하세요. 이 헤더를 컴퓨터 사용 또는 브라우저 사용 툴셋 항목과 함께 보내면 400 오류가 반환됩니다. 세분화된 도구 스트리밍을 참조하세요.

구조화된 출력. output_format 매개변수는 지원 중단되었으며 향후 제거될 예정입니다. 그래도 이 매개변수를 사용하려면 structured-outputs-2025-11-13 베타 헤더를 추가해야 하며, 헤더가 없으면 API가 400 오류를 반환합니다. 대신 output_config.format을 사용하세요.

Claude Sonnet 4 이하에서 마이그레이션하기

Claude Sonnet 4는 Claude API에서 종료되었지만 Amazon Bedrock과 Google Cloud에서는 계속 사용할 수 있습니다. Claude 3.7 Sonnet은 종료되었습니다. 두 모델 중 어느 모델에서 옮기든, 먼저 앞의 모든 섹션을 적용한 다음 아래 변경 사항을 적용하세요.

• 도구 버전: text_editor_20250728을 사용하세요. 이 버전의 도구 이름은 str_replace_based_edit_tool이며, undo_edit 명령은 지원하지 않습니다. 코드 실행에는 code_execution_20260521을 사용하세요. 텍스트 편집기 도구와 코드 실행 도구를 참조하세요.
• 중지 이유: refusal을 처리하세요. 또한 Claude 4.5 이상 모델은 컨텍스트 윈도우 한도에 도달하면 model_context_window_exceeded로 중지됩니다. 중지 이유 처리를 참조하세요.
• 후행 줄바꿈: Claude 4.5 이상 모델은 도구 호출의 문자열 매개변수에서 후행 줄바꿈을 제거하지 않고 유지합니다.
• 레거시 베타 헤더: token-efficient-tools-2025-02-19 및 output-128k-2025-02-19를 제거하세요.
• 프롬프트: 프롬프팅 모범 사례를 기준으로 프롬프트를 검토하세요.

Claude Haiku 4.5에서 Claude Sonnet 5.5로 마이그레이션하기

먼저 Claude Sonnet 4.5 이하에서 마이그레이션하기까지(해당 섹션 포함) 모든 섹션을 적용하되, Claude Sonnet 4 하위 섹션은 건너뛰세요. 그런 다음 아래 변경 사항을 적용하세요.

• 모델 ID: claude-haiku-4-5-20251001 또는 별칭 claude-haiku-4-5를 claude-sonnet-5-5로 바꾸세요.
• 비용: 토큰당 가격이 더 높고, 같은 텍스트에서 더 많은 토큰이 생성됩니다. 토큰 수를 다시 계산하고 비용 기준선을 다시 설정하세요. Claude 가격을 참조하세요.
• 프롬프트 캐싱: 캐시할 수 있는 최소 프롬프트 길이가 4,096 토큰에서 Claude Sonnet 5.5의 최소값으로 줄어듭니다.
• "Interleaved thinking"(인터리브 사고): 적응형 사고는 베타 헤더 없이도 도구 호출 사이에서 자동으로 실행됩니다.
• 라우팅: Claude Sonnet 5.5는 Claude Haiku 4.5의 사고 블록을 읽을 수 있으므로, Claude Haiku 4.5에서 Claude Sonnet 5.5로 넘어간 대화는 기존 추론을 유지합니다. 반대로 Claude Haiku 4.5로 다시 넘어간 대화에서는 Claude Sonnet 5.5의 사고 블록이 제거됩니다.