Um assistente recebe solicitações, classifica a intenção e devolve um JSON para o sistema de atendimento. Quando o provedor principal fica indisponível, um segundo modelo pode assumir a geração. Essa alternativa, chamada fallback, só funciona bem se o restante da aplicação continuar recebendo o que espera: campos corretos, significados consistentes e as mesmas regras de decisão.
Trocar apenas o nome do modelo na configuração deixa perguntas importantes em aberto. O substituto aceita o esquema? Entende os mesmos anexos? Pode acessar os mesmos dados? O resultado será revisado antes de abrir um chamado ou executar outra ação?
Resumo rápido
- Defina um contrato de entrada e saída independente do fornecedor, com validação na aplicação.
- Acione a contingência por uma política de erros; não trate toda falha como indisponibilidade temporária.
- Preserve limites, dados autorizados e identidade da operação quando mudar de modelo.
Comece pelo contrato que o sistema precisa cumprir
Descreva os campos, tipos, valores permitidos e significado de ausência. Se o pedido não informa uma data, o contrato deve permitir indicar essa falta, sem exigir que o modelo invente uma. Versione o esquema e as instruções de negócio juntos.
No JSON Schema, declarar propriedades não as torna automaticamente obrigatórias. A lista required define essa exigência, enquanto additionalProperties controla campos extras. Esses detalhes merecem revisão antes de usar a saída como entrada de outro sistema.
Crie um adaptador por provedor: ele transforma a solicitação interna na chamada aceita pela API e normaliza a resposta recebida. A camada seguinte deve trabalhar com o contrato interno, sem depender dos nomes de campos particulares de cada serviço.
A documentação de saídas estruturadas do Claude descreve suporte a esquemas com limitações e transformações feitas pelos SDKs. A consequência prática é conferir a compatibilidade efetiva do esquema escolhido. Uma restrição aceita por sua biblioteca local pode não ser aplicada da mesma forma durante a geração.
Para distinguir formato de resposta e execução de ferramentas, veja também o guia de function calling e structured outputs.
Defina quando trocar, esperar ou interromper
Uma política de fallback precisa distinguir problema temporário, configuração inválida e bloqueio permanente. Na referência de erros da Claude API, autenticação, permissões, limite de uso e sobrecarga têm tratamentos diferentes. Até um código 429 pode representar um teto de gasto que não desaparece após alguns segundos.
Recomendamos organizar a decisão em três caminhos:
- Repetir com limite: falha transitória identificada, respeitando a orientação de espera do provedor e o prazo total da tarefa.
- Usar o substituto aprovado: indisponibilidade elegível, desde que o modelo alternativo tenha sido validado para os mesmos dados e requisitos.
- Interromper e registrar: credencial inválida, permissão ausente, esquema incompatível, teto financeiro ou outra condição que exige correção.
Uma recusa relacionada ao conteúdo também não deve virar uma corrida entre modelos até algum aceitar. Trate o motivo conforme a política da aplicação. Se o resultado estiver incompleto, registre essa condição antes de decidir se uma nova geração faz sentido.
Conte tentativas feitas tanto pelo orquestrador quanto pelo SDK. Sem esse controle, uma configuração aparentemente pequena pode produzir várias chamadas e consumir todo o prazo do atendimento.
Exemplo hipotético: classificação de solicitações
Uma empresa recebe “Quero mudar minha entrega, mas ainda não escolhi o dia”. Seu contrato pede intencao, nova_data e precisa_confirmacao. O fluxo permite classificar a intenção, mas só altera a entrega depois de uma confirmação válida.
{
"intencao": "alterar_entrega",
"nova_data": null,
"precisa_confirmacao": true
}O provedor principal falha por sobrecarga. O orquestrador encaminha ao substituto a mesma mensagem, as mesmas regras e o mesmo esquema compatível. O identificador da tarefa permanece na aplicação, sem depender de o modelo reproduzi-lo.
Depois da geração, o validador confere a estrutura. Outra verificação compara a resposta com a solicitação: a data realmente foi informada? A ação exige confirmação? Existe informação suficiente para continuar? A documentação do Gemini recomenda validar os valores mesmo com saídas estruturadas e tratar resultados semanticamente incorretos.
Se o substituto preencher uma data inexistente no texto, o JSON pode estar bem formado e ainda assim ser rejeitado. A aplicação solicita o dado ausente ou encaminha o caso para revisão. O sucesso do fallback deve significar uma tarefa válida, e não apenas uma resposta HTTP recebida.
Se a primeira tentativa já puder ter executado uma ferramenta, consulte o estado da operação antes de repetir. Trocar de modelo não desfaz efeitos anteriores e não autoriza duplicar ações externas.
Checklist para homologar a contingência
- Rodar os mesmos casos nos dois modelos, incluindo informações ausentes, ambiguidades e anexos incompatíveis.
- Validar o contrato completo na aplicação, inclusive restrições não aplicadas durante a geração.
- Confirmar quais dados podem ser enviados a cada provedor alternativo.
- Definir teto de custo, prazo total e quantidade de tentativas por tarefa.
- Testar falhas forçadas, respostas incompletas e resultados válidos na forma, mas errados no conteúdo.
- Registrar modelo, versão do contrato, motivo da troca e resultado final, sem expor dados desnecessários.
Inclua a contingência nos testes de regressão de prompts e ferramentas. Compare também a proporção de tarefas que exigem revisão: uma alternativa sempre disponível pode aumentar o retrabalho.
Perguntas frequentes
O modelo alternativo precisa ser da mesma empresa?
Não. Precisa atender ao contrato, à autorização de uso dos dados e aos critérios de qualidade definidos para a tarefa.
Posso devolver qualquer texto se o JSON falhar?
Apenas se existir um caminho explicitamente preparado para isso. Um consumidor que espera dados estruturados deve receber um resultado válido ou um estado de erro conhecido.
