Esforço

O parâmetro "effort" (esforço) permite que você controle quantos tokens Claude gasta ao responder a solicitações. Você pode equilibrar entre a profundidade da resposta e a eficiência de tokens com um único modelo. O parâmetro effort de nível superior está disponível em todos os modelos compatíveis, sem necessidade de cabeçalho beta. O esforço por mensagem está em beta.

Definir o nível de esforço

Defina output_config.effort na solicitação. O exemplo a seguir executa uma solicitação com esforço medium e imprime o texto da resposta.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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)

Como o esforço funciona

A maioria dos modelos Claude usa esforço alto por padrão, gastando quantos tokens forem necessários para obter resultados excelentes; o Claude Opus 5.5 usa esforço médio por padrão. Você pode elevar o nível de esforço para max para obter a capacidade mais alta absoluta, ou reduzi-lo para ser mais conservador no uso de tokens, otimizando velocidade e custo ao aceitar alguma redução na capacidade.

O parâmetro effort afeta todos os tokens na resposta, incluindo:

• Respostas de texto e explicações
• Chamadas de ferramentas e argumentos de funções
• Pensamento (quando ativo)

Como o esforço se aplica a cada token de saída, ele funciona independentemente de o pensamento estar habilitado ou não. Esforço mais baixo também significa menos chamadas de ferramentas e chamadas mais concisas.

Níveis de esforço

Nem todo modelo que suporta max suporta xhigh.

As recomendações por modelo a seguir substituem esta tabela onde houver divergência.

Níveis de esforço recomendados para o Claude Fable 5.1

O Claude Fable 5.1 suporta todos os cinco níveis de esforço. Comece com high, o padrão. Suba para xhigh ou max para os trabalhos agênticos e de codificação mais sensíveis à capacidade, e desça para medium ou low para trabalhos rotineiros ou sensíveis à latência, uma vez que suas avaliações mostrem que a qualidade se mantém. Em high e acima, defina um max_tokens grande. É um limite rígido na saída total (pensamento mais texto da resposta). As mesmas recomendações se aplicam ao Claude Mythos 5.1. Consulte Prompting do Claude Fable 5.1.

O Claude Fable 5.1 também suporta alterar o esforço no meio da conversa com um output_config por mensagem, o que preserva o cache de prompt.

Níveis de esforço recomendados para o Claude Fable 5

O esforço é o controle principal para equilibrar inteligência, latência e custo no Claude Fable 5. Comece com high, o padrão, para a maioria das tarefas, use xhigh para as cargas de trabalho mais sensíveis à capacidade e desça para medium ou low para trabalhos rotineiros. Configurações de esforço mais baixas no Claude Fable 5 ainda têm bom desempenho e frequentemente superam o desempenho de xhigh em modelos anteriores. Em high e xhigh, defina um max_tokens grande. É um limite rígido na saída total (pensamento mais texto da resposta). Consulte Controle de custos.

Reduza o esforço se uma tarefa for concluída, mas demorar mais do que o necessário, ou se você quiser um estilo de trabalho mais rápido e interativo. As mesmas recomendações se aplicam ao Claude Mythos 5. Para orientações mais completas, consulte Prompting do Claude Fable 5.

Níveis de esforço recomendados para o Claude Opus 5.5

O Claude Opus 5.5 suporta todos os cinco níveis de esforço, e medium é o padrão (o Claude Opus 5 e os modelos Opus anteriores usam high por padrão, então uma solicitação que omite effort é executada um nível abaixo do que era no Claude Opus 5). O pensamento adaptativo está sempre ativo e não pode ser desativado, então o esforço é o principal controle de quanto o modelo raciocina e de quanto uma solicitação custa. Execute uma varredura de esforço nas suas próprias avaliações em vez de reaproveitar configurações de um modelo anterior, e defina um max_tokens grande nos níveis mais altos: ele é um limite rígido para a saída total (pensamento mais texto da resposta). Solicitações que definem thinking: {"type": "disabled"} retornam um erro 400 em todos os níveis de esforço. O Claude Opus 5.5 também suporta alterar o esforço no meio da conversa com um output_config por mensagem, o que preserva o cache de prompt. Consulte Prompting do Claude Opus 5.5.

Níveis de esforço recomendados para o Claude Opus 5

O Claude Opus 5 suporta todos os cinco níveis de esforço. Comece com high, o padrão, e ajuste com base em suas avaliações: suba para xhigh para trabalhos exigentes de codificação e agênticos, ou para max quando uma tarefa justificar gasto irrestrito de tokens, e use low e medium livremente como seu controle principal de custo de tokens e tempo de resposta sempre que suas avaliações mostrarem que a qualidade se mantém. Se você trouxe configurações de esforço de um modelo anterior, execute uma nova varredura de esforço em suas avaliações em vez de reutilizá-las.

O esforço controla o volume de pensamento, não o comprimento visível da resposta: no Claude Opus 5, alterar o esforço não encurta as respostas de forma confiável, então use prompts para controlar o comprimento em vez disso.

O padrão da API é high. Defina effort explicitamente para usar um nível diferente. O valor que você passa substitui o padrão.

No Claude Opus 5, o pensamento não pode ser desabilitado com esforço xhigh ou max: solicitações que definem thinking: {"type": "disabled"} nesses níveis retornam um erro 400. Consulte Esforço com pensamento.

Ao executar o Claude Opus 5 com esforço xhigh ou max, defina um max_tokens grande para que o modelo tenha espaço para pensar e agir entre subagentes e chamadas de ferramentas. Começar com 64k tokens e ajustar a partir daí é um padrão razoável.

O Claude Opus 5 também suporta alterar o esforço no meio da conversa com um output_config por mensagem, o que preserva o cache de prompt.

Níveis de esforço recomendados para o Claude Opus 4.8

As orientações para o Claude Opus 4.7 também se aplicam ao Claude Opus 4.8. Comece com xhigh para casos de uso de codificação e agênticos, use high para a maioria das outras cargas de trabalho sensíveis à inteligência e desça para medium ou low apenas quando você tiver medido que o nível mais baixo mantém a qualidade em suas avaliações.

O padrão da API é high. Defina effort explicitamente para usar um nível diferente. O valor que você passa substitui o padrão.

Ao executar o Claude Opus 4.8 com esforço xhigh ou max, defina um max_tokens grande para que o modelo tenha espaço para pensar e agir entre subagentes e chamadas de ferramentas. Começar com 64k tokens e ajustar a partir daí é um padrão razoável.

Níveis de esforço recomendados para o Claude Opus 4.7

Comece com xhigh para casos de uso de codificação e agênticos, e use high como o mínimo para a maioria das cargas de trabalho sensíveis à inteligência. Desça para medium para cargas de trabalho sensíveis a custo, ou suba para max apenas quando suas avaliações mostrarem margem mensurável em xhigh.

O padrão da API é high. Para usar xhigh, defina effort explicitamente. O valor que você passa substitui o padrão.

O Claude Opus 4.7 também respeita os níveis de esforço de forma mais estrita do que o Claude Opus 4.6, especialmente em low e medium. Em níveis de esforço mais baixos, o modelo delimita seu trabalho ao que foi pedido em vez de fazer mais do que o solicitado. Se você observar raciocínio superficial em problemas complexos com o Claude Opus 4.7, aumente o esforço em vez de contornar isso com prompts. Se você precisar manter o esforço baixo por causa da latência, adicione orientações direcionadas como "Esta tarefa envolve raciocínio em várias etapas. Pense cuidadosamente antes de responder."

Ao executar o Claude Opus 4.7 com esforço xhigh ou max, defina um max_tokens grande para que o modelo tenha espaço para pensar e agir entre subagentes e chamadas de ferramentas. Começar com 64k tokens e ajustar a partir daí é um padrão razoável.

Níveis de esforço recomendados para o Claude Sonnet 5.5

O Claude Sonnet 5.5 suporta todos os cinco níveis de esforço, e high é o padrão na Claude API. Seus níveis foram recalibrados, então um nível não produz a mesma quantidade de pensamento que o mesmo nível no Claude Sonnet 5. Execute uma nova varredura de esforço nas suas avaliações em vez de reaproveitar a configuração que você usava no Claude Sonnet 5. Comece com high, a menos que sua carga de trabalho seja agêntica ou sensível à latência. Para programação agêntica e uso de ferramentas em várias etapas, comece com medium para tarefas bem especificadas e passe para high para as mais difíceis ou mais longas. Para chat e outros trabalhos sensíveis à latência, comece com medium ou low. Use xhigh ou max somente onde suas avaliações mostrarem ganho de qualidade. Defina max_tokens com espaço para o pensamento e a resposta. O pensamento conta para max_tokens mesmo quando o conteúdo do pensamento não é retornado. Para programação agêntica, defina max_tokens como 128.000, o máximo do modelo, e faça streaming da resposta.

Para desativar o pensamento antecipado, envie thinking: {"type": "between_tools"} em vez de "disabled". Essa é a configuração de pensamento mais baixa no Claude Sonnet 5.5, e funciona com esforço low, medium e high. Em xhigh ou max, uma solicitação com ela retorna um erro 400, então use o pensamento adaptativo nesses níveis: omita o campo thinking ou envie thinking: {"type": "adaptive"}. Consulte Executar sem pensamento antecipado.

O Claude Sonnet 5.5 também suporta alterar o esforço no meio da conversa com um output_config por mensagem, o que preserva o cache de prompt. Com between_tools, o esforço não pode mudar no meio da conversa: um output_config.effort por mensagem que difira do nível em vigor retorna um erro 400. Para variar o esforço por turno, use o pensamento adaptativo. Consulte Prompting para o Claude Sonnet 5.5.

Níveis de esforço recomendados para o Claude Sonnet 5

O Claude Sonnet 5 usa esforço high por padrão na API do Claude e no Claude Code.

• Esforço high (padrão): Adequado para raciocínio complexo, codificação e tarefas agênticas em que a qualidade importa mais do que velocidade ou custo.
• Esforço xhigh: Para as tarefas de codificação e agênticas mais difíceis. Consulte Prompting do Claude Sonnet 5.
• Esforço medium: Redução de custo em relação ao padrão. Comparável ao Claude Sonnet 4.6 com esforço high.
• Esforço low: Para cargas de trabalho de alto volume ou sensíveis à latência. Adequado para chat e casos de uso que não envolvem codificação, em que um retorno mais rápido é priorizado.
• Esforço max: Para tarefas que exigem a capacidade absolutamente mais alta sem restrições no gasto de tokens.

Níveis de esforço recomendados para o Claude Sonnet 4.6

O Sonnet 4.6 usa esforço high por padrão. Defina o esforço explicitamente ao usar o Sonnet 4.6 para evitar latência inesperada:

• Esforço medium (padrão recomendado): Melhor equilíbrio entre velocidade, custo e desempenho para a maioria das aplicações. Adequado para codificação agêntica, fluxos de trabalho com uso intenso de ferramentas e geração de código.
• Esforço low: Para cargas de trabalho de alto volume ou sensíveis à latência. Adequado para chat e casos de uso que não envolvem codificação, em que um retorno mais rápido é priorizado.
• Esforço high: Para raciocínio complexo e tarefas em que a qualidade importa mais do que velocidade ou custo.
• Esforço max: Para tarefas que exigem a capacidade absolutamente mais alta sem restrições no gasto de tokens.

Esforço com uso de ferramentas

Ao usar ferramentas, o parâmetro effort afeta tanto as explicações em torno das chamadas de ferramentas quanto as próprias chamadas de ferramentas. Níveis de esforço mais baixos tendem a:

• Combinar várias operações em menos chamadas de ferramentas
• Fazer menos chamadas de ferramentas
• Prosseguir diretamente para a ação sem preâmbulo
• Usar mensagens de confirmação concisas após a conclusão

Níveis de esforço mais altos podem:

• Fazer mais chamadas de ferramentas
• Explicar o plano antes de agir
• Fornecer resumos detalhados das alterações
• Incluir comentários de código mais abrangentes

Esforço com pensamento

O parâmetro thinking controla se o Claude pensa em blocos de pensamento antes de responder; o parâmetro effort controla quanto trabalho o Claude dedica à resposta inteira, o que, no modo adaptativo, inclui com que frequência e com que profundidade ele pensa. Não passe adaptive como um valor de effort: adaptive é um modo de pensamento, não um nível de esforço.

Em níveis de esforço mais altos, Claude pensa com mais facilidade e por mais tempo. Em um loop de uso de ferramentas, solicitações de acompanhamento que apenas processam resultados de ferramentas ainda podem pular o pensamento em qualquer nível. Em níveis mais baixos, Claude pode pular o pensamento completamente em problemas mais simples. Consulte Pensamento e esforço para orientações completas sobre como os dois controles funcionam juntos.

No Claude Opus 4.5, o único modelo exclusivamente de "extended thinking" (pensamento estendido) que suporta esforço, ele funciona em conjunto com budget_tokens: defina o nível de esforço para sua tarefa e, em seguida, defina o orçamento de tokens de pensamento com base em quanta profundidade de raciocínio a tarefa precisa.

Para a disponibilidade de pensamento por modelo, consulte a tabela de configuração por modelo. O esforço funciona com ou sem pensamento. Consulte Como o esforço funciona.

Alterar o esforço no meio da conversa

Você pode executar turnos posteriores de uma conversa com um nível de esforço diferente de duas maneiras. No Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5 e Claude Sonnet 5.5, use uma alteração de esforço por mensagem, que mantém o cache de prompt. Em outros modelos, defina um novo valor de nível superior na próxima solicitação, o que reinicia o cache.

Esforço por mensagem (beta)

O esforço por mensagem está em beta e requer o cabeçalho beta mid-conversation-output-config-2026-07-01. Modelos sem esforço por mensagem, incluindo o Claude Fable 5, retornam um erro 400: output_config.effort requires a model that supports per-turn effort; this model does not. No Claude Sonnet 5.5 com thinking: {"type": "between_tools"}, o esforço não pode mudar no meio da conversa: um output_config.effort por mensagem que difira do nível em vigor retorna um erro 400. Para variar o esforço por turno, use o pensamento adaptativo.

Adicione uma mensagem role: "system" com content vazio e o novo nível em output_config.effort. O novo nível entra em vigor a partir do próximo turno user e se mantém até que uma mensagem posterior o altere. Tudo antes dessa mensagem permanece inalterado, então o prefixo em cache ainda corresponde.

O exemplo a seguir começa em high e depois desce para low para um acompanhamento rotineiro:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=4096,
    output_config={"effort": "high"},
    messages=[
        {
            "role": "user",
            "content": "Plan a migration from SQLite to PostgreSQL in three short steps.",
        },
        {
            "role": "assistant",
            "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.",
        },
        # Mensagem do sistema só de esforço: o novo nível vale a partir do próximo turno do usuário.
        {"role": "system", "content": [], "output_config": {"effort": "low"}},
        {"role": "user", "content": "Summarize the plan in one sentence."},
    ],
    betas=["mid-conversation-output-config-2026-07-01"],
)

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

Uma mensagem de sistema apenas de esforço não carrega texto, então as regras de posicionamento para mensagens de sistema no meio da conversa não se aplicam. Ela pode aparecer em qualquer lugar em messages, inclusive como a primeira entrada ou entre um turno assistant e o próximo turno user. Os valores são os nomes dos níveis (low, medium, high, xhigh e max).

No Claude Fable 5.1, prefira esta forma em vez de alterar o valor de nível superior entre solicitações. Uma alteração de nível superior reinicia o cache e também direciona o modelo de forma menos confiável: suas respostas anteriores foram escritas no nível anterior, e ele tende a permanecer consistente com elas.

Esforço de nível superior na próxima solicitação

O output_config.effort de nível superior se aplica à solicitação inteira. Para executar uma parte posterior de uma conversa em um nível diferente, defina o novo valor na próxima solicitação. Como o esforço de nível superior molda o prompt renderizado, alterá-lo entre solicitações não preserva os prefixos em cache de turnos anteriores. Se você depende de cache de prompt ao longo de uma sessão longa e seu modelo não suporta esforço por mensagem, escolha um nível de esforço no início e mantenha-o constante.

Melhores práticas

1. Defina o esforço explicitamente: A API usa high por padrão (medium no Claude Opus 5.5), mas o ponto de partida certo depende do seu modelo e da sua carga de trabalho.
2. Use low para tarefas sensíveis à velocidade ou simples: Quando a latência importa ou as tarefas são diretas, o esforço baixo pode reduzir significativamente os tempos de resposta e os custos.
3. Teste seu caso de uso: O impacto dos níveis de esforço varia conforme o tipo de tarefa. Avalie o desempenho nos seus casos de uso específicos antes de implantar.
4. Considere o esforço dinâmico: Ajuste o esforço com base na complexidade da tarefa. Consultas simples podem justificar esforço baixo, enquanto codificação agêntica e raciocínio complexo se beneficiam de esforço alto. Veja o próximo item antes de variá-lo dentro de uma mesma conversa.
5. Mantenha o esforço de nível superior constante em conversas com cache: Alterar o valor de esforço de nível superior entre solicitações invalida o cache de prompt, então varie-o entre cargas de trabalho, e não dentro de uma conversa que depende de acertos de cache. Em modelos que oferecem suporte, use uma alteração de esforço por mensagem, que preserva o cache. Consulte Pensamento e cache de prompt.

Próximos passos

Compatibility