Como usar o parâmetro effort na API do Claude Haiku 5.5 em Python

O parâmetro effort da API do Claude controla quantos tokens o modelo gasta ao responder. No novo Claude Haiku 5.5, lançado em 7 de outubro de 2026, ele é a principal forma de equilibrar qualidade, velocidade e custo. Este tutorial mostra como chamar o modelo em Python e trocar o nível de esforço, com base na documentação oficial da Anthropic.

Pré-requisitos

• Python 3 instalado.
• Uma chave de API da Anthropic, guardada na variável de ambiente ANTHROPIC_API_KEY. Nunca escreva a chave dentro do código.
• A biblioteca oficial anthropic.

Instale a biblioteca:

pip install anthropic

O que é o effort

Segundo a documentação, o effort é um sinal de comportamento, e não um limite rígido de tokens. Ele afeta todos os tokens da resposta: o texto, as chamadas de ferramentas e o raciocínio, quando ativo. Os níveis são:

Nível	Quando usar, segundo a documentação
low	Mais eficiente. Tarefas simples, em que velocidade e custo são prioridade
medium	Equilíbrio entre velocidade, custo e desempenho. É o padrão do Haiku 5.5
high	Raciocínio complexo, problemas difíceis de código e tarefas de agentes
xhigh	Trabalho longo de agentes e código
max	Capacidade máxima, sem restrição de gasto

No Haiku 5.5, o padrão é medium, e enviar "medium" equivale a omitir o parâmetro. A Anthropic recomenda começar por medium, usar low para chat, tarefas curtas com ferramentas e alto volume, e high para trabalho de conhecimento, agentes mais longos e instruções estritas. Sobre xhigh e max, a orientação é só usar quando seus testes mostrarem ganho de qualidade.

Passo 1: fazer uma chamada com effort

O effort fica em output_config. Este código roda uma requisição em low com o Haiku 5.5. O formato da chamada segue o exemplo da documentação, trocando apenas o modelo e o nível:

import anthropic

client = anthropic.Anthropic()  # lê ANTHROPIC_API_KEY do ambiente

response = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Explique em três frases a diferença entre lista e tupla em Python.",
        }
    ],
    output_config={"effort": "low"},
)

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

O laço no final percorre os blocos da resposta e imprime só os de texto, porque a resposta pode trazer outros tipos de bloco.

Passo 2: comparar níveis

Para ver o efeito na prática, rode a mesma pergunta em dois níveis e compare o uso de tokens, que vem no campo usage da resposta:

import anthropic

client = anthropic.Anthropic()
pergunta = "Revise esta função e aponte problemas: def soma(a, b): return a - b"

for nivel in ["low", "high"]:
    r = client.messages.create(
        model="claude-haiku-5-5",
        max_tokens=4096,
        messages=[{"role": "user", "content": pergunta}],
        output_config={"effort": nivel},
    )
    texto = next(b.text for b in r.content if b.type == "text")
    print(f"--- effort={nivel} | saída: {r.usage.output_tokens} tokens ---")
    print(texto)

Os números vão variar a cada execução e a cada pergunta. O que a documentação afirma é que níveis mais baixos economizam tokens, com alguma redução de capacidade, e níveis mais altos pensam mais. Use suas próprias perguntas e meça: a Anthropic recomenda avaliar o efeito do effort nos seus casos de uso antes de colocar em produção.

Passo 3: reservar espaço para o raciocínio

No Haiku 5.5, o raciocínio vem ativado por padrão e conta dentro de max_tokens. Se o teto for muito baixo, o modelo pode gastar o limite pensando e entregar uma resposta incompleta. Por isso o exemplo usa 4096. Em níveis altos, a documentação orienta definir um max_tokens grande.

Se quiser menos raciocínio, a documentação dá duas opções: baixar o nível de effort ou enviar thinking: {"type": "disabled"} em high ou abaixo. Em xhigh e max, desativar o raciocínio causa erro 400; nesses níveis, omita o campo thinking ou use {"type": "adaptive"}.

Passo 4: trocar o effort no meio da conversa (beta)

Alterar o effort de topo entre requisições invalida o cache de prompt. Para conversas longas que dependem de cache, a documentação descreve um recurso em beta, o effort por mensagem, que exige o cabeçalho beta mid-conversation-output-config-2026-07-01. Segundo a página, o Haiku 5.5 o suporta na API da Anthropic e no Google Cloud. Como está em beta, leia a seção "Change effort mid-conversation" da documentação antes de adotá-lo.

Resultado esperado

Ao rodar o primeiro script com a chave configurada, o terminal imprime uma resposta curta de três frases. O segundo script imprime duas respostas, cada uma precedida pelo nível e pelo total de tokens de saída.

Erros comuns

• Resposta cortada ou vazia: o max_tokens foi gasto no raciocínio. Aumente o valor.
• Erro 400 ao desativar o thinking: isso ocorre em xhigh e max. Use adaptive ou omita o campo.
• Chave de API ausente: se o SDK reclamar de autenticação, confira se ANTHROPIC_API_KEY está definida no terminal em que você roda o script.
• Usar "adaptive" como effort: adaptive é um modo de thinking, não um nível de effort. Os valores válidos são low, medium, high, xhigh e max.
• Mudar o effort sem perceber o cache: em conversas com cache de prompt, fixe um nível no início.

Quanto custa

O preço do Haiku 5.5, segundo a Anthropic, é de US$ 0,10 por milhão de tokens de entrada e US$ 0,50 por milhão de saída em prompts de até 100 mil tokens. O novo tokenizador usa um pouco mais de tokens por tarefa, então compare o consumo real antes de migrar de modelo.