Claude 확장 사고(extended thinking) — API에서 추론을 켜고 다루기

확장 사고(extended thinking)는 Claude가 최종 답을 내기 전에 단계별로 추론하도록 켜는 기능입니다. 복잡한 수학·코딩·분석처럼 깊은 사고가 도움이 되는 작업에서 답 품질을 높일 수 있습니다. 이 글은 API에서 확장 사고를 켜는 법과 주의점을 공식 기준으로 정리합니다. (공식 문서: platform.claude.com/docs · 기준 시점: 2026년 9월, thinking·extended-thinking 문서 재대조)

확장 사고란

확장 사고를 켜면 Claude는 먼저 thinking(추론) 블록에 생각을 적고, 그 통찰을 반영해 text(최종 답) 블록을 내놓습니다. 응답에는 추론 블록과 답변 블록이 순서대로 포함됩니다. 단순한 일상 작업보다는 단계적 사고가 필요한 문제에서 효과가 큽니다.

켜는 법 (2026년 9월 공식 문서 기준)

모델 세대에 따라 켜는 방식이 다릅니다. 현재 라인업인 Claude Opus 5·Sonnet 5·Fable 5.1은 사고가 기본으로 켜져 있어 아무 설정도 필요 없습니다. 다만 이 모델들은 사고 요약문을 응답에 넣지 않는 것(display: "omitted")이 기본이라, 요약을 보려면 아래처럼 adaptive + display: "summarized"를 지정합니다.

import anthropic
client = anthropic.Anthropic()
msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[{"role": "user", "content": "복잡한 문제를 단계적으로 풀어줘"}],
)

• Opus 4.6·4.7·4.8, Sonnet 4.6 — 사고가 꺼져 있으므로 thinking: {"type": "adaptive"}로 켭니다. 언제·얼마나 생각할지는 모델이 요청을 보고 정하고, 깊이는 effort로 조절합니다.
• 수동 모드(type: "enabled" + budget_tokens) — 4.5 이하 모델에서는 유일한 방식이고, 4.6에서는 deprecated(요청은 아직 성공), 4.7 이후 모델은 거부(400 오류)합니다. 예전 예제 코드의 budget_tokens를 현행 모델에 그대로 쓰면 "thinking.type.enabled" is not supported 오류가 나므로 adaptive로 옮기세요. 수동 모드를 쓰는 경우 budget_tokens는 최소 1,024, max_tokens보다 작아야 합니다.
• 끄기 — Sonnet 5·Opus 5는 thinking: {"type": "disabled"}로 끌 수 있습니다. 단 Opus 5는 effort가 xhigh·max일 때는 끌 수 없습니다(400).

요약된 사고와 과금

Claude 4 계열에서 Messages API는 전체 추론이 아니라 요약된 사고를 반환합니다. 중요한 점은 과금은 요약이 아니라 원래 생성된 전체 thinking 토큰 기준이라는 것입니다. 따라서 청구된 출력 토큰 수가 화면에 보이는 토큰과 다를 수 있습니다. 추론 토큰량은 응답의 usage.output_tokens_details.thinking_tokens로 확인할 수 있고, 스트리밍에서는 마지막 message_delta에만 나타납니다.

언제 쓰나

확장 사고는 단계적 추론이 도움이 되는 복잡한 작업에 적합합니다 — 수학, 까다로운 코딩·디버깅, 다단계 분석 등. 반대로 단순 질의·요약·정형 변환처럼 가벼운 작업에는 굳이 켜지 않아도 됩니다. 추론은 응답을 느리고 비싸게 만들 수 있으니 작업 성격에 맞게 선택하세요.

주의할 점

• 비호환 설정 — 사고를 켜면 temperature·top_p·top_k 일부 조정이 제한됩니다(예: temperature는 1만 허용).
• 응답 시간 — 추가 처리로 응답이 느려질 수 있습니다.
• 큰 budget — 32k를 넘는 큰 추론은 타임아웃·연결 한계를 피하려 배치 처리가 권장됩니다(비용 줄이기 참고).
• 변동성 — 파라미터(adaptive·effort·budget_tokens)와 지원 모델은 바뀔 수 있으니 공식 문서가 기준입니다.

관련 가이드

스트리밍에서 추론은 thinking_delta로 도착합니다(스트리밍 참고). 에러·한도 대응은 에러와 레이트리밋 다루기, 첫 호출은 Claude API 시작하기를 함께 보세요.

반대로 정해진 형식의 출력이 더 중요하다면 구조화된 출력이 적합할 수 있습니다.

확장 사고·웹 검색·리서치 세 모드를 언제 쓰는지는 웹 검색·리서치 가이드에서 비교해 정리했습니다.

더 알아보기: 한 요청이 다룰 수 있는 용량과 토큰 관리법은 컨텍스트 윈도우와 토큰 가이드를 참고하세요.

확장 사고의 파라미터(adaptive·effort·budget_tokens), 지원 모델, 토큰 최소값 등은 변동될 수 있으며(일부는 deprecated 표시), 가장 정확한 정보는 공식 문서(platform.claude.com/docs)에서 확인하시기 바랍니다. 본 사이트는 Anthropic 공식 사이트가 아닙니다.

관련 글

• Claude API 비용 줄이기 — 프롬프트 캐싱과 배치 처리(Batch API)
• Claude API 스트리밍 응답 — SSE로 실시간 출력 받기
• Claude API 에러와 레이트리밋 다루기 — 429·529와 재시도 전략
• Claude API 시작하기: 첫 호출까지 (개발자 입문)
• Claude API 키 발급·요금·사용법 완전정리 (2026)