확장 사고(extended thinking)는 Claude가 최종 답을 내기 전에 단계별로 추론하도록 켜는 기능입니다. 복잡한 수학·코딩·분석처럼 깊은 사고가 도움이 되는 작업에서 답 품질을 높일 수 있습니다. 이 글은 API에서 확장 사고를 켜는 법과 주의점을 공식 기준으로 정리합니다. (공식 문서: docs.claude.com · 기준 시점: 2026년 6월)
확장 사고란
확장 사고를 켜면 Claude는 먼저 thinking(추론) 블록에 생각을 적고, 그 통찰을 반영해 text(최종 답) 블록을 내놓습니다. 응답에는 추론 블록과 답변 블록이 순서대로 포함됩니다. 단순한 일상 작업보다는 단계적 사고가 필요한 문제에서 효과가 큽니다.
켜는 법
요청에 thinking 객체를 추가합니다. 전통적으로는 type: "enabled"와 추론 토큰 상한인 budget_tokens를 함께 지정했습니다.
import anthropic
client = anthropic.Anthropic()
msg = client.messages.create(
model="<모델 ID>",
max_tokens=2048,
thinking={"type": "enabled", "budget_tokens": 1024}, # budget_tokens < max_tokens
messages=[{"role": "user", "content": "복잡한 문제를 단계적으로 풀어줘"}],
)다만 최신 모델 흐름에서는 토큰 수를 직접 정하는 대신, "얼마나 깊이 생각할지"를 effort로 지정하는 adaptive(적응형) 사고가 권장됩니다. 일부 최신 모델에서는 budget_tokens 방식이 deprecated(향후 제거 예정)로 표시됩니다. 정확한 파라미터와 지원 모델은 변동되니 공식 문서로 확인하세요. 참고로 추론 토큰 최소값은 1,024로 안내되며, 작게 시작해 점차 늘리는 것이 권장됩니다.
요약된 사고와 과금
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 표시), 가장 정확한 정보는 공식 문서(docs.claude.com)에서 확인하시기 바랍니다. 본 사이트는 Anthropic 공식 사이트가 아닙니다.