Claude Sonnet 5.5의 새로운 기능

Claude Sonnet 5.5는 속도와 지능의 최상의 조합을 제공합니다. 다섯 가지 "breaking change"(호환성을 깨는 변경 사항)가 이미 Claude Sonnet 5에서 실행 중인 코드에 영향을 미칩니다:

• between_tools로 사전 사고를 끄세요.
• 강제 도구 사용은 오류를 반환합니다.
• 사고 블록은 모델 및 대화에 연결됩니다.
• Claude API와 Google Cloud에서는 이전 computer_20251124 컴퓨터 사용 도구가 허용되지 않습니다.
• 어드바이저 도구는 Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5를 어드바이저로 거부합니다.

또 하나의 변경 사항은 요청을 실패시키지 않으면서 응답 형태를 바꿉니다: 도구 호출 사이의 텍스트가 thinking 블록으로 반환됩니다. 해당 텍스트를 사용자에게 스트리밍하는 애플리케이션은 텍스트를 반환하는 display 값을 설정하거나 between_tools로 사전 사고를 끄기 전까지 도구 호출 사이에 아무것도 출력하지 않게 됩니다.

새로운 모델

Adaptive thinking(적응형 사고)은 기본적으로 켜져 있으며, effort 매개변수가 사고의 깊이를 제어합니다. Claude API에서의 기본값은 high입니다. "Tokenizer"(토크나이저)는 Claude Sonnet 5와 동일하므로, 같은 텍스트는 같은 토큰 수를 생성합니다. 컨텍스트 윈도우, 출력 한도, 지식 컷오프 및 가격은 Claude Sonnet 5.5 모델 페이지를 참조하세요.

현재 제공되는 모든 모델은 모델 개요를 참조하세요.

호환성을 깨는 변경 사항

between_tools로 사전 사고 끄기

Claude Sonnet 5.5에서 "up-front thinking"(사전 사고)을 끄려면 "disabled" 대신 thinking: {"type": "between_tools"}를 보내세요. 이는 이 모델에서 가장 낮은 사고 설정입니다. Claude Sonnet 5.5를 제공하는 모든 플랫폼에서 사용할 수 있으며, 베타 헤더가 필요하지 않습니다. 모델이 도구 호출 사이에 작성하는 짧은 진행 상황 업데이트는 여전히 요약 텍스트와 함께 thinking 블록으로 반환됩니다. 이러한 블록은 나머지 어시스턴트 턴과 함께 변경하지 않고 그대로 다시 전달하세요. 다시 보낸 진행 상황 업데이트 블록은 요약이 아니라 모델이 작성한 전체 메모를 모델에 제공합니다. 요청에서 도구를 사용하지 않는 경우, Claude Sonnet 5에서 disabled를 사용할 때와 마찬가지로 응답에는 텍스트만 포함됩니다.

Claude Sonnet 5.5에서 thinking: {"type": "disabled"}를 보내는 요청은 between_tools를 안내하는 메시지와 함께 400 invalid_request_error를 반환합니다.

between_tools는 low, medium, high effort에서 허용됩니다. xhigh 또는 max effort에서 between_tools를 사용하는 요청은 400 오류를 반환합니다. xhigh 또는 max로 실행하려면 적응형 사고를 사용하세요: thinking 필드를 생략하거나, 이와 동일한 thinking: {"type": "adaptive"}를 보내면 됩니다. between_tools를 사용하면 대화 도중에 effort를 변경할 수 없습니다: 현재 적용 중인 수준과 다른 메시지별 output_config.effort는 400 오류를 반환합니다. 턴마다 effort를 다르게 하려면 적응형 사고를 사용하세요.

between_tools는 다른 필드를 받지 않습니다: 함께 보낸 display, budget_tokens 또는 block_binding은 400 오류를 반환합니다. 수동 사고 예산(thinking: {"type": "enabled", "budget_tokens": N})은 400 오류를 반환합니다. 사고 및 마이그레이션 가이드의 변경 전후 비교를 참조하세요.

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

Claude Sonnet 5.5는 "forced tool use"(강제 도구 사용)를 지원하지 않습니다. tool_choice를 {"type": "any"} 또는 {"type": "tool", "name": "..."}로 설정하면 400 invalid_request_error가 반환됩니다:

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

tool_choice: {"type": "auto"}(기본값)와 {"type": "none"}은 지원됩니다. 동일한 검사가 토큰 카운팅 엔드포인트에도 적용됩니다. 스키마에 맞는 도구 입력이 필요하다면 tool_choice: {"type": "auto"}를 유지하고 엄격한 도구 사용으로 strict: true를 설정하거나, 스키마를 구조화된 출력으로 옮기세요. 모델이 텍스트로 답하는 대신 도구를 호출하도록 하려면, 프롬프트에서 해당 도구가 언제 적용되는지 명시하세요. 마이그레이션 가이드에서 변경 전후 비교를 확인할 수 있습니다.

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

모든 "thinking block"(사고 블록)은 자신을 생성한 모델을 기록합니다. 각 모델은 자신의 블록을 읽을 수 있으며, 다른 모델의 블록은 일부만 읽을 수 있습니다. 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 모델의 사고 블록은 읽을 수 없습니다. 다른 어떤 모델도 Claude Sonnet 5.5의 사고 블록을 읽을 수 없습니다.

따라서 Claude Sonnet 5에서 Claude Sonnet 5.5로 옮겨 가는 대화는 추론을 유지하지만, Claude Sonnet 5.5에서 다른 모델로 옮겨 가는 대화는 전환 이후의 턴을 추론 없이 실행합니다. 요청에 대상 모델이 읽을 수 없는 블록이 포함되어 있으면, API는 모델이 이를 보기 전에 해당 블록을 제거합니다: 요청은 성공하며, 제거된 블록에는 요금이 청구되지 않습니다. thinking-binding-controls-2026-08-01 베타 헤더를 사용하면 제거 내역이 최상위 input_transformations 배열에 보고됩니다. 대화 도중 모델 전환을 참조하세요.

API는 또한 Claude Sonnet 5.5 사고 블록이 생성된 이후 그 앞에 있는 내용, 즉 system 프롬프트, tools 또는 이전 메시지가 변경되었는지도 확인합니다. 2026년 8월 31일 00:00 UTC 이후에 생성된 계정에 대해서는 Claude API, Amazon Bedrock, Google Cloud에서 기본적으로 이 검사를 적용합니다. 해당 계정에서는 이러한 변경 이후 블록을 다시 전송하는 요청이 400 오류를 반환합니다. 대신 영향을 받는 블록을 제거하려면 thinking-binding-controls-2026-08-01 베타 헤더를 보내고 thinking.block_binding.prefix_mismatch_behavior를 "drop_block"으로 설정하세요. 이전 계정에서는 이 필드를 어느 값으로든 설정하면 해당 요청에 검사가 적용됩니다. block_binding은 thinking: {"type": "adaptive"}에서만 작동합니다. between_tools를 사용하는 경우 기록을 추가 전용으로 유지하거나, 편집된 턴부터 이후의 사고 블록을 제거하세요.

검사가 실패하지 않도록 대화를 추가 전용으로 유지하세요: 지시 사항이나 도구는 편집하는 대신 대화 중간 시스템 메시지로 변경하세요. 보존된 사고 및 마이그레이션 가이드의 이 변경 사항에 대한 참고를 참조하세요.

Claude API와 Google Cloud에서는 computer_20251124 컴퓨터 사용 도구가 지원되지 않습니다

Claude API와 Google Cloud에서 Claude Sonnet 5.5는 computer_toolset_20260801 도구 세트를 통해서만 컴퓨터 사용을 지원합니다. 이전 computer_20251124 도구를 선언하는 요청은 400 invalid_request_error를 반환합니다. Claude API에서는 메시지가 거부된 유형을 명시한 다음, 모델이 허용하는 도구 유형을 나열합니다. 메시지는 다음과 같이 시작합니다:

'claude-sonnet-5-5' does not support tool types: computer_20251124.

Amazon Bedrock에서는 Claude Sonnet 5.5가 이전 computer_20251124 도구를 허용합니다.

Claude API 또는 Google Cloud의 기존 통합을 이전하려면 요청의 변경 전후를 보여 주는 computer_20251124에서 마이그레이션을 따르세요. 베타 헤더를 제거하고, tools 항목을 {"type": "computer_toolset_20260801"}로 교체한 다음, 멤버 tool_use 블록, 일괄 작업, 결과의 toolset_name에 맞게 에이전트 루프를 업데이트하세요. 이 툴셋은 Claude API와 Google Cloud에서 사용할 수 있습니다. 다른 플랫폼의 경우 컴퓨터 사용 도구의 호환성 섹션을 참조하세요. 이미 툴셋을 사용하는 통합과 browser use tool(브라우저 사용 도구)은 변경할 필요가 없습니다.

일부 어드바이저 도구 조합은 지원되지 않습니다

어드바이저 도구(베타)를 사용할 때, Claude Sonnet 5.5 "executor"(실행자)는 Claude Mythos 5.1, Claude Fable 5.1, Claude Mythos 5, Claude Fable 5, Claude Opus 5.5 또는 Claude Opus 5를 어드바이저로 사용하거나, Claude Sonnet 5.5 자체를 사용해야 합니다. Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5 어드바이저는 Claude Sonnet 5 실행자와는 작동하지만, Claude Sonnet 5.5 실행자와 함께 사용하면 400 invalid_request_error를 반환합니다. Claude Sonnet 5.5가 허용하는 모든 어드바이저는 조언을 advisor_redacted_result 블록으로 암호화하여 반환하므로, 클라이언트에서 조언 텍스트를 읽을 수 없습니다. 어드바이저 도구의 모델 호환성 및 결과 변형을 참조하세요.

기능 지원

Claude Sonnet 5.5는 메시지별 effort(베타), 대화 중간 시스템 메시지, 대화 중간 도구 변경(베타), 최소 캐시 가능 프롬프트가 512 토큰인 프롬프트 캐싱, 배치 처리, Files API, PDF 지원, 비전, 그리고 서버 측 및 클라이언트 측 도구를 지원합니다. 메시지별 effort, 대화 중간 시스템 메시지, 대화 중간 도구 변경은 Claude Sonnet 5에서는 사용할 수 없으며, Claude Sonnet 5의 최소 캐시 가능 프롬프트는 1,024 토큰입니다. Claude API와 Google Cloud에서 컴퓨터 사용에는 computer_toolset_20260801 도구 세트가 필요합니다(호환성을 깨는 변경 사항 참조). 모델별 제공 여부는 각 기능의 페이지를 참조하세요.

온디맨드 압축(베타)

compact-2026-09-04 베타 헤더를 사용하면, 최상위 compaction 매개변수를 보내는 요청이 전체 대화를 요약한 서명된 compaction 블록을 반환합니다. 그런 다음 요약된 메시지 대신 해당 블록을 맨 앞에 보내면 됩니다. 압축 시점은 직접 선택할 수 있으며, 유지하는 턴의 사고 블록은 압축과 보존된 사고에 설명된 조건에 따라 교체 후에도 유효하게 유지될 수 있습니다. Claude Sonnet 5.5에서는 사고 블록이 대화에 연결되어 있기 때문에 이 점이 중요합니다. 플랫폼별 제공 여부와 전체 요청 흐름은 온디맨드 압축을 참조하세요.

메시지에서 도구 정의하기(베타)

inline-tools-2026-09-15 베타 헤더를 사용하면, 대화 중간 시스템 메시지의 tool_addition 블록에 참조 대신 전체 도구 정의를 담을 수 있습니다. tools를 편집하지 않고 프롬프트 캐시를 잃지 않으면서 대화 도중에 도구를 추가하거나, 스키마를 변경하거나, 서버 도구를 최신 버전으로 옮길 수 있습니다. 메시지에서 도구 정의하기를 참조하세요.

사고 블록은 이를 생성한 계정에 귀속됩니다

Claude Sonnet 5.5가 생성한 사고 블록은 이를 생성한 계정 또는 그 계정에 연결된 계정에서만 작동합니다. 다른 계정이 이러한 블록을 보내면, API는 모델이 이를 보기 전에 해당 블록을 제거하며 요청은 성공합니다. Claude API와 Google Cloud에서 thinking-binding-controls-2026-08-01 베타 헤더를 사용하면, 응답의 input_transformations에 제거된 각 블록이 reason: "organization_binding_mismatch"와 함께 나열됩니다. 이전 모델의 블록은 영향을 받지 않습니다. 보존된 사고를 참조하세요.

동작 차이

Claude Sonnet 5.5는 코드를 변경하지 않아도 드러나는 여러 측면에서 Claude Sonnet 5와 다릅니다. Claude Sonnet 5.5 프롬프팅에서 각 항목에 대한 안내를 확인할 수 있습니다:

• Effort 수준이 재조정되었습니다. Effort 수준은 Claude Sonnet 5에서와 같은 양의 사고를 생성하지 않습니다. 기존 설정을 그대로 가져오지 말고 effort 비교 테스트를 다시 실행하세요. 워크로드가 에이전트형이거나 "latency"(지연 시간)에 민감하지 않다면 high에서 시작하세요. 에이전트형 코딩과 다단계 도구 사용의 경우, 명확하게 정의된 작업은 medium에서 시작하고 더 어렵거나 긴 작업은 high로 올리세요. 채팅 및 기타 지연 시간에 민감한 작업의 경우 medium 또는 low에서 시작하세요.
• 도구 호출 사이의 텍스트가 사고 블록으로 반환됩니다. 도구 호출 사이에서 한두 문장보다 긴 메모는 진행 상황 업데이트 thinking 블록으로 반환됩니다. 더 짧은 언급은 text로 유지됩니다. 기본값인 display: "omitted"에서는 진행 상황 업데이트 블록의 텍스트가 비어 있으므로, 이러한 메모를 사용자에게 스트리밍하는 애플리케이션은 오류 없이 도구 호출 사이에 아무것도 출력하지 않게 됩니다. between_tools로 사전 사고를 끄면 텍스트가 다시 반환됩니다. 마이그레이션 가이드에서 이를 받는 방법을 확인할 수 있습니다.
• 안전장치 카테고리. 모델의 "safeguard"(안전장치)는 다섯 가지 stop_details 카테고리로 요청을 거절할 수 있습니다. "cyber"는 요청이 사이버 피해를 가능하게 할 수 있음을 의미합니다. "bio"는 생물학적 피해를 가능하게 할 수 있음을 의미합니다. "frontier_llm"은 경쟁 AI 모델 개발을 도울 수 있음을 의미합니다. "reasoning_extraction"은 모델에게 내부 추론을 응답 텍스트에 재현하도록 요청함을 의미합니다. "general_harms"는 다른 사용 정책 영역에 해당함을 의미합니다. 거절, 폴백 및 요금 청구를 참조하세요.

거절, 폴백 및 요금 청구

거절 및 폴백의 모든 내용이 Claude Sonnet 5.5에 적용됩니다. 거절된 요청은 HTTP 200과 함께 stop_reason: "refusal" 및 정책 영역을 명시하는 stop_details 객체를 반환합니다. 거절을 처리하고 "fallback"(폴백)을 구성하세요. 서버 측 폴백(fallbacks: "default", 베타, Claude API에서 제공)은 "cyber" 및 "frontier_llm" 거절을 Claude Sonnet 5에서 재시도합니다. "bio", "reasoning_extraction" 또는 "general_harms" 거절은 재시도하지 않습니다. SDK 미들웨어나 자체 재시도 로직을 사용할 수도 있습니다. 출력이 생성되기 전에 발생한 거절에 요금이 청구되는지 여부는 거절 카테고리에 따라 다르며, 어느 경우든 속도 제한에는 포함됩니다. 거절에 대한 요금 청구 방식을 참조하세요.

가격

Claude Sonnet 5.5는 프롬프트 캐싱 및 배치 처리 요금을 포함하여 Claude Sonnet 5와 가격이 동일합니다. 전체 목록, 데이터 레지던시 및 도구 가격은 가격을 참조하세요.

제공 여부

Claude Sonnet 5.5는 다음에서 사용할 수 있습니다:

• Claude API: 모든 고객, claude-sonnet-5-5로 제공.
• AWS: Claude in Amazon Bedrock에서 anthropic.claude-sonnet-5-5로, 그리고 Claude Platform on AWS에서 claude-sonnet-5-5로 제공.
• Google Cloud: Claude on Google Cloud에서 claude-sonnet-5-5로 제공.
• Microsoft Foundry: Claude in Microsoft Foundry에서 claude-sonnet-5-5로 제공.

Claude Sonnet 5에서 마이그레이션

모델 ID를 업데이트하세요:

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

그런 다음 다음 여섯 가지를 확인하세요:

1. 코드에서 disabled로 사고를 끄고 있다면, high 이하의 effort에서 대신 between_tools를 보내세요.
2. tool_choice 유형 any와 tool을 auto와 엄격한 도구 사용의 조합으로 바꾸세요.
3. 대화를 추가 전용으로 유지하세요. 이전 기록을 편집한 후 Claude Sonnet 5.5 사고 블록을 다시 전송하는 요청은 400 오류를 반환할 수 있습니다. 사고 블록은 모델 및 대화에 연결됩니다를 참조하세요.
4. Claude API 또는 Google Cloud에서 computer_20251124를 통해 컴퓨터 사용을 이용하고 있다면, 도구 세트로 옮기세요.
5. Claude Opus 4.8, Claude Opus 4.7 또는 Claude Sonnet 5 어드바이저와 함께 어드바이저 도구를 사용하고 있다면, Claude Sonnet 5.5가 허용하는 어드바이저로 전환하세요.
6. 인터페이스에 도구 호출 사이의 텍스트를 표시한다면, 적응형 사고를 사용할 때 thinking.display를 설정하세요. between_tools를 사용하면 이 설정 없이도 텍스트가 반환됩니다. 도구 호출 사이의 텍스트가 사고 블록으로 반환됩니다를 참조하세요.

마이그레이션 가이드에는 Claude Sonnet 5 및 이전 모델에서 옮겨 오는 단계별 안내와 전체 체크리스트가 있습니다.

다음 단계