Introduzir Roteador

Problema

Um único prompt ou agente atende vários assuntos, com regras e ferramentas de todos ao mesmo tempo. São os smells System Prompt Roteador, Ferramentas Demais e Mega-Agente.

Pense na assistente virtual de uma operadora de telefonia. Ela começou com vendas. Depois ganhou suporte técnico, depois cobrança. Cada assunto trouxe um bloco de regras para o system prompt e algumas ferramentas novas. Hoje, quando alguém pergunta “por que minha fatura veio mais alta?”, o modelo lê também as regras de portabilidade e as instruções de reiniciar o modem.

Os sintomas aparecem aos poucos. Um cliente de cobrança recebe uma oferta de plano no meio da explicação. Uma correção na regra de suporte piora as respostas de vendas. E ninguém consegue dizer, olhando o trace, qual parte do prompt o modelo seguiu.

Solução

Classifique a entrada primeiro, com um passo curto e saída estruturada, e mande cada tipo para um prompt ou agente especializado, com só as regras e as ferramentas daquele assunto. A decisão da rota fica no código.

Antes e depois

-SYSTEM = """Você é a assistente da Operadora.
-SE for vendas: [800 tokens]
-SE for suporte técnico: [1.200 tokens]
-SE for cobrança: [900 tokens]"""
-reply = agent(SYSTEM, tools=ALL_TOOLS, message=msg)
+class Route(BaseModel):
+    topic: Literal["sales", "tech", "billing", "other"]
+    confidence: float
+
+ROUTES = {
+    "sales":   Agent(SALES_PROMPT,   tools=[plans, offers]),
+    "tech":    Agent(TECH_PROMPT,    tools=[device_status, open_ticket]),
+    "billing": Agent(BILLING_PROMPT, tools=[get_invoice, explain_charge]),
+}
+
+route = llm_parse(ROUTER_PROMPT, msg, schema=Route, model="small")
+if route.topic == "other" or route.confidence < 0.7:
+    return handoff_to_human(msg)
+reply = ROUTES[route.topic].run(msg)

Antes: um prompt e todas as ferramentas para tudo.

flowchart LR
  IN(["1. Mensagem"]):::io --> A(["2. Prompt único com três assuntos"]):::llm
  A --> T["Todas as ferramentas"]:::tool
  A --> OUT(["3. Resposta"]):::io

Depois: classificação, decisão em código e especialistas.

flowchart LR
  IN(["1. Mensagem"]):::io --> R(["2. Classificar assunto"]):::llm
  R --> D{"3. Rota"}
  D -->|vendas| S(["4a. Vendas"]):::llm
  D -->|suporte| T(["4b. Suporte técnico"]):::llm
  D -->|cobrança| B(["4c. Cobrança"]):::llm
  D -->|outro| H((("4d. Atendente"))):::human

1. A mensagem chega.
2. Um modelo pequeno classifica o assunto com confiança.
3. O código decide a rota.
4. Cada rota tem prompt e ferramentas próprios; o resto vai para uma pessoa.

Exemplo trabalhado

Siga uma mensagem real pelos dois desenhos: “Minha fatura de setembro veio R$ 40 a mais, o que é isso?”.

No antes, o modelo recebe cerca de 3.000 tokens de instruções (os três blocos mais o cabeçalho) e seis ferramentas. Ele precisa descobrir sozinho que só o bloco de cobrança importa.

No depois, o classificador recebe um prompt curto, com a lista de assuntos e alguns exemplos, e devolve isto:

{ "topic": "billing", "confidence": 0.93 }

O código lê topic, vê que a confiança passa do limiar e chama o agente de cobrança. Esse agente recebe só os 900 tokens de cobrança e duas ferramentas: get_invoice e explain_charge. Ele não tem como oferecer um plano, porque nem conhece a ferramenta de ofertas.

No trace, a conversa ganha um campo novo: route=billing. Quando a resposta sair errada, você sabe se o erro foi da classificação ou do especialista.

Checagem +20 XP de primeiraDepois do roteador, uma conversa de cobrança terminou com uma resposta errada sobre a multa de cancelamento. O trace mostra route=billing e confiança 0,95. Onde você procura o problema primeiro?

No classificador, porque ele é o ponto único de falha

No limiar de confiança, que deveria ser mais alto

No prompt ou nas ferramentas do agente de cobrança

Por que funciona

Um prompt com três assuntos obriga o modelo a decidir, a cada mensagem, quais instruções valem. Às vezes ele mistura. Separar a decisão (classificar) da execução (responder) transforma uma escolha implícita e invisível numa escolha explícita, registrada e testável.

Classificar é uma tarefa mais fácil que responder. A saída é uma de quatro palavras, e um modelo pequeno costuma dar conta. Por isso o passo extra é barato e rápido.

Cada especialista fica pequeno: só as regras e as ferramentas do seu assunto. Isso melhora a qualidade, reduz o custo por chamada e permite que times diferentes cuidem de rotas diferentes sem se atrapalhar. Uma mudança no prompt de vendas não tem mais como quebrar a cobrança.

O padrão de destino é o Roteamento. Quando o que muda por rota é só o conjunto de ferramentas, e o prompt pode ser o mesmo, o destino é o Roteador de Ferramentas. O post “Building effective agents” da Anthropic (dezembro de 2024) descreve o roteamento como um dos workflows básicos e cita justamente o atendimento ao cliente, com perguntas gerais, pedidos de reembolso e suporte técnico indo para caminhos diferentes.

Passo a passo seguro

0. Meça. Rode o eval por assunto, com conversas reais, e guarde a qualidade de cada um.
1. Defina as rotas a partir de mensagens reais agrupadas à mão.
2. Escreva o classificador com saída estruturada (rota e confiança) e um eval só dele.
3. Divida o prompt antigo em prompts por rota, cada um com seu trecho e suas ferramentas.
4. Implemente a decisão em código, com limiar de confiança e rota padrão (humano ou resposta genérica).
5. Registre a rota no trace de cada conversa.
6. Meça de novo, por assunto e no total.

O eval do classificador

O eval do passo 2 é simples de montar. Separe algumas centenas de mensagens reais, rotule cada uma com a rota correta e compare com a saída do classificador. O resultado mais útil é uma matriz de confusão: quantas mensagens de cobrança foram para suporte, quantas de suporte foram para vendas, e assim por diante.

A matriz mostra onde as rotas se confundem. Se cobrança e suporte se misturam muito, talvez a fronteira entre elas esteja mal definida, e o conserto é na lista de rotas, não no prompt.

Erro comum: confiar no número de confiança

A confidence que o modelo escreve no JSON é um palpite dele sobre si mesmo, não uma probabilidade calibrada. Um modelo pode escrever 0,9 para quase tudo. Não escolha o limiar de 0,7 por intuição.

Use o eval para escolher. Veja em qual faixa de confiança os erros se concentram e coloque o corte ali. Se o número não separa acertos de erros, ele não serve como limiar, e a rota “outro” com bons exemplos no prompt faz mais efeito.

Riscos

• Mensagens com dois assuntos. “Paguei a fatura e o celular não liga”. Defina a regra: o assunto mais urgente, ou responder em sequência.
• Classificador como ponto único de falha. Se ele erra, a resposta inteira erra. O eval do classificador é obrigatório.
• Troca de assunto no meio da conversa. Reclassifique a cada mensagem, ou quando o especialista sinalizar que o assunto mudou.
• Latência extra. Uma chamada a mais por mensagem. Use um modelo pequeno, e considere regras em código para os casos óbvios (uma mensagem que só contém um código de barras de boleto é cobrança).
• Rotas demais. Vinte rotas com fronteiras finas confundem o classificador tanto quanto o prompt único confundia o modelo. Comece com poucas e divida só quando o eval mostrar necessidade.

Checagem +20 XP de primeiraO time quer adicionar uma rota nova para 'portabilidade', separada de 'vendas'. No eval do classificador, 30% das mensagens de portabilidade estão indo para vendas. Qual é a leitura certa?

A fronteira entre as duas rotas não está clara, e talvez portabilidade deva ser uma regra dentro de vendas

O classificador precisa de um modelo maior

Basta subir o limiar de confiança para 0,9

Desafio

Um agente interno de TI responde dúvidas, reseta senhas e cria acessos a sistemas. Como você dividiria as rotas, e qual delas precisa de cuidado extra?

Ver solução

Três rotas: dúvidas (RAG na base de TI, sem ferramentas de efeito), reset de senha (fluxo fixo em código, com verificação de identidade) e pedido de acesso (agente com ferramenta de criar acesso, sempre com aprovação do gestor). A rota de acesso precisa de cuidado extra: tem efeito sobre permissões, então passa por Humano no Circuito e por ferramentas com escopo mínimo. Mensagens com baixa confiança vão para o atendente.

Repare que a rota de reset de senha nem precisa de modelo depois da classificação. Um fluxo fixo é mais seguro e mais previsível que um agente para uma tarefa com sempre os mesmos passos.

Teste seu entendimento

Checagem +20 XP de primeiraQual é a principal diferença entre colocar 'SE for cobrança, faça X' no system prompt e usar um roteador?

O roteador usa um modelo mais inteligente para decidir

Com o roteador, a decisão vira um valor explícito que o código usa, registra e testa

O roteador elimina a necessidade de eval por assunto

Checagem +20 XP de primeiraUm agente tem 25 ferramentas e um único system prompt. As rotas usariam o mesmo prompt e mudariam só as ferramentas disponíveis. Qual destino faz mais sentido?

Roteamento completo, com um agente especializado por rota

Manter as 25 ferramentas e melhorar as descrições

Roteador de Ferramentas, que escolhe o subconjunto de ferramentas por mensagem

Checagem +20 XP de primeiraO cliente escreve: 'Paguei o boleto ontem e mesmo assim cortaram minha internet'. O classificador devolve billing com 0,55 de confiança. O limiar é 0,7. O que acontece no desenho da página, e está certo?

Vai para um atendente, e está certo: a mensagem mistura cobrança e suporte

Vai para cobrança, porque é o assunto com maior confiança

Vai para cobrança e suporte ao mesmo tempo