적응형 사고

적응형 사고는 Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 및 Claude Sonnet 4.6에서 확장 사고를 사용하는 권장 방법입니다. Claude Fable 5 및 Claude Mythos 5에서는 사고가 항상 활성화되어 있으며 비활성화할 수 없습니다. 적응형 사고가 유일한 사고 모드입니다. Claude Mythos Preview에서는 적응형 사고가 기본 모드이며 thinking이 설정되지 않은 경우 자동으로 적용됩니다. 사고 토큰 예산을 수동으로 설정하는 대신, 적응형 사고는 Claude가 각 요청의 복잡성에 따라 확장 사고를 언제, 얼마나 사용할지 동적으로 결정하도록 합니다. Claude Opus 4.8 및 Claude Opus 4.7에서는 적응형 사고가 유일하게 지원되는 사고 모드입니다. 수동 thinking: {type: "enabled", budget_tokens: N}은 더 이상 허용되지 않습니다.



지원되는 모델

적응형 사고는 다음 모델에서 지원됩니다.

• Claude Fable 5 (claude-fable-5) 및 Claude Mythos 5 (claude-mythos-5): 적응형 사고가 항상 켜져 있으며 thinking: {type: "disabled"}는 지원되지 않습니다.
• Claude Mythos Preview (claude-mythos-preview): 적응형 사고가 기본값이며 thinking: {type: "disabled"}는 지원되지 않습니다.
• Claude Opus 4.8 (claude-opus-4-8): 적응형 사고가 유일하게 지원되는 사고 모드입니다. 요청에서 thinking: {type: "adaptive"}를 명시적으로 설정하지 않으면 사고가 꺼져 있습니다. 수동 thinking: {type: "enabled"}는 400 오류와 함께 거부됩니다.
• Claude Opus 4.7 (claude-opus-4-7): 적응형 사고가 유일하게 지원되는 사고 모드입니다. 요청에서 thinking: {type: "adaptive"}를 명시적으로 설정하지 않으면 사고가 꺼져 있습니다. 수동 thinking: {type: "enabled"}는 400 오류와 함께 거부됩니다.
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Sonnet 4.6 (claude-sonnet-4-6)



적응형 사고의 작동 방식

적응형 모드에서는 모델이 사고를 선택적으로 수행합니다. Claude는 각 요청의 복잡성을 평가하고 확장 사고를 사용할지 여부와 사용량을 결정합니다. 기본 effort 수준(high)에서 Claude는 거의 항상 사고합니다. 더 낮은 effort 수준에서는 Claude가 더 간단한 문제에 대해 사고를 건너뛸 수 있습니다.

적응형 사고는 또한 인터리브 사고를 자동으로 활성화합니다. 이는 Claude가 도구 호출 사이에 사고할 수 있음을 의미하며, 에이전트 워크플로에 특히 효과적입니다.



적응형 사고 사용 방법

API 요청에서 thinking.type을 "adaptive"로 설정하세요.



effort 매개변수와 함께 사용하는 적응형 사고

적응형 사고를 effort 매개변수와 결합하여 Claude가 수행하는 사고의 양을 안내할 수 있습니다. effort 수준은 Claude의 사고 할당에 대한 소프트 가이드 역할을 합니다.



적응형 사고와 스트리밍

적응형 사고는 스트리밍과 원활하게 작동합니다. 사고 블록은 수동 사고 모드와 마찬가지로 thinking_delta 이벤트를 통해 스트리밍됩니다.



적응형 vs 수동 vs 비활성화 사고



중요 고려 사항



유효성 검사 변경 사항

적응형 사고를 사용할 때 이전 어시스턴트 턴이 사고 블록으로 시작할 필요가 없습니다. 이는 API가 사고가 활성화된 턴이 사고 블록으로 시작하도록 강제하는 수동 모드보다 더 유연합니다.



프롬프트 캐싱

adaptive 사고를 사용하는 연속 요청은 프롬프트 캐시 중단점을 유지합니다. 그러나 adaptive와 enabled/disabled 사고 모드 간 전환은 메시지에 대한 캐시 중단점을 무효화합니다. 시스템 프롬프트와 도구 정의는 모드 변경과 관계없이 캐시된 상태로 유지됩니다.



사고 동작 조정

적응형 사고의 트리거 동작은 프롬프트로 조정할 수 있습니다. Claude가 원하는 것보다 더 자주 또는 덜 자주 사고하는 경우 시스템 프롬프트에 지침을 추가할 수 있습니다.

Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality — typically for problems
that require multi-step reasoning. When in doubt, respond directly.

반대로 사고를 유도하려면 다음과 같은 문구를 사용하세요.

This task involves multi-step reasoning. Think carefully before responding.

조정 효과는 정확한 표현에 민감할 수 있습니다. 한 표현이 원하는 동작을 생성하지 않으면 더 직접적인 변형을 시도해 보세요.

사용자 턴에서 메시지별로 사고를 조정할 수도 있습니다. 사용자 메시지에 "Please think hard before responding."를 추가하면 Claude가 해당 턴에서 사고하도록 유도합니다. "Answer directly without deliberating."는 이를 억제합니다. 이는 시스템 프롬프트와 독립적으로 작동하며 대화의 일부 요청만 확장된 추론이 필요한 경우에 유용합니다.



비용 제어

총 출력(사고 + 응답 텍스트)에 대한 하드 제한으로 max_tokens를 사용하세요. effort 매개변수는 Claude가 할당하는 사고의 양에 대한 추가적인 소프트 가이드를 제공합니다. 이 둘을 함께 사용하면 비용을 효과적으로 제어할 수 있습니다.

high 및 max effort 수준에서 Claude는 더 광범위하게 사고할 수 있으며 max_tokens 예산을 소진할 가능성이 더 높습니다. 응답에서 stop_reason: "max_tokens"를 관찰하는 경우 모델에 더 많은 여유를 주기 위해 max_tokens를 늘리거나 effort 수준을 낮추는 것을 고려하세요.



사고 블록 작업

다음 개념은 적응형 모드 또는 수동 모드 사용 여부와 관계없이 확장 사고를 지원하는 모든 모델에 적용됩니다.



요약된 사고

확장 사고가 활성화되면 Claude 4 모델용 Messages API는 Claude의 전체 사고 과정에 대한 요약을 반환합니다. 요약된 사고는 확장 사고의 모든 지능적 이점을 제공하면서 오용을 방지합니다. 이는 사고 구성의 display 필드가 설정되지 않았거나 "summarized"로 설정된 경우 Claude 4 모델의 기본 동작입니다. Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, Claude Opus 4.7 및 Claude Mythos Preview에서는 display가 기본적으로 "omitted"로 설정되므로, 요약된 사고를 받으려면 display: "summarized"를 명시적으로 설정해야 합니다.

요약된 사고에 대한 몇 가지 중요한 고려 사항은 다음과 같습니다:

• 요약 토큰이 아니라 원래 요청에서 생성된 전체 사고 토큰에 대해 요금이 청구됩니다.
• 청구된 출력 토큰 수는 응답에서 확인하는 토큰 수와 일치하지 않습니다.
• Claude 4 모델에서는 사고 출력의 처음 몇 줄이 더 상세하여, 프롬프트 엔지니어링 목적에 특히 유용한 자세한 추론을 제공합니다. Claude Mythos Preview는 첫 번째 토큰부터 요약하므로, 해당 사고 블록에는 이러한 상세한 서두가 표시되지 않습니다.
• Anthropic이 확장 사고 기능을 개선하고자 함에 따라 요약 동작은 변경될 수 있습니다.
• 요약은 최소한의 추가 "latency"(지연 시간)로 Claude의 사고 과정의 핵심 아이디어를 보존하여 스트리밍 가능한 사용자 경험을 제공합니다.
• 요약은 요청에서 대상으로 지정한 모델과 다른 모델에 의해 처리됩니다. 사고 모델은 요약된 출력을 보지 않습니다.



사고 표시 제어

thinking 구성의 display 필드는 API 응답에서 사고 콘텐츠가 반환되는 방식을 제어합니다. 이 필드는 두 가지 값을 허용합니다:

• "summarized": 사고 블록에 요약된 사고 텍스트가 포함됩니다. 자세한 내용은 요약된 사고를 참조하세요. 이는 Claude Opus 4.6, Claude Sonnet 4.6 및 이전 Claude 4 모델의 기본값입니다.
• "omitted": 사고 블록이 빈 thinking 필드와 함께 반환됩니다. signature 필드는 멀티턴 연속성을 위해 암호화된 전체 사고를 여전히 포함합니다(사고 암호화 참조). 이는 Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, Claude Opus 4.7 및 Claude Mythos Preview의 기본값입니다.

display: "omitted" 설정은 애플리케이션이 사용자에게 사고 콘텐츠를 표시하지 않는 경우에 유용합니다. 주요 이점은 스트리밍 시 첫 텍스트 토큰까지의 시간 단축입니다. 서버가 사고 토큰 스트리밍을 완전히 건너뛰고 서명만 전달하므로 최종 텍스트 응답의 스트리밍이 더 빨리 시작됩니다.

생략된 사고에 대한 몇 가지 중요한 고려 사항은 다음과 같습니다:

• 전체 사고 토큰에 대한 비용은 여전히 청구됩니다. 생략은 지연 시간을 줄이지만 비용은 줄이지 않습니다.
• 멀티턴 대화에서 사고 블록을 다시 전달하는 경우 변경하지 않고 그대로 전달하세요. 서버는 signature를 복호화하여 프롬프트 구성을 위한 원본 사고를 재구성합니다(사고 블록 보존 참조). 왕복된 생략 블록의 thinking 필드에 입력한 텍스트는 무시됩니다.
• display는 thinking.type: "disabled"와 함께 사용할 수 없습니다(표시할 내용이 없기 때문입니다).
• thinking.type: "adaptive"를 사용하고 모델이 간단한 요청에 대해 사고를 건너뛰는 경우, display 값과 관계없이 사고 블록이 생성되지 않습니다.

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

display: "omitted"를 사용한 코드 예제 및 스트리밍 동작은 확장 사고 페이지의 사고 표시 제어를 참조하세요. 해당 예제는 type: "enabled"를 사용합니다. 적응형 사고에서는 다음을 사용하세요.

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



사고 암호화

전체 사고 콘텐츠는 암호화되어 signature 필드로 반환됩니다. 이 필드는 사고 블록이 API로 다시 전달될 때 Claude에 의해 생성되었음을 검증하는 데 사용됩니다.

다음은 사고 암호화에 대한 몇 가지 중요한 고려 사항입니다:

• 응답을 스트리밍할 때, 서명은 content_block_stop 이벤트 직전에 content_block_delta 이벤트 내부의 signature_delta를 통해 추가됩니다.
• signature 값은 이전 모델보다 Claude 4 모델에서 훨씬 더 깁니다.
• signature 필드는 불투명한 필드이며 해석하거나 파싱해서는 안 됩니다.
• signature 값은 플랫폼 간에 호환됩니다(Claude API, Amazon Bedrock, Vertex AI). 한 플랫폼에서 생성된 값은 다른 플랫폼과 호환됩니다.



Claude Fable 5 및 Claude Mythos 5의 사고 출력

Claude Fable 5 및 Claude Mythos 5에서는 원시 사고 과정이 절대 반환되지 않습니다. 수신하는 사고 블록은 redacted_thinking이 아닌 일반 thinking 블록입니다. thinking.display 설정은 다른 모델과 동일하게 작동합니다.

• "summarized"는 추론의 읽을 수 있는 요약을 반환합니다.
• "omitted"(이러한 모델의 기본값)는 여전히 응답에 thinking 블록을 포함하지만 thinking 필드는 빈 문자열입니다.

사고 블록의 응답 형태는 Messages API 참조를 참조하세요.

동일한 모델에서 대화를 계속할 때는 thinking 필드가 비어 있는 블록을 포함하여 각 사고 블록을 받은 그대로 API에 다시 전달하세요. 편집하거나 재구성하지 마세요. 표시를 위해 요약 텍스트를 읽는 것은 괜찮습니다. API는 읽은 블록이 아니라 내용이 수정된 블록을 거부합니다.

예를 들어 분류기 거부 폴백 후 모델을 전환하는 경우, 이전 어시스턴트 턴에서 thinking 및 redacted_thinking 블록을 제거하세요. 사고 블록은 이를 생성한 모델에 연결되어 있습니다. 다른 모델은 요청을 거부하는 대신 조용히 무시하지만, 무시된 블록도 여전히 입력 토큰을 추가합니다.

폴백 크레딧에서 다루는 두 가지 예외가 있습니다.

• 폴백 크레딧 재시도는 거부된 요청 본문을 변경 없이 그대로 전달해야 합니다.
• 출력 중간 폴백의 fallback 블록은 나타난 위치에 그대로 유지됩니다.

모델의 추론에 대한 가시성을 얻으려면 응답 텍스트에서 추론을 요청하는 프롬프트를 사용하는 대신 이 섹션에서 설명한 thinking 블록을 읽으세요. Claude Fable 5에서는 모델의 내부 추론을 응답 텍스트의 일부로 유도하려는 요청이 stop_details.category: "reasoning_extraction"과 함께 거부될 수 있습니다. 필드 참조 및 처리 지침은 거부 카테고리를 참조하세요.



가격 책정

기본 요금, 캐시 쓰기, 캐시 히트 및 출력 토큰을 포함한 전체 가격 정보는 가격 페이지를 참조하세요.

사고 과정에서는 다음에 대한 비용이 발생합니다:

• 사고 중에 사용된 토큰(출력 토큰)
• 컨텍스트에 유지되는 이전 어시스턴트 턴의 사고 블록: 이전 Opus/Sonnet 모델 및 모든 Haiku 모델에서는 마지막 턴만 해당되며, Opus 4.5+ 및 Sonnet 4.6+에서는 기본적으로 모든 턴이 해당됩니다(입력 토큰)
• 표준 텍스트 출력 토큰

요약된 사고를 사용할 때:

• 입력 토큰: 원래 요청의 토큰(이전 턴의 사고 토큰 제외)
• 출력 토큰(청구됨): Claude가 내부적으로 생성한 원래 사고 토큰
• 출력 토큰(표시됨): 응답에서 볼 수 있는 요약된 사고 토큰
• 비용 없음: 요약을 생성하는 데 사용된 토큰

display: "omitted"를 사용할 때:

• 입력 토큰: 원래 요청의 토큰(요약된 경우와 동일)
• 출력 토큰(청구됨): Claude가 내부적으로 생성한 원래 사고 토큰(요약된 경우와 동일)
• 출력 토큰(표시됨): 사고 토큰 0개(thinking 필드가 비어 있음)

내부 추론에 사용된 청구 출력 토큰 수를 확인하려면 응답에서 usage.output_tokens_details.thinking_tokens를 읽으세요. 이 값은 모델이 생성한 원시 추론(본문에 반환된 요약 텍스트가 아님)을 반영하며 항상 output_tokens보다 작거나 같습니다. output_tokens에서 이 값을 빼면 출력에서 추론이 아닌 부분을 대략적으로 계산할 수 있습니다.

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

output_tokens는 청구에 사용되는 포괄적이고 권위 있는 총계로 유지됩니다. output_tokens_details는 관찰 가능성을 위한 읽기 전용 세부 내역입니다.



추가 주제

확장 사고 페이지에서는 모드별 코드 예제와 함께 여러 주제를 더 자세히 다룹니다.

• 사고와 함께 도구 사용: 적응형 사고에도 동일한 규칙이 적용됩니다. 도구 호출 사이에 사고 블록을 보존하고 사고가 활성화된 경우 tool_choice 제한 사항을 인지하세요.
• 프롬프트 캐싱: 적응형 사고를 사용하면 동일한 사고 모드를 사용하는 연속 요청이 캐시 중단점을 유지합니다. adaptive와 enabled/disabled 모드 간 전환은 메시지에 대한 캐시 중단점을 무효화합니다(시스템 프롬프트와 도구 정의는 캐시된 상태로 유지됨).
• 컨텍스트 윈도우: 사고 토큰이 max_tokens 및 컨텍스트 윈도우 제한과 상호작용하는 방식.



다음 단계