Ajustando o Parâmetro effort para Custo e Velocidade

O parâmetro effort define quanta profundidade de raciocínio o Claude aplica a uma requisição, permitindo que você troque qualidade por custo e velocidade em uma base por chamada.

Resumo

Toda requisição tem um orçamento implícito de custo e latência.

O parâmetro effort, passado em output_config, oferece uma alavanca direta sobre esse orçamento.

Menor effort favorece velocidade e custo, maior effort favorece completude.

Isso é distinto da configuração thinking, que controla se o raciocínio é adaptativo e visível.

As duas configurações se compõem, então um sistema de produção bem ajustado geralmente define ambas deliberadamente em vez de deixar qualquer uma no padrão.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Resuma este thread de suporte ao cliente."}],
)
 
print(response.content[-1].text)

Quando usar isso:

• Endpoints de alto volume e sensíveis à latência onde o effort low mantém o custo previsível.
• Revisão de código, planejamento ou tarefas críticas de segurança onde high ou max effort vale o custo.
• Teste A/B de qualidade versus trade-offs de custo entre níveis de effort para o mesmo prompt.
• Roteamento de effort dinamicamente com base no tipo de requisição em vez de uma única configuração fixa.
• Limitação de custo de raciocínio descontrolado em uma carga de trabalho que anteriormente não tinha um teto de effort.

Exemplo de Trabalho

import anthropic
 
client = anthropic.Anthropic()
 
EFFORT_BY_TASK_TYPE = {
    "classify": "low",
    "summarize": "medium",
    "code_review": "high",
    "incident_root_cause": "max",
}
 
 
def run_task(task_type: str, prompt: str) -> str:
    effort = EFFORT_BY_TASK_TYPE.get(task_type, "medium")
 
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1536,
        thinking={"type": "adaptive"},
        output_config={"effort": effort},
        messages=[{"role": "user", "content": prompt}],
    )
 
    for block in response.content:
        if block.type == "text":
            return block.text
    return ""
 
 
if __name__ == "__main__":
    ticket = "Usuário relata 502s intermitentes no checkout, começou após o deploy da noite passada."
    result = run_task("incident_root_cause", ticket)
    print(result)

O que isso demonstra:

• Uma tabela de consulta que mapeia o tipo de tarefa para um nível de effort, evitando uma única configuração codificada em toda a aplicação.
• Emparelhamento de thinking={"type": "adaptive"} com um teto de effort explícito, as duas configurações se compondo de forma limpa.
• Retorno para "medium" para tipos de tarefa não reconhecidos em vez de falhar.
• Extração apenas do bloco text, ignorando qualquer bloco thinking para os propósitos deste local de chamada.
• Aplicação de effort max especificamente para o tipo de tarefa de maior risco, análise de causa raiz de incidentes.

Mergulho Profundo

Como Funciona

• output_config={"effort": "<level>"} define um teto para quanta computação de raciocínio o Claude aplica antes de responder.
• Os níveis são ordenados low, medium, high, max, do mais rápido e barato ao mais completo e caro.
• O effort se aplica independentemente de o bloco thinking ser visível; ele governa o orçamento de raciocínio subjacente, não apenas sua exibição.
• Aumentar o effort geralmente aumenta tanto o número de tokens de saída (quando o thinking é visível) quanto a latência, pois o Claude faz mais trabalho interno por requisição.
• O effort se compõe com thinking: o thinking adaptativo decide se o raciocínio acontece ou não para um determinado prompt; o effort limita o quão profundo ele vai quando acontece.

Níveis de Effort em Resumo

Notas de Python

# Padrão: falhar ruidosamente em um valor de effort inválido em vez de usar o padrão silenciosamente.
VALID_EFFORTS = {"low", "medium", "high", "max"}
 
 
def build_output_config(effort: str) -> dict:
    if effort not in VALID_EFFORTS:
        raise ValueError(f"Nível de effort desconhecido: {effort!r}")
    return {"effort": effort}

Validar a string de effort antes que ela chegue à chamada da API captura erros de digitação ("med" em vez de "medium") no local da chamada em vez de como um erro de requisição opaco.

Armadilhas

• Definir effort max em todos os lugares "para garantir." Isso infla o custo e a latência em toda a sua aplicação; a maioria das requisições não precisa disso. Correção: mapeie o effort para o tipo de tarefa deliberadamente, reserve max para chamadas genuinamente de alto risco.
• Assumir que effort controla se um bloco de thinking aparece. O effort controla a profundidade e o custo, não a visibilidade; essa é a função da configuração thinking. Correção: defina explicitamente thinking e output_config.effort quando precisar de auto-calibração e um teto de custo.
• Não medir o impacto da latência antes de enviar um nível de effort mais alto. high e max podem desacelerar significativamente um endpoint voltado para o usuário. Correção: compare a latência p50 e p95 em cada nível de effort candidato com seu tráfego real antes de escolher um.
• Codificar um único nível de effort para uma carga de trabalho mista. Um único endpoint que atende tanto a requisições triviais quanto complexas desperdiça orçamento nas fáceis ou atende inadequadamente às difíceis. Correção: roteie o effort por requisição usando um classificador upstream barato ou uma dica explícita fornecida pelo chamador.
• Comparar níveis de effort em poucos prompts de teste. O impacto da qualidade do effort é mais visível em tarefas genuinamente difíceis; testar apenas em prompts fáceis esconde a diferença. Correção: crie um conjunto de avaliação que inclua seus casos mais difíceis do mundo real antes de decidir sobre um padrão.
• Passar uma string de effort inválida e descobri-la apenas no momento da requisição. Um erro de digitação como "med" para "medium" aparece como um erro de API no meio de um caminho de requisição. Correção: valide contra o conjunto conhecido de níveis antes de construir a requisição.

Alternativas

FAQs

effort = EFFORT_BY_TASK_TYPE.get(task_type, "medium")
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    output_config={"effort": effort},
    messages=[{"role": "user", "content": prompt}],
)

Relacionados

• Extended Thinking e o Parâmetro Effort Explicados - a relação conceitual entre thinking e effort.
• Habilitando Thinking Adaptativo com thinking: {type: 'adaptive'} - a configuração complementar com a qual o effort se emparelha.
• Níveis de Effort e Opções de Exibição de Thinking - Referência - uma tabela de referência completa para cada nível.
• Fundamentos de Extended Thinking, Effort & Multimodal - exemplos mínimos cobrindo effort junto com thinking e imagens.
• Melhores Práticas de Extended Thinking, Effort & Multimodal - práticas numeradas para ajustar o effort em produção.

Versões da Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.