사고

한 번에 답변하는 모델은 첫 시도에서 모든 것을 올바르게 해내야 합니다. 중간 풀이도, 검토도, 도중에 방향을 바꾸는 것도 불가능합니다. 증명, 까다로운 버그, 긴 에이전트 작업에서는 처음 택한 접근 방식이 최선이 아닌 경우가 많습니다.

"Thinking"(사고)은 이러한 제약을 없앱니다. 사고가 활성화되면 Claude는 답변하기 전에 자신의 언어로 문제를 풀어 나갑니다. 무엇을 요청받았는지 다시 정리하고, 여러 접근 방식을 시도하고, 중간 결과를 확인하고, 타당하지 않은 경로는 버립니다. 이러한 "up-front thinking"(사전 사고)은 응답보다 앞서 thinking 콘텐츠 블록으로 전달되며, Claude는 이를 바탕으로 최종 답변을 생성합니다. 이것이 사고가 수학, 코딩, 분석, 장시간 실행되는 에이전트형 작업처럼 복잡한 작업의 성능을 향상시키는 이유입니다. 이러한 작업에서는 답변의 품질이 중간 작업에 달려 있는데, 사고가 없으면 그 중간 작업이 응답 자체에 압축되거나 생략됩니다.

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

사고의 작동 방식

Claude가 특정 요청에서 사고하는지 여부와 얼마나 깊이 사고하는지는 사고 구성과 요청의 복잡성에 따라 달라집니다.

다음은 응답에서 사전 사고가 어떻게 나타나는지 보여 줍니다. 하나 이상의 thinking 콘텐츠 블록이 text 블록보다 먼저 도착합니다. 사고 블록도 뒤따르는 text 블록과 마찬가지로 생성된 콘텐츠이지만, 정식 응답과는 분리되어 있습니다. 각 사고 블록에는 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)이 아닙니다. 사고 블록의 텍스트는 Claude 추론의 요약입니다. 사고 구성의 display 필드는 이 요약을 반환할지 여부를 제어합니다. "summarized"는 요약을 반환하고, 많은 모델에서 기본값인 "omitted"는 thinking 필드가 비어 있는 사고 블록을 반환합니다. 어느 쪽이든 블록은 동일하게 청구되며 멀티턴 대화에서 동일하게 다시 전달됩니다. 모델별 기본값과 세부 사항은 사고 표시 제어를 참조하세요.

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

사고 구성

대부분의 모델에서 사고는 기본적으로 켜져 있거나 매개변수 하나만 설정하면 켤 수 있습니다. 다음 표는 요청이 보낼 수 있는 각 thinking 값에 대해 각 모델이 어떻게 동작하는지 보여 줍니다. 400 오류는 API가 요청을 거부한다는 의미이며, 사고 문제 해결에서 각 오류와 해결 방법을 확인할 수 있습니다.

표에서 "high effort 이하"는 요청이 low, medium, high effort에서 작동하고 xhigh 또는 max에서는 400 오류를 반환한다는 의미입니다.

Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Haiku 5.5에서는 사고가 이미 켜져 있으며 별도의 구성이 필요하지 않습니다. 이러한 모델에서는 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"}를 설정하기 전까지 사고가 꺼져 있습니다. 이 설정을 사용하면 Claude가 요청에 따라 언제, 얼마나 깊이 사고할지 결정합니다. 다음 예제는 이 설정을 적용하고, 사고 텍스트가 보이도록 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:
    match block.type:
        case "thinking":
            print(f"\nThinking: {block.thinking}")
        case "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에서는 사고를 끌 수 없습니다. thinking: {type: "disabled"}를 이러한 effort 수준과 함께 사용하는 요청은 400 오류를 반환합니다. 이 제한은 각 요청마다 적용됩니다. 사고가 비활성화된 상태에서 Claude Opus 5는 가끔 도구 호출을 일반 텍스트로 출력하거나 보이는 출력에 내부 XML 태그를 포함할 수 있습니다. 프롬프트를 통한 완화 방법은 사고를 비활성화한 상태로 실행하기를 참조하세요.

Claude Sonnet 5.5도 사고가 기본적으로 켜져 있으며, thinking: {type: "disabled"}를 400 오류로 거부합니다. 사전 사고를 끄려면 대신 thinking: {type: "between_tools"}를 보내세요. 이는 Claude Sonnet 5.5에서 가장 낮은 사고 설정이며, effort high 이하에서 허용됩니다. 모델은 여전히 도구 호출 사이의 진행 상황 업데이트를 반환합니다. 도구가 없으면 Claude Sonnet 5에서 disabled를 사용할 때와 마찬가지로 응답에는 텍스트만 포함됩니다. 프롬프트 작성 지침은 사전 사고 없이 실행하기를 참조하세요.

Claude Haiku 5.5도 사고가 기본적으로 켜져 있으며, effort high 이하에서 thinking: {type: "disabled"}를 허용합니다. xhigh 또는 max effort에서는 이 조합이 400 오류를 반환합니다. 사고를 줄이려면 먼저 effort 수준을 낮추세요. 사고가 꺼진 상태에서 JSON 출력도 함께 요청하면 모델이 필요한 도구 호출을 건너뛸 수 있습니다. 사고가 꺼져 있는 동안 현재 적용 중인 수준과 다른 메시지별 output_config.effort도 400 오류를 반환합니다. effort를 사용하여 사고 제어하기와 JSON 출력 및 자체 도구와 함께 적응형 사고 사용하기를 참조하세요.

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

요청을 보내기 전에 모델이 "disabled"를 허용하는지 확인하려면 Models API에서 해당 모델의 capabilities.thinking.types.disabled.supported 값을 읽으세요. Models API 사용하기에서 이 필드를 설명합니다.

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

사고 출력 읽기

사고 표시 제어

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

• "summarized": 사고 블록에 Claude 추론의 읽기 쉬운 요약인 요약된 사고 텍스트가 포함됩니다. Claude Opus 4.6, Claude Sonnet 4.6 및 이전 모델의 기본값입니다.
• "omitted": 사고 블록이 빈 thinking 필드와 함께 반환됩니다. signature 필드는 멀티턴 연속성을 위해 여전히 암호화된 전체 사고를 담고 있습니다(사고 암호화 참조). Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Mythos Preview, Claude Haiku 5.5의 기본값입니다.
• "updates" (베타): 추론 블록은 "omitted"와 마찬가지로 빈 thinking 필드와 함께 반환되며, 일부 모델이 도구 호출 사이에 작성하는 짧은 진행 상황 업데이트는 읽을 수 있는 텍스트로 반환됩니다. 베타 헤더 thinking-display-updates-2026-08-18이 필요합니다.

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

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

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

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

• 전체 사고 토큰에 대해서는 여전히 요금이 청구됩니다. 생략은 비용이 아니라 "latency"(지연 시간)를 줄여 줍니다.
• 멀티턴 대화에서 사고 블록을 다시 전달하는 경우 변경하지 않고 그대로 전달하세요. 서버는 signature를 복호화하여 프롬프트 구성을 위한 원래 사고를 재구성합니다(사고 블록 보존 참조). 다시 전달된 생략 블록의 thinking 필드에 넣은 텍스트는 무시됩니다.
• display는 thinking.type: "disabled"(표시할 내용이 없음)와 함께 사용할 수 없으며, 다른 필드를 허용하지 않는 thinking.type: "between_tools"(Claude Sonnet 5.5 전용)와도 함께 사용할 수 없습니다. between_tools를 사용하면 display: "updates"에서와 마찬가지로 진행 상황 업데이트가 여전히 요약 텍스트와 함께 반환됩니다(진행 상황 업데이트 참조).
• thinking.type: "adaptive"를 사용하고 모델이 간단한 요청에 대해 사고를 건너뛰는 경우, display와 관계없이 사고 블록이 생성되지 않습니다.
• display: "omitted"로 스트리밍할 때는 사고 텍스트가 스트리밍되지 않습니다. 각 사고 블록은 빈 thinking 문자열을 가진 thinking_delta를 스트리밍한 다음 signature_delta를 스트리밍합니다. display: "updates"를 사용하면 진행 상황 업데이트 블록만 텍스트를 담은 thinking_delta 이벤트를 스트리밍합니다. 이벤트 순서는 사고 스트리밍을 참조하세요.

요약된 사고

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

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

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

모델의 추론을 보려면 응답 텍스트에서 추론을 요청하는 대신 thinking 블록을 읽으세요. Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5에서는 모델의 내부 추론을 응답 텍스트의 일부로 끌어내려는 요청이 stop_details.category: "reasoning_extraction"과 함께 거부될 수 있습니다. 필드 레퍼런스는 거부 카테고리를, 대신 무엇을 요청해야 하는지는 추론을 사고 블록에 유지하기를 참조하세요.

사고 스트리밍

사고는 스트리밍과 함께 작동합니다. 사고 블록은 content_block_delta 이벤트 내부의 thinking_delta 이벤트로 스트리밍되며, 블록의 content_block_stop 직전에 단일 signature_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:
        match event.type:
            case "content_block_start":
                print(f"\nStarting {event.content_block.type} block...")
            case "content_block_delta":
                delta = event.delta
                match delta.type:
                    case "thinking_delta":
                        print(delta.thinking, end="", flush=True)
                    case "text_delta":
                        print(delta.text, end="", flush=True)

스트리밍 후 서명이 포함된 완전한 사고 블록을 재조립하려면 델타를 직접 이어 붙이는 대신 SDK의 메시지 누적 헬퍼인 stream.get_final_message()를 사용하세요.

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "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": "EqQBCgIYAhIM1gbcDa9GJwZA2b..."}}

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"가 설정되면 사고 블록이 열리고, 빈 thinking 문자열을 가진 thinking_delta가 도착하고, 단일 signature_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":"thinking_delta","thinking":""}}

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":""}}

display: "updates"(베타)를 사용하면 추론 블록은 "omitted"에서와 같이 스트리밍됩니다. 각 진행 상황 업데이트 블록은 자신이 소개하는 tool_use 블록보다 먼저 텍스트를 thinking_delta 이벤트로 스트리밍합니다. 진행 상황 업데이트 블록이 열리기 전에 몇 초간 멈추는 것은 정상입니다:

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

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call."}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"signature_delta","signature":"Es8CCkYICxIM..."}}

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

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"tool_use","id":"toolu_01D7FLrfh4GYq7yT1ULFeyMV","name":"edit_file","input":{}}}

"updates"에서는 블록의 thinking_delta 이벤트 중 하나가 비어 있지 않은 텍스트를 담는 즉시 해당 블록을 진행 상황 업데이트로 취급하세요.

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

사고와 effort

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

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

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

• 사고가 활성화된 워크로드에서 비용이나 지연 시간을 낮추려는 경우: 먼저 effort를 낮추세요. 사고를 포함한 전체 응답이 축소됩니다.
• Claude가 너무 드물게 또는 너무 얕게 사고하는 경우: effort를 높이거나, 조정 페이지의 Claude가 얼마나 자주 사고하는지 조정하기를 참조하세요.
• 사고를 완전히 꺼야 하는 경우: 이를 허용하는 모델에서 thinking: {type: "disabled"}를 사용하세요(모델별 구성 표 참조). Claude Sonnet 5.5는 "disabled"를 거부합니다. 이 모델의 가장 낮은 설정은 사전 사고를 끄는 thinking: {type: "between_tools"}입니다.
• 지출에 엄격한 상한이 필요한 경우: 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": "..."}를 사용하면 오류가 발생합니다. 이러한 옵션은 도구 사용을 강제하며, 이는 수동 확장 사고와 호환되지 않기 때문입니다. 사고가 기본적으로 켜져 있는 모델을 포함하여 적응형 사고는 강제 도구 사용을 지원하지만, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1은 예외입니다(응답 프리필 및 강제 도구 사용 참조). 강제 도구 사용이 허용되는 경우 응답은 도구 호출로 시작하며 thinking 블록이 없습니다.
2. 사고 블록 보존: 도구 결과를 반환할 때는 어시스턴트 메시지의 사고 블록을 완전하고 수정되지 않은 상태로 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)

사고 모드를 전환하면 프롬프트 캐싱도 무효화됩니다. 사고와 프롬프트 캐싱을 참조하세요.

사고 블록 보존

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

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

요약하면 다음과 같습니다.

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

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

최신 어시스턴트 메시지 내에서 연속된 thinking 블록의 순서는 원래 요청에서 모델이 생성한 것과 일치해야 합니다. 블록을 재배열하거나, 편집하거나, 일부만 제거할 수 없습니다. 이는 redacted_thinking 블록에도 적용됩니다.

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

인터리브 사고

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

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

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

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

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

도구 호출 사이의 진행 상황 업데이트

Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5에서는 모델이 도구 호출 사이에 "progress update"(진행 상황 업데이트)를 작성할 수 있습니다. 진행 상황 업데이트는 모델이 방금 발견한 것과 다음에 하려는 일에 대한 메모로, 추론이 아니라 에이전트를 지켜보는 사람을 위해 작성됩니다. 각 업데이트는 자체 signature를 가진 별도의 thinking 블록으로 반환되며, 같은 지점의 추론 블록과는 분리되어 있습니다. 이 블록은 자신이 소개하는 tool_use 또는 server_tool_use 블록 바로 앞에 위치합니다. 각 도구 호출 앞에는 최대 하나의 진행 상황 업데이트가 오며, 모델은 이를 건너뛸 수 있습니다. 진행 상황 업데이트는 인터리브 사고가 아닙니다. 도구 호출 사이에 추론 블록이 나타나는지 여부와 관계없이 나타나며, 하나의 응답에 둘 다 포함될 수 있습니다.

진행 상황 업데이트 블록에 포함되는 내용은 display에 따라 달라집니다:

Claude Sonnet 5.5에서 가장 낮은 사고 설정은 thinking: {type: "between_tools"}입니다. 이 설정은 사전 사고를 끄며, 각 진행 상황 업데이트는 display: "updates"에서와 마찬가지로 요약 텍스트와 함께 반환됩니다. between_tools는 effort high 이하에서만 허용됩니다. xhigh 또는 max에서는 이 설정을 사용한 요청이 400 오류를 반환합니다. between_tools는 다른 필드를 받지 않습니다. 함께 보낸 display, budget_tokens, block_binding은 400 오류를 반환합니다. 이 설정은 베타 헤더가 필요하지 않으며 Claude Sonnet 5.5를 제공하는 모든 플랫폼에서 작동합니다. 블록은 변경하지 않고 그대로 다시 전달하세요. 다시 보낸 진행 상황 업데이트 블록은 요약이 아니라 모델이 작성한 전체 메모를 모델에 제공합니다.

추론은 숨기고 각 단계에서 사용자에게 상태 표시줄을 보여 주는 에이전트 인터페이스에는 display: "updates"를 사용하세요. 이 설정에서는 비어 있지 않은 텍스트를 가진 모든 thinking 블록이 진행 상황 업데이트이므로, 해당 블록만 렌더링하고 나머지는 렌더링하지 마세요. 이 기능은 베타이며 베타 헤더 thinking-display-updates-2026-08-18이 필요합니다(Amazon Bedrock, Google Cloud 또는 Microsoft Foundry에서 보내려면 다른 플랫폼의 베타 기능을 참조하세요). 헤더가 없으면 이 값은 알 수 없는 display 값과 동일한 400 invalid_request_error로 거부됩니다.

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive", "display": "updates" },
  "tools": [
    {
      "name": "edit_file",
      "description": "Replace the contents of a file in the repository.",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "content": { "type": "string" }
        },
        "required": ["path", "content"]
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "The login test fails after an hour of uptime. Find out why and fix it."
    }
  ]
}

"updates"에서 tool_result 다음에 오는 응답의 시작 부분은 다음과 같습니다. 첫 번째 블록은 추론이며 "omitted"에서와 마찬가지로 비어 있습니다. 두 번째 블록은 텍스트를 담고 있으므로 진행 상황 업데이트입니다. "summarized"에서는 두 블록 모두 텍스트를 담고, "omitted"에서는 둘 다 비어 있습니다.

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EqMBCkYICxIM..."
    },
    {
      "type": "thinking",
      "thinking": "Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call.",
      "signature": "Es8CCkYICxIM..."
    },
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "edit_file",
      "input": { "path": "auth.py", "content": "..." }
    }
  ]
}

진행 상황 업데이트를 사용할 때는 다음 사항에 유의하세요:

• 진행 상황 업데이트 블록은 다른 thinking 블록과 마찬가지로 어시스턴트 턴의 나머지 부분과 함께 변경하지 않고 그대로 다시 전달하세요.
• 받게 되는 텍스트는 진행 상황 업데이트의 요약으로, 보통 한두 문장입니다. 길이에 의존하지 마세요. 진행 상황 업데이트는 요약의 길이가 아니라 전체 길이로 usage.output_tokens에 포함됩니다.
• 진행 상황 업데이트 블록은 어떤 display 값에서든 빈 thinking 필드와 함께 반환될 수 있습니다. 빈 블록에 대해서는 아무것도 렌더링하지 마세요. "updates"에서는 빈 추론 블록과 똑같이 보이므로 별도의 처리가 필요하지 않습니다.
• 응답이 도구 호출이나 도구 결과 직후에 max_tokens, model_context_window_exceeded 또는 stop_sequence로 중지되면, 마지막 블록이 모델이 완료하지 못한 작업을 대신하는 진행 상황 업데이트 블록일 수 있습니다. "updates"와 "summarized"에서는 그 텍스트가 정확히 This part of the response was interrupted before it finished.이며, 다른 업데이트와 마찬가지로 표시할 수 있습니다. "omitted"에서는 비어 있습니다. 계속하려면 어시스턴트 턴을 변경하지 않고 그대로 다시 전달하고 새 user 메시지를 추가하세요(해당 턴의 각 tool_use 블록에 대한 tool_result 포함).
• 스트리밍할 때는 진행 상황 업데이트 블록이 열리기 전에 몇 초간 멈출 수 있습니다. 사고 스트리밍의 "updates" 추적을 참조하세요.
• 이러한 모델은 더 높은 effort와 긴 도구 체인에서 진행 상황 업데이트를 더 적게 작성합니다. 인터페이스가 진행 상황 업데이트에 의존하는 경우 사용자 대상 진행 상황 업데이트 요청하기를 참조하거나, Claude Opus 5.5의 경우 사용자 대상 진행 상황 업데이트를 참조하세요. Claude Sonnet 5.5의 경우 사용자 대상 진행 상황 업데이트를 참조하세요.

모델별 사고 블록 보존

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

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

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

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

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

대화 중 모델 전환. 예를 들어 분류기 거부 폴백 이후처럼 모델을 전환할 때에도 사고 블록을 변경하지 않고 계속 다시 전달하세요. 사고 블록은 그것을 생성한 모델과 특정 다른 모델만 읽을 수 있으며, API는 대상 모델이 읽을 수 없는 블록을 무시하거나 삭제합니다. Claude Fable 5.1과 Claude Mythos 5.1에서는 방향이 중요합니다. 이 두 모델은 이전 모델의 사고 블록을 읽으며, 서로의 블록은 이 두 모델만 읽을 수 있으므로, 이 모델로 전환하면 대화의 추론이 유지되고 이 모델에서 다른 모델로 전환하면 추론이 삭제됩니다(삭제된 블록의 청구 및 보고 방식 참조). Claude Opus 5.5는 Claude Opus 5의 사고 블록과 이전 Opus, Sonnet, Haiku 모델의 사고 블록을 읽으며, Claude API와 Google Cloud에서는 Claude Haiku 5.5의 사고 블록도 읽지만, Claude Fable 및 Claude Mythos 모델의 사고 블록은 읽지 않습니다. Claude API에서는 Claude Fable 5.1과 Claude Mythos 5.1이 Claude Opus 5.5의 블록을 읽습니다. Claude API에서 Claude Opus 5.5에서 Claude Fable 5.1로 상향 전환하면 이전 턴의 추론이 유지되고, Claude Fable 5.1에서 Claude Opus 5.5로 전환하면 추론이 삭제됩니다. Claude Sonnet 5.5는 Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 및 이전 모델의 사고 블록을 읽으며, Claude API와 Google Cloud에서는 Claude Haiku 5.5의 사고 블록도 읽지만, Claude Opus 5, Claude Opus 5.5 또는 Claude Fable이나 Claude Mythos 모델의 사고 블록은 읽지 않습니다. Claude API와 Google Cloud에서는 Claude Opus 5.5만 Claude Sonnet 5.5의 블록을 읽으며 다른 모델은 읽지 않습니다. Claude API와 Google Cloud에서 Claude Sonnet 5.5에서 Claude Opus 5.5로 상향 전환하면 이전 턴의 추론이 유지되고, Claude Sonnet 5.5에서 그 밖의 다른 모델로 전환하면 추론이 삭제됩니다. Claude Haiku 5.5는 Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 및 이전 모델의 사고 블록을 읽지만, Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5 또는 Claude Fable이나 Claude Mythos 모델의 사고 블록은 읽지 않습니다. Claude API와 Google Cloud에서는 Claude Opus 5.5와 Claude Sonnet 5.5만 Claude Haiku 5.5의 블록을 읽으며 다른 모델은 읽지 않습니다. 이전 thinking 및 redacted_thinking 블록을 직접 제거하는 것은 블록을 삭제하지 않고 무시하는 모델에서 입력 토큰을 절약하려는 경우에만 하세요. 본문이 변경되지 않아야 하는 폴백 크레딧을 사용할 때는 절대 제거하지 마세요.

보존된 사고

Preserved thinking(보존된 사고)은 이전 턴에서 다시 보낸 사고 블록을 모델이 사용할 수 있는지 여부를 결정합니다. Claude Fable 5.1부터 API는 요청에 포함된 모든 thinking 또는 redacted_thinking 블록의 signature를 두 가지 측면에서 확인합니다:

• 블록을 생성한 모델. 각 모델은 자신의 사고 블록과 고정된 일부 다른 모델의 사고 블록을 읽습니다. Claude Fable 5.1은 Claude Opus 5의 블록을 읽으며, Claude API에서는 Claude Opus 5.5의 블록도 읽습니다. Claude Opus 5와 Claude Opus 5.5는 모두 Claude Fable 5.1의 블록을 읽지 않습니다. API는 현재 모델이 읽을 수 없는 블록을 오류 없이, 그리고 요금을 청구하지 않고 삭제합니다. 대화 중 모델 전환을 참조하세요.
• 블록 이전에 전송된 모든 것. 블록은 최상위 system 프롬프트, tools, 그리고 그 이전의 메시지가 변경되지 않은 동안에만 유효합니다. 이 중 하나라도 변경되면 해당 블록과 이후의 모든 사고 블록이 무효가 되며, API는 선택에 따라 400 오류로 요청을 거부하거나 무효한 블록을 삭제합니다. 접두사를 변경하지 않고 유지하기를 참조하세요.

Claude Sonnet 5.5 및 Claude Haiku 5.5의 사고 블록은 이를 생성한 계정에도 연결됩니다. API가 이를 적용하는 위치는 사고 블록은 생성한 계정에 귀속됩니다를 참조하세요.

모델 확인은 모든 계정에 적용됩니다. API는 2026년 8월 31일 00:00 UTC 이후에 생성된 계정에 대해 기본적으로 접두사 확인을 적용합니다. 이전 계정에서는 thinking.block_binding.prefix_mismatch_behavior를 설정한 요청에만 확인을 적용합니다. 계정 생성 시기와 관계없이 통합을 추가 전용(append-only)으로 만들어, 기본적으로 적용되는 최신 계정을 포함한 모든 계정에서 동일한 코드가 작동하도록 하세요.

사고를 유효하게 유지하려면 모든 어시스턴트 턴을 받은 그대로 다시 보내고, 새 메시지는 messages의 끝에만 추가하세요. 코드에서 messages 배열을 직접 구성하는 경우, 보존된 사고 페이지에서 다음 내용을 다룹니다:

• 편집으로 간주되는 것, 그리고 코드가 편집을 수행하는지 확인하는 방법.
• 일반적인 편집 방식을 각각 대체하는 API 기능: 새 지침 및 턴별 알림을 위한 대화 중간 시스템 메시지, 도구 변경을 위한 tool_addition 및 tool_removal 블록, effort 변경을 위한 메시지별 output_config, 그리고 트리밍을 위한 서버 측 압축 및 컨텍스트 편집.
• 클라이언트 측 압축: 어떤 패턴이 사고를 유효하게 유지하고 어떤 패턴이 그렇지 않은지.
• thinking-binding-controls-2026-08-01 베타 헤더. 이 헤더는 사고 구성에 block_binding.prefix_mismatch_behavior 필드("error" 또는 "drop_block")를 추가하고, 모든 응답에 input_transformations 배열을 추가합니다. 이 배열에는 API가 삭제했거나 접두사 확인에 실패했지만 통과된 각 사고 블록이 나열됩니다.

사고와 프롬프트 캐싱

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

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

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

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

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]

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

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를 컨텍스트와 캐시에 유지합니다.

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

사고와 컨텍스트 윈도우

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

사고가 윈도우에 계산되는 방식은 생성된 시점에 따라 다릅니다:

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

실제로는:

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

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

두 번째 다이어그램은 "tool use"(도구 사용)가 포함된 동일한 방식을 보여줍니다. 사고는 어시스턴트 턴 동안 도구 결과와 함께 컨텍스트에 유지되다가 다음 사용자 턴에서 빠집니다.

특정 사용 사례, 특히 사고가 포함된 멀티턴 대화에 대한 정확한 토큰 수를 얻으려면 토큰 카운팅 API를 사용하세요.

사고 암호화

전체 사고 콘텐츠는 암호화되어 각 사고 블록의 signature 필드로 반환됩니다. 사고 블록을 다시 전달하면 API는 signature(서명)를 사용하여 해당 블록이 Claude가 생성한 것인지 확인합니다.

서명을 다룰 때는 다음 사항에 유의하세요:

• 사고 블록을 반드시 다시 보내야 하는 경우는 사고와 함께 도구를 사용할 때뿐입니다. 그 외에는 이전 턴의 사고 블록을 생략해도 됩니다. 사고 블록을 다시 전달하는 경우, API가 이를 유지할지 제거할지는 모델에 따라 다릅니다(모델별 사고 블록 보존 참조). 이 동작은 context editing(컨텍스트 편집)으로 구성할 수 있습니다.
• 사고 블록을 다시 보낼 때는 일관성을 유지하고 잠재적인 문제를 방지하기 위해 받은 내용을 그대로 모두 전달하세요.
• 응답을 스트리밍하는 경우, 서명은 content_block_stop 이벤트 직전에 content_block_delta 이벤트 안의 signature_delta로 전달됩니다.
• Claude 4 이상 모델의 signature 값은 이전 모델보다 훨씬 깁니다.
• signature 필드는 불투명(opaque)한 값입니다. 해석하거나 파싱하지 마세요.
• signature 값은 플랫폼 간에 호환됩니다(Claude API, Amazon Bedrock, Google Cloud). 한 플랫폼에서 생성된 값은 다른 플랫폼에서도 작동하지만, Claude Sonnet 5.5와 Claude Haiku 5.5의 사고 블록은 이를 생성한 계정 또는 해당 계정에 연결된 계정에서만 작동합니다. 사고 블록은 생성한 계정에 귀속됩니다를 참조하세요.

편집된 사고 블록

Claude의 추론 중 일부가 안전상의 이유로 편집(redacted)되면, API는 일반 thinking 블록 외에 redacted_thinking 블록을 반환할 수 있습니다. redacted_thinking 블록에는 읽을 수 있는 텍스트가 없으며, 암호화된 사고 콘텐츠가 data 필드에 담겨 있습니다:

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

data 필드는 불투명하며 암호화되어 있습니다. 도구를 사용하는 멀티턴 대화를 이어갈 때는 일반 사고 블록의 signature 필드와 마찬가지로 redacted_thinking 블록을 수정하지 말고 그대로 API에 다시 전달하세요.

제한 사항 및 기능 호환성

샘플링 매개변수

Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5, Claude Haiku 5.5에서는 사고 사용 여부와 관계없이 기본값이 아닌 temperature, top_p 또는 top_k 값이 모든 요청에서 400 오류를 반환합니다. 이러한 모델에서 top_p 기본값은 0.99이므로 top_p를 1로 설정하면 400 오류가 반환되며, temperature와 top_p를 모두 포함하는 요청도 기본값이더라도 400 오류가 반환됩니다. 샘플링 매개변수 제거하기를 참조하세요. 이전 모델에서는 사고가 켜져 있는 동안에만 제한이 적용됩니다. temperature와 top_k는 사고와 호환되지 않으며, top_p는 0.95에서 1 사이의 값으로 허용됩니다.

응답 프리필 및 강제 도구 사용

Claude 4.6 이상 모델과 Claude Mythos Preview는 사고 사용 여부와 관계없이 프리필된 마지막 어시스턴트 턴을 400 오류로 거부합니다(프리필 미지원 참조). 이전 모델에서는 사고가 켜져 있는 동안 어시스턴트 응답을 프리필할 수 없습니다. 강제 도구 사용(tool_choice: {"type": "any"} 또는 {"type": "tool", ...})은 수동 확장 사고와 호환되지 않지만 적응형 사고에서는 작동합니다. 예외는 Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1로, 이 모델들은 모든 요청에서 강제 도구 사용을 400 오류로 거부합니다. 이러한 모델에서는 대신 엄격한 도구 사용 또는 구조화된 출력과 함께 tool_choice: {"type": "auto"}를 사용하세요. 강제 도구 사용이 허용되는 경우 응답은 도구 호출로 시작하며 thinking 블록이 없습니다. 모델이 도구를 호출하기 전에 사고하도록 하려면 tool_choice: {"type": "auto"}를 사용하고 프롬프트에서 도구를 언제 사용할지 명시하세요. 도구 사용과 함께하는 사고를 참조하세요.

출력 제한

각 모델에서 max_tokens는 아래 표에 나열된 상한까지 지정할 수 있습니다. Message Batches API에서는 output-300k-2026-03-24 beta header(베타 헤더)를 사용하면, 배치 상한이 표시된 모델의 상한이 높아집니다.

레거시 모델의 제한은 모델 개요를 참조하세요.

긴 요청

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

다음 단계