적응형 사고

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

적응형 사고는 Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6과 함께 확장 사고를 사용하는 권장 방법이며, Claude Mythos Preview의 기본 모드입니다(thinking이 설정되지 않을 때마다 자동으로 적용됨). 사고 토큰 예산을 수동으로 설정하는 대신, 적응형 사고를 통해 Claude는 각 요청의 복잡성에 따라 확장 사고를 언제 어떻게 사용할지 동적으로 결정할 수 있습니다. Claude Opus 4.7에서는 적응형 사고가 유일한 지원되는 사고 모드입니다. 수동 thinking: {type: "enabled", budget_tokens: N}은 더 이상 허용되지 않습니다.

적응형 사고는 특히 이중 모드 작업과 장기 에이전트 워크플로우의 경우 고정 budget_tokens을 사용한 확장 사고보다 더 나은 성능을 제공할 수 있습니다. 베타 헤더가 필요하지 않습니다.

워크로드가 예측 가능한 지연 시간이나 사고 비용에 대한 정확한 제어가 필요한 경우, Claude Opus 4.6 및 Claude Sonnet 4.6에서는 budget_tokens을 사용한 확장 사고가 여전히 작동하지만 더 이상 권장되지 않습니다. 아래 경고를 참조하세요.

지원되는 모델

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

Claude Mythos Preview (claude-mythos-preview), 적응형 사고가 기본값입니다. thinking: {type: "disabled"}는 지원되지 않습니다.
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)

thinking.type: "enabled"와 budget_tokens은 Opus 4.6 및 Sonnet 4.6에서 더 이상 사용되지 않으며 향후 모델 릴리스에서 제거될 예정입니다. 대신 effort 매개변수와 함께 thinking.type: "adaptive"를 사용하세요. 기존 budget_tokens 구성은 여전히 작동하지만 더 이상 권장되지 않습니다. 마이그레이션을 계획하세요.

이전 모델(Sonnet 4.5, Opus 4.5 등)은 적응형 사고를 지원하지 않으며 thinking.type: "enabled"과 budget_tokens이 필요합니다.

적응형 사고의 작동 방식

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

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

적응형 사고 사용 방법

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

노력 매개변수를 사용한 적응형 사고

노력 매개변수와 함께 적응형 사고를 결합하여 Claude가 얼마나 많이 생각하는지 안내할 수 있습니다. 노력 수준은 Claude의 사고 할당에 대한 소프트 안내 역할을 합니다:

노력 수준	사고 동작
`max`	Claude는 사고 깊이에 제약 없이 항상 생각합니다. Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6에서 사용 가능합니다.
`xhigh`	Claude는 확장된 탐색으로 항상 깊게 생각합니다. Claude Opus 4.7에서 사용 가능합니다.
`high` (기본값)	Claude는 항상 생각합니다. 복잡한 작업에 대해 깊은 추론을 제공합니다.
`medium`	Claude는 중간 정도의 사고를 사용합니다. 매우 간단한 쿼리에 대해 사고를 건너뛸 수 있습니다.
`low`	Claude는 사고를 최소화합니다. 속도가 가장 중요한 간단한 작업에 대해 사고를 건너뜁니다.

적응형 사고를 사용한 스트리밍

적응형 사고는 스트리밍과 원활하게 작동합니다. 사고 블록은 수동 사고 모드처럼 thinking_delta 이벤트를 통해 스트리밍됩니다:

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

모드	구성	가용성	사용 시기
적응형	`thinking: {type: "adaptive"}`	Claude Mythos Preview (기본값), Opus 4.7 (유일한 모드), Opus 4.6, Sonnet 4.6	Claude가 확장 사고를 언제 어떻게 사용할지 결정합니다. `effort`를 사용하여 안내하세요.
수동	`thinking: {type: "enabled", budget_tokens: N}`	Claude Opus 4.7을 제외한 모든 모델(거부됨). Opus 4.6 및 Sonnet 4.6에서 더 이상 사용되지 않음(대신 적응형 모드 고려).	사고 토큰 지출에 대한 정확한 제어가 필요할 때.
비활성화됨	`thinking` 매개변수를 생략하거나 `{type: "disabled"}` 전달	Claude Mythos Preview를 제외한 모든 모델	확장 사고가 필요하지 않고 가장 낮은 지연 시간을 원할 때.

적응형 사고는 Claude Mythos Preview, Claude Opus 4.7, Opus 4.6, Sonnet 4.6에서 사용 가능합니다. Mythos Preview에서는 적응형 사고가 기본값이며 thinking이 설정되지 않을 때마다 자동으로 적용됩니다. Claude Opus 4.7에서는 적응형 사고가 유일하게 지원되는 모드이며 budget_tokens을 사용한 type: "enabled"는 거부됩니다. 이전 모델은 budget_tokens을 사용한 type: "enabled"만 지원합니다. Opus 4.6 및 Sonnet 4.6에서는 budget_tokens을 사용한 type: "enabled"가 여전히 작동하지만 더 이상 사용되지 않습니다.

모드별 인터리브된 사고 가용성:

적응형 모드: 인터리브된 사고는 Claude Mythos Preview, Claude Opus 4.7, Opus 4.6, Sonnet 4.6에서 자동으로 활성화됩니다. Mythos Preview 및 Opus 4.7에서는 도구 간 추론이 항상 사고 블록 내에 있습니다.
Sonnet 4.6의 수동 모드: 인터리브된 사고는 interleaved-thinking-2025-05-14 베타 헤더를 통해 작동합니다.
Opus 4.6의 수동 모드: 인터리브된 사고를 사용할 수 없습니다. Opus 4.6의 에이전트 워크플로우가 도구 호출 사이의 사고를 필요로 하는 경우 적응형 모드를 사용하세요.

중요한 고려사항

검증 변경사항

적응형 사고를 사용할 때 이전 어시스턴트 턴은 사고 블록으로 시작할 필요가 없습니다. 이는 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.

Claude가 덜 자주 생각하도록 유도하면 추론의 이점을 얻는 작업의 품질이 저하될 수 있습니다. 프롬프트 기반 조정을 프로덕션에 배포하기 전에 특정 워크로드에 미치는 영향을 측정하세요. 먼저 더 낮은 노력 수준으로 테스트하는 것을 고려하세요.

비용 제어

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

high 및 max 노력 수준에서 Claude는 더 광범위하게 생각할 수 있으며 max_tokens 예산을 소진할 가능성이 더 높습니다. 응답에서 stop_reason: "max_tokens"을 관찰하면 모델에 더 많은 공간을 제공하기 위해 max_tokens을 늘리거나 노력 수준을 낮추는 것을 고려하세요.

사고 블록 작업

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

요약된 사고

With extended thinking enabled, the Messages API for Claude 4 models returns a summary of Claude's full thinking process. Summarized thinking provides the full intelligence benefits of extended thinking, while preventing misuse. This is the default behavior on Claude 4 models when the display field on the thinking configuration is unset or set to "summarized". On Claude Opus 4.7 and Claude Mythos Preview, display defaults to "omitted" instead, so you must set display: "summarized" explicitly to receive summarized thinking.

Here are some important considerations for summarized thinking:

You're charged for the full thinking tokens generated by the original request, not the summary tokens.
The billed output token count will not match the count of tokens you see in the response.
On Claude 4 models, the first few lines of thinking output are more verbose, providing detailed reasoning that's particularly helpful for prompt engineering purposes. Claude Mythos Preview summarizes from the first token, so its thinking blocks do not show this verbose preamble.
As Anthropic seeks to improve the extended thinking feature, summarization behavior is subject to change.
Summarization preserves the key ideas of Claude's thinking process with minimal added latency, enabling a streamable user experience and easy migration from Claude Sonnet 3.7 to Claude 4 and later models.
Summarization is processed by a different model than the one you target in your requests. The thinking model does not see the summarized output.

Claude Sonnet 3.7 continues to return full thinking output.

In rare cases where you need access to full thinking output for Claude 4 models, contact our sales team.

사고 표시 제어

The display field on the thinking configuration controls how thinking content is returned in API responses. It accepts two values:

"summarized": Thinking blocks contain summarized thinking text. See Summarized thinking for details. This is the default on Claude Opus 4.6, Claude Sonnet 4.6, and earlier Claude 4 models.
"omitted": Thinking blocks are returned with an empty thinking field. The signature field still carries the encrypted full thinking for multi-turn continuity (see Thinking encryption). This is the default on Claude Opus 4.7 and Claude Mythos Preview.

Setting display: "omitted" is useful when your application doesn't surface thinking content to users. The primary benefit is faster time-to-first-text-token when streaming: The server skips streaming thinking tokens entirely and delivers only the signature, so the final text response begins streaming sooner.

Here are some important considerations for omitted thinking:

You're still charged for the full thinking tokens. Omitting reduces latency, not cost.
If you pass thinking blocks back in multi-turn conversations, pass them unchanged. The server decrypts the signature to reconstruct the original thinking for prompt construction (see Preserving thinking blocks). Any text you place in the thinking field of a round-tripped omitted block is ignored.
display is invalid with thinking.type: "disabled" (there is nothing to display).
When using thinking.type: "adaptive" and the model skips thinking for a simple request, no thinking block is produced regardless of display.

The signature field is identical whether display is "summarized" or "omitted". Switching display values between turns in a conversation is supported.

Claude Opus 4.7에서 thinking.display의 기본값은 "omitted"입니다. 사고 블록은 여전히 응답 스트림에 나타나지만 명시적으로 옵트인하지 않으면 thinking 필드가 비어 있습니다. 이는 기본값이 "summarized"였던 Claude Opus 4.6의 자동 변경입니다. Claude Opus 4.7에서 요약된 사고 텍스트를 복원하려면 thinking.display를 명시적으로 "summarized"로 설정하세요:

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

display: "omitted"을 사용한 코드 예제 및 스트리밍 동작은 사고 표시 제어를 참조하세요. 거기의 예제는 type: "enabled"를 사용합니다. 적응형 사고를 사용하려면:

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

사고 암호화

Full thinking content is encrypted and returned in the signature field. This field is used to verify that thinking blocks were generated by Claude when passed back to the API.

It is only strictly necessary to send back thinking blocks when using tools with extended thinking. Otherwise you can omit thinking blocks from previous turns. If you pass them back, whether the API keeps or strips them depends on the model: Opus 4.5+ and Sonnet 4.6+ keep them in context by default; earlier Opus/Sonnet models and all Haiku models strip them. See context editing to configure this.

If sending back thinking blocks, we recommend passing everything back as you received it for consistency and to avoid potential issues.

Here are some important considerations on thinking encryption:

When streaming responses, the signature is added via a signature_delta inside a content_block_delta event just before the content_block_stop event.
signature values are significantly longer in Claude 4 models than in previous models.
The signature field is an opaque field and should not be interpreted or parsed.
signature values are compatible across platforms (Claude APIs, Amazon Bedrock, and Vertex AI). Values generated on one platform will be compatible with another.

가격 책정

For complete pricing information including base rates, cache writes, cache hits, and output tokens, see the pricing page.

The thinking process incurs charges for:

Tokens used during thinking (output tokens)
Thinking blocks from prior assistant turns kept in context: only the last turn on earlier Opus/Sonnet models and all Haiku models; all turns by default on Opus 4.5+ and Sonnet 4.6+ (input tokens)
Standard text output tokens

When extended thinking is enabled, a specialized system prompt is automatically included to support this feature.

When using summarized thinking:

Input tokens: Tokens in your original request (excludes thinking tokens from previous turns)
Output tokens (billed): The original thinking tokens that Claude generated internally
Output tokens (visible): The summarized thinking tokens you see in the response
No charge: Tokens used to generate the summary

When using display: "omitted":

Input tokens: Tokens in your original request (same as summarized)
Output tokens (billed): The original thinking tokens that Claude generated internally (same as summarized)
Output tokens (visible): Zero thinking tokens (the thinking field is empty)

The billed output token count will not match the visible token count in the response. You are billed for the full thinking process, not the thinking content visible in the response.

추가 주제

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

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

다음 단계

확장 사고

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "Explain why the sum of two even numbers is always even.",
        }
    ],
)

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "What is the capital of France?"}],
)

print(response.content[0].text)

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    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)