Como usar o Claude Haiku 5.5 para classificar registros e gerar consultas a banco de dados em volume

Fala aí, beleza? Classificar milhares de registros e transformar pedido em consulta de banco é EXATAMENTE o trabalho para o qual a Anthropic posicionou o Claude Haiku 5.5, lançado em 7 de outubro de 2026

Ele já está disponível na Claude Platform, na Amazon Web Services, no Google Cloud e no Microsoft Azure

A própria documentação descreve o modelo para trabalho de alto volume e sensível a latência: classificação, roteamento, extração e tarefas de subagente

E a Anthropic cita com todas as letras consultas a banco de dados e pedidos de classificação como cargas que ele dá conta 🙂

A ideia é te mostrar como montar o fluxo e, principalmente, onde ele quebra quando são milhares de chamadas, beleza?

O que você precisa antes de começar

Pouca coisa, mas cada item tem um motivo:

• Acesso à API: pela Claude Platform ou por um dos três provedores de nuvem (AWS, Google Cloud ou Microsoft Azure)
• O ID do modelo: claude-haiku-5-5
• Um SDK de Python, TypeScript, Ruby ou PHP: são esses que transformam schemas com recursos não suportados e validam a resposta contra o schema original, e isso vai fazer diferença no passo 2
• Um conjunto de registros de exemplo: uma amostra pequena e representativa, com os casos chatos incluídos (registro vazio, texto ambíguo, idioma misturado e por aí vai)
• O schema do banco descrito em texto: tabelas, colunas e relações, para a parte de gerar consultas

Por que o schema em texto?

Porque o modelo não enxerga o seu banco, ele só conhece o que você manda no prompt

Se a descrição for confusa, a consulta sai confusa também…

Se o teu problema hoje é mais de query lenta do que de volume, vale ler sobre ajuda de banco com Opus 5.5, que é outro tipo de rotina

Passo a passo: classificação e geração de consultas com o Haiku 5.5

Os exemplos estão em Python, mas a lógica é a mesma nos outros SDKs

Cada passo tem o erro comum logo depois, porque é ali que a rotina em volume costuma morrer haha

Passo 1: faça a chamada básica com o modelo certo e o effort ajustado

O Haiku 5.5 é o primeiro Haiku com nível de esforço (effort) ajustável por requisição

Os níveis são low, medium, high, xhigh e max, e o padrão é medium

A recomendação da Anthropic é simples: low para trabalho curto e barato, high para tarefas mais longas e para seguir instruções à risca, e xhigh ou max só quando as avaliações mostrarem ganho

Pra classificar registro em rótulo curto, low é o ponto de partida natural

import anthropic

client = anthropic.Anthropic()

resposta = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=1024,
    output_config={"effort": "low"},
    messages=[
        {"role": "user", "content": "Classifique este chamado: 'Não consigo emitir a segunda via do boleto'"}
    ],
)

O erro comum deste passo: copiar a chamada de outro modelo com temperature, top_p ou top_k fora do padrão

No Haiku 5.5 isso retorna erro 400, então remova esses parâmetros da requisição

Passo 2: defina o JSON Schema da classificação

Aqui entra o structured outputs: output_config.format restringe a resposta a um JSON Schema, pelo caminho GA, sem header beta

schema_classificacao = {
    "type": "object",
    "properties": {
        "categoria": {
            "type": "string",
            "enum": ["financeiro", "suporte_tecnico", "cancelamento", "outro"]
        },
        "motivo": {"type": "string"}
    },
    "required": ["categoria", "motivo"],
    "additionalProperties": False
}

resposta = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=1024,
    output_config={
        "effort": "low",
        "format": {"type": "json_schema", "schema": schema_classificacao}
    },
    messages=[{"role": "user", "content": "Classifique: 'Quero cancelar meu plano'"}],
)

O enum fecha as categorias possíveis, e o additionalProperties: False é obrigatório nos objetos

O erro comum deste passo: confiar em minimum/maximum, minLength/maxLength ou limites de array

O structured outputs não aplica essas restrições (em array, só minItems 0 ou 1)

Os SDKs removem essas regras, jogam a informação na descrição e validam a resposta contra o schema original, mas no envio pro modelo elas não estão sendo impostas

Passo 3: traduza o pedido em consulta usando uma tool com strict: true

Com tools[].strict, os argumentos da ferramenta seguem o input_schema que você definiu

Feche o schema com o campo da consulta e a lista de tabelas usadas, assim fica fácil conferir depois

ferramentas = [{
    "name": "gerar_consulta",
    "description": "Gera uma consulta SQL de leitura a partir do pedido do usuário",
    "strict": True,
    "input_schema": {
        "type": "object",
        "properties": {
            "sql": {"type": "string"},
            "tabelas": {"type": "array", "items": {"type": "string"}}
        },
        "required": ["sql", "tabelas"],
        "additionalProperties": False
    }
}]

schema_banco = """
clientes(id, nome, cidade, criado_em)
pedidos(id, cliente_id, valor, status, criado_em)
"""

resposta = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=2048,
    output_config={"effort": "high"},
    tools=ferramentas,
    tool_choice={"type": "tool", "name": "gerar_consulta"},
    messages=[{
        "role": "user",
        "content": f"Schema:\n{schema_banco}\nPedido: total vendido por cidade no último mês"
    }],
)

Repara que aqui usei high: gerar consulta exige seguir instruções à risca, que é justamente o caso que a Anthropic indica pra esse nível

O erro comum deste passo: pegar a consulta gerada e executar direto no banco

O schema garante o FORMATO, não garante que a consulta seja segura ou correta

Trate a saída do modelo como texto a validar, nunca como comando confiável: confira se as tabelas estão na sua lista permitida, se é só leitura e rode com um usuário de banco com permissão mínima

A mesma lógica vale quando a IA mexe no banco por outro caminho, e tem um post inteiro sobre alterar o banco sem riscos 😀

Passo 4: leia a resposta pelo tipo do bloco

No Haiku 5.5, o thinking adaptativo vem ligado por padrão

Resultado: a resposta pode começar com um ou mais blocos de thinking antes do conteúdo que te interessa

import json

texto = next(b.text for b in resposta.content if b.type == "text")
classificacao = json.loads(texto)

# no caso da tool:
chamada = next(b for b in resposta.content if b.type == "tool_use")
sql = chamada.input["sql"]

O erro comum deste passo: usar resposta.content[0] achando que é a resposta

Com thinking na frente, o primeiro bloco pode não ser texto nem tool, e o teu código quebra ou lê lixo

Passo 5: cheque o stop_reason antes de usar o resultado

Tem dois casos em que a saída pode sair fora do schema: recusa (stop_reason: refusal) e corte por max_tokens

Nesses dois casos a validação do SDK é pulada e o parsed_output vem None

E se liga: a recusa volta com status 200 e os tokens são cobrados, então ela não aparece como erro HTTP

if resposta.stop_reason in ("refusal", "max_tokens"):
    registrar_para_reprocessar(registro_id, resposta.stop_reason)
else:
    salvar_classificacao(registro_id, classificacao)

O erro comum deste passo: max_tokens apertado demais, cortando o JSON no meio

Em mil chamadas isso vira uma fração de registros que some em silêncio se você não checar

Passo 6: escale com a Message Batches API

Quando o volume não precisa de resposta na hora, o batch é o caminho

O processamento é assíncrono, com 50% de desconto sobre o preço padrão

Cada lote aceita até 100.000 requisições ou 256 MB, o que vier primeiro

A maioria dos lotes termina em até 1 hora, o lote expira se não terminar em 24 horas e os resultados ficam disponíveis por 29 dias após a criação

lote = client.messages.batches.create(
    requests=[
        {
            "custom_id": f"registro-{r['id']}",
            "params": {
                "model": "claude-haiku-5-5",
                "max_tokens": 1024,
                "output_config": {
                    "effort": "low",
                    "format": {"type": "json_schema", "schema": schema_classificacao}
                },
                "messages": [{"role": "user", "content": f"Classifique: {r['texto']}"}],
            },
        }
        for r in registros
    ]
)

O custom_id é o que liga cada resultado de volta ao registro original, então use o ID do seu banco ali

O erro comum deste passo: usar batch num fluxo que precisa de resposta imediata

Usuário esperando na tela não combina com lote que pode levar até 24 horas, né?

Onde a rotina em volume quebra e o que fazer

Agora a parte que separa a demo bonitinha da rotina de produção

Cada item tem sintoma, causa, solução e como prevenir

Erro 429 (rate_limit_error): o que fazer?

• Sintoma: várias chamadas voltando 429 de uma vez
• Causa: a sua organização bateu o limite de requisições ou de tokens por minuto, ou o teto de gasto
• Solução: ler o header retry-after, que vem em segundos, e esperar esse tempo antes de tentar de novo
• Como prevenir: controlar a concorrência (quantas chamadas rodam em paralelo) em vez de disparar tudo de uma vez

Erro 529 (overloaded_error): é problema na minha conta?

• Sintoma: chamadas falhando com 529 sem você ter mudado nada
• Causa: a infraestrutura da Anthropic está sobrecarregada para todos os usuários, não é limite da sua conta
• Solução: retentar com espera, porque é temporário
• Como prevenir: separar o tratamento de 529 dos erros de configuração, pra não sair mexendo no código à toa

Erro 400 depois de migrar do Haiku 4.5:

• Sintoma: código que funcionava no Haiku 4.5 começa a voltar 400
• Causa: temperature, top_p ou top_k fora do padrão, ou thinking no formato antigo com budget_tokens
• Solução: remover esses parâmetros e trocar thinking {type: enabled, budget_tokens: N} por thinking {type: adaptive}
• Como prevenir: revisar todas as chamadas no momento da troca de modelo, não só a principal

parsed_output vindo None:

• Sintoma: alguns registros ficam sem classificação
• Causa: stop_reason igual a refusal ou max_tokens
• Solução: registrar o item e reprocessar separado, olhando por que ele recusou ou cortou
• Como prevenir: checar o stop_reason em toda resposta e lembrar que recusa cobra tokens, então reprocessar sem mudar nada só gasta de novo

Resposta vazia ou estranha:

• Sintoma: o código lê string vazia, objeto esquisito ou quebra no parse
• Causa: o código pega o primeiro bloco de conteúdo, e ele é um bloco de thinking
• Solução: filtrar os blocos pelo type, como no passo 4
• Como prevenir: nunca depender da posição do bloco na lista

Custo ou corte acima do previsto depois da migração:

• Sintoma: a conta veio maior que a estimativa, ou respostas começaram a cortar
• Causa: no Haiku 5.5, o mesmo texto passa a contar como mais tokens
• Solução: recontar os prompts, revisar os limites de max_tokens e refazer as estimativas de custo
• Como prevenir: fazer essa recontagem antes de subir o volume, não depois de ver a fatura xD

Valor fora da faixa passando pela validação:

• Sintoma: uma nota que devia ir de 1 a 5 aparece como 7, ou um texto vem maior que o permitido
• Causa: o schema não impõe restrições numéricas nem de tamanho
• Solução: validar faixas e tamanhos no seu código depois do parse
• Como prevenir: sempre que a regra for numérica ou de tamanho, considerar que é você quem garante, não o modelo

Quanto custa rodar milhares de chamadas com o Haiku 5.5

O preço depende de duas coisas: o tamanho do prompt e se a chamada é síncrona ou em lote

O modelo tem 1M tokens de contexto e saída máxima de 128K (no Haiku 4.5 eram 200K e 64K), aceitando texto e imagem como entrada

Mas passar de 100.000 tokens de prompt muda a faixa de preço, então o prompt de classificação tem que ser ENXUTO: instrução curta, categorias claras e só o registro da vez

A Anthropic afirma que o Haiku 5.5 custa em média cerca de 75% menos para rodar do que o Haiku 4.5

É afirmação dela, e o teu custo real depende do teu prompt e da recontagem de tokens que comentei acima

Quando usar chamada síncrona?

Quando alguém está esperando a resposta:

• Roteamento em tempo real (chamado entra, já cai na fila certa)
• Pedido do usuário virando consulta na hora

Quando usar batch?

Quando o volume é grande e ninguém está olhando a tela:

• Reclassificar a base inteira depois de mudar as categorias
• Enriquecer histórico antigo com rótulos novos

Aqui o desconto de 50% faz MUITA diferença, e o limite de 100.000 requisições por lote dá conta de bastante coisa 🙂

Próximo passo: comece pequeno e meça antes de escalar

Recapitulando a ordem prática:

1. Schema fechado, com enum e additionalProperties: false
2. Effort low como ponto de partida pra classificação (e high pra gerar consulta)
3. Checagem de stop_reason e leitura da resposta pelo tipo do bloco
4. Retry respeitando retry-after no 429 e com espera no 529
5. Só depois, batch para o volume

Antes de jogar a base inteira, roda uma amostra pequena e compara os níveis de effort no mesmo conjunto

Se xhigh ou max não mostrarem ganho real na tua avaliação, não tem por que pagar por eles, que é exatamente o que a Anthropic recomenda

E aproveita a amostra pra conferir se as classificações e as consultas estão saindo do jeito que você espera

Medir antes de escalar é chato, mas é muiiito mais barato que descobrir o problema com 100 mil registros classificados errado haha

Até o próximo post! =)