A tool errada não é uma aproximação aceitável

"A Máquina da Confiança: Estudo de Caso em Desenvolvimento Agêntico Bancário" — visão geral antes do aprofundamento técnico: o problema, o Crash Silencioso, a barreira de quatro guardas e o que os números provam — e o que não provam.

Construir o cérebro de roteamento de um agente de atendimento de um banco digital. Antes de qualquer chamada a LLM caro, o sistema decide o caminho mais barato e seguro para responder cada mensagem.

Os três pilares da arquitetura

A restrição inegociável do domínio

A Fronteira: produção não vê o gabarito

O que separa engenharia de ajuste ao gabarito é uma linha só: expected_tool vive na camada de avaliação e nunca na lógica de produção.

grep -n "expected_tool" candidate_starter/retrieval.py candidate_starter/router.py candidate_starter/taxonomy.py
# Saída: zero resultados.

Numa iteração intermediária (commit c8f30d2), o projeto exibia: 54 testes no verde, router 100%, Hit Rate@2 de 100%, zero execuções incorretas e status aprovado com louvor. Uma revisão externa, porém, solicitou um teste de colisão entre vocabulário de leitura e escrita.

Query do Cliente: "Qual e o email cadastrado na minha conta?" — uma LEITURA.

Nenhuma das três guardas antigas pegou: o erro não é um empate — é uma decisão confiante e errada. Isso ilustra a tese central do pilar Engenharia de Confiança: o erro mais perigoso em IA não gera exceção de código. Ele passa no verde e toma uma decisão ruinosa com margem folgada.

Quando o problema apareceu, a primeira tentativa foi ajustar a combinação de pesos entre busca lexical e busca por intenção (score = (1−α)·lexical + α·intent). A demonstração matemática abaixo prova por que isso é impossível:

Query: "Quero mudar o e-mail vinculado a minha conta" (ESCRITA)

consultar_email_vinculado_conta  -> lexical = 0.8457 | intent = 0.4400
atualizar_email                  -> lexical = 0.1983 | intent = 0.3200

Para a escrita vencer por ajuste de α:
(1 - α)·0.1983 + α·0.3200 > (1 - α)·0.8457 + α·0.4400
α·(0.3200 - 0.4400 - 0.1983 + 0.8457) > 0.8457 - 0.1983
0.5274·α > 0.6474  =>  α > 1.227 (IMPOSSÍVEL, pois α ∈ [0, 1])

A lição estrutural: Leitura e escrita sobre o mesmo objeto compartilham todos os substantivos (e-mail, conta, cadastro). A diferença entre consultar e alterar é uma só palavra: o verbo. Num saco de palavras com TF-IDF, esse verbo é diluído entre dez tokens. A direção da operação não é recuperável por similaridade textual — precisa ser uma restrição semântica declarada.

Quem decide, neste pipeline, não é um modelo de linguagem. São cinco técnicas clássicas de estatística e de recuperação de informação, cada uma respondendo a um problema concreto do atendimento bancário. Cada técnica abaixo tem duas camadas: o conceito, em linguagem simples, e o trecho de Python que o implementa.

Os trechos são da branch feature/solucao-enxuta (commit e2dcd7f), a versão simplificada: quatro módulos e um script de execução, cerca de 560 linhas, sem taxonomy.py e sem ADRs. Onde a main faz diferente, uma nota avisa. Os números vêm da saída de python -m candidate_starter.run_case nessa branch e de recontagens offline sobre o mesmo relatório. Não são os números da main citados no resto da página.

1 · Classificação supervisionada: TF-IDF e regressão logística

Problema operacional. Saudações e perguntas de FAQ ("Qual o horário de atendimento?") não precisam de LLM nem de ferramenta. Responder isso localmente tem custo zero de LLM. O router precisa separar FAST_PATH de AGENT em milissegundos, antes de qualquer chamada cara.

Conceito. Classificação supervisionada é ensinar com exemplos já rotulados: aqui, 53 mensagens marcadas FAST_PATH (25) ou AGENT (28). O modelo aprende o que separa as duas classes e aplica isso a mensagens novas, em dois passos: transformar texto em números e aprender uma fronteira entre as classes.

O TF-IDF dá a cada termo um peso que cresce com a frequência dele na mensagem (TF) e diminui com o número de mensagens do conjunto que o contêm (IDF). "De" aparece em quase tudo e pesa pouco; "bloquear" aparece em poucas e pesa muito. Com n-grams de 1 a 2 termos, pares como "segunda via" também viram termos. Cada mensagem vira um vetor esparso (quase tudo zero) de comprimento 1.

A regressão logística transforma uma soma ponderada dos termos em uma probabilidade, entre 0 e 1, de a mensagem ser AGENT. A regularização L2 penaliza pesos grandes, para o modelo não decorar 53 exemplos; C controla a força (1,0 é o padrão do scikit-learn e é o valor usado). É um classificador linear e leve, e cada termo tem um coeficiente que dá para ler, o que importa numa auditoria.

normalize() é o preprocessor do vetorizador, então o mesmo tratamento (minúsculas, sem acento, variantes de domínio como "segunda via" → segundavia, sem pontuação) vale no treino e na consulta. Se os dois fossem normalizados de jeitos diferentes, o vocabulário aprendido não casaria com a pergunta real.

Medido nesta branch:

• Vocabulário de 378 termos (unigramas e bigramas) sobre os 53 exemplos de treino.
• Router 30/30 no benchmark; matriz de confusão FAST_PATH 10 · 0 / AGENT 0 · 20.
• predict(), já com a calibração da técnica 2: mediana de 2,2 ms e p95 de 4,4 ms em 200 chamadas locais (Windows, scikit-learn 1.9).

2 · Calibração de probabilidades: Platt scaling e validação cruzada estratificada

Problema operacional. O limiar de 0,75 da guarda G1 (seção A Barreira) só é uma política de risco se "0,75" significar "o modelo acerta em cerca de 75% dos casos". Uma regressão logística regularizada, com 53 exemplos e 378 termos, encolhe os pesos e devolve probabilidades tímidas, perto de 0,5, mesmo quando a classe está certa. Sem calibração, nesta branch, 20 das 20 mensagens AGENT do benchmark ficam abaixo de 0,75 (a maior confiança é 0,713), embora o router acerte todas. O limiar deixaria de separar decisão boa de decisão ruim e só descartaria cobertura.

Conceito. Calibrar é corrigir a escala do número sem mudar o que o modelo decide. O escalonamento de Platt treina uma segunda regressão logística, de uma única variável, sobre o score bruto f do modelo. Os parâmetros A e B são estimados por máxima verossimilhança em previsões feitas sobre exemplos que o modelo não viu no treino (out-of-fold: previsões sobre a parte dos dados deixada de fora em cada rodada). Estimá-los nos próprios exemplos de treino mediria a memória do modelo, não a capacidade de generalizar.

A validação cruzada estratificada divide os 53 exemplos em 3 dobras que preservam a proporção de classes; cada dobra serve uma vez de conjunto não visto. Sem embaralhar (shuffle=False), as dobras são as mesmas em qualquer máquina, e os testes são reproduzíveis. O código não chama StratifiedKFold diretamente: passar cv=3 a um classificador faz o scikit-learn usar esse divisor (conferido na versão 1.9). O número de dobras vem da menor classe: 3 se ela tem ao menos 3 exemplos, 2 se tem 2, e sem calibração abaixo disso, para o fit() não quebrar em conjuntos minúsculos de teste.

Por que sigmoide e não isotônica. A calibração isotônica é não paramétrica: com poucos dados ela sobreajusta e satura a confiança perto de 1, o problema oposto. A sigmoide tem dois parâmetros e é estável. A main mediu essa comparação no ADR-007.

Medido nesta branch:

• Sem calibração, 20 de 20 mensagens AGENT ficam abaixo de 0,75. Com calibração, 1 de 20 (0,732).
• No benchmark inteiro, G1 barrou 2 mensagens: "Troquei de número, preciso atualizar o telefone cadastrado" (AGENT, 0,732) e "Quais documentos preciso para abrir uma conta?" (FAST_PATH, 0,718). Nesta branch, G1 vale para as duas rotas.
• A menor confiança aceita é 0,753: folga de 0,003 sobre o limiar. A calibração corrigiu a escala, mas a margem continua estreita.
• O repositório não mede a calibração em si (Brier score, erro esperado de calibração, curva de confiabilidade), só o efeito dela no limiar. Com 20 queries AGENT, uma curva de confiabilidade teria poucos pontos por faixa.

3 · Recuperação vetorial: similaridade de cosseno, score multi-campo e colapso por capacidade

Problema operacional. O catálogo tem 285 ferramentas. Pôr todas no prompt de um LLM estoura o contexto, confunde o modelo e custa caro, então o retriever escolhe as 2 mais relevantes antes de qualquer chamada. E o catálogo tem duplicatas: 8 ferramentas diferentes fazem "obter a fatura".

Conceito. A similaridade de cosseno mede o ângulo entre dois vetores: 1 quando têm o mesmo vocabulário ponderado, 0 quando não compartilham nenhum termo. Como o TF-IDF já entrega vetores de comprimento 1, o cosseno é só o produto escalar, ou seja, uma multiplicação de matriz esparsa entre a query e as 285 ferramentas.

O score combina dois campos com peso igual. O documento da ferramenta é nome + descrição + categoria; o campo de "intenção" é nome + descrição. Manter campos separados, em vez de concatenar tudo, existe para que a normalização L2 não dilua os termos originais quando se acrescentam sinônimos ao mesmo texto (o ADR-006 da main documenta esse problema). Uma lista de palavras funcionais (a, de, para, quero…) sai do vocabulário antes, para uma query curta não pontuar só por preposições.

Um limite desta branch. Os dois campos saem do mesmo texto: diferem só pela categoria. Medido, a correlação entre as duas similaridades é de pelo menos 0,97, e o top-1 do score combinado é idêntico ao do campo único nas 30 queries. Aqui, α = 0,5 praticamente não muda o resultado. Um segundo campo só ajuda quando traz informação nova, como o glossário escrito à mão da main.

O colapso por capacidade agrupa as duplicatas com um dicionário embutido (CANONICAL_TOOL_MAP: 49 ferramentas em 12 capacidades) e guarda, por grupo, o maior score (max-pooling, uma agregação por máximo). Assim k=2 devolve duas capacidades distintas, não duas variantes da mesma. Depois, o código ordena por score decrescente e corta em k. Candidatos com score 0 são descartados: uma query sem nenhuma palavra em comum com o catálogo devolve lista vazia. Empates seguem a ordem do catálogo, porque o sorted do Python é estável. Isso é determinístico para o mesmo arquivo, mas não é um desempate explícito (a main desempata pelo nome da capacidade).

Medido nesta branch: recontando por capacidade (get_canonical_name sobre o resultado), a capacidade esperada está no top-1 em 19 das 20 queries transacionais e no top-2 em 20 das 20. O relatório impresso mostra outro número. A explicação está na técnica 5.

4 · Decisão sob incerteza: limiares, margem relativa e guarda de direção

Problema operacional. Escolher a melhor ferramenta não basta: o sistema precisa saber quando não executar. Um erro que passa em silêncio (ver O Crash Silencioso) custa mais do que uma pergunta de confirmação.

Conceito. Em vez de agir sempre sobre o melhor candidato, o pipeline testa três sinais estatísticos, em ordem, e só executa se todos passarem. Nenhum deles lê o expected_tool do gabarito.

• G1 · confiança: a probabilidade calibrada do router é ≥ 0,75.
• G2 · relevância mínima: o score do top-1 é ≥ 0,10, um piso contra casamentos por acaso.
• G3 · margem relativa: (s₁ − s₂) / s₁ ≥ 0,25. Mede quanto o primeiro candidato vence o segundo em proporção do próprio score. É relativa para não depender da escala: uma diferença de 0,03 pesa diferente quando o top-1 vale 0,18 e quando vale 0,80.

A margem em três queries reais, todas desviadas por G3 no benchmark:

A terceira falha por 0,019: 0,25 é uma política, não uma constante da natureza. Nesta branch os três limiares são literais no código; na main são constantes nomeadas, e a margem é parâmetro do harness.

G4 · guarda de direção. Ela não é uma medida de similaridade, e o motivo é estatístico: leitura e escrita sobre o mesmo dado dividem quase todos os termos (a seção Por que nenhum peso resolve mostra a aritmética). Então a direção entra como sinal declarado: verbos e palavras-chave da query dizem se ela é de leitura ou de escrita, e o prefixo do nome da ferramenta (consultar_, atualizar_…) diz de que tipo ela é. Query de leitura com ferramenta de escrita: score zerado.

Medido e limitado nesta branch:

• Leitura protegida. "Qual e o email cadastrado na minha conta?" resolve confirmar_email_cadastrado (leitura) em primeiro. atualizar_email não aparece entre os três primeiros.
• Escrita→leitura não é tratada. A especificação enxuta previa rebaixar a ferramenta de leitura, mas o código não faz nada nesse sentido. "Quero mudar o e-mail vinculado à minha conta" executa consultar_email_vinculado_conta (score 0,664): não altera nada, mas não cumpre o pedido.
• Só enxerga o que o nome revela. Por prefixo, 82 das 285 ferramentas são de leitura, 85 são de escrita e 118 ferramentas (41%) não revelam direção pelo nome e passam sem restrição.
• Leitura agrupada sob escrita. O dicionário de colapso põe consultar_email_vinculado_conta e confirmar_email_cadastrado, ferramentas de leitura, sob atualizar_email, que é de escrita. A main proíbe isso por invariante: leitura e escrita não se agrupam.

5 · Métricas de avaliação e economia

Problema operacional. Sem medição, "funciona" é opinião. E uma métrica mal lida é pior que nenhuma: a economia de custo sobe quando o sistema se abstém mais, mesmo que atenda menos.

Conceito. A acurácia é a proporção de acertos: acertos divididos pelo total. A matriz de confusão 2×2 separa os dois erros possíveis, que custam coisas diferentes: mandar uma FAQ ao agente gasta LLM à toa; mandar um pedido transacional ao FAST_PATH dá ao cliente uma resposta genérica no lugar da operação. O código inicializa todas as células com zero, então a estrutura fica completa mesmo sem erros cruzados.

O hit rate@k é a fração das queries em que a ferramenta esperada aparece entre as k primeiras. Não é a Precision@K clássica (relevantes entre as k, divididos por k): com uma só ferramenta relevante e k = 2, a Precision@2 máxima seria 0,5. A função se chama compute_precision_at_k, mas o que ela calcula é hit rate.

A economia é a redução percentual contra o baseline (mandar toda mensagem ao LLM, com todas as ferramentas no prompt), com guarda para baseline zero. No MVP, custos e latências vêm de constantes de mock (US$ 0,03 por chamada do baseline, US$ 0,01 por chamada do agente), então o percentual mede a estrutura do pipeline, não um preço real.

Saída de python -m candidate_starter.run_case na branch enxuta, 30 queries:

Por que 26,3% não é a qualidade da recuperação. O ToolMatch.name que o retriever devolve é o nome da variante que casou (por exemplo verificar_saldo_conta_corrente), e o expected_tool do dataset é o nome canônico (consultar_saldo). A comparação por string falha mesmo com a capacidade certa. Recontando por capacidade, o resultado é 19/20 e 20/20. O denominador também é 19, não 20: a query barrada por G1 nunca chegou ao retriever e ficou fora da conta.

Por que 82,2% é maior que os 77,8% do resto da página. Cinco mensagens foram desviadas por abstenção e não chamaram LLM. É o mesmo efeito descrito em Economia sem taxa de sucesso é risco disfarçado: a economia sobe quando o sistema faz menos. A execução que sai da capacidade esperada é "Manda o pdf da minha fatura atual" → reenviar_fatura_email, que o dicionário não agrupa em consultar_fatura. E as 15 certas incluem a query de e-mail, cuja ferramenta de leitura o dicionário agrupa sob atualizar_email. A branch enxuta não calcula execuções incorretas nem o ponto de equilíbrio do custo de atendimento humano: essas duas contas só existem na main.

Branch enxuta × main, técnica por técnica

O diagnóstico inicial de baixo recall (35% Hit Rate@2) parecia uma falha do modelo. O exame do registrador de ferramentas revelou a causa real: duplicações semânticas acumuladas por times diferentes ao longo de anos.

consultar_fatura                  -> "Gera o PDF ou linha digitável da fatura do mês atual."
gerar_linha_digitavel_fatura      -> "Gera a linha digitável da fatura ... para pagamentos."
enviar_pdf_fatura_atual           -> "Envia o PDF da fatura atual ... para o cliente."
consultar_valor_fatura_mes_atual  -> "Consulta o valor da fatura ... do mês atual."

Para um retriever lexical simples, a variante hiperespecífica sempre vence a canônica porque repete palavra por palavra da query. A solução foi introduzir o conceito de Capacidade Canônica com Colapso: o retriever agrupa as variantes sob a mesma capacidade e devolve em k=2 duas capacidades distintas. A variante específica que casou é preservada em matched_variant como trilha de auditoria para o runtime.

O desenvolvimento não seguiu uma linha reta. Duas rodadas foram impulsionadas por revisão adversarial externa, onde cada apontamento gerou um ciclo de diagnóstico, medição em ADR (Architecture Decision Record) e suíte de testes estendida. A terceira não teve revisor: apareceu porque o estado estacionário foi testado em vez de aceito no verde.

A procedência que contaminava a própria medição

O relatório de métricas é versionado — e um JSON versionado envelhece em silêncio: o código muda, o arquivo fica, e quem lê acredita em números que o commit atual não produz mais. O projeto tem um teste que recomputa as decisões contra o código vigente. Esse teste teve três defeitos da mesma família, todos com o relatório sujando a medição que deveria auditá-lo:

1. Asserção insatisfazível. Exigia snapshot.git_commit == HEAD. Como commitar o relatório cria um commit novo, o snapshot sempre aponta para o anterior — a asserção nunca poderia passar. A propriedade realmente auditável é outra: entre o commit que gerou o relatório e o HEAD, nada fora de reports/ mudou — e a falha passa a nomear os arquivos atrasados.
2. git_dirty se auto-sujava. build_snapshot() contava reports/ na verificação de árvore suja. Como o relatório é escrito pela própria função, da segunda execução em diante ele se declarava irreprodutível por causa do arquivo que acabara de gerar.
3. _git().strip() comia o espaço do prefixo de status. O filtro fatiava line[3:] do --porcelain, mas o .strip() na saída remove o espaço inicial da primeira linha: o caminho saía deslocado (eports/...), o filtro nunca casava e o teste voltava a pular em silêncio. Resolvido delegando o filtro ao próprio git (pathspec ':(exclude)reports'), sem parsing.

Uma suíte verde com 1 skipped parecia saudável. Não era — o skip era um teste desistindo em silêncio, e só apareceu porque o estado estacionário foi testado (regenerar o relatório, rodar a suíte de novo) em vez de aceitar o verde. É a terceira instância da tese desta página: métricas verdes não são cobertura.

Princípios que governaram as decisões

• Medir antes de editar: Nenhuma alteração foi feita sem antes registrar a tabela de métricas antes/depois na ADR.
• Nunca mover a trave: Soluções fáceis (como subir parâmetros de probabilidade para mascarar erros) foram sumariamente rejeitadas.
• Testes de Ausência de Efeito: Testes que garantem que mock_tool_execution nunca é chamada se qualquer guarda reprovar.
• Testar o estado estacionário: Não basta a suíte passar uma vez — ela tem de continuar passando depois que o sistema escreve os próprios artefatos.

Oito arquivos de teste divididos por invariantes de segurança e integridade. A parte mais valiosa não verifica um valor retornado; verifica que nada aconteceu:

def test_a_read_request_can_never_resolve_to_a_write_capability(retriever):
    """Antes da guarda de direcao, "Qual e o email cadastrado na minha conta?"
    devolvia atualizar_email (ESCRITA) em 1o lugar com margem relativa de 0.47 —
    acima do limiar de 0.25: a guarda de margem NAO pegava."""
    for query in read_requests:            # 5 consultas puras
        for m in retriever.search(query, k=3).matches:
            assert CAPABILITY_MODE.get(m.name) != "write"

Categorias da Suíte de Testes

• Ausência de efeito: mock_tool_execution nunca é chamada quando qualquer guarda reprova (executed.assert_not_called()).
• Integridade da Taxonomia: 7 invariantes de autoria (existência no catálogo, ausência de colisão, leitura ≠ escrita, direção declarada e herdada).
• Generalização sem Ajuste ao Gabarito: 12 paráfrases escritas com vocabulário totalmente ausente do dataset oficial (9/12 no top-1, 11/12 no top-2).
• Estabilidade e Procedência: Embaralhar a ordem do catálogo não altera decisão alguma; o relatório em JSON corresponde exatamente ao commit e código vigentes — e essa checagem não pode pular (foi o defeito da rodada 3).

Publicar limitações é o que separa engenharia de propaganda. As 7 restrições abaixo estão registradas no README do repositório oficial:

1. Aprovado neste benchmark, não para produção bancária viva: 30 queries, 53 exemplos de treino e tools mockadas. Tráfego real com adversários exige camadas de MFA, autorização e idempotência fora deste escopo.
2. A guarda de direção só protege o que está declarado: 59 das 285 ferramentas têm mode (14 capacidades canônicas + 45 variantes). As outras 226 passam sem restrição de direção. O lugar arquitetural correto para mode é o próprio registry — é metadado do endpoint, não da taxonomia.
3. Teto de recuperação lexical em paráfrase: O recall de paráfrases puras sem palavras-chave atinge 9/12 no top-1. O próximo degrau exige embeddings densos/reranker.
4. Taxonomia mantida manualmente: 14 capacidades e 45 variantes configuradas em código Python sobre 285 ferramentas.
5. As guardas 2 e 3 não são mais exercitadas pelo benchmark oficial: Com 20/20 e zero abstenções, elas passam a ser provadas só pelos testes de ausência de efeito. Um benchmark que nunca aciona a rede de segurança não demonstra que ela funciona.
6. Folga de calibração do router é estreita: A query AGENT menos confiante registra 0.7674 contra o limiar de 0.75 — 0.017 de folga, registrada como risco. (Já as margens das decisões corretas ficam entre 0.592 e 0.741 contra o limiar de 0.25: essa, sim, folgada.)
7. Custo de fallback humano é premissa, não medição: O número confiável é o ponto de equilíbrio, que é derivado das medições.