사고

한 번에 답변하는 모델은 첫 시도에서 모든 것을 정확히 맞혀야 합니다. 즉, 초안 작업도, 검증도, 중간에 방향을 바꾸는 것도 불가능합니다. 증명, 까다로운 버그, 또는 긴 에이전트 작업의 경우, 첫 번째 접근 방식이 최선이 아닌 경우가 많습니다.

사고(thinking)는 이러한 제약을 제거합니다. 사고가 활성화되면 Claude는 답변하기 전에 자신의 언어로 문제를 풀어나갑니다. 요청된 내용을 다시 정리하고, 여러 접근 방식을 시도하고, 중간 결과를 확인하고, 유효하지 않은 경로를 포기합니다. 이러한 추론은 응답에 앞서 thinking 콘텐츠 블록으로 도착하며, Claude는 이를 활용하여 최종 답변을 생성합니다. 이것이 사고가 수학, 코딩, 분석, 장기 실행 에이전트 작업과 같은 복잡한 작업에서 성능을 향상시키는 이유입니다. 이러한 작업에서는 답변의 품질이 중간 작업에 달려 있는데, 사고가 없다면 이 중간 작업은 응답 자체에 압축되거나 생략됩니다.

사고에는 비용이 있습니다. Claude가 추론에 사용하는 토큰은 사고 텍스트가 반환되지 않더라도 출력 토큰으로 청구되며, 응답 텍스트와 함께 max_tokens에 포함됩니다. 이 페이지에서는 API 전반에서 사고가 어떻게 동작하는지 다룹니다. 사고를 켜는 방법, 출력을 읽는 방법, 그리고 도구, 스트리밍, 캐싱, 컨텍스트 윈도우와의 상호작용을 관리하는 방법을 설명합니다.



사고의 작동 방식

주어진 요청에서 Claude가 사고하는지 여부와 그 깊이는 사고 구성과 요청의 복잡성에 따라 달라집니다.

응답에서 사고는 다음과 같이 나타납니다. 하나 이상의 thinking 콘텐츠 블록이 text 블록보다 먼저 도착합니다. thinking 블록은 뒤따르는 text 블록과 마찬가지로 생성된 콘텐츠이지만, 정식 응답과는 분리되어 있습니다. 각 thinking 블록에는 signature 필드도 포함되어 있는데, 이는 전체 추론의 암호화된 사본으로, 멀티턴 및 도구 사용 대화에서 변경 없이 그대로 다시 전달해야 합니다(사고 암호화 참조):

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me break this down. The question has two parts, so I'll start with the simpler one and use its result to constrain the second...",
      "signature": "WaUjzkypQ2mUEVM36O2Txu...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

이 텍스트가 항상 보이는 것은 아니며, 보이는 내용도 원시 사고 과정(chain of thought)이 아닙니다. thinking 블록의 텍스트는 Claude의 추론 요약입니다. 사고 구성의 display 필드는 해당 요약의 반환 여부를 제어합니다. "summarized"는 요약을 반환하고, 최신 모델의 기본값인 "omitted"는 thinking 필드가 비어 있는 thinking 블록을 반환합니다. 어느 쪽이든 블록은 동일하게 청구되며 멀티턴 대화에서 동일하게 다시 전달됩니다. 모델별 기본값과 자세한 내용은 사고 표시 제어를 참조하세요.

Claude가 도구를 사용하는 경우, 사고는 도구 호출 사이에도 나타날 수 있습니다. 도구 사용과 함께하는 사고를 참조하세요. 전체 응답 형식은 Messages API 레퍼런스를 참조하세요.



사고 구성하기

현재 모델에서 사고는 기본적으로 켜져 있거나 매개변수 하나만 설정하면 됩니다. 각 모델이 허용하는 구성과 기본값은 문제 해결 페이지의 모델별 구성 표에 나열되어 있습니다.

Claude Opus 5, Claude Sonnet 5, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview에서는 사고가 이미 켜져 있으므로 구성이 필요하지 않습니다. 이러한 모델에서 대부분의 개발자에게 가장 먼저 필요한 것은 사고 텍스트를 보는 것인데, 이 모델들에서는 display의 기본값이 "omitted"이기 때문입니다. thinking: {"type": "adaptive", "display": "summarized"}로 옵트인하세요. 이는 모델 문자열만 바꾸면 아래 요청과 정확히 동일합니다.

Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6에서는 요청에 thinking: {type: "adaptive"}를 설정하기 전까지 사고가 꺼져 있습니다. 다음 예제는 이를 설정하고, 사고 텍스트가 보이도록 display: "summarized"를 설정하며, 여유 있는 max_tokens를 사용합니다:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
)

for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

예제를 실행하면 요약된 사고가 먼저 출력되고, 그다음 답변이 출력됩니다:

Thinking: Use Euclidean algorithm.
1071 = 2*462 + 147
462 = 3*147 + 21
147 = 7*21 + 0
GCD = 21

Response: ## Finding GCD of 1071 and 462

I'll use the **Euclidean algorithm**, repeatedly dividing and taking remainders...

사고 토큰은 max_tokens에 포함되므로, 사고와 응답 텍스트 모두를 위한 공간이 충분하도록 높게 설정하세요. 조정 페이지의 비용 제어와 사고와 컨텍스트 윈도우를 참조하세요.



사고 끄기

사고가 기본적으로 켜져 있는 Claude Sonnet 5에서는 사고를 끌 수 있습니다:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "Summarize this article in one sentence."}],
)

Claude Opus 5도 사고가 기본적으로 켜져 있으며, effort가 high 이하일 때 thinking: {type: "disabled"}를 허용합니다. xhigh 또는 max effort에서는 사고를 끌 수 없습니다. 해당 effort 수준과 thinking: {type: "disabled"}를 결합한 요청은 400 오류를 반환합니다. 이 제한은 Claude Opus 5 이상 모델에 적용되며 각 요청마다 적용됩니다. 사고가 비활성화된 상태에서 Claude Opus 5는 간혹 도구 호출을 일반 텍스트로 출력하거나 내부 XML 태그를 표시되는 출력에 포함할 수 있습니다. 프롬프트를 통한 완화 방법은 사고 비활성화 상태로 실행하기를 참조하세요.

Claude Fable 5, Claude Mythos 5, Claude Mythos Preview는 thinking: {type: "disabled"}를 거부합니다. 이러한 모델에서는 사고를 끌 수 없습니다.

사용 중인 모델이 확장 사고만 지원하는 경우(모델별 구성 표 참조), 대신 type: "enabled"와 budget_tokens 값으로 구성하세요. 해당 구성은 확장 사고 페이지에서 다룹니다. 그리고 어떤 사고 구성이든 400 오류가 반환되면, 사고 문제 해결에서 각 오류 메시지에 대한 해결 방법을 찾을 수 있습니다.



사고 출력 읽기



사고 표시 제어

사고 구성의 display 필드는 API 응답에서 사고 콘텐츠가 반환되는 방식을 제어합니다. display는 두 모드 모두에서 작동합니다. type: "adaptive" 또는 type: "enabled"와 함께 설정하세요. 두 가지 값을 허용합니다:

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

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

display: "omitted"를 사용하면 응답에 빈 thinking 필드를 가진 thinking 블록이 포함됩니다:

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

생략된 사고를 다룰 때 다음 사항에 유의하세요:

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

Ruby SDK에서는 Ruby의 Kernel#display와의 충돌을 피하기 위해 이 필드를 display_:(뒤에 밑줄 포함)로 설정하세요. 와이어 필드는 여전히 display입니다.



요약된 사고

display가 "summarized"일 때, 받게 되는 사고 텍스트는 원시 사고 과정이 아니라 Claude의 전체 사고 프로세스를 요약한 것입니다. 요약된 사고는 오용을 방지하면서 사고의 모든 지능적 이점을 제공합니다. 어떤 display 설정도 원시 사고 과정을 반환하지 않습니다.

요약된 사고를 다룰 때 다음 사항에 유의하세요:

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



사고 스트리밍

사고는 스트리밍과 함께 작동합니다. thinking 블록은 content_block_delta 이벤트 내부의 thinking_delta 이벤트로 스트리밍되며, 블록의 content_block_stop 직전에 단일 signature_delta 이벤트가 뒤따릅니다. 그 후 text 블록이 평소와 같이 스트리밍됩니다.

다음 예제는 적응형 사고로 응답을 스트리밍하며, thinking 및 text delta가 도착하는 대로 출력합니다:

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

display: "omitted"가 설정되면 thinking 블록이 열리고, 단일 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":""}}

일반적인 스트리밍 메커니즘은 메시지 스트리밍을 참조하세요.



사고와 effort

thinking 매개변수는 Claude가 답변하기 전에 사고 블록에서 사고할지 여부를 제어하며, effort 매개변수는 Claude가 전체 응답에 얼마나 많은 노력을 기울일지를 제어합니다. adaptive 모드에서는 여기에 사고의 빈도와 깊이도 포함됩니다. effort 값으로 adaptive를 전달하지 마세요. adaptive는 사고 모드이지 노력 수준이 아닙니다.

각 effort 수준이 사고 동작에 미치는 영향은 사고 조정 페이지의 수준별 사고 동작 표를 참조하세요. Effort 페이지는 각 모델이 지원하는 수준을 포함하여 매개변수 자체를 문서화합니다. effort를 지원하는 유일한 확장 사고 전용 모델인 Claude Opus 4.5에서는 effort가 budget_tokens와 함께 구성됩니다. 예산 규칙 및 조정을 참조하세요.

두 제어가 이렇게 분리되어 있으므로, 목표에 맞는 것을 선택하세요:

• 사고가 활성화된 워크로드에서 비용 또는 지연 시간 절감: 먼저 effort를 낮추세요. 사고를 포함한 전체 응답이 축소됩니다.
• Claude가 너무 드물게 또는 너무 얕게 사고하는 경우: effort를 높이거나, 조정 페이지의 Claude의 사고 빈도 조정을 참조하세요.
• 사고를 완전히 꺼야 하는 경우: 이를 허용하는 모델에서 thinking: {type: "disabled"}를 사용하세요(모델별 구성 표 참조).
• 지출에 대한 엄격한 상한이 필요한 경우: max_tokens를 사용하세요. Effort는 유연한 지침이고, max_tokens는 엄격한 제한입니다.



도구 사용과 함께하는 사고

사고는 도구 사용과 함께 작동하여 Claude가 도구 선택을 추론하고 도구 결과를 처리할 수 있게 합니다. 두 가지 제약이 적용됩니다:

1. 도구 선택 제한(수동 모드): 수동 확장 사고(thinking: {type: "enabled"})와 함께하는 도구 사용은 tool_choice: {"type": "auto"}(기본값) 또는 tool_choice: {"type": "none"}만 지원합니다. tool_choice: {"type": "any"} 또는 tool_choice: {"type": "tool", "name": "..."}를 사용하면 오류가 발생합니다. 이러한 옵션은 도구 사용을 강제하는데, 이는 수동 확장 사고와 호환되지 않기 때문입니다. 사고가 기본적으로 켜져 있는 모델을 포함하여 적응형 사고는 강제 도구 사용을 지원합니다.
2. thinking 블록 보존: 도구 결과를 반환할 때, 어시스턴트 메시지의 thinking 블록을 완전하고 수정되지 않은 상태로 API에 다시 전달해야 합니다. thinking 블록 보존을 참조하세요.

도구 사용 루프는 하나의 어시스턴트 턴입니다. 모델의 관점에서 어시스턴트 턴은 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가 추가로 사고가 활성화된 요청의 마지막 어시스턴트 턴이 thinking 블록으로 시작하도록 강제합니다. 적응형 모드는 이를 완화합니다. 어떤 어시스턴트 턴도 thinking 블록으로 시작할 필요가 없습니다.

턴 중간의 충돌은 우아하게 저하됩니다. 턴 중간에 사고를 전환하면(예: 도구 호출을 보내고 그 결과를 반환하는 사이), API는 오류를 발생시키지 않습니다. 대신 해당 요청에 대해 사고를 조용히 비활성화합니다. 모델 품질을 보존하기 위해 API는 유효하지 않은 턴 구조를 만들 수 있는 thinking 블록을 제거하거나, 대화 기록이 사고 활성화와 호환되지 않을 때 사고를 비활성화할 수 있습니다. 사고가 활성화되었는지 확인하려면 응답에 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 블록 보존

Claude가 도구를 호출하면 외부 정보를 기다리기 위해 응답 구성을 일시 중지합니다. 도구 결과를 반환하면 Claude는 동일한 응답을 계속 구성하므로, 이전 추론이 여전히 존재해야 합니다. 모든 thinking 블록을 함께 있던 tool_use 블록과 함께 완전하고 수정되지 않은 상태로 API에 다시 전달하세요. 이것이 중요한 이유는 두 가지입니다:

1. 추론 연속성: thinking 블록은 도구 요청으로 이어진 단계별 추론을 담고 있습니다. 이를 포함하면 Claude가 중단한 지점부터 추론을 계속할 수 있습니다.
2. 컨텍스트 유지: 도구 결과는 API 구조에서 사용자 메시지로 나타나지만, 하나의 연속적인 추론 흐름의 일부입니다. thinking 블록을 보존하면 API 호출 전반에 걸쳐 그 흐름이 유지됩니다.

요약하면:

• 필수: 도구 사용 턴 내에서는 thinking 블록을 다시 전달하세요.
• 권장: 턴 전반에 걸쳐 모든 것을 다시 전달하세요.
• 허용: 도구 사용 외에는 이전 턴의 사고를 생략할 수 있습니다.

오래된 사고를 직접 정리할 필요는 없습니다. 멀티턴 대화에서 모든 thinking 블록을 다시 전달하면 API가 자동으로 필터링하고, 모델의 추론을 보존하는 데 필요한 블록을 유지하며, 실제로 Claude에게 표시되는 블록에 대해서만 입력 토큰을 청구합니다. 어떤 이전 턴 블록이 유지되는지는 모델별로 다릅니다. 모델별 thinking 블록 보존을 참조하세요. 기본값을 재정의하려면 clear_thinking_20251015 컨텍스트 편집 전략을 사용하세요.

가장 최근 어시스턴트 메시지 내에서 연속된 thinking 블록의 순서는 모델이 원래 요청에서 생성한 것과 일치해야 합니다. 재배열, 편집, 부분 삭제는 불가능합니다. 여기에는 redacted_thinking 블록도 포함됩니다.

모든 SDK의 코드가 포함된 완전한 2턴 연습은 도구 및 멀티턴 워크플로에서의 사고를 참조하세요. 도구를 정의하고, 사고와 도구 사용이 포함된 응답을 받고, 도구 결과와 함께 어시스턴트 턴을 다시 전달합니다.



인터리브 사고

인터리브 사고(interleaved thinking)는 Claude가 도구 호출 사이에 사고하여 각 도구 결과에 대해 행동하기 전에 추론할 수 있게 합니다. 인터리브 사고를 사용하면 Claude는 다음을 수행할 수 있습니다:

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

적응형 사고를 사용하면 적응형 사고를 지원하는 모든 모델에서 인터리브 사고가 자동으로 적용되며, 베타 헤더가 필요하지 않습니다. Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7에서는 도구 호출 사이의 추론이 항상 thinking 블록에 나타납니다. Claude Haiku 4.5는 인터리브 사고를 지원하지 않습니다. 수동 확장 사고를 사용하는 모델에서는 인터리빙에 베타 헤더가 필요하며 사고 예산이 계산되는 방식이 달라집니다. 수동 모드에서의 인터리브 사고에서 모델별 규칙과 플랫폼별 헤더 동작을 다룹니다.

인터리브 사고를 사용하면 사고 할당량이 단일 응답이 아니라 전체 어시스턴트 턴에 걸쳐 적용될 수 있습니다. 인터리브 사고는 Messages API를 통해 사용되는 도구에서만 지원됩니다.

두 개의 도구를 사용하는 워크플로에서 인터리브 사고가 무엇을 변경하는지 보여주는 비교 예제는 인터리브 사고가 흐름을 변경하는 방식을 참조하세요.



모델별 thinking 블록 보존

이전 어시스턴트 턴의 thinking 블록이 기본적으로 컨텍스트에 유지되는지 여부는 모델에 따라 다릅니다:

• 모든 이전 턴 유지: Claude Opus 4.5 및 이후 Opus 모델, Claude Sonnet 4.6 및 이후 Sonnet 모델, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview.
• 마지막 턴만 유지: 이전 Opus 및 Sonnet 모델, 그리고 Claude Haiku 4.5까지의 모든 Haiku 모델. 오래된 thinking 블록을 다시 전달하면 API가 자동으로 제거하므로 직접 제거할 필요가 없습니다.

보존에는 두 가지 이점이 있습니다:

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

트레이드오프는 컨텍스트 사용량입니다. 유지된 thinking 블록은 다른 대화 기록과 마찬가지로 입력으로 계산되므로, 모든 턴을 유지하는 모델에서는 긴 대화가 더 많은 컨텍스트 공간을 소비합니다(사고와 컨텍스트 윈도우 참조). 이 동작은 두 방식 모두에서 자동입니다. 코드 변경이나 베타 헤더가 필요하지 않으며, thinking 블록 보존에 설명된 대로 완전하고 수정되지 않은 thinking 블록을 계속 다시 전달해야 합니다. 어느 방향으로든 기본값을 재정의하려면 thinking 블록 지우기를 사용하세요.

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



사고와 프롬프트 캐싱

프롬프트 캐싱은 몇 가지 특정한 방식으로 사고와 상호작용합니다. 다음 규칙은 두 사고 모드 모두에 적용됩니다.

구성 변경은 캐싱을 무효화합니다. 사고 구성과 확정된 effort 수준은 프롬프트 자체에 렌더링되므로, 이 중 하나라도 변경하면 새로운 캐시 접두사가 시작됩니다. adaptive, enabled, disabled 간 전환, budget_tokens 변경, effort 값 변경은 모두 캐시 중단점을 무효화합니다. 메시지 수준 중단점은 항상 미스되며, 모델이 구성을 렌더링하는 위치에 따라 도구 및 시스템 프롬프트 중단점도 미스될 수 있습니다. 사고 또는 effort 변경은 캐시를 처음부터 다시 시작하는 것으로 간주하세요. 동일한 구성을 유지하는 연속 요청은 캐시를 보존하며, 매개변수를 기본값으로 명시적으로 설정하는 것은 생략하는 것과 동일합니다. 사용량 출력이 포함된 실제 시연은 사고 조정 페이지에 있습니다.

thinking 블록은 도구 결과와 함께 캐시됩니다. 도구 사용 루프 중에는 도구 결과를 포함하는 후속 요청을 할 때 캐싱이 발생합니다. 이 시점에서 thinking 블록을 포함한 이전 대화 기록이 캐시될 수 있으며, 캐시에서 읽을 때 이러한 캐시된 thinking 블록은 사용량 지표에서 입력 토큰으로 계산됩니다. 이는 명시적인 cache_control 마커 없이도 자동으로 발생하며, 일반 사고와 인터리브 사고에서 동일하게 동작합니다. 트레이드오프: 응답에서 다시 볼 수 없는 thinking 블록도 캐시에서 읽을 때 여전히 입력 토큰 사용량에 기여합니다.

이전 블록이 컨텍스트에 있는지 여부는 모델별로 다릅니다. 보존 기본값이 이를 결정합니다. 모든 턴을 유지하는 모델에서는 이전 턴의 thinking 블록이 캐시되고 컨텍스트에 유지됩니다. 마지막 턴만 유지하는 모델에서는 도구 결과가 아닌 사용자 메시지를 보내는 순간 모든 이전 thinking 블록이 컨텍스트에서 제거됩니다. 이러한 모델에서 다음과 같은 대화는:

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]

thinking 블록이 처음부터 없었던 것처럼 처리됩니다:

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]

모든 턴을 유지하는 모델에서는 동일한 요청이 thinking_block_1과 thinking_block_2를 컨텍스트와 캐시에 유지합니다.

저하는 캐시 가능한 기록에서 사고를 제거합니다. 턴 중간에 사고가 비활성화되고 현재 도구 사용 턴에서 사고 콘텐츠를 전달하면, 사고 콘텐츠가 제거되고 해당 요청에 대해 사고가 비활성화된 상태로 유지됩니다(우아한 저하 참조). 인터리브 사고는 thinking 블록이 여러 도구 호출 사이에 나타날 수 있으므로 캐시 무효화 효과를 증폭시킵니다.



사고와 컨텍스트 윈도우

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

사고가 윈도우에 어떻게 계산되는지는 생성 시점에 따라 다릅니다:

• 현재 턴의 사고는 항상 max_tokens에 포함되고, 출력 토큰으로 청구되며, 이를 생성한 턴 동안 컨텍스트 윈도우 공간을 차지합니다.
• 이전 턴의 사고는 보존 기본값에 따라 다릅니다. 모든 이전 턴을 유지하는 모델에서는 이전 thinking 블록이 컨텍스트에 유지되고, 윈도우에 포함되며, 나머지 대화 기록과 마찬가지로 입력 토큰으로 청구됩니다. 마지막 턴만 유지하는 모델에서는 다시 전달할 때 API가 오래된 thinking 블록을 자동으로 제거하므로 윈도우 공간이나 입력 토큰을 소비하지 않습니다.

실제로는:

• 모든 턴을 유지하는 모델에서는 사고가 일반 대화 기록인 것처럼 컨텍스트 윈도우 예산을 계획하세요. 실제로 그렇기 때문입니다. 긴 에이전트 세션은 컨텍스트에 사고를 누적합니다. 공간을 회수해야 하는 경우 thinking 블록 지우기를 사용하세요.
• 마지막 턴만 유지하는 모델에서는 사고가 턴별 비용일 뿐입니다. 각 턴의 사고는 해당 턴의 max_tokens에 포함된 후 윈도우에서 제외됩니다.

다음 다이어그램은 마지막 턴만 유지(제거) 방식을 보여줍니다. 첫 번째는 멀티턴 대화를 보여줍니다. 각 턴의 thinking 블록은 출력에서 생성되지만 이후 턴의 입력으로 전달되지 않습니다.

두 번째는 도구 사용이 포함된 동일한 방식을 보여줍니다. 사고는 어시스턴트 턴 동안 도구 결과와 함께 컨텍스트에 유지된 다음, 다음 사용자 턴에서 제외됩니다.

특히 사고가 포함된 멀티턴 대화의 경우, 토큰 계산 API를 사용하여 특정 사용 사례에 대한 정확한 수치를 얻으세요.



사고 암호화

전체 사고 콘텐츠는 암호화되어 각 thinking 블록의 signature 필드에 반환됩니다. API는 thinking 블록을 다시 전달할 때 signature를 사용하여 해당 블록이 Claude에 의해 생성되었는지 확인합니다.

signature를 다룰 때 다음 사항에 유의하세요:

• thinking 블록을 다시 보내는 것이 엄격하게 필요한 경우는 사고와 함께 도구를 사용할 때뿐입니다. 그 외에는 이전 턴의 thinking 블록을 생략할 수 있습니다. 다시 전달하는 경우, API가 이를 유지하는지 제거하는지는 모델에 따라 다릅니다(모델별 thinking 블록 보존 참조). 이를 구성하려면 컨텍스트 편집을 사용하세요.
• thinking 블록을 다시 보낼 때는 일관성을 유지하고 잠재적인 문제를 피하기 위해 받은 그대로 모든 것을 다시 전달하세요.
• 응답을 스트리밍할 때 signature는 content_block_stop 이벤트 직전의 content_block_delta 이벤트 내부에 signature_delta로 도착합니다.
• signature 값은 이전 모델보다 Claude 4 이상 모델에서 상당히 깁니다.
• signature 필드는 불투명합니다. 해석하거나 파싱하지 마세요.
• signature 값은 플랫폼 간에 호환됩니다(Claude API, Amazon Bedrock, Google Cloud). 한 플랫폼에서 생성된 값은 다른 플랫폼에서도 작동합니다.



편집된 thinking 블록

일반 thinking 블록 외에도, Claude의 추론 일부가 안전상의 이유로 편집된 경우 API는 redacted_thinking 블록을 반환할 수 있습니다. redacted_thinking 블록은 읽을 수 있는 텍스트 없이 data 필드에 암호화된 사고 콘텐츠를 포함합니다:

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

data 필드는 불투명하고 암호화되어 있습니다. 일반 thinking 블록의 signature 필드와 마찬가지로, 도구를 사용하는 멀티턴 대화를 계속할 때 redacted_thinking 블록을 변경 없이 API에 다시 전달하세요.



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

Claude Fable 5 및 Claude Mythos 5에서는 원시 사고 과정이 절대 반환되지 않습니다. 받게 되는 블록은 redacted_thinking이 아닌 일반 thinking 블록이며, display 설정은 다른 모델과 동일하게 작동합니다(요약된 텍스트, 또는 여기서 기본값인 생략 시 빈 thinking 필드). thinking 블록의 응답 형태는 Messages API 레퍼런스를 참조하세요.

동일한 모델에서 대화를 계속할 때는 thinking 필드가 비어 있는 블록을 포함하여 각 thinking 블록을 받은 그대로 API에 다시 전달하세요. 편집하거나 재구성하지 마세요. 표시를 위해 요약 텍스트를 읽는 것은 괜찮습니다. API는 반환된 콘텐츠가 수정된 블록을 거부하는 것이지, 읽은 블록을 거부하는 것이 아닙니다. 생략된 빈 thinking 필드에 넣은 텍스트는 거부되지 않고 무시됩니다.

대화 중간에 모델을 전환할 때 thinking 블록에 어떤 일이 발생하는지는 모델별 thinking 블록 보존을 참조하세요.

폴백 크레딧에서 다루는 두 가지 예외:

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

모델의 추론에 대한 가시성을 얻으려면 응답 텍스트에서 추론을 요청하는 대신 이 페이지에 설명된 thinking 블록을 읽으세요. Claude Fable 5에서는 응답 텍스트의 일부로 모델의 내부 추론을 이끌어내려는 요청이 stop_details.category: "reasoning_extraction"으로 거부될 수 있습니다. 필드 레퍼런스와 처리 지침은 거부 카테고리를 참조하세요.



제한 사항 및 기능 호환성

샘플링 매개변수. Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5에서는 기본값이 아닌 temperature, top_p 또는 top_k 값을 사용하면 사고 사용 여부와 관계없이 모든 요청에서 400 오류가 반환됩니다. 이전 모델에서는 사고가 켜져 있는 동안에만 제한이 적용됩니다. temperature와 top_k는 사고와 호환되지 않으며, top_p는 0.95에서 1 사이의 값이 허용됩니다.

응답 프리필 및 강제 도구 사용. 사고가 켜져 있는 동안에는 어시스턴트 응답을 미리 채울 수 없습니다. 강제 도구 사용(tool_choice: {"type": "any"} 또는 {"type": "tool", ...})은 수동 확장 사고와 호환되지 않지만 적응형 사고에서는 작동합니다. 도구 사용과 함께하는 사고를 참조하세요.

출력 제한. Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, Claude Opus 4.6, Claude Sonnet 4.6은 요청당 최대 128k 출력 토큰을 지원합니다. Claude Haiku 4.5, Claude Sonnet 4.5, Claude Opus 4.5는 최대 64k를 지원합니다. Message Batches API에서는 output-300k-2026-03-24 베타 헤더를 사용하면 Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, Claude Opus 4.6, Claude Sonnet 4.6의 제한이 300k로 늘어납니다. 레거시 모델의 제한은 모델 개요를 참조하세요.

긴 요청. SDK는 장시간 실행되는 요청에서 HTTP 타임아웃을 방지하기 위해 max_tokens가 21,333보다 클 때 스트리밍을 요구합니다. 이는 클라이언트 측 유효성 검사이며 API 제한이 아닙니다. 이벤트를 점진적으로 처리할 필요가 없다면 .stream()과 함께 .get_final_message()(Python) 또는 .finalMessage()(TypeScript)를 사용하여 개별 이벤트를 처리하지 않고도 완전한 Message 객체를 얻을 수 있습니다. 메시지 스트리밍을 참조하세요. 사고 블록을 생성하는 데 처리 시간이 추가되므로 사고가 활성화되어 있을 때는 응답 시간이 더 길어질 것으로 예상하세요. 요청당 사고가 약 32k 토큰을 초과하는 워크로드의 경우 네트워킹 문제를 피하기 위해 배치 처리를 사용하세요. 이러한 요청은 시스템 타임아웃과 열린 연결 제한에 도달할 만큼 오래 실행될 수 있습니다.



다음 단계