Anthropic Effort 파라미터

effort 파라미터로 Claude가 응답할 때 사용하는 토큰 수를 제어해서, 응답의 철저함과 토큰 효율성 사이에서 트레이드오프를 조절할 수 있어요.

출처: 문서

본문

개요 (Overview)

effort 파라미터를 사용하면 Claude가 요청에 응답할 때 토큰을 쓰는 데 얼마나 적극적인지 제어할 수 있어요. 단일 모델로 응답의 철저함과 토큰 효율성 사이를 트레이드오프할 수 있게 해 주는 기능이에요.

지원 모델:

Claude 4.6 (Opus 4.6, Sonnet 4.6): output_config가 안정적인 API 기능이라 베타 헤더가 필요 없어요. Opus 4.6은 effort="max"도 지원해요.
Claude Opus 4.5 — effort-2025-11-24 베타 헤더가 필요해요 (LiteLLM이 자동으로 추가해요).

LiteLLM은 모든 지원 모델에 대해 reasoning_effort를 output_config={"effort": ...}로 자동 매핑해요.

Effort는 어떻게 동작하나요? (How Effort Works)

기본적으로 Claude는 최대 effort를 사용해, 최상의 결과를 위해 필요한 만큼 많은 토큰을 사용해요. effort 수준을 낮추면 토큰 사용을 더 보수적으로 하도록 지시해서, 속도와 비용을 최적화하면서 능력은 다소 희생하는 거예요.

팁: effort를 "high"로 설정하면 effort 파라미터를 완전히 생략한 것과 똑같이 동작해요.

effort 파라미터는 응답의 모든 토큰에 영향을 미쳐요:

텍스트 응답과 설명
도구 호출 및 함수 인자
확장 사고(extended thinking, 활성화된 경우)

이 방식에는 두 가지 큰 장점이 있어요:

이를 사용하기 위해 thinking을 활성화할 필요가 없어요.
도구 호출을 포함한 모든 토큰 지출에 영향을 줄 수 있어요. 예를 들어 effort가 낮으면 Claude가 도구 호출을 더 적게 해요.

이렇게 하면 효율성에 대한 훨씬 더 큰 제어력을 얻을 수 있어요.

Effort 수준 (Effort Levels)

수준	설명	일반적 사용 사례
`max`	high를 넘어선 최대 능력 — 가장 철저한 결과를 위해 Claude가 더 많은 토큰을 사용. Claude Opus 4.6에서만 지원.	가장 어려운 추론 문제, 복잡한 다단계 연구
`high`	최대 능력 — 최상의 결과를 위해 필요한 만큼 많은 토큰 사용. 파라미터를 설정하지 않은 것과 동등.	복잡한 추론, 어려운 코딩 문제, 에이전트 작업
`medium`	중간 수준의 토큰 절약을 동반한 균형 잡힌 접근.	속도·비용·성능의 균형이 필요한 에이전트 작업
`low`	가장 효율적 — 상당한 토큰 절약과 일부 능력 감소.	최고의 속도와 최저 비용이 필요한 단순 작업 (예: 서브에이전트)

빠른 시작 (Quick Start)

LiteLLM SDK 사용하기

Python

import litellm

# Works with Claude 4.6 models (no beta header needed)
response = litellm.completion(
    model="anthropic/claude-sonnet-4-6",
    messages=[{
        "role": "user",
        "content": "Analyze the trade-offs between microservices and monolithic architectures"
    }],
    reasoning_effort="medium"  # Automatically mapped to output_config
)

print(response.choices[0].message.content)

# Also works with Claude Opus 4.5 (beta header auto-injected)
response = litellm.completion(
    model="anthropic/claude-opus-4-5-20251101",
    messages=[{
        "role": "user",
        "content": "Analyze the trade-offs between microservices and monolithic architectures"
    }],
    reasoning_effort="medium"
)

TypeScript

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

// Claude 4.6 — output_config is a stable API feature (no beta header)
const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 4096,
  messages: [{
    role: "user",
    content: "Analyze the trade-offs between microservices and monolithic architectures"
  }],
  output_config: {
    effort: "medium"
  }
});

console.log(response.content[0].text);

LiteLLM 프록시 사용하기

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "messages": [{
      "role": "user",
      "content": "Analyze the trade-offs between microservices and monolithic architectures"
    }],
    "reasoning_effort": "medium"
  }'

직접 Anthropic API 호출

Claude 4.6 (안정적)

# Claude 4.6 — no beta header needed
curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 4096,
    "messages": [{
      "role": "user",
      "content": "Analyze the trade-offs between microservices and monolithic architectures"
    }],
    "output_config": {
      "effort": "medium"
    }
  }'

Claude Opus 4.5 (베타)

# Claude Opus 4.5 — requires beta header
curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: effort-2025-11-24" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-4-5-20251101",
    "max_tokens": 4096,
    "messages": [{
      "role": "user",
      "content": "Analyze the trade-offs between microservices and monolithic architectures"
    }],
    "output_config": {
      "effort": "medium"
    }
  }'

모델 호환성 (Model Compatibility)

effort 파라미터를 지원하는 모델:

Claude Opus 4.6 (claude-opus-4-6): high, medium, low, max 지원
Claude Sonnet 4.6 (claude-sonnet-4-6): high, medium, low 지원
Claude Opus 4.5 (claude-opus-4-5-20251101): high, medium, low 지원

참고: effort="max"는 Claude Opus 4.6에서만 사용할 수 있어요. 다른 모델에서 사용하면 검증 오류가 발생해요.

언제 effort 파라미터를 조절해야 하나요? (When Should I Adjust the Effort Parameter?)

high effort(기본값)는 Claude의 최고 성능이 필요할 때: 복잡한 추론, 상세 분석, 어려운 코딩 문제, 또는 품질이 최우선인 어떤 작업이든.
medium effort는 high effort의 전체 토큰 지출 없이 확실한 성능을 원할 때의 균형 잡힌 옵션.
low effort는 속도(Claude가 더 적은 토큰으로 답하기 때문)나 비용을 최적화할 때: 단순 분류 작업, 빠른 조회, 또는 미미한 품질 개선이 추가 지연·지출을 정당화하지 않는 대량 사용 사례.

도구 사용과 Effort (Effort with Tool Use)

도구를 사용할 때 effort 파라미터는 도구 호출 주변의 설명과 도구 호출 자체 모두에 영향을 줘요. 낮은 effort 수준은 대체로:

여러 작업을 더 적은 도구 호출로 결합
더 적은 도구 호출을 수행
직접 행동으로 진행

도구 예시:

import litellm

response = litellm.completion(
    model="anthropic/claude-sonnet-4-6",
    messages=[{
        "role": "user",
        "content": "Check the weather in multiple cities"
    }],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            }
        }
    }],
    reasoning_effort="low"  # Mapped to output_config — will make fewer tool calls
)

확장 사고와 Effort (Effort with Extended Thinking)

effort 파라미터는 확장 사고(extended thinking)와 함께 동작해요. 둘 다 활성화되면 effort가 모든 응답 유형에 걸쳐 토큰 예산을 제어해요:

import litellm

response = litellm.completion(
    model="anthropic/claude-sonnet-4-6",
    messages=[{
        "role": "user",
        "content": "Solve this complex problem"
    }],
    reasoning_effort="medium"  # Mapped to adaptive thinking + output_config for 4.6 models
)

모범 사례 (Best Practices)

새 작업은 **기본(high)**으로 시작하고, 비용 최적화를 원하면 낮은 effort 수준을 실험해 보세요.
프로덕션 에이전트 워크플로우에는 medium effort를 사용해 품질과 효율성의 균형을 맞추세요.
대량·단순 작업(분류, 라우팅, 데이터 추출)에는 low effort를 아끼세요.
토큰 사용을 모니터링해 사용 사례별로 effort 수준에 따른 실제 절약 효과를 파악하세요.
고유한 프롬프트로 테스트하세요. effort 수준의 영향은 작업 복잡성에 따라 달라질 수 있기 때문이에요.

프로바이더 지원 (Provider Support)

effort 파라미터는 모든 Anthropic 호환 프로바이더에서 지원돼요.

표준 Anthropic API: ✅ 지원 (Claude 4.6, Opus 4.5)
Azure Anthropic / Microsoft Foundry: ✅ 지원 (Claude 4.6, Opus 4.5)
Amazon Bedrock: ✅ 지원 (Claude 4.6, Opus 4.5)
Google Cloud Vertex AI: ✅ 지원 (Claude 4.6, Opus 4.5)

LiteLLM이 자동으로 처리하는 것:

파라미터 매핑: 모든 지원 모델에 대해 reasoning_effort → output_config={"effort": ...}
베타 헤더 주입(effort-2025-11-24)은 Claude Opus 4.5에서만 (4.6 모델에는 불필요)

사용량·가격 (Usage and Pricing)

다양한 effort 수준의 토큰 사용량은 표준 사용량 객체에 추적돼요. 낮은 effort 수준은 출력 토큰을 줄여 직접 비용을 절감해요.

response = litellm.completion(
    model="anthropic/claude-opus-5",
    messages=[{"role": "user", "content": "Analyze this"}],
    ...
)

문제 해결 (Troubleshooting)

모델 미지원 (Model not supported)

effort 파라미터는 Claude Opus 4.6, Sonnet 4.6, Opus 4.5에서 지원돼요. 다른 모델에서 사용하면 파라미터가 무시되거나 오류가 발생할 수 있어요.

확장 사고 (Extended Thinking) — Claude의 추론 과정 제어
도구 사용 (Tool Use) — Claude가 도구와 함수를 사용하게 하기
프로그래매틱 도구 호출 — Claude가 도구를 호출하는 코드를 작성하게 하기
프롬프트 캐싱 — 비용 절감을 위한 프롬프트 캐싱

Anthropic Effort 파라미터