Effort

effort 매개변수를 사용하면 Claude가 요청에 응답할 때 사용하는 토큰 수를 제어할 수 있습니다. 단일 모델로 응답의 완전성과 토큰 효율성 사이에서 균형을 조정할 수 있습니다. effort 매개변수는 베타 헤더 없이 지원되는 모든 모델에서 사용할 수 있습니다.



effort 작동 방식

기본적으로 Claude는 high effort를 사용하여 우수한 결과를 위해 필요한 만큼의 토큰을 사용합니다. 최고 수준의 성능을 위해 effort 수준을 max로 높이거나, 토큰 사용을 더 보수적으로 하여 속도와 비용을 최적화하면서 일부 성능 저하를 감수하도록 낮출 수 있습니다.

effort 매개변수는 다음을 포함하여 응답의 모든 토큰에 영향을 미칩니다:

• 텍스트 응답 및 설명
• 도구 호출 및 함수 인수
• 사고(활성화된 경우)

이 접근 방식에는 두 가지 주요 이점이 있습니다:

1. 사고를 활성화할 필요가 없습니다.
2. 도구 호출을 포함한 모든 토큰 사용에 영향을 미칠 수 있습니다. 예를 들어, effort가 낮을수록 Claude는 더 적은 도구 호출을 수행합니다. 이를 통해 효율성을 훨씬 더 세밀하게 제어할 수 있습니다.



Effort 수준

xhigh는 더 최근에 추가된 수준입니다. max를 지원하는 일부 모델은 xhigh를 지원하지 않습니다.



Claude Sonnet 5의 권장 effort 수준

Claude Sonnet 5는 Claude API 및 Claude Code에서 기본적으로 high effort를 사용합니다.

• High effort(기본값): 속도나 비용보다 품질이 더 중요한 복잡한 추론, 코딩, 에이전트 작업에 적합합니다.
• Xhigh effort: 가장 어려운 코딩 및 에이전트 작업에 적합합니다. Claude Sonnet 5 프롬프트 작성을 참조하세요.
• Medium effort: 기본값에서 비용을 절감하기 위한 단계 하향. high effort의 Claude Sonnet 4.6과 유사합니다.
• Low effort: 대량 처리 또는 지연 시간에 민감한 워크로드에 적합합니다. 더 빠른 처리가 우선시되는 채팅 및 비코딩 사용 사례에 적합합니다.
• Max effort: 토큰 사용에 제약 없이 절대적인 최고 성능이 필요한 작업에 적합합니다.



Claude Sonnet 4.6의 권장 effort 수준

Sonnet 4.6은 기본적으로 high effort를 사용합니다. 예상치 못한 지연 시간을 방지하려면 Sonnet 4.6을 사용할 때 effort를 명시적으로 설정하세요:

• Medium effort(권장 기본값): 대부분의 애플리케이션에서 속도, 비용, 성능의 최적 균형. 에이전트 코딩, 도구 중심 워크플로, 코드 생성에 적합합니다.
• Low effort: 대량 처리 또는 지연 시간에 민감한 워크로드에 적합합니다. 더 빠른 처리가 우선시되는 채팅 및 비코딩 사용 사례에 적합합니다.
• High effort: 속도나 비용보다 품질이 더 중요한 복잡한 추론 및 작업에 적합합니다.
• Max effort: 토큰 사용에 제약 없이 절대적인 최고 성능이 필요한 작업에 적합합니다.



Claude Opus 4.7의 권장 effort 수준

코딩 및 에이전트 사용 사례에는 xhigh로 시작하고, 대부분의 지능 민감 워크로드에는 최소 high를 사용하세요. 비용에 민감한 워크로드에는 medium으로 낮추고, 평가에서 xhigh에서도 측정 가능한 여유가 있는 경우에만 max로 높이세요.

API 기본값은 high입니다. xhigh를 사용하려면 effort를 명시적으로 설정하세요. 전달한 값이 기본값을 재정의합니다.

Claude Opus 4.7은 또한 Claude Opus 4.6보다 effort 수준을 더 엄격하게 준수하며, 특히 low와 medium에서 그렇습니다. 낮은 effort 수준에서 모델은 요청된 것보다 더 많은 작업을 수행하기보다는 요청된 범위로 작업을 제한합니다. Claude Opus 4.7에서 복잡한 문제에 대해 얕은 추론이 관찰되면 프롬프트로 우회하기보다는 effort를 높이세요. 지연 시간 때문에 effort를 낮게 유지해야 하는 경우 "이 작업은 다단계 추론이 필요합니다. 응답하기 전에 신중하게 생각하세요."와 같은 구체적인 지침을 추가하세요.

Claude Opus 4.7을 xhigh 또는 max effort로 실행할 때는 모델이 서브에이전트와 도구 호출 전반에 걸쳐 사고하고 행동할 여유를 갖도록 큰 max_tokens를 설정하세요. 64k 토큰에서 시작하여 조정하는 것이 합리적인 기본값입니다.



Claude Opus 4.8의 권장 effort 수준

Claude Opus 4.7에 대한 지침은 Claude Opus 4.8에도 적용됩니다. 코딩 및 에이전트 사용 사례에는 xhigh로 시작하고, 대부분의 다른 지능 민감 워크로드에는 high를 사용하며, 평가에서 낮은 수준이 품질을 유지한다는 것을 측정한 경우에만 medium 또는 low로 낮추세요.

API 기본값은 high입니다. 다른 수준을 사용하려면 effort를 명시적으로 설정하세요. 전달한 값이 기본값을 재정의합니다.

Claude Opus 4.8을 xhigh 또는 max effort로 실행할 때는 모델이 서브에이전트와 도구 호출 전반에 걸쳐 사고하고 행동할 여유를 갖도록 큰 max_tokens를 설정하세요. 64k 토큰에서 시작하여 조정하는 것이 합리적인 기본값입니다.



Claude Opus 5의 권장 effort 수준

Claude Opus 5는 다섯 가지 effort 수준을 모두 지원합니다. 기본값인 high로 시작하고 평가를 기반으로 조정하세요: 까다로운 코딩 및 에이전트 작업에는 xhigh로 높이거나, 제약 없는 토큰 사용이 정당화되는 작업에는 max로 높이고, 평가에서 품질이 유지되는 경우 토큰 비용과 응답 시간의 주요 제어 수단으로 low와 medium을 자유롭게 사용하세요. 이전 모델에서 effort 설정을 가져온 경우, 재사용하기보다는 평가에서 새로운 effort 스윕을 실행하세요.

Effort는 가시적인 응답 길이가 아니라 사고량을 제어합니다: Claude Opus 5에서 effort를 변경해도 응답이 안정적으로 짧아지지 않으므로 대신 길이에 대한 프롬프트를 사용하세요.

API 기본값은 high입니다. 다른 수준을 사용하려면 effort를 명시적으로 설정하세요. 전달한 값이 기본값을 재정의합니다.

Claude Opus 5에서는 xhigh 또는 max effort에서 사고를 비활성화할 수 없습니다: 해당 수준에서 thinking: {"type": "disabled"}를 설정하는 요청은 400 오류를 반환합니다. 사고와 함께 사용하는 effort를 참조하세요.

Claude Opus 5를 xhigh 또는 max effort로 실행할 때는 모델이 서브에이전트와 도구 호출 전반에 걸쳐 사고하고 행동할 여유를 갖도록 큰 max_tokens를 설정하세요. 64k 토큰에서 시작하여 조정하는 것이 합리적인 기본값입니다.



Claude Fable 5의 권장 effort 수준

Effort는 Claude Fable 5에서 지능, 지연 시간, 비용 간의 균형을 조정하는 주요 제어 수단입니다. 대부분의 작업에는 기본값인 high로 시작하고, 성능에 가장 민감한 워크로드에는 xhigh를 사용하며, 일상적인 작업에는 medium 또는 low로 낮추세요. Claude Fable 5의 낮은 effort 설정도 여전히 우수한 성능을 발휘하며 이전 모델의 xhigh 성능을 능가하는 경우가 많습니다. high 및 xhigh에서는 큰 max_tokens를 설정하세요: 이는 사고와 응답 텍스트를 합한 총 출력에 대한 엄격한 제한입니다. 비용 제어를 참조하세요.

작업이 완료되지만 필요 이상으로 오래 걸리거나, 더 빠르고 상호작용적인 작업 스타일을 원하는 경우 effort를 줄이세요. 동일한 권장 사항이 Claude Mythos 5에도 적용됩니다. 더 자세한 지침은 Claude Fable 5 프롬프트 작성을 참조하세요.



기본 사용법

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

for block in response.content:
    if block.type == "text":
        print(block.text)



effort 매개변수를 조정해야 하는 경우

• 제약 없이 절대적인 최고 성능이 필요한 경우 max effort를 사용하세요: 가장 철저한 추론과 가장 깊은 분석. Claude 4.6 이상 모델 및 Claude Mythos Preview에서 사용 가능합니다.
• 반복적인 도구 호출 및 상세한 검색과 같이 확장된 탐색이 필요한 고급 코딩 및 복잡한 에이전트 작업에는 xhigh effort를 사용하세요. Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5에서 사용 가능합니다.
• 복잡한 추론, 미묘한 분석, 어려운 코딩 문제 또는 속도나 비용보다 품질이 더 중요한 모든 작업에는 high effort(기본값)를 사용하세요.
• high effort의 전체 토큰 소비 없이 견고한 성능을 원하는 경우 균형 잡힌 옵션으로 medium effort를 사용하세요.
• 속도(Claude가 더 적은 토큰으로 응답하기 때문) 또는 비용을 최적화하는 경우 low effort를 사용하세요. 예를 들어, 간단한 분류 작업, 빠른 조회 또는 한계적인 품질 향상이 추가 지연 시간이나 비용을 정당화하지 못하는 대량 사용 사례에 적합합니다.



도구 사용과 함께 사용하는 effort

도구를 사용할 때 effort 매개변수는 도구 호출에 대한 설명과 도구 호출 자체 모두에 영향을 미칩니다. 낮은 effort 수준은 다음과 같은 경향이 있습니다:

• 여러 작업을 더 적은 도구 호출로 결합
• 더 적은 도구 호출 수행
• 서두 없이 바로 작업 진행
• 완료 후 간결한 확인 메시지 사용

높은 effort 수준은 다음과 같을 수 있습니다:

• 더 많은 도구 호출 수행
• 작업을 수행하기 전에 계획 설명
• 변경 사항에 대한 상세한 요약 제공
• 더 포괄적인 코드 주석 포함



사고와 함께 사용하는 effort

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

높은 effort 수준에서 Claude는 대부분의 요청에 대해 더 길게 사고합니다. 낮은 수준에서는 간단한 문제에 대해 사고를 완전히 건너뛸 수 있습니다. 두 제어 방식이 함께 작동하는 방식에 대한 전체 지침은 사고와 effort를 참조하세요.

effort를 지원하는 유일한 확장 사고 전용 모델인 Claude Opus 4.5에서는 budget_tokens와 함께 작동합니다: 작업에 맞는 effort 수준을 설정한 다음, 작업에 필요한 추론 깊이에 따라 사고 토큰 예산을 설정하세요.

모델별 사고 가용성은 모델별 구성 표를 참조하세요. Effort는 사고 유무와 관계없이 작동합니다. effort 작동 방식을 참조하세요.



대화 중 effort 변경

output_config.effort는 요청 수준 설정입니다: 각 요청은 자체 값을 가지므로, 대화의 이후 부분을 다른 effort 수준으로 실행하려면 다음 요청에서 새 값을 설정하세요. effort 수준은 전체 요청에 적용됩니다. effort는 렌더링된 프롬프트를 형성하기 때문에 요청 간에 변경하면 이전 턴의 캐시된 접두사가 보존되지 않습니다. 긴 세션에서 프롬프트 캐싱에 의존하는 경우 시작 시 effort 수준을 선택하고 일정하게 유지하세요.



모범 사례

1. effort를 명시적으로 설정하세요: API 기본값은 high이지만, 올바른 시작점은 모델과 워크로드에 따라 다릅니다.
2. 속도에 민감하거나 간단한 작업에는 low를 사용하세요: 지연 시간이 중요하거나 작업이 간단한 경우 low effort는 응답 시간과 비용을 크게 줄일 수 있습니다.
3. 사용 사례를 테스트하세요: effort 수준의 영향은 작업 유형에 따라 다릅니다. 배포하기 전에 특정 사용 사례에서 성능을 평가하세요.
4. 동적 effort를 고려하세요: 작업 복잡성에 따라 effort를 조정하세요. 간단한 쿼리는 low effort가 적합할 수 있으며, 에이전트 코딩 및 복잡한 추론은 high effort의 이점을 얻습니다. 하나의 대화 내에서 변경하기 전에 다음 항목을 참조하세요.
5. 캐시된 대화 내에서는 effort를 일정하게 유지하세요: 요청 간에 effort 값을 변경하면 프롬프트 캐싱이 무효화되므로, 캐시 적중에 의존하는 대화 내에서가 아니라 워크로드 간에 effort를 변경하세요. 사고와 프롬프트 캐싱을 참조하세요.



다음 단계