Claude Platform Docs
Messages사고

확장 사고

이를 지원하는 Claude 모델에서 고정된 budget_tokens 예산으로 수동 확장 사고를 구성하고, 적응형 사고로 마이그레이션합니다.

수동 모드의 "extended thinking"(확장 사고)은 Claude가 얼마나 많이 사고할지를 직접 제어할 수 있게 해줍니다. 각 요청에서 thinking: {type: "enabled", budget_tokens: N}으로 사고 토큰 예산을 설정하면, Claude는 최종 답변을 시작하기 전에 해당 예산에 맞춰 사고합니다. 수동 모드는 워크로드에 예측 가능한 지연 시간이나 사고 비용에 대한 정밀한 제어가 필요한 경우 여전히 유용합니다. 이 페이지에서는 예산을 설정하고 조정하는 방법, 수동 모드가 인터리브 사고 및 "prompt caching"(프롬프트 캐싱)과 어떻게 상호작용하는지, 그리고 적응형 사고로 마이그레이션하는 방법을 다룹니다.

사고 블록과 응답 형태, display 매개변수, 스트리밍, 도구 사용과 함께하는 사고, 암호화 등 사고 자체가 어떻게 작동하는지 알아보려면 사고 개요를 참조하세요.

지원 모델

확장 사고가 유일한 모드인 모델을 포함하여 모델별 확장 사고 사용 가능 여부는 모델별 구성 표에 나열되어 있습니다.

확장 사고 사용 방법

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# 응답에는 요약된 사고 블록과 텍스트 블록이 포함됩니다
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

수동 확장 사고를 켜려면 type이 enabled로 설정되고 budget_tokens 값이 있는 thinking 객체를 추가하세요.

budget_tokens 매개변수는 Claude가 내부 추론 과정에 사용할 수 있는 토큰 수의 목표치를 설정합니다. 더 큰 예산은 복잡한 문제에 대해 더 철저한 분석을 가능하게 하여 응답 품질을 향상시킬 수 있습니다.

예산 규칙 및 조정

budget_tokens는 다음 제약 조건을 충족해야 합니다:

  • 최소 1,024 토큰. API는 더 작은 값을 거부합니다.
  • max_tokens보다 작아야 함. 사고 토큰은 해당 턴의 max_tokens 한도에 포함되므로, 예산은 최종 응답을 위한 여유를 남겨야 합니다. 한 가지 예외는 인터리브 사고로, 이 경우 예산이 하나의 어시스턴트 턴 내 모든 사고 블록에 걸쳐 적용되므로 budget_tokens가 max_tokens를 초과할 수 있습니다.
  • 캐시 사전 워밍 불가. budget_tokens는 max_tokens보다 작아야 하므로, 확장 사고는 max_tokens: 0(캐시 사전 워밍)과 함께 사용할 수 없습니다.

예산은 엄격한 상한이 아니라 목표치입니다. 실제 토큰 사용량은 작업에 따라 달라지며, Claude는 예산이 소진되기 훨씬 전에 추론을 멈출 수 있습니다. max_tokens는 여전히 총 출력에 대한 엄격한 상한입니다.

effort를 지원하는 유일한 확장 사고 전용 모델인 Claude Opus 4.5에서는 effort가 전체 응답을 형성하고 budget_tokens가 사고 깊이를 설정합니다. 둘 다 설정하세요.

예산을 조정하려면:

  • 시작점을 작업에 맞추세요. 간단한 작업의 경우 최소값인 1,024 토큰 근처에서 시작하여 점진적으로 늘려가며 사용 사례에 맞는 최적 범위를 찾으세요. 복잡한 작업의 경우 16,000 토큰 이상의 더 큰 예산으로 시작하여 지연 시간 및 품질 요구 사항에 맞게 조정하세요. 더 높은 예산은 더 포괄적인 추론을 가능하게 하지만, 작업에 따라 수익이 감소하며 지연 시간이 증가하는 비용이 따릅니다. 중요한 작업의 경우 다양한 설정을 테스트하여 적절한 균형을 찾으세요.
  • 32k를 초과하는 사고 예산의 경우 네트워킹 문제를 피하기 위해 배치 처리를 사용하세요. 모델이 32k 토큰을 넘어 사고하도록 하면 시스템 타임아웃 및 열린 연결 제한에 도달할 수 있는 장시간 실행 요청이 생성됩니다.

예산이 실제로 얼마의 비용을 발생시키는지 추적하려면 응답의 usage.output_tokens_details.thinking_tokens 필드를 모니터링하세요. 이 필드는 청구된 출력 토큰 중 내부 추론에 사용된 토큰 수를 보고합니다. 스트리밍 시 이 세부 내역은 최종 message_delta 이벤트에만 나타납니다.

수동 예산에서 벗어날 준비가 되면 적응형 사고로 마이그레이션을 참조하세요.

수동 모드의 인터리브 사고

"Interleaved thinking"(인터리브 사고)은 Claude가 단일 어시스턴트 턴 내에서 도구 호출 사이에 사고할 수 있게 하여, 다음에 무엇을 할지 결정하기 전에 각 도구 결과에 대해 추론하도록 합니다. 개념, 턴 구조, 그리고 적응형 사고 모델에서의 동작 방식은 사고 개요의 인터리브 사고를 참조하세요. 이 섹션에서는 수동 type: "enabled" 사고를 사용할 때 이를 활성화하는 방법을 다룹니다.

Claude Opus 4.5, Claude Sonnet 4.5 및 이전 Claude 4 모델에서는 API 요청에 interleaved-thinking-2025-05-14 베타 헤더를 추가하세요.

4.6 세대는 수동 모드에서 나뉩니다:

  • Claude Sonnet 4.6: 수동 type: "enabled"와 함께 사용하는 베타 헤더는 여전히 작동하지만 지원 중단되었습니다. 헤더 없이 자동으로 인터리브하는 적응형 사고를 사용하는 것이 좋습니다.
  • Claude Opus 4.6: 수동 모드에는 인터리브 사고가 전혀 없습니다. 적응형 모드만 인터리브하므로, 이 모델에서 도구 호출 사이의 추론이 필요하다면 thinking: {type: "adaptive"}로 전환하세요.

Claude Haiku 4.5는 인터리브 사고를 지원하지 않습니다. Claude API에서는 베타 헤더가 수락되지만 무시됩니다.

수동 모드의 인터리브 사고에 대한 두 가지 추가 고려 사항:

플랫폼이 베타 헤더를 처리하는 방식은 다릅니다. Claude API와 Claude Platform on AWS는 모든 모델에서 interleaved-thinking-2025-05-14를 수락하며 지원되지 않는 경우 무시합니다. 수락이 효과와 같은 것은 아닙니다. type: "enabled"를 거부하는 모델(4.7 이상)이나 수동 모드 인터리빙이 없는 모델(Claude Opus 4.6)에서는 헤더가 수동 모드에 아무런 효과가 없으며, 해당 모델에서는 적응형 사고가 자동으로 인터리브합니다.

파트너 운영 플랫폼(Amazon Bedrock 및 Google Cloud)도 마찬가지로 오류를 반환하지 않고 모든 모델에서 헤더를 수락하며, 인터리브 사고를 지원하지 않는 모델에서는 이를 무시합니다.

수동 모드의 턴 구조

단일 턴 도구 사용 루프, 턴 중간 충돌 처리, 턴 간 사고 전환을 포함한 일반적인 턴 구조 규칙은 도구 사용과 함께하는 사고에 있습니다.

수동 모드는 한 가지 요구 사항을 추가합니다. 사고가 활성화된 요청의 마지막 어시스턴트 턴은 사고 블록으로 시작해야 합니다(적응형 사고는 이 요구 사항을 제거합니다). 턴 간에 사고 구성을 변경하면 프롬프트 캐싱도 무효화됩니다. 다음 섹션을 참조하세요.

수동 모드의 프롬프트 캐싱

수동 모드는 사고와 프롬프트 캐싱에 설명된 모드 중립적 캐싱 동작 위에 한 가지 규칙을 추가합니다. 요청 간에 budget_tokens를 변경하면 사고 모드를 전환하는 것과 마찬가지로 캐시 중단점이 무효화됩니다. 예산 값이 프롬프트에 렌더링되기 때문입니다. 메시지 수준 중단점은 예산 변경 후 항상 미스가 발생하며, 도구 및 시스템 프롬프트 중단점도 미스가 발생하는지 여부는 모델이 구성을 어디에 렌더링하는지에 따라 달라집니다.

실제로는 예산을 하나 정하고 캐시된 대화의 수명 동안 안정적으로 유지하세요. Claude Sonnet 4.6에서 메시지 수준 캐싱으로 멀티턴 대화를 실행하면서 세 번째 요청에서 예산을 4,000에서 8,000 토큰으로 변경하면 무효화가 직접적으로 드러납니다:

Output
First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

요청 간에 예산이 변경되었기 때문에 세 번째 요청은 캐시를 다시 생성합니다(cache_creation_input_tokens=1370, cache_read_input_tokens=0). 여기서 budget_tokens가 하는 캐시 역할을 effort 수준이 대신하는 적응형 모드에서 동일한 실험의 실행 가능한 버전은 조정 페이지의 프롬프트 캐싱을 참조하세요.

공통 메커니즘

대부분의 사고 동작은 모드 중립적이며 사고 페이지에 한 번 문서화되어 있습니다. 그곳의 모든 내용은 수동 모드에도 적용됩니다:

적응형 사고로 마이그레이션

사용 중인 모델이 확장 사고만 지원하는 경우(Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5 및 이전 Claude 4 모델), 지금은 조치가 필요하지 않습니다. 해당 모델에서는 적응형 사고를 사용할 수 없으며, type: "adaptive"는 400 오류를 반환합니다. 적응형 사고를 지원하는 모델로 이동할 때까지 budget_tokens를 유지한 다음, 아래의 매핑을 적용하세요.

다음의 경우 type: "enabled"에서 마이그레이션해야 합니다:

  • budget_tokens가 지원 중단된 Claude Opus 4.6 또는 Claude Sonnet 4.6을 사용하는 경우.
  • type: "enabled"가 400 오류를 반환하는 Claude 4.7 이상의 모델(예: Claude Opus 5.5, Claude Sonnet 5, Claude Fable 5.1)을 사용하는 경우.

매핑은 간단합니다. budget_tokens를 제거하고, thinking: {type: "adaptive"}를 설정하고, 토큰 예산 대신 output_config: {effort: ...}로 추론 깊이를 제어하세요.

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}

위 코드는 다음과 같이 바뀝니다:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}

effort: "high"는 API 기본값과 일치합니다. 여기서는 깊이 제어가 이제 어디에 있는지 보여주기 위해서만 표시되었으며, 생략해도 동일한 동작이 나타납니다.

단순한 구문 변경이 아니라 동작상의 차이를 예상하세요. 고정 예산에서는 Claude가 모든 요청에서 사고합니다. 적응형 사고에서는 Claude가 각 요청에서 사고할지 여부와 얼마나 사고할지를 결정하며, 낮은 effort 설정에서는 쉬운 입력에 대해 사고를 완전히 건너뛸 수 있습니다. 마이그레이션 후에는 interleaved-thinking-2025-05-14 베타 헤더도 제거할 수 있습니다. 적응형 사고는 자동으로 인터리브하며, Claude API는 이러한 모델에서 헤더를 무시합니다. 사고 블록 보존도 변경됩니다. Claude Opus 4.5 및 4.6 이상 번호의 모델은 이전 턴의 사고 블록을 컨텍스트에 유지하고 입력으로 청구하는 반면, Claude Sonnet 4.5, Claude Haiku 4.5 및 이전 모델은 이를 제거했습니다. 모델별 사고 블록 보존을 참조하세요.

모드 전환은 사고 구성 변경이므로, 수동 모드의 프롬프트 캐싱에 설명된 대로 전환 후 첫 번째 요청은 캐시 중단점을 무효화합니다.

전체 지침은 적응형 사고, effort 및 모델 마이그레이션 가이드를 참조하세요.

다음 단계

사고

블록, 표시, 스트리밍, 도구 사용 등 사고가 어떻게 작동하는지 알아보세요.

사고 조정

각 요청에서 언제 얼마나 사고할지 Claude가 결정하도록 하세요.

도구 및 멀티턴 워크플로의 사고

사고 블록을 보존하고 도구 호출과 턴 전반에 걸쳐 사고를 관리하세요.

Was this page helpful?