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

Mudar para o Claude Fable 5.1 é, em grande parte, uma troca de ID de 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 todos ao Fable 5. Mas três mudanças retornam erros que o Fable 5 nunca retornou, e uma delas, a verificação de edição de histórico, pode degradar silenciosamente um sistema de agente que funcionou bem por um ano. Vir do Opus 5 adiciona mais quatro itens.

Este guia é a lista de verificação com o texto de erro exato e a correção para cada item, na ordem em que você os encontrará, construído a partir do guia de migração da Anthropic e do que há de novo no 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 do modelo, comece com o que é o Claude Fable 5.1.

Passo 0: Confirme se você deve migrar

A documentação da Anthropic afirma que se deve 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 passar nas suas avaliações, a migração dobra o seu preço por token sem ganho mensurável. Se você estiver no Fable 5, é o mesmo preço com leituras de cache mais baratas e números alegados melhores, então a questão é apenas quanto trabalho de adaptação isso exige. As comparações Fable 5.1 vs Fable 5 e Fable 5.1 vs Opus 5 cobrem a decisão.

Três verificações de elegibilidade primeiro:

• Retenção de dados. O Fable 5.1 requer retenção de 30 dias e não está disponível sob retenção de dados zero, a menos que a Anthropic o autorize expressamente. Uma organização ZDR recebe 400 invalid_request_error em cada solicitação sem outra dica. O Opus 5 está disponível sob ZDR.
• Tier de Prioridade. Não suportado no Fable 5.1. O Fable 5 o suporta.
• Limites de taxa. O Fable 5.1 compartilha um pool “Fable 5.x” com o Fable 5, então 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, o ID é anthropic.claude-fable-5-1. Google Cloud, Microsoft Foundry e Claude Platform no AWS usam claude-fable-5-1. Se você usa Claude Managed Agents, esta é a única mudança necessária.

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

O Fable 5 aceitava os valores auto, none, any e tool para tool_choice. O Fable 5.1 rejeita os dois últimos, 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.

A razão da Anthropic: o pensamento está sempre ativo, e uma chamada forçada o pularia, então o modelo escreveria seu raciocínio nos argumentos da ferramenta.

Antes (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 (Fable 5.1): mantenha tool_choice como auto, nomeie a ferramenta na instrução e defina strict: true (uso de ferramenta estrito) para que os argumentos ainda correspondam ao seu 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, substitua por saídas estruturadas (output_config.format). Se o aplicativo exige a chamada neste turno, adicione uma mensagem role: "system" após o último turno do usuário que nomeia a ferramenta e diz que a chamada é obrigatória, e a mantenha no histórico depois. Se você dependia de any para “exatamente uma ferramenta”, disable_parallel_tool_use: true ainda funciona com auto, mas agora significa no máximo uma chamada. Exclua qualquer loop de "tentar novamente se a ferramenta estiver faltando"; a Anthropic diz que o Fable 5.1 segue instruções explícitas de ferramentas de forma confiável. Em uma organização CMEK, strict: true e saídas estruturadas não estão disponíveis nos modelos Fable, então dependa apenas da instrução.

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

Cada bloco de pensamento registra o modelo que o produziu. O Fable 5.1 lê blocos do Opus 5, Fable 5, Mythos 5 e modelos anteriores, então uma conversa que passa para o Fable 5.1 mantém seu raciocínio. Além do Mythos 5.1, nenhum outro modelo pode ler um bloco do Fable 5.1.

Uma conversa do Fable 5.1 chega a um modelo mais antigo através de um switch de roteador, uma nova tentativa do lado do cliente ou um fallback de recusa do classificador. Em todos os casos, a API descarta os blocos que esse modelo não consegue ler antes de vê-los. A solicitação é bem-sucedida, os tokens descartados não são cobrados, e o modelo de destino replaneja sem o raciocínio, o que aumenta o custo e a latência no primeiro turno após a troca.

Nada a corrigir no código. Continue passando os blocos de pensamento inalterados; removê-los você mesmo pode acionar 400s de assinatura. Para visibilidade, envie o cabeçalho beta thinking-binding-controls-2026-08-01 e a resposta conterá um array input_transformations nomeando cada bloco descartado com reason: "model_binding_mismatch".

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

Este é o item para o qual você deve dedicar tempo. Um bloco de pensamento do Fable 5.1 é válido apenas contra o prompt system exato, o array tools e o histórico de mensagens que o precederam (pensamento preservado). Onde a verificação é aplicada, uma solicitação que reproduz um bloco depois que qualquer um desses elementos foi alterado é rejeitada:

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. Contas mais antigas registram a incompatibilidade, mas só agem sobre ela se a solicitação definir thinking.block_binding.prefix_mismatch_behavior. A Anthropic diz que modelos futuros a aplicarão para todas as contas. Se você distribuir uma ferramenta que outros executam com sua própria chave de API, teste com o campo definido: seus usuários em novas contas serão afetados antes de você. Claude Code, claude.ai, Managed Agents e o Agent SDK mantêm o prefixo intacto para você; Mythos 5.1 não executa a verificação.

O que invalida cada bloco posterior: editar, reordenar ou remover um turno anterior (incluindo excluir resultados de ferramentas antigas); injetar texto por solicitação que você remove na próxima solicitação; reconstruir system ou tools entre as solicitações; um URL de imagem que serve bytes diferentes mais tarde. O que mantém os blocos válidos: históricos somente de adição, remover uma sequência inicial de blocos de pensamento do mais antigo para o mais novo, alterar qualquer parâmetro fora de system, tools e messages, mover marcadores cache_control e compactação ou edição de contexto no lado do servidor.

A saída de emergência. Envie o cabeçalho beta e defina o campo 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 cada bloco de pensamento após ele, prossegue e relata cada descarte. Isso se aplica apenas a essa solicitação, então continue enviando o campo. Defina "error" explicitamente no CI para que uma edição de histórico falhe na execução. O guia de pensamento preservado possui a auditoria de três etapas e as formas de compactação que causam falhas.

A tabela de correções:

Vindo do Opus 5: mais quatro itens

1. O pensamento não pode ser desativado em nenhum esforço. O Opus 5 aceitava thinking: {"type": "disabled"} em high ou inferior. O Fable 5.1 retorna um 400 em qualquer esforço. Remova o campo, controle os gastos com menor esforço e revise max_tokens para rotas que funcionavam sem pensamento.

2. A narração entre ferramentas move-se para blocos de pensamento. No Opus 5, o texto entre as chamadas de ferramentas retornava como blocos text. No Fable 5.1, ele retorna como blocos thinking de atualização de progresso que estão vazios sob o display: "omitted" padrão. Se sua UI renderizava essa narração, defina thinking: {"type": "adaptive", "display": "updates"} com o cabeçalho thinking-display-updates-2026-08-18.

3. O conjunto de classificadores é mais amplo. O Opus 5 executa classificadores apenas cibernéticos. O Fable 5.1 cobre cyber, bio, frontier_llm, reasoning_extraction e general_harms. Lide com stop_reason: "refusal" antes de ler o content, e opte por fallbacks: "default" com o cabeçalho server-side-fallback-2026-07-01. Os alvos permitidos são Opus 4.8 e Opus 5, então uma solicitação recusada pode retornar ao modelo do qual você migrou.

4. Preço e retenção. $10 e $50 em vez de $5 e $25, com leituras de cache a $0.25 em vez de $0.50. ZDR é perdido. A análise de preços tem os cálculos.

Vindo do Opus 4.8 ou anterior, primeiro aplique a migração do Opus 4.8 para o Opus 5, depois este guia. As integrações escritas para o Opus 4.8 frequentemente truncam turnos antigos ou reconstroem o prompt do sistema a cada solicitação, e o Opus 4.8 nunca se opôs.

Mudanças de comportamento a serem testadas

Nenhuma retorna erros, e cada uma tem uma correção de uma linha no guia de prompts. Em loops longos, o Fable 5.1 pode emitir uma chamada de ferramenta por turno, onde o Fable 5 agrupava várias; meça a proporção de turnos com várias chamadas e adicione o estímulo de agrupamento se ela diminuiu. Ele escreve menos mensagens de progresso, então defina display: "updates" e remova as linhas de prompt que o instruem a reter descobertas. Com esforço low, ele chama ferramentas de busca com menos frequência, então aumente o esforço para turnos que precisam de dados recentes.

Mudanças recomendadas

• Esforço por mensagem (beta mid-conversation-output-config-2026-07-01). Altere o esforço com uma mensagem role: "system" de conteúdo vazio contendo output_config em vez de alterar o valor de nível superior, o que reinicia o cache.
• Comece em high e varra. Os ganhos sobre o Fable 5 são maiores em xhigh e max; a Anthropic diz que medium se assemelha ao Fable 5 com menor custo. Os nomes dos níveis não se aplicam entre os modelos.
• Corte o contexto no servidor. A compactação no lado do servidor (beta compact-2026-01-12) e a edição de contexto não contam como edições de histórico.

A lista de verificação de migração

• [ ] Confirme retenção de dados de 30 dias e nenhuma dependência do Tier de Prioridade.
• [ ] Atualize o nome do modelo para claude-fable-5-1.
• [ ] Substitua todo tool_choice do tipo any ou tool por auto mais uma instrução e strict: true, ou saídas estruturadas.
• [ ] Do Opus 5: remova thinking: {"type": "disabled"} e revise max_tokens.
• [ ] Retorne os blocos de pensamento inalterados em cada turno, incluindo os vazios.
• [ ] Se seu 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 você nunca exclui.
• [ ] Escolha um prefix_mismatch_behavior de produção e monitore-o.
• [ ] Lide com stop_reason: "refusal"; adicione fallbacks: "default".
• [ ] Se sua UI renderiza texto entre ferramentas, defina display: "updates".
• [ ] Refaça a varredura de esforço a partir de high e re-estabeleça o custo. As contagens de tokens não mudam em relação ao Fable 5; as leituras de cache custam um quarto do preço.

Executando a lista de verificação no Apidog

Crie uma coleção com uma solicitação para cada mudança disruptiva: uma chamada tool_choice forçada (espere o 400 acima), uma chamada thinking: disabled (espere um 400) e uma sequência de duas solicitações que edita o prompt do sistema entre os turnos com o cabeçalho `thinking-binding` definido (espere uma entrada prefix_binding_mismatch). Adicione as versões aprovadas ao lado delas com asserções sobre stop_reason e um array input_transformations vazio, e execute-o na CI através do Apidog CLI em cada alteração de sistema. Baixe o Apidog para construí-lo; o passo a passo da API possui os corpos das solicitações.

Perguntas Frequentes (FAQ)

A migração do Fable 5 para o Fable 5.1 é uma mudança "plug-and-play"? Em sua maioria. tool_choice forçado retorna um 400, modelos mais antigos não conseguem ler blocos de pensamento do Fable 5.1, e a edição de turnos anteriores invalida blocos de pensamento posteriores em contas com aplicação. Todo o resto é transferido.

O que significa “vinculado a uma conversa diferente”? Seu código alterou algo antes de um bloco de pensamento do Fable 5.1 e depois reproduziu o 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 de histórico? Se foi criada em ou após 31 de agosto de 2026, sim. Contas mais antigas a impõem apenas quando você define prefix_mismatch_behavior.

Posso manter meus prompts do Fable 5? Sim. A Anthropic diz que eles devem ter bom desempenho sem alterações. Refaça a varredura de esforço e espere menos chamadas de ferramentas paralelas em loops longos.

O que quebra quando migro do Opus 5? Tudo na lista do Fable 5, mais thinking: disabled retorna um 400 em qualquer esforço, a narração entre ferramentas move-se para blocos de pensamento, o conjunto de classificadores é mais amplo, o preço dobra e o ZDR é perdido.

O Bedrock e o Google Cloud têm as mesmas mudanças disruptivas? As mudanças no modelo, sim. Os controles de vinculação de pensamento estavam na API Claude e na Claude Platform no AWS no lançamento e estão chegando por modelo no Bedrock e no Google Cloud. Sem os controles, a recuperação é remover os blocos de pensamento e tentar novamente uma vez.