Centenas de Ferramentas em Seu Agente — Como Escolher a Certa

O Problema Que Ninguém Fala

Você construiu um agente. Você conectou mais de 100 ferramentas. Você se sente bem com isso.

Então, ele começa a alucinar. Escolhendo a ferramenta errada. Colapsando fluxos de trabalho inteiros devido a uma única consulta mal classificada.

A falha não está no LLM. Está na arquitetura.

Meu post anterior abordou um caso de uso genuíno que encontrei para o Gemma4 — e é exatamente aqui que ele se encaixa.

A Abordagem Ingênua (e Por Que Ela Falha)

Carregar todas as ferramentas no contexto do LLM e deixar que ele decida.

Parece simples. É. E quebra em escala.

• Alucinações aumentam com o comprimento do contexto
• Contexto inchado = chamadas mais lentas e caras
• LLM fica confuso ao escolher entre mais de 50 descrições de ferramentas

Resultado: Agentes lentos. Não confiáveis. Caros.

A Abordagem "Um Pouco Mais Inteligente" (Ainda Quebrada)

RAG sobre descrições de ferramentas. Parece razoável:

Consulta do usuário → incorporação → 5 melhores correspondências → LLM escolhe

Parece limpo. Mas incorporações não conseguem distinguir intenção.

Palavras semelhantes ≠ mesmo significado.

Exemplo:

Usuário diz: "Eu preciso de um iPhone"
Ferramenta: check_product_catalog

A busca por incorporação pode:

• Perder completamente a ferramenta
• Recuperar ferramentas irrelevantes
• Quebrar todo o fluxo de trabalho a montante

A ferramenta errada é selecionada. Todo o fluxo de trabalho colapsa.

O problema não é o modelo de incorporação. É que você está pedindo a uma única camada para carregar muita responsabilidade.

O Que Realmente Funcionou: Uma Pilha de Filtragem em Camadas

A abordagem que funciona em produção é filtragem em camadas — não busca semântica pura, não raciocínio bruto do LLM. Ambos juntos, na ordem certa.

Aqui está a pilha que eu uso:

A Arquitetura em 5 Passos

Passo 1 — Classifique a Intenção Primeiro

Um LLM leve mapeia a consulta para uma categoria de alto nível antes que qualquer busca aconteça.

Isso elimina domínios irrelevantes inteiros desde o início. Se o usuário está perguntando sobre pedidos, você nem olha para ferramentas de inventário.

"Eu preciso de um iPhone" → categoria: descoberta_de_produtos

Passo 2 — Filtro Rigoroso por Metadados

Regras determinísticas. Não incorporações.

Apenas ferramentas que correspondem à categoria de intenção classificada são elegíveis. O espaço de busca colapsa de mais de 100 ferramentas para talvez 10–15.

categoria: descoberta_de_produtos → ferramentas elegíveis: [check_catalog, search_products, get_inventory, ...]

Passo 3 — Busca Semântica Dentro do Subconjunto Limpo

Agora RAG funciona — porque está rodando sobre um conjunto pequeno e relevante, não centenas barulhentas.

nomic-embed-text encontra as correspondências semânticas mais próximas dentro do seu pool filtrado. Falsos positivos caem dramaticamente.

Passo 4 — Pontuação e Classificação

Pontuação de confiança nos principais candidatos. Auditável. Explicável.

Sem decisões de caixa preta. Você pode registrar exatamente por que uma ferramenta foi selecionada — o que importa quando as coisas quebram em produção.

Passo 5 — Escolha Final do LLM

Envie os principais candidatos + a consulta original do usuário para o LLM.

Agora ele está escolhendo entre 3–5 ferramentas relevantes, não 100+. O contexto é limpo. A decisão é precisa.

[check_product_catalog, search_products, get_item_details] + "Eu preciso de um iPhone"
→ LLM escolhe: check_product_catalog

Por Que Isso Funciona

Cada camada faz uma única tarefa. Nenhuma camada única carrega muita responsabilidade.

Classificador de intenção  → reduz o espaço de domínio
Filtro de metadados    → reduz a contagem de ferramentas (determinístico, rápido)
Busca semântica       → encontra a correspondência mais próxima no subconjunto limpo
Pontuação            → adiciona confiança + auditabilidade
LLM                  → faz a chamada final com contexto mínimo

É por isso que é confiável. É por isso que é rápido.

A Parte Que Ninguém Fala

Mesmo a melhor arquitetura falha se suas descrições de ferramentas forem escritas como documentos de API.

# Ruim — escrito para engenheiros
def check_product_catalog(sku: str, region: str) -> dict:
    """Consulta o catálogo de produtos pelo SKU com filtragem por região."""

# Bom — escrito para usuários
def check_product_catalog(...):
    """
    Use isso quando alguém quiser encontrar um produto, verificar se algo
    está disponível, procurar um item pelo nome ou modelo, ou navegar pelo que'está
    em estoque. Funciona para consultas como 'você tem iPhone 15?' ou
    'mostre-me suas opções de laptop'.
    """

Escreva descrições na linguagem que seus usuários entendem.