Lucas

Posted on Sep 2 Originally published at apidog.com

Migrando para o Claude Fable 5.1 do Fable 5 ou Opus 5: Todas as Breaking Changes

Migração do Claude Fable 5 para o Fable 5.1: checklist prática

Migrar para o Claude Fable 5.1 é, em grande parte, trocar o ID do modelo. A superfície da API, os limites, o preço por token, o tokenizador, o pensamento adaptativo sempre ativo e o tratamento de recusas correspondem ao Fable 5. Porém, três mudanças introduzem erros que o Fable 5 nunca retornava. Uma delas — a verificação de edição do histórico — pode degradar silenciosamente um sistema de agentes que funcionou bem por um ano. Quem vem do Opus 5 precisa considerar mais quatro itens.

Experimente o Apidog hoje

Este guia apresenta o texto exato dos erros e a correção para cada item, na ordem em que você provavelmente os encontrará. Ele combina o guia de migração da Anthropic com as novidades do Claude Fable 5.1. Cada trecho pode ser colado no Apidog e executado contra o endpoint real antes de chegar à produção. Para uma visão geral, consulte O que é o Claude Fable 5.1.

Passo 0: confirme se você deve migrar

A documentação da Anthropic recomenda começar com o Opus 5 e usar o Fable 5.1 “para raciocínio exigente e trabalho de agente de longo prazo, ou quando suas avaliações no Claude Opus 5 com maior esforço ainda forem insuficientes”.

Se o Opus 5 já passar nas suas avaliações, migrar para o Fable 5.1 dobra o preço por token sem ganho mensurável. Se você já usa o Fable 5, o preço permanece igual, com leituras de cache mais baratas e resultados alegadamente melhores. Nesse caso, a decisão depende do esforço de adaptação. Consulte as comparações Fable 5.1 vs. Fable 5 e Fable 5.1 vs. Opus 5.

Verifique primeiro estes requisitos:

Retenção de dados: o Fable 5.1 exige retenção de 30 dias e não está disponível com retenção zero, salvo autorização expressa da Anthropic. Uma organização ZDR recebe 400 invalid_request_error em cada solicitação, sem outra indicação. O Opus 5 continua disponível sob ZDR.
Tier de Prioridade: não é compatível com o Fable 5.1, embora seja compatível com o Fable 5.
Limites de taxa: o Fable 5.1 compartilha o pool “Fable 5.x” com o Fable 5. Uma transição gradual usa a mesma capacidade.

Passo 1: atualize o nome do modelo

model = "claude-fable-5"    # Antes
model = "claude-opus-5"     # Ou antes
model = "claude-fable-5-1"  # Depois

No Amazon Bedrock, use anthropic.claude-fable-5-1. No Google Cloud, Microsoft Foundry e Claude Platform no AWS, use claude-fable-5-1.

Se você usa Claude Managed Agents, essa é a única alteração necessária.

Mudança disruptiva 1: uso forçado de ferramenta retorna 400

O Fable 5 aceitava auto, none, any e tool em tool_choice. O Fable 5.1 rejeita tool e any na API de Mensagens, na API de Batches e no endpoint de contagem de tokens:

tool_choice: type "tool" and "any" are not supported for this model.

Segundo a Anthropic, o pensamento está sempre ativo. Uma chamada forçada pularia essa etapa e faria o modelo escrever o raciocínio nos argumentos da ferramenta.

Antes, no Fable 5

response = client.messages.create(
    model="claude-fable-5",
    max_tokens=16000,
    tools=[record_summary_tool],
    tool_choice={"type": "tool", "name": "record_summary"},
    messages=[{"role": "user", "content": "Summarize: The meeting moved to Thursday."}],
)

Depois, no Fable 5.1

Mantenha tool_choice como auto, nomeie a ferramenta na instrução e use strict: true para garantir que os argumentos correspondam ao esquema.

record_summary_tool["strict"] = True
record_summary_tool["input_schema"]["additionalProperties"] = False

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    tools=[record_summary_tool],
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "Summarize: The meeting moved to Thursday. Call the record_summary tool with your result."}],
)

Migre por intenção:

Se você forçava uma ferramenta para obter JSON, use saídas estruturadas com output_config.format.
Se a chamada precisa ocorrer neste turno, adicione uma mensagem role: "system" após o último turno do usuário, nomeando a ferramenta e declarando que a chamada é obrigatória. Mantenha essa mensagem no histórico.
Se você usava any para permitir exatamente uma ferramenta, disable_parallel_tool_use: true continua funcionando com auto, mas agora significa “no máximo uma chamada”.
Remova loops que tentam novamente quando a ferramenta não é chamada. A Anthropic afirma que o Fable 5.1 segue instruções explícitas de ferramenta de forma confiável.
Em uma organização CMEK, strict: true e saídas estruturadas não estão disponíveis nos modelos Fable. Nesse caso, dependa apenas da instrução.

Mudança disruptiva 2: modelos antigos não leem blocos de pensamento do Fable 5.1

Cada bloco de pensamento registra o modelo que o produziu. O Fable 5.1 consegue ler blocos do Opus 5, Fable 5, Mythos 5 e modelos anteriores. Além do Mythos 5.1, nenhum outro modelo consegue ler um bloco produzido pelo Fable 5.1.

Uma conversa do Fable 5.1 pode chegar a um modelo antigo por:

uma troca de roteador;
uma nova tentativa no cliente;
um fallback de recusa do classificador.

Antes de o modelo antigo receber a conversa, a API remove os blocos que ele não consegue ler. A solicitação é bem-sucedida, os tokens removidos não são cobrados e o modelo de destino replaneja sem o raciocínio. Isso aumenta custo e latência no primeiro turno após a troca.

Não há correção de código necessária. Continue enviando os blocos de pensamento inalterados. Removê-los manualmente pode causar erros 400.

Para obter visibilidade, envie o cabeçalho beta thinking-binding-controls-2026-08-01. A resposta incluirá um array input_transformations identificando cada bloco descartado com:

reason: "model_binding_mismatch"

Mudança disruptiva 3: editar turnos anteriores invalida blocos de pensamento

Este é o item que exige mais atenção.

Um bloco de pensamento do Fable 5.1 só é válido em relação ao prompt system, ao array tools e ao histórico de mensagens exatos que o precederam — o chamado pensamento preservado.

Quando a verificação está ativa, reproduzir um bloco depois de alterar qualquer um desses elementos gera:

messages.5.content.0: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block". That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.

Quem é afetado

Contas criadas em ou após 31 de agosto de 2026 aplicam a verificação.
Contas mais antigas apenas registram a incompatibilidade, a menos que a solicitação defina thinking.block_binding.prefix_mismatch_behavior.
A Anthropic afirma que modelos futuros aplicarão a verificação a todas as contas.
Se você distribui uma ferramenta que outros executam com a própria chave de API, teste com o campo definido: usuários com contas novas podem ser afetados antes de você.
Claude Code, claude.ai, Managed Agents e o Agent SDK mantêm o prefixo intacto automaticamente.
O Mythos 5.1 não executa essa verificação.

O que invalida os blocos posteriores

Editar, reordenar ou remover um turno anterior, incluindo a exclusão de resultados antigos de ferramentas.
Injetar texto por solicitação e removê-lo na solicitação seguinte.
Reconstruir system ou tools entre solicitações.
Usar uma URL de imagem que forneça bytes diferentes posteriormente.

O que mantém os blocos válidos

Histórico somente de adição.
Remoção de uma sequência inicial de blocos de pensamento, do mais antigo para o mais novo.
Alteração de qualquer parâmetro fora de system, tools e messages.
Movimentação de marcadores cache_control.
Compactação ou edição de contexto no lado do servidor.

Saída de emergência

Envie o cabeçalho beta e defina prefix_mismatch_behavior como "drop_block":

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    thinking={"type": "adaptive", "block_binding": {"prefix_mismatch_behavior": "drop_block"}},
    betas=["thinking-binding-controls-2026-08-01"],
    messages=history,
)
for t in response.input_transformations or []:
    print(t.path, t.reason)   # prefix_binding_mismatch or model_binding_mismatch

A API descarta o primeiro bloco incompatível e todos os blocos de pensamento posteriores, prossegue a execução e relata cada descarte.

Isso vale apenas para a solicitação atual, portanto continue enviando o campo. No CI, defina "error" explicitamente para que qualquer edição do histórico faça a execução falhar.

O guia de pensamento preservado detalha a auditoria em três etapas e os formatos de compactação que causam falhas.

Tabela de correções

Você estava fazendo	Faça isto em vez disso
Editando `system` no meio da sessão	Congele-o no início; anexe uma mensagem `role: "system"` quando a mudança se tornar verdadeira.
Editando `tools` no meio da sessão	Declare o conjunto completo antecipadamente; envie blocos `tool_addition` ou `tool_removal` em uma mensagem de sistema, usando o beta `mid-conversation-tool-changes-2026-07-01`.
Injetando um lembrete por turno e excluindo-o depois	Use uma mensagem de sistema com escopo de turno e `clear_at: "next_user_message"`, usando o beta `mid-conversation-system-clear-at-2026-08-21`; mantenha-a no histórico.
Excluindo resultados antigos de ferramentas no cliente	Use edição de contexto no lado do servidor.
Compactando no cliente e mantendo os turnos recentes literalmente	Use compactação no lado do servidor ou uma mensagem de resumo seguida pelo novo turno do usuário, sem reproduzir o restante.
Referenciando uma imagem por URL entre turnos	Faça upload uma vez para a API de Arquivos e envie o `file_id`.

Vindo do Opus 5: mais quatro itens

1. O pensamento não pode ser desativado

O Opus 5 aceitava:

thinking = {"type": "disabled"}

em esforço high ou inferior. O Fable 5.1 retorna 400 em qualquer nível de esforço. Remova o campo, controle o gasto com um esforço menor e revise max_tokens nas rotas que funcionavam sem pensamento.

2. A narração entre ferramentas muda para blocos de pensamento

No Opus 5, o texto entre chamadas de ferramenta retornava como blocos text. No Fable 5.1, ele retorna como blocos thinking de atualização de progresso, que ficam vazios quando a exibição padrão está definida como "omitted".

Se sua UI renderiza essa narração, use:

thinking = {"type": "adaptive", "display": "updates"}

com o cabeçalho beta thinking-display-updates-2026-08-18.

3. O conjunto de classificadores é mais amplo

O Opus 5 executa apenas classificadores cibernéticos. O Fable 5.1 também cobre:

cyber;
bio;
frontier_llm;
reasoning_extraction;
general_harms.

Trate stop_reason: "refusal" antes de ler content e opte por fallbacks: "default" com o cabeçalho server-side-fallback-2026-07-01.

Os destinos permitidos são Opus 4.8 e Opus 5. Assim, uma solicitação recusada pode retornar ao modelo do qual você migrou.

4. Preço e retenção

O preço passa para US$ 10 e US$ 50, em vez de US$ 5 e US$ 25. As leituras de cache passam a custar US$ 0,25, em vez de US$ 0,50, e o ZDR deixa de ser compatível. A análise de preços apresenta os cálculos.

Se você vem do Opus 4.8 ou anterior, aplique primeiro a migração do Opus 4.8 para o Opus 5. Integrações antigas frequentemente truncam turnos ou reconstroem o prompt do sistema a cada solicitação — algo que o Opus 4.8 tolerava.

Mudanças de comportamento para testar

Essas mudanças não retornam erros, mas exigem validação:

Em loops longos, o Fable 5.1 pode emitir uma chamada de ferramenta por turno, enquanto o Fable 5 agrupava várias. Meça a proporção de turnos com múltiplas chamadas. Se ela cair, adicione uma instrução para agrupamento.
O Fable 5.1 escreve menos mensagens de progresso. Defina display: "updates" e remova prompts que instruem o modelo a reter descobertas.
Com esforço low, ele chama ferramentas de busca com menos frequência. Aumente o esforço nos turnos que precisam de dados recentes.

Mudanças recomendadas

Esforço por mensagem: usando o beta mid-conversation-output-config-2026-07-01, altere o esforço por meio de uma mensagem role: "system" de conteúdo vazio contendo output_config, em vez de mudar o valor de nível superior e reiniciar o cache.
Comece em high e faça uma varredura: os ganhos sobre o Fable 5 são maiores em xhigh e max. Segundo a Anthropic, medium se aproxima do Fable 5 com menor custo. Os nomes dos níveis não são equivalentes entre modelos.
Corte o contexto no servidor: a compactação no lado do servidor, usando o beta compact-2026-01-12, e a edição de contexto não contam como edições do histórico.

Checklist de migração

[ ] Confirme retenção de dados de 30 dias e ausência de dependência do Tier de Prioridade.
[ ] Atualize o modelo para claude-fable-5-1.
[ ] Substitua todo tool_choice do tipo any ou tool por auto, uma instrução explícita e strict: true, ou use saídas estruturadas.
[ ] Se vier do Opus 5, remova thinking: {"type": "disabled"} e revise max_tokens.
[ ] Retorne os blocos de pensamento inalterados em cada turno, incluindo os vazios.
[ ] Se o código constrói messages, execute uma sessão com prefix_mismatch_behavior: "drop_block", registre input_transformations e corrija cada prefix_binding_mismatch.
[ ] Congele system e tools no início da sessão.
[ ] Mova lembretes por turno para mensagens de sistema com escopo de turno que nunca sejam excluídas.
[ ] Escolha um prefix_mismatch_behavior para produção e monitore-o.
[ ] Trate stop_reason: "refusal" e adicione fallbacks: "default".
[ ] Se a UI renderiza texto entre ferramentas, defina display: "updates".
[ ] Refaça a varredura de esforço a partir de high e restabeleça o custo. A contagem de tokens não muda em relação ao Fable 5; as leituras de cache custam um quarto do preço.

Execute a checklist no Apidog

Crie uma coleção com uma solicitação para cada mudança disruptiva:

Uma chamada com tool_choice forçado, esperando o erro 400 correspondente.
Uma chamada com thinking: disabled, esperando um erro 400.
Uma sequência de duas solicitações que edita o prompt do sistema entre turnos, com o cabeçalho thinking-binding, esperando uma entrada prefix_binding_mismatch.

Adicione as versões aprovadas ao lado das solicitações negativas, com asserções sobre:

stop_reason;
um array input_transformations vazio.

Execute a coleção no CI por meio do Apidog CLI a cada alteração do sistema. Baixe o Apidog para criar a coleção. O passo a passo da API contém os corpos das solicitações.

Perguntas frequentes

A migração do Fable 5 para o Fable 5.1 é plug-and-play?

Em grande parte. O tool_choice forçado retorna 400, modelos antigos não conseguem ler blocos de pensamento do Fable 5.1 e editar turnos anteriores invalida blocos posteriores em contas com a verificação ativa. O restante é transferido.

O que significa “vinculado a uma conversa diferente”?

Seu código alterou algo anterior a um bloco de pensamento do Fable 5.1 e depois reproduziu esse bloco. Pare de editar o histórico ou envie o cabeçalho thinking-binding-controls-2026-08-01 com prefix_mismatch_behavior: "drop_block".

Minha conta impõe a verificação de edição do histórico?

Se ela foi criada em ou após 31 de agosto de 2026, sim. Contas mais antigas só aplicam a verificação quando você define prefix_mismatch_behavior.

Posso manter meus prompts do Fable 5?

Sim. A Anthropic afirma que eles devem continuar funcionando sem alterações. Ainda assim, refaça a varredura de esforço e espere menos chamadas paralelas de ferramenta em loops longos.

O que quebra ao migrar do Opus 5?

Tudo nesta lista, além de:

thinking: disabled retornar 400 em qualquer esforço;
a narração entre ferramentas migrar para blocos de pensamento;
o conjunto de classificadores ficar mais amplo;
o preço dobrar;
o ZDR deixar de ser compatível.

Bedrock e Google Cloud têm as mesmas mudanças disruptivas?

As mudanças do modelo são as mesmas. Os controles de vinculação de pensamento estavam disponíveis na API Claude e na Claude Platform no AWS no lançamento, e estão chegando por modelo ao Bedrock e ao Google Cloud. Sem esses controles, remova os blocos de pensamento e tente novamente uma vez.

DEV Community