확장 사고로 구축하기

확장 사고는 Claude에게 복잡한 작업을 위한 향상된 추론 능력을 제공하며, 최종 답변을 제공하기 전에 단계별 사고 과정에 대한 다양한 수준의 투명성을 제공합니다.



지원되는 모델

수동 확장 사고(thinking: {type: "enabled", budget_tokens: N})는 Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, Claude Opus 4.7을 제외한 모든 현재 Claude 모델에서 지원되며, 해당 모델에서는 허용되지 않고 400 오류를 반환합니다. 일부 모델에는 모드별 동작이 있습니다:

• Claude Fable 5 (claude-fable-5) 및 Claude Mythos 5 (claude-mythos-5): 수동 확장 사고는 지원되지 않으며 400 오류를 반환합니다. 적응형 사고가 항상 켜져 있습니다. effort 매개변수를 사용하여 사고 깊이를 제어하세요.
• Claude Opus 4.8 (claude-opus-4-8): 수동 확장 사고는 지원되지 않으며 400 오류를 반환합니다. 대신 적응형 사고(thinking: {type: "adaptive"})를 effort 매개변수와 함께 사용하세요. 모델은 각 요청에 따라 확장 사고를 사용할지 여부와 사용량을 결정합니다.
• Claude Opus 4.7 (claude-opus-4-7): 수동 확장 사고는 더 이상 지원되지 않습니다. 대신 적응형 사고(thinking: {type: "adaptive"})를 effort 매개변수와 함께 사용하세요.
• Claude Mythos Preview: 적응형 사고가 기본값입니다. thinking: {type: "enabled", budget_tokens: N}도 허용됩니다. thinking: {type: "disabled"}는 지원되지 않으며, display는 사고 콘텐츠를 반환하는 대신 "omitted"가 기본값입니다. 요약을 받으려면 display: "summarized"를 전달하세요.
• Claude Opus 4.6 (claude-opus-4-6): 적응형 사고가 권장됩니다. 수동 모드(type: "enabled")는 더 이상 사용되지 않지만 여전히 작동합니다.
• Claude Sonnet 4.6 (claude-sonnet-4-6): 적응형 사고가 권장됩니다. 인터리브 모드를 사용하는 수동 모드(type: "enabled")는 더 이상 사용되지 않지만 여전히 작동합니다.



확장 사고의 작동 방식

확장 사고가 켜져 있으면 Claude는 내부 추론을 출력하는 thinking 콘텐츠 블록을 생성합니다. Claude는 최종 응답을 작성하기 전에 이 추론에서 얻은 통찰을 반영합니다.

API 응답에는 thinking 콘텐츠 블록이 포함되고, 그 뒤에 text 콘텐츠 블록이 이어집니다.

다음은 기본 응답 형식의 예입니다:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

확장 사고의 응답 형식에 대한 자세한 내용은 Messages API 참조를 참조하세요.



확장 사고 사용 방법

다음은 Messages API에서 확장 사고를 사용하는 예입니다:

확장 사고를 켜려면 thinking 객체를 추가하고, type 매개변수를 enabled로 설정하고 budget_tokens를 확장 사고를 위한 지정된 토큰 예산으로 설정하세요. Claude Opus 4.6 및 Claude Sonnet 4.6의 경우 대신 type: "adaptive"를 사용하세요. 자세한 내용은 적응형 사고를 참조하세요. 이러한 모델에서 budget_tokens를 사용하는 type: "enabled"는 여전히 작동하지만, 더 이상 사용되지 않으며 향후 릴리스에서 제거될 예정입니다.

budget_tokens 매개변수는 Claude가 내부 추론 과정에 사용할 수 있는 최대 토큰 수를 결정합니다. 이 제한은 요약된 출력이 아닌 전체 사고 토큰에 적용됩니다. 더 큰 예산은 복잡한 문제에 대해 더 철저한 분석을 가능하게 하여 응답 품질을 향상시킬 수 있지만, Claude가 할당된 예산 전체를 사용하지 않을 수 있으며, 특히 32k 이상의 범위에서 그렇습니다.

budget_tokens는 max_tokens보다 작은 값으로 설정해야 합니다. 그러나 도구와 함께 인터리브 사고를 사용할 때는 토큰 제한이 전체 컨텍스트 윈도우가 되므로 이 제한을 초과할 수 있습니다. budget_tokens는 max_tokens보다 작아야 하므로, 확장 사고는 max_tokens: 0(캐시 사전 워밍)과 결합할 수 없습니다.



요약된 사고

확장 사고가 활성화되면 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 값과 관계없이 사고 블록이 생성되지 않습니다.

최종 사용자에게 사고 콘텐츠를 표시하지 않는 자동화된 파이프라인은 네트워크를 통해 사고 토큰을 수신하는 오버헤드를 건너뛸 수 있습니다. 지연 시간에 민감한 애플리케이션은 최종 응답이 시작되기 전에 사고 텍스트가 스트리밍되기를 기다리지 않고도 동일한 추론 품질을 얻을 수 있습니다.

display: "omitted"가 설정되면 응답에는 빈 thinking 필드를 가진 thinking 블록이 포함됩니다:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EosnCkYICxIMMb3LzNrMu..."
    },
    {
      "type": "text",
      "text": "The answer is 12,231."
    }
  ]
}

display: "omitted"로 스트리밍할 때는 thinking_delta 이벤트가 발생하지 않습니다. 이벤트 순서는 아래의 사고 스트리밍을 참조하세요.



사고 스트리밍

server-sent events (SSE)를 사용하여 확장 사고 응답을 스트리밍할 수 있습니다.

확장 사고에 대해 스트리밍이 활성화되면 thinking_delta 이벤트를 통해 사고 콘텐츠를 수신합니다.

display: "omitted"가 설정되면 thinking_delta 이벤트가 발생하지 않습니다. 사고 표시 제어를 참조하세요.

Messages API를 통한 스트리밍에 대한 자세한 문서는 메시지 스트리밍을 참조하세요.

다음은 사고와 함께 스트리밍을 처리하는 방법입니다:

스트리밍 출력 예시:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-6", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": "", "signature": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21\n147 = 7 × 21 + 0\n\nSo GCD(1071, 462) = 21"}}

// Additional thinking deltas...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}

// Additional text deltas...

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

display: "omitted"가 설정되면 사고 블록이 열리고, 단일 signature_delta가 도착한 후, thinking_delta 이벤트 없이 블록이 닫힙니다. 텍스트 스트리밍은 그 직후에 시작됩니다:

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"EosnCkYICxIMMb3LzNrMu..."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}



도구 사용과 함께하는 확장 사고

확장 사고는 도구 사용과 함께 사용할 수 있으며, Claude가 도구 선택 및 결과 처리를 추론할 수 있게 합니다.

도구 사용과 함께 확장 사고를 사용할 때는 다음 제한 사항에 유의하세요:

1. 도구 선택 제한: 사고와 함께하는 도구 사용은 tool_choice: {"type": "auto"}(기본값) 또는 tool_choice: {"type": "none"}만 지원합니다. tool_choice: {"type": "any"} 또는 tool_choice: {"type": "tool", "name": "..."}를 사용하면 오류가 발생합니다. 이러한 옵션은 도구 사용을 강제하는데, 이는 확장 사고와 호환되지 않기 때문입니다.

2. 사고 블록 보존: 도구 사용 중에는 마지막 어시스턴트 메시지에 대한 thinking 블록을 API에 다시 전달해야 합니다. 추론 연속성을 유지하려면 수정되지 않은 완전한 블록을 API에 다시 포함하세요.



대화에서 사고 모드 전환

도구 사용 루프를 포함하여 어시스턴트 턴 중간에 사고를 전환할 수 없습니다. 전체 어시스턴트 턴은 단일 사고 모드에서 작동해야 합니다:

• 사고가 활성화된 경우, 최종 어시스턴트 턴은 사고 블록으로 시작해야 합니다.
• 사고가 비활성화된 경우, 최종 어시스턴트 턴에는 사고 블록이 포함되지 않아야 합니다

모델의 관점에서 도구 사용 루프는 어시스턴트 턴의 일부입니다. 어시스턴트 턴은 Claude가 전체 응답을 완료할 때까지 완료되지 않으며, 여기에는 여러 도구 호출과 결과가 포함될 수 있습니다.

예를 들어, 이 시퀀스는 모두 단일 어시스턴트 턴의 일부입니다:

User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]

여러 API 메시지가 있더라도 도구 사용 루프는 개념적으로 하나의 연속적인 어시스턴트 응답의 일부입니다.



우아한 사고 저하

턴 중간 사고 충돌이 발생하면(예: 도구 사용 루프 중에 사고를 켜거나 끄는 경우), API는 해당 요청에 대해 자동으로 사고를 비활성화합니다. 모델 품질을 보존하고 분포 내에 유지하기 위해 API는 다음을 수행할 수 있습니다:

• 유효하지 않은 턴 구조를 만들 수 있는 경우 대화에서 사고 블록 제거
• 대화 기록이 사고 활성화와 호환되지 않는 경우 현재 요청에 대해 사고 비활성화

즉, 턴 중간에 사고를 전환하려고 해도 오류가 발생하지 않지만, 해당 요청에 대해 사고가 조용히 비활성화됩니다. 사고가 활성화되었는지 확인하려면 응답에 thinking 블록이 있는지 확인하세요.



실용적인 지침

모범 사례: 턴 중간에 전환하려고 하기보다는 각 턴 시작 시 사고 전략을 계획하세요.

예시: 턴 완료 후 사고 전환

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"]
User: "What about tomorrow?"
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)

사고를 전환하기 전에 어시스턴트 턴을 완료함으로써 새 요청에 대해 사고가 실제로 활성화되도록 보장할 수 있습니다.



사고 블록 보존

도구 사용 중에는 thinking 블록을 API에 다시 전달해야 하며, 수정되지 않은 완전한 블록을 API에 다시 포함해야 합니다. 이는 모델의 추론 흐름과 대화 무결성을 유지하는 데 매우 중요합니다.

Claude가 도구를 호출할 때, 외부 정보를 기다리기 위해 응답 구성을 일시 중지합니다. 도구 결과가 반환되면 Claude는 기존 응답을 계속 구축합니다. 이로 인해 다음과 같은 몇 가지 이유로 도구 사용 중에 사고 블록을 보존해야 합니다:

1. 추론 연속성: 사고 블록은 도구 요청으로 이어진 Claude의 단계별 추론을 담고 있습니다. 도구 결과를 게시할 때 원래 사고를 포함하면 Claude가 중단된 지점부터 추론을 계속할 수 있습니다.

2. 컨텍스트 유지: 도구 결과는 API 구조에서 사용자 메시지로 나타나지만, 연속적인 추론 흐름의 일부입니다. 사고 블록을 보존하면 여러 API 호출에 걸쳐 이 개념적 흐름이 유지됩니다. 컨텍스트 관리에 대한 자세한 내용은 컨텍스트 윈도우 가이드를 참조하세요.

중요: thinking 블록을 제공할 때, 연속된 thinking 블록의 전체 시퀀스는 원래 요청 중에 모델이 생성한 출력과 일치해야 합니다. 이러한 블록의 시퀀스를 재배열하거나 수정할 수 없습니다.



인터리브 사고

Claude 4 모델에서 도구 사용과 함께하는 확장 사고는 인터리브 사고를 지원하며, 이를 통해 Claude는 도구 호출 사이에 사고하고 도구 결과를 받은 후 더 정교한 추론을 할 수 있습니다.

인터리브 사고를 사용하면 Claude는 다음을 수행할 수 있습니다:

• 다음에 무엇을 할지 결정하기 전에 도구 호출 결과에 대해 추론
• 추론 단계를 사이에 두고 여러 도구 호출을 연결
• 중간 결과를 기반으로 더 세밀한 결정

모델 지원:

• Claude Opus 4.8: 적응형 사고(Claude Opus 4.8에서 유일하게 지원되는 사고 모드)를 사용할 때 인터리브 사고가 자동으로 활성화됩니다. 베타 헤더가 필요하지 않습니다.
• Claude Mythos Preview: 인터리브 사고가 자동으로 발생합니다. 모든 도구 간 추론 단계가 일반 텍스트 대신 사고 블록으로 이동하며, 사고 블록은 기본적으로 턴 간에 보존됩니다. 베타 헤더가 필요하지 않으며 지원되지도 않습니다.
• Claude Opus 4.7: 적응형 사고(Opus 4.7에서 유일하게 지원되는 사고 모드)를 사용할 때 인터리브 사고가 자동으로 활성화됩니다. 베타 헤더가 필요하지 않습니다.
• Claude Opus 4.6: 적응형 사고를 사용할 때 인터리브 사고가 자동으로 활성화됩니다. 베타 헤더가 필요하지 않습니다. interleaved-thinking-2025-05-14 베타 헤더는 Opus 4.6에서 더 이상 사용되지 않으며 포함되어도 안전하게 무시됩니다.
• Claude Sonnet 4.6: 적응형 사고(권장)를 사용할 때 인터리브 사고가 자동으로 활성화됩니다. 수동 확장 사고(thinking: {type: "enabled"})와 함께 사용하는 interleaved-thinking-2025-05-14 베타 헤더는 여전히 작동하지만 더 이상 사용되지 않습니다.
• 기타 Claude 4 모델 (Opus 4.5, Opus 4.1 (더 이상 사용되지 않음), Opus 4 (더 이상 사용되지 않음), Sonnet 4.5, Sonnet 4 (더 이상 사용되지 않음)): 인터리브 사고를 활성화하려면 API 요청에 를 추가하세요.

인터리브 사고에 대한 몇 가지 중요한 고려 사항은 다음과 같습니다:

• 인터리브 사고를 사용하면 budget_tokens가 max_tokens 매개변수를 초과할 수 있습니다. 이는 하나의 어시스턴트 턴 내 모든 사고 블록에 걸친 총 예산을 나타내기 때문입니다.
• 인터리브 사고는 Messages API를 통해 사용되는 도구에 대해서만 지원됩니다.
• Claude API 및 AWS의 Claude Platform은 오류를 반환하지 않고 모든 모델에 대한 요청에서 interleaved-thinking-2025-05-14를 허용합니다. 인터리브 사고를 지원하지 않는 모델에서는 헤더가 무시됩니다. Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6에서는 더 이상 사용되지 않으며 안전하게 무시됩니다. Claude Mythos Preview에서는 필요하지 않으며 안전하게 무시됩니다.
• 파트너 운영 플랫폼(예: Amazon Bedrock 및 Vertex AI)에서 Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5, Claude Opus 4.1 (더 이상 사용되지 않음), Opus 4 (더 이상 사용되지 않음), Sonnet 4.5, Sonnet 4 (더 이상 사용되지 않음) 이외의 모델에 interleaved-thinking-2025-05-14를 전달하면 요청이 실패합니다.



프롬프트 캐싱과 함께하는 확장 사고

사고와 함께하는 프롬프트 캐싱에는 몇 가지 중요한 고려 사항이 있습니다:

사고 블록 컨텍스트 제거

• 이전 Opus/Sonnet 모델 및 모든 Haiku 모델에서는 이전 턴의 사고 블록이 컨텍스트에서 제거되며, 이는 캐시 중단점에 영향을 줄 수 있습니다. Opus 4.5+ 및 Sonnet 4.6+에서는 기본적으로 유지됩니다.
• 도구 사용으로 대화를 계속할 때 사고 블록은 캐시되며 캐시에서 읽을 때 입력 토큰으로 계산됩니다
• 이는 트레이드오프를 만듭니다: 사고 블록이 시각적으로 컨텍스트 윈도우 공간을 소비하지 않지만, 캐시될 때 여전히 입력 토큰 사용량에 포함됩니다
• 사고가 비활성화되고 현재 도구 사용 턴에서 사고 콘텐츠를 전달하면, 사고 콘텐츠가 제거되고 해당 요청에 대해 사고가 비활성화된 상태로 유지됩니다

캐시 무효화 패턴

• 사고 매개변수 변경(활성화/비활성화 또는 예산 할당)은 메시지 캐시 중단점을 무효화합니다
• 인터리브 사고는 사고 블록이 여러 도구 호출 사이에 발생할 수 있으므로 캐시 무효화를 증폭시킵니다
• 시스템 프롬프트와 도구는 사고 매개변수 변경이나 블록 제거에도 불구하고 캐시된 상태로 유지됩니다



사고 블록 캐싱 동작 이해하기

도구 사용과 함께 확장 사고를 사용할 때, 사고 블록은 토큰 계산에 영향을 미치는 특정 캐싱 동작을 보입니다:

작동 방식:

1. 캐싱은 도구 결과를 포함하는 후속 요청을 할 때만 발생합니다
2. 후속 요청이 이루어지면 이전 대화 기록(사고 블록 포함)이 캐시될 수 있습니다
3. 이러한 캐시된 사고 블록은 캐시에서 읽을 때 사용량 지표에서 입력 토큰으로 계산됩니다
4. 도구 결과가 아닌 사용자 블록이 포함되면: Opus 4.5+ 및 Sonnet 4.6+에서는 이전 사고 블록이 유지됩니다. 이전 Opus/Sonnet 모델 및 모든 Haiku 모델에서는 모든 이전 사고 블록이 무시되고 컨텍스트에서 제거됩니다

상세 예시 흐름:

요청 1:

User: "What's the weather in Paris?"

응답 1:

[thinking_block_1] + [tool_use block 1]

요청 2:

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]

응답 2:

[thinking_block_2] + [text block 2]

요청 2는 요청 콘텐츠(응답이 아님)의 캐시를 작성합니다. 캐시에는 원래 사용자 메시지, 첫 번째 사고 블록, 도구 사용 블록, 도구 결과가 포함됩니다.

요청 3:

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]

Opus 4.5+ 및 Sonnet 4.6+의 경우, 모든 이전 사고 블록이 기본적으로 유지됩니다. 이전 Opus/Sonnet 모델 및 모든 Haiku 모델의 경우, 도구 결과가 아닌 사용자 블록이 포함되었기 때문에 모든 이전 사고 블록이 무시되고 컨텍스트에서 제거됩니다. 이 요청은 다음과 동일하게 처리됩니다:

User: ["What's the weather in Paris?"],
Assistant: [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [text block 2],
User: [Text response, cache=True]

핵심 사항:

• 이 캐싱 동작은 명시적인 cache_control 마커 없이도 자동으로 발생합니다
• 이 동작은 일반 사고를 사용하든 인터리브 사고를 사용하든 일관됩니다



확장 사고와 함께하는 최대 토큰 및 컨텍스트 윈도우 크기

max_tokens(사고가 활성화된 경우 사고 예산 포함)는 엄격한 제한으로 적용됩니다. Claude 4.5 모델 이상에서는 입력 토큰과 max_tokens의 합이 컨텍스트 윈도우 크기를 초과하면 API가 요청을 수락합니다. 생성이 컨텍스트 윈도우 제한에 도달하면 stop_reason: "model_context_window_exceeded"로 중지됩니다. 이전 모델에서는 API가 대신 유효성 검사 오류를 반환합니다. 중지 이유 처리를 참조하세요.



확장 사고와 함께하는 컨텍스트 윈도우

사고가 활성화된 상태에서 컨텍스트 윈도우 사용량을 계산할 때 알아야 할 몇 가지 고려 사항이 있습니다:

• Opus 4.5+ 및 Sonnet 4.6+에서는 이전 턴의 사고 블록이 유지되며 컨텍스트 윈도우에 포함됩니다. 이전 Opus/Sonnet 모델 및 모든 Haiku 모델에서는 제거되며 계산되지 않습니다
• 현재 턴의 사고는 해당 턴의 max_tokens 제한에 포함됩니다

아래 다이어그램은 확장 사고가 활성화되었을 때의 특수한 토큰 관리를 보여줍니다:

유효 컨텍스트 윈도우는 다음과 같이 계산됩니다:

context window =
  (current input tokens - previous thinking tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

특히 사고가 포함된 다중 턴 대화를 다룰 때는 토큰 계산 API를 사용하여 특정 사용 사례에 대한 정확한 토큰 수를 확인하세요.



확장 사고 및 도구 사용과 함께하는 컨텍스트 윈도우

도구 사용과 함께 확장 사고를 사용할 때는 사고 블록을 명시적으로 보존하고 도구 결과와 함께 반환해야 합니다.

도구 사용과 함께하는 확장 사고의 유효 컨텍스트 윈도우 계산은 다음과 같습니다:

context window =
  (current input tokens + previous thinking tokens + tool use tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

아래 다이어그램은 도구 사용과 함께하는 확장 사고의 토큰 관리를 보여줍니다:



확장 사고와 함께 토큰 관리하기

확장 사고와 함께하는 컨텍스트 윈도우 및 max_tokens 동작을 고려할 때 다음이 필요할 수 있습니다:

• 토큰 사용량을 더 적극적으로 모니터링하고 관리
• 프롬프트 길이가 변경됨에 따라 max_tokens 값 조정
• 토큰 계산 엔드포인트를 더 자주 사용할 가능성
• 이전 사고 블록이 컨텍스트 윈도우에 누적되지 않는다는 점 인지



사고 암호화

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

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

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



편집된 사고 블록

일반 thinking 블록 외에도 API는 redacted_thinking 블록을 반환할 수 있습니다. redacted_thinking 블록은 읽을 수 있는 요약 없이 data 필드에 암호화된 사고 콘텐츠를 포함합니다:

{
  "type": "redacted_thinking",
  "data": "..."
}

data 필드는 불투명하고 암호화되어 있습니다. 일반 사고 블록의 signature 필드와 마찬가지로, 도구와 함께 다중 턴 대화를 계속할 때 redacted_thinking 블록을 변경하지 않고 API에 다시 전달해야 합니다.



모델 버전별 사고의 차이점

Messages API는 Claude 모델 버전에 따라 사고를 다르게 처리합니다. 다음 표는 간략한 비교를 제공합니다:



모델별 사고 블록 보존

이전 어시스턴트 턴의 사고 블록이 기본적으로 컨텍스트에 보존되는지 여부는 모델 클래스에 따라 다릅니다. Opus: Claude Opus 4.5 및 이후 Opus 모델은 모든 이전 사고 블록을 유지합니다. Claude Opus 4.1 (더 이상 사용되지 않음) 및 이전 Opus 모델은 마지막 어시스턴트 턴의 사고만 유지합니다. Sonnet: Claude Sonnet 4.6 및 이후 Sonnet 모델은 모두 유지합니다. Claude Sonnet 4.5 및 이전 Sonnet 모델은 마지막 턴만 유지합니다. Haiku: Claude Haiku 4.5까지의 모든 Haiku 모델은 마지막 턴만 유지합니다. Claude Mythos Preview도 모든 이전 사고 블록을 유지합니다.

사고 블록 보존의 이점:

• 캐시 최적화: 도구 사용 시 보존된 사고 블록은 도구 결과와 함께 다시 전달되고 어시스턴트 턴 전체에 걸쳐 점진적으로 캐시되므로 캐시 히트를 가능하게 하여 다단계 워크플로에서 토큰 절약을 가져옵니다
• 지능에 영향 없음: 사고 블록을 보존해도 모델 성능에 부정적인 영향이 없습니다

중요한 고려 사항:

• 컨텍스트 사용량: 사고 블록이 컨텍스트에 유지되므로 긴 대화는 더 많은 컨텍스트 공간을 소비합니다
• 자동 동작: 이는 위에 나열된 대로 각 모델의 기본값입니다. 코드 변경이나 베타 헤더가 필요하지 않습니다
• 하위 호환성: 이 기능을 활용하려면 도구 사용 시와 마찬가지로 완전하고 수정되지 않은 사고 블록을 API에 계속 다시 전달하세요



가격 책정

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

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

• 사고 중에 사용된 토큰(출력 토큰)
• 컨텍스트에 유지되는 이전 어시스턴트 턴의 사고 블록: 이전 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는 관찰 가능성을 위한 읽기 전용 세부 내역입니다.



확장 사고에 대한 모범 사례 및 고려 사항



사고 예산 작업하기

• 예산 최적화: 최소 예산은 1,024 토큰입니다. 최소값에서 시작하여 사고 예산을 점진적으로 늘려가며 사용 사례에 맞는 최적의 범위를 찾으세요. 더 높은 토큰 수는 더 포괄적인 추론을 가능하게 하지만 작업에 따라 수익이 감소합니다. 예산을 늘리면 latency(지연 시간) 증가를 감수하는 대신 응답 품질을 향상시킬 수 있습니다. 중요한 작업의 경우 다양한 설정을 테스트하여 최적의 균형을 찾으세요. 사고 예산은 엄격한 제한이 아니라 목표치라는 점에 유의하세요. 실제 토큰 사용량은 작업에 따라 달라질 수 있습니다.
• 시작점: 복잡한 작업의 경우 더 큰 사고 예산(16k+ 토큰)으로 시작하고 필요에 따라 조정하세요.
• 큰 예산: 32k를 초과하는 사고 예산의 경우 네트워킹 문제를 피하기 위해 배치 처리를 사용하세요. 모델이 32k 토큰 이상으로 사고하도록 하는 요청은 장시간 실행되는 요청을 발생시켜 시스템 타임아웃 및 열린 연결 제한에 부딪힐 수 있습니다.
• 토큰 사용량 추적: 비용과 성능을 최적화하기 위해 사고 토큰 사용량을 모니터링하세요. 응답의 usage.output_tokens_details.thinking_tokens 필드는 청구된 출력 토큰 중 내부 추론에 사용된 토큰 수를 보고합니다. 스트리밍 시 이 세부 내역은 마지막 message_delta 이벤트에만 나타납니다.



성능 고려 사항

• 응답 시간: 추가 처리로 인해 더 긴 응답 시간에 대비하세요. 사고 블록 생성은 전체 응답 시간을 증가시킵니다.
• 스트리밍 요구 사항: SDK는 장시간 실행되는 요청에서 HTTP 타임아웃을 피하기 위해 max_tokens가 21,333보다 클 때 스트리밍을 요구합니다. 이는 클라이언트 측 검증이며 API 제한이 아닙니다. 이벤트를 점진적으로 처리할 필요가 없다면 .stream()과 함께 .get_final_message()(Python) 또는 .finalMessage()(TypeScript)를 사용하여 개별 이벤트를 처리하지 않고 완전한 Message 객체를 얻으세요. 자세한 내용은 메시지 스트리밍을 참조하세요. 스트리밍 시 사고 및 텍스트 콘텐츠 블록이 도착할 때 둘 다 처리할 준비를 하세요.
• 지연 시간을 위한 사고 생략: 애플리케이션이 사고 콘텐츠를 표시하지 않는 경우, 사고 구성에서 display: "omitted"를 설정하여 첫 텍스트 토큰까지의 시간을 줄이세요. 사고 표시 제어를 참조하세요.



기능 호환성

• 사고는 temperature 또는 top_k 수정 및 강제 도구 사용과 호환되지 않습니다.
• 사고가 활성화된 경우 top_p를 1에서 0.95 사이의 값으로 설정할 수 있습니다.
• 사고가 활성화된 경우 응답을 미리 채울 수 없습니다.
• 사고 예산을 변경하면 메시지를 포함하는 캐시된 프롬프트 접두사가 무효화됩니다. 그러나 캐시된 시스템 프롬프트와 도구 정의는 사고 매개변수가 변경되어도 계속 작동합니다.



사용 지침

• 작업 선택: 수학, 코딩, 분석과 같이 단계별 추론이 도움이 되는 특히 복잡한 작업에 확장 사고를 사용하세요.
• 컨텍스트 처리: 이전 사고 블록을 직접 제거할 필요가 없습니다. Opus 4.5+ 및 Sonnet 4.6+에서는 Claude API가 기본적으로 이전 턴의 사고 블록을 유지하며, 이전 Opus/Sonnet 모델 및 모든 Haiku 모델에서는 자동으로 무시되고 컨텍스트 사용량 계산 시 포함되지 않습니다.
• 프롬프트 엔지니어링: Claude의 사고 능력을 극대화하려면 확장 사고 프롬프팅 팁을 검토하세요.



다음 단계