🪜 Os 5 níveis de esforço
🧠 Imagine assim: effort não é um botão de "burro/esperto" — é um controle de o quanto o modelo dedica de raciocínio a um problema antes de responder. Cinco degraus, do mais rápido ao sem-limite.
O Claude Fable 5 expõe cinco níveis de esforço configuráveis por chamada: low, medium, high, xhigh e max. Cada nível é um sinal de comportamento — não uma trava dura de tokens — que diz ao modelo o quanto vale a pena deliberar antes de agir ou responder.
Isso é diferente de simplesmente truncar a resposta: em low, o Fable 5 ainda pensa o suficiente pra problemas genuinamente difíceis — só pensa menos do que pensaria no mesmo problema em high ou xhigh. O nível certo depende do tipo de tarefa, não de "quanto você confia no modelo".
| Nível | Descrição oficial | Caso de uso típico |
|---|---|---|
| low | Mais eficiente, economia significativa | Tarefas simples que precisam de velocidade/custo mínimo, ex. subagents |
| medium | Equilíbrio, economia moderada | Tarefas agênticas que precisam de balanço velocidade/custo/performance |
| high (default) | Alta capacidade — equivale a não setar o parâmetro | Raciocínio complexo, coding difícil, tarefas agênticas |
| xhigh | Capacidade estendida pra trabalho de longo horizonte | Tarefas agênticas/coding longas (>30min), budgets na casa dos milhões de tokens |
| max | Capacidade máxima absoluta, sem restrição de gasto de tokens | Raciocínio mais profundo, análise mais completa |
Fonte: doc oficial effort — platform.claude.com/docs/en/build-with-claude/effort
A escada dos 5 níveis: cada degrau sobe em capacidade permitida (linha ciano tracejada) — high é o degrau em destaque porque é o que você recebe sem setar nada.
Em 1 frase: 5 níveis (low→max), configuráveis por chamada, onde high é o que você já tem hoje se não mexer em nada.
🔌 Como configurar via API
O nível de esforço entra no corpo da chamada via output_config, um objeto que aceita um único campo effort com uma das cinco strings. Omitir o campo inteiro equivale a usar "high" — é literalmente o default.
Isso significa que trocar de nível não exige mudar de modelo, endpoint ou SDK: é um parâmetro a mais na mesma chamada que você já faz hoje. Dá pra variar o nível por tipo de chamada dentro do mesmo agente — por exemplo, orquestrador em high e subagents em low.
medium antes de assumir que precisa de high.{
"model": "claude-fable-5",
"max_tokens": 4096,
"output_config": { "effort": "medium" },
"messages": [
{ "role": "user", "content": "<isto você troca — descreva a tarefa>" }
]
}
usage (tokens de saída) e o tempo de resposta contra a mesma tarefa com "effort": "high". Em medium, espere menos tokens de raciocínio e resposta mais rápida — se a qualidade cair pra sua tarefa, suba um nível.💡 Dica prática
O mesmo campo output_config funciona igual na Claude API, na Claude Platform on AWS (Bedrock) e no Vertex AI — não há um parâmetro diferente por provedor de nuvem. Isso facilita testar níveis diferentes sem reescrever a camada de integração.
Em 1 frase: output_config: {"effort": "..."} no corpo da chamada — sem parâmetro, você já está em high.
🎯 Recomendação oficial pro Fable 5
🧭 A régua prática
Pro Fable 5, a régua recomendada não é "sempre o máximo pra garantir qualidade" — é calibrar por tipo de tarefa:
- •high como default — cobre a maioria do trabalho agêntico e de coding difícil, e é o que você já recebe sem tocar em nada.
- •xhigh pra trabalho capability-sensitive — sessões longas (>30min), orçamento de milhões de tokens, onde o teto de raciocínio importa mais que a velocidade.
- •medium/low pra rotina — subagents, tarefas simples e repetitivas, onde velocidade e custo pesam mais que profundidade de raciocínio.
A própria documentação da Anthropic é explícita sobre o que o parâmetro não é: um cortador de orçamento fixo. É um sinal de comportamento que o modelo interpreta caso a caso.
Effort is a behavioral signal, not a strict token budget. At lower effort levels, Claude will still think on sufficiently difficult problems, but it will think less than it would at higher effort levels for the same problem.
Esforço é um sinal comportamental, não um orçamento rígido de tokens. Em níveis de esforço mais baixos, o Claude ainda vai pensar em problemas suficientemente difíceis, mas vai pensar menos do que pensaria em níveis mais altos para o mesmo problema.
Fonte: platform.claude.com/docs/en/build-with-claude/effort
Ressalva importante: esforço baixo no Fable 5 não é um "downgrade burro". É um modelo de ponta operando com menos deliberação — na prática, ainda entrega resultado sólido pra tarefas dentro da sua complexidade real. Quem vem do Opus 4.8 tende a superestimar o nível necessário por hábito.
✓ O que FAZER
- ✓Deixar
highcomo default pra coding difícil e tarefas agênticas normais. - ✓Subir pra
xhighsó quando a tarefa é de longo horizonte (>30min, milhões de tokens de budget). - ✓Descer pra
medium/lowem subagents, rotina e tarefas simples que só precisam de velocidade.
✗ O que EVITAR
- ✗Presumir que
effortbaixo dá resposta "capenga" — o Fable 5 ainda performa bem emlow. - ✗Deixar tudo em
max"pra garantir", sem medir se o ganho compensa o custo. - ✗Nunca comparar o mesmo prompt em 2 níveis diferentes antes de fixar o padrão do seu app.
Em 1 frase: high por padrão, xhigh pra trabalho sensível a capacidade, medium/low pra rotina — e esforço baixo não é sinônimo de fraco.
🛡️ O mecanismo de refusal
⚠️ Atenção — isso não é um erro
Quando o Fable 5 recusa um pedido por segurança, a resposta HTTP é 200 — sucesso — com stop_reason: "refusal" no corpo. Não é uma exceção, não é um 4xx/5xx, e seu tratamento de erro genérico não vai pegar isso sozinho. Você precisa checar stop_reason explicitamente.
Quando isso acontece, stop_details.category vem preenchido com uma de quatro categorias possíveis. Nenhuma delas significa "seu pedido era malicioso" — os textos oficiais deixam explícito que trabalho benigno também pode disparar a categoria.
| category | O que significa (texto oficial) |
|---|---|
| cyber | "The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category." O pedido poderia habilitar dano cibernético (malware/exploit); trabalho legítimo de cibersegurança também pode disparar. |
| bio | "The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category." O pedido poderia habilitar dano biológico; trabalho benéfico de ciências da vida também pode disparar. |
| frontier_llm | "The request could assist the development of competing AI models, which is restricted under Anthropic's commercial terms. Benign machine learning work can also trigger this category." O pedido poderia ajudar a desenvolver modelos de IA concorrentes (restrito pelos termos comerciais); trabalho benigno de ML também pode disparar. |
| reasoning_extraction | "The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use adaptive thinking." O pedido pede pro modelo reproduzir o raciocínio interno como texto; use adaptive thinking pra obter isso de forma estruturada. |
Fonte: doc oficial refusals-and-fallback — platform.claude.com/docs/en/build-with-claude/refusals-and-fallback
A categoria reasoning_extraction merece atenção especial porque é a mais fácil de disparar sem querer: basta uma skill ou system prompt antigo pedindo pro modelo "mostrar o raciocínio" na resposta. A própria Anthropic recomenda auditar instruções desse tipo ao migrar pro Fable 5.
Don't instruct Claude to reproduce its reasoning in the response. Prompts, skills, or harness instructions that tell the model to echo, transcribe, or explain its internal reasoning as response text can trigger the reasoning_extraction refusal category on Claude Fable 5, causing elevated fallbacks to Claude Opus 4.8. Audit existing skills and system prompts for reflection or show-your-thinking instructions when migrating. If your application needs reasoning visibility, read the structured thinking blocks from adaptive thinking instead.
Não instrua o Claude a reproduzir seu raciocínio na resposta. Prompts, skills ou instruções de harness que pedem pro modelo ecoar, transcrever ou explicar seu raciocínio interno como texto de resposta podem disparar a categoria de recusa reasoning_extraction no Claude Fable 5, causando mais fallbacks pro Claude Opus 4.8. Audite skills e system prompts existentes em busca de instruções de reflexão ou de "mostre seu raciocínio" ao migrar. Se sua aplicação precisa de visibilidade do raciocínio, leia os blocos de thinking estruturado do adaptive thinking em vez disso.
Como verificar: cole o aviso (EN ou PT-BR, tanto faz — é lido por você, não pelo modelo) como lembrete no seu processo de migração, audite as skills/system prompts do seu projeto atrás de instruções tipo "explique seu raciocínio" ou "mostre como chegou nessa resposta", e remova-as. O sinal de sucesso: menos recusas reasoning_extraction nos logs.
Em 1 frase: recusa por segurança é HTTP 200 com stop_reason: "refusal" + 1 de 4 categorias — nunca uma exceção de rede.
🧾 Billing de uma recusa + como configurar fallback
📐 Regra de billing
- Recusa antes de qualquer output — não é cobrada. O campo
usageaparece na resposta, mas não gera cobrança nem consome rate limit. - Recusa no meio do stream — cobra o input e o output já emitido até o ponto da recusa (você paga pelo que já foi gerado, não pelo pedido inteiro).
Pra não deixar o usuário final esbarrando numa recusa, a Anthropic oferece três caminhos pra rotear automaticamente pro Claude Opus 4.8 quando o Fable 5 recusa — cada um com um nível diferente de esforço de implementação.
Fallback no servidor (server-side)
Claude API / Claude Platform on AWS, via beta header
Resolvido numa única request — você manda a chamada normal com o header beta ligado, e se o Fable 5 recusar, a própria plataforma reemite pro Opus 4.8 antes de te devolver a resposta. Zero lógica extra no seu código.
Middleware do SDK
BetaRefusalFallbackMiddleware — TS/Python/Go/Java/C#
Um middleware oficial do SDK intercepta o stop_reason: "refusal" no seu próprio processo e refaz a chamada pro Opus 4.8 automaticamente — útil quando você já orquestra as chamadas no seu backend e quer manter o controle nele.
Retry manual com fallback credit
Ruby/PHP/HTTP cru — linguagens sem middleware oficial
Você mesmo checa stop_reason na resposta e, se for "refusal", dispara uma nova chamada pro Opus 4.8 usando o fallback credit — a forma mais manual, mas a única disponível fora do ecossistema de SDKs oficiais.
O ciano marca o desvio: pedido → classificador (foco em glow) → se recusado, a categoria vira ponte pro Opus 4.8; se aprovado, segue no fluxo normal do Fable 5.
Look at how we call the Claude API in this codebase (SDK, language, whether we stream responses) and tell me which of the three Fable 5 refusal-fallback options fits best: (1) server-side fallback via the beta header, (2) SDK middleware (BetaRefusalFallbackMiddleware), or (3) manual retry with a fallback credit. Point to the exact file/line where I'd wire it in, and flag if we're on a language (Ruby/PHP/raw HTTP) that only supports the manual-retry path.
Olhe como chamamos a API da Claude neste código (SDK, linguagem, se as respostas são via streaming) e me diga qual das três opções de fallback de recusa do Fable 5 se encaixa melhor: (1) fallback no servidor via beta header, (2) middleware do SDK (BetaRefusalFallbackMiddleware), ou (3) retry manual com fallback credit. Aponte o arquivo/linha exatos onde eu conectaria isso, e avise se estamos numa linguagem (Ruby/PHP/HTTP cru) que só suporta o caminho de retry manual.
Em 1 frase: recusa antes do output não é cobrada; pra fallback automático, escolha entre server-side, middleware do SDK ou retry manual conforme sua stack.
📊 Comparação de custo
O Fable 5 custa exatamente o dobro do Opus 4.8 por token, tanto de entrada quanto de saída. À primeira vista, parece sempre mais caro. Só que preço por token e custo total da tarefa são coisas diferentes — e é aí que mora o insight prático deste tópico.
| Modelo | Input | Cache write 5m | Cache write 1h | Cache hit | Output |
|---|---|---|---|---|---|
| Fable 5 / Mythos 5 | $10/MTok | $12.50/MTok | $20/MTok | $1/MTok | $50/MTok |
| Opus 4.8 | $5/MTok | — | — | — | $25/MTok |
| Sonnet 5 (até 31/ago/2026) | $1/MTok | — | — | — | $5/MTok |
| Haiku 4.5 | $0.50/MTok | — | — | — | $2.50/MTok |
Fonte: platform.claude.com/docs/en/about-claude/pricing · MTok = milhão de tokens. Batch API (50% off) deixa o Fable 5 em $5/$25 por MTok — mesmo preço nominal do Opus 4.8 síncrono.
🧮 Exemplo ilustrativo (números de tokens hipotéticos — não é benchmark oficial)
Tarefa hipotética de coding: 300k tokens de entrada + 40k de saída pra terminar.
- Fable 5 @ low, acerta de primeira (1 rodada): 0.3 × $10 + 0.04 × $50 = $3 + $2 = $5
- Opus 4.8 @ xhigh, precisa de 3 rodadas pra chegar no mesmo resultado (relendo contexto a cada iteração — 900k entrada + 120k saída acumulados): 0.9 × $5 + 0.12 × $25 = $4.5 + $3 = $7.5
Mesmo custando o dobro por token, o Fable 5 sai mais barato no total nesse cenário — porque "acerto de primeira em sistemas complexos" (capacidade que a própria Anthropic destaca do Fable 5 vs. Opus 4.8) elimina rodadas inteiras de iteração, não só reduz o preço da rodada.
✓ O que FAZER
- ✓Medir o custo total da tarefa (entrada + saída até o resultado final), não só o $/MTok.
- ✓Usar Batch API (50% off) pra jobs assíncronos que não precisam de resposta imediata.
- ✓Aproveitar cache (5min = 1.25x, 1h = 2x, hit = 0.1x) quando o mesmo contexto grande se repete entre chamadas.
✗ O que EVITAR
- ✗Concluir que o Opus 4.8 é sempre mais barato só porque custa metade por token.
- ✗Ignorar quantas rodadas/iterações a tarefa precisa pra realmente terminar.
- ✗Esquecer o multiplicador
inference_geo:"us"(1.1x) ao orçar por região.
💡 Contexto extra: o Fable 5 tem janela de 1M tokens por padrão e até 128k tokens de output por request, sem prêmio de preço por contexto longo — outra variável que entra na conta de "custo total" e não aparece só olhando o $/MTok da tabela.
Em 1 frase: Fable 5 em esforço baixo pode custar menos no total que Opus 4.8 em xhigh/max — mesmo custando o dobro por token — porque erra menos vezes.
🧾 Resumo do Módulo
high é o default, configurável via output_config.effort.high pra maioria, xhigh só em tarefas longas, medium/low pra rotina — e esforço baixo ainda performa bem.stop_reason, não erro — HTTP 200, 4 categorias (cyber/bio/frontier_llm/reasoning_extraction), recusa antes do output não é cobrada.Próximo módulo:
1.7 — Bônus: subagents, memória e send_to_user.
Fontes deste módulo: platform.claude.com/docs/en/build-with-claude/effort · platform.claude.com/docs/en/build-with-claude/refusals-and-fallback · platform.claude.com/docs/en/about-claude/pricing · platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5