Roteador de Ferramentas

Intenção

Escolher um subconjunto pequeno de ferramentas antes de chamar o modelo principal. Serve para agentes que cobrem muitos assuntos e precisam de muitas ferramentas no total, mas poucas em cada tarefa.

Problema

Fábio cuida do assistente de back-office de uma distribuidora. O agente concilia pagamentos, emite notas fiscais, consulta estoque, abre chamados com transportadoras e responde dúvidas de comissão. Depois de consolidar as ferramentas duplicadas, sobraram 34, todas legítimas e diferentes entre si.

Mesmo assim o agente erra. Num pedido de conciliação, ele chama consultar_estoque em vez de buscar_pagamento, porque as duas recebem um código de pedido e as descrições começam parecidas. O trace mostra o modelo hesitando entre ferramentas que nem deveriam estar na mesa.

Tem também a conta. Cada chamada leva as 34 definições, e o contexto de toda tarefa começa com milhares de tokens de ferramentas que não têm nada a ver com ela. Num loop de seis voltas, essas definições vão seis vezes para o modelo.

Fábio não pode remover ferramentas: todas são usadas por alguém. O que ele pode mudar é quantas o modelo vê de cada vez.

A pergunta que este padrão responde: como manter muitas ferramentas no sistema sem obrigar o modelo a escolher entre todas em toda chamada?

Solução

Organize as ferramentas em grupos por assunto (conciliação, notas, estoque, logística). Antes do loop do agente, um passo curto decide quais grupos a tarefa precisa. O agente principal roda só com esses grupos.

O roteador pode ser um modelo pequeno com saída estruturada, uma busca por similaridade entre a tarefa e a descrição dos grupos, ou regras simples quando o canal já diz o assunto. Sempre exista um caminho de volta: se o agente perceber que precisa de outro grupo, ele pode pedir.

A escolha que importa é tirada do modelo grande e colocada num passo pequeno, testável e barato. O agente principal deixa de responder “qual destas 34?” e passa a responder “qual destas 8?”.

Exemplo trabalhado

Chega a tarefa: “Concilia o pagamento do pedido 88231 com o extrato de ontem e, se bater, dá baixa no título”. O roteador recebe a tarefa e quatro linhas de descrição, uma por grupo:

billing:   Use para conciliar pagamentos com extratos e dar baixa em títulos.
invoices:  Use para emitir, cancelar ou consultar notas fiscais (NF-e).
stock:     Use para saldo, reserva e movimentação de estoque.
logistics: Use para frete, coleta e chamados com transportadoras.

E devolve uma saída estruturada curta:

{ "groups": ["billing"], "confidence": 0.92 }

O agente principal roda com as 7 ferramentas de billing e mais request_group. A ferramenta de estoque, que causava a confusão, nem aparece.

Agora a conta, com números ilustrativos. Suponha que cada definição de ferramenta ocupe uns 250 tokens. As 34 somam cerca de 8.500 tokens por chamada; num loop de seis voltas, são uns 51 mil tokens só de definições. Com 8 ferramentas, a mesma tarefa carrega uns 12 mil. O roteador custa uma chamada curta num modelo pequeno, com o texto da tarefa e quatro linhas de grupo.

Os números exatos variam com o seu catálogo e o seu provedor. O formato da conta não varia: o roteador paga uma vez, a economia acontece em toda volta do loop.

Estrutura

flowchart LR
  IN(["1. Tarefa"]):::io --> R(["2. Roteador de ferramentas"]):::llm
  C[("3. Catálogo de grupos")]:::store --> R
  R --> S["4. Subconjunto escolhido"]:::tool
  S --> A(["5. Agente principal"]):::llm
  A --> T["6. Ferramentas do grupo"]:::tool
  T --> A
  A -->|"precisa de outro grupo"| R
  A --> OUT(["7. Resposta"]):::io

1. A tarefa chega como texto do usuário ou evento do sistema.
2. Um modelo pequeno lê a tarefa e a lista de grupos, com uma linha de descrição cada.
3. O catálogo guarda os grupos e as ferramentas de cada um, versionados.
4. O roteador devolve os grupos escolhidos e a confiança.
5. O agente principal roda com as ferramentas desses grupos e mais uma ferramenta para pedir outro grupo.
6. As ferramentas executam normalmente.
7. A resposta sai e o trace registra quais grupos foram usados.

Pseudocódigo

schema Selection { groups: list["billing" | "invoices" | "stock" | "logistics"], confidence: float }

GROUPS = catalog.load("tool-groups@4")

function handle(task):
    # 2. escolher grupos com modelo pequeno
    sel = llm(ROUTER_PROMPT + GROUPS.summaries(), task) -> Selection
    trace.span("tool_route", sel)

    if sel.confidence < 0.6:
        sel.groups = GROUPS.default_set()           # 4. conjunto padrão seguro

    tools = GROUPS.tools_for(sel.groups) + [request_group]
    # 5 e 6. agente principal só com o subconjunto
    while budget.check():
        reply = llm_with_tools(AGENT_PROMPT, tools, state)
        if reply.is_final:
            return reply.text                        # 7
        for call in reply.tool_calls:
            if call.name == "request_group":
                tools += GROUPS.tools_for([call.args.group])
                trace.span("tool_route_expand", call.args)
            state.add(execute(call))

Cenários reais

• Automação de back-office com execução durável. Conciliação, emissão de notas e cobrança têm ferramentas próprias. Cada processo começa com o grupo do seu assunto e pede outro grupo só quando precisa. O que muda: o processo de cobrança nunca vê a ferramenta que cancela NF-e.
• Bot de suporte com escalonamento humano. O roteador de intenção já escolhe a rota; cada rota recebe só as ferramentas do seu assunto, e as de efeito ficam fora das rotas de dúvida. O que muda: uma pergunta sobre prazo de entrega não tem como disparar um estorno.

Aplicabilidade

• O agente tem mais de 15 ou 20 ferramentas, todas necessárias, de assuntos diferentes.
• Cada tarefa usa ferramentas de um ou dois assuntos.
• As definições de ferramenta ocupam uma parte grande do contexto de cada chamada.
• Você quer limitar quais ferramentas de efeito ficam ao alcance em cada tipo de tarefa.

Quando não usar

• O agente tem poucas ferramentas. Consolide antes: veja Consolidar Ferramentas.
• As tarefas cruzam todos os assuntos o tempo todo. O roteador sempre escolheria tudo.
• O provedor oferece busca de ferramentas sob demanda e o seu problema é só o custo em tokens. Esse mecanismo resolve sem um passo extra; veja também Revelação Progressiva.
• O canal de entrada já define o assunto. Use uma regra fixa em código, sem modelo.

Como implementar

1. Agrupe as ferramentas por assunto, com no máximo 8 a 10 por grupo.
2. Escreva uma descrição de uma linha por grupo, focada em quando usar.
3. Defina um conjunto padrão para baixa confiança: o grupo mais comum ou só ferramentas de leitura.
4. Implemente o roteador com saída estruturada e um modelo pequeno.
5. Dê ao agente uma ferramenta request_group para pedir um grupo que ficou de fora.
6. Monte um eval do roteador sozinho: tarefa e grupos esperados.
7. Rode o eval completo do agente e compare com a versão sem roteador.

Armadilhas comuns

• Agrupar por sistema, não por tarefa. “Tudo que fala com o ERP” vira um grupo de 25 ferramentas. Agrupe pelo que a pessoa quer fazer: conciliar, emitir, despachar.
• Descrever o conteúdo, não o uso. “Ferramentas de faturamento” não ajuda o roteador. “Use para conciliar pagamentos com extratos” ajuda, porque bate com o jeito como as tarefas chegam.
• Conjunto padrão com efeito. Se a confiança é baixa, o roteador está em dúvida. O padrão seguro é leitura, não “tudo, por garantia”.
• Esquecer a saída de emergência. Sem request_group, um erro do roteador vira um agente que responde sem a ferramenta certa, ou que inventa o dado.

Variações

• Roteamento por embedding. Compare a tarefa com exemplos ou descrições de cada grupo. Sem chamada de modelo, mais fraco em tarefas ambíguas.
• Roteamento por regra. Fila, canal ou tipo de evento define o grupo. Zero custo, zero erro de classificação, só funciona quando o assunto vem na entrada.
• Busca de ferramentas pelo provedor. O modelo vê um índice e carrega a definição completa quando precisa. Resolve o custo de tokens e parte da confusão.
• Roteador por agente. Em vez de grupos de ferramentas, cada rota leva a um agente especializado. Aí o padrão vira Roteamento ou uma passagem entre agentes.

Custo, latência e falhas

A falha mais cara é a silenciosa: o grupo certo ficou de fora e o agente não pediu. Ele responde “não encontrei o pagamento” com toda a calma do mundo. Por isso o eval de cobertura, abaixo, importa mais que o de tamanho.

Como avaliar

• Cobertura: em quantas tarefas os grupos escolhidos incluem todas as ferramentas que a solução certa usa.
• Tamanho médio do subconjunto escolhido.
• Taxa de expansão: quantas vezes o agente precisou pedir um grupo.
• Eval completo: taxa de conclusão e escolha correta de ferramenta, antes e depois.

{ "task": "Concilia o pagamento do pedido 88231 com o extrato de ontem", "expected_groups": ["billing"] }

Monte o dataset a partir dos traces que você já tem. Para cada tarefa resolvida com sucesso, os grupos esperados são os grupos das ferramentas que o agente de fato chamou. Inclua de propósito tarefas que cruzam assuntos (“emite a nota e agenda a coleta”) e tarefas vagas (“vê o que aconteceu com o pedido 88231”).

Cobertura e tamanho puxam para lados opostos. Um roteador que sempre escolhe tudo tem cobertura perfeita e não serve para nada. Acompanhe os dois juntos.

Em produção

• Span tool_route com grupos, confiança e versão do catálogo.
• Painel com a frequência de request_group por grupo. Um grupo pedido com frequência deve entrar na seleção inicial daquele tipo de tarefa.
• Alerta quando a média de grupos por tarefa sobe, sinal de roteador inseguro.
• Ao adicionar uma ferramenta nova, rode o eval do roteador de novo. Uma descrição de grupo que mudou pode desviar tarefas que antes iam certo.

Segurança

O roteador reduz a superfície: ferramentas de efeito só aparecem nas rotas que precisam delas. Não trate isso como controle de acesso. Um texto malicioso dentro da tarefa pode convencer o roteador a escolher outro grupo, e o agente também pode pedir grupos via request_group.

A permissão de verdade fica na ferramenta e no backend: quem é o usuário, o que ele pode fazer, qual é o limite de valor. Veja Reduzir Permissões da Ferramenta.

Prós e contras

Relações

• Smell que cura: Ferramentas Demais, quando todas as ferramentas são necessárias mas não ao mesmo tempo.
• Refatorações que chegam aqui: Introduzir Roteador e, antes dela, Consolidar Ferramentas.
• Vizinhos: Roteamento escolhe o prompt ou o agente; o Roteador de Ferramentas escolhe só a caixa de ferramentas e mantém um agente. Revelação Progressiva deixa o próprio agente abrir mais ferramentas aos poucos, sem passo prévio.

Código

As abas fazem a seleção com um modelo pequeno e rodam o agente só com os grupos escolhidos. Python e TypeScript montam a lista e chamam o modelo. LangGraph separa as duas peças: um nó escolhe os grupos, o nó seguinte cria o agente só com as ferramentas desses grupos.

from typing import Literal

import anthropic
from pydantic import BaseModel

client = anthropic.Anthropic()

GROUPS = {  # 3. catálogo: grupo -> (descrição, ferramentas)
    "billing": ("Use para conciliar pagamentos com extratos e dar baixa em títulos.", BILLING_TOOLS),
    "invoices": ("Use para emitir, cancelar ou consultar notas fiscais.", INVOICE_TOOLS),
    "stock": ("Use para saldo, reserva e movimentação de estoque.", STOCK_TOOLS),
    "logistics": ("Use para frete, coleta e chamados com transportadoras.", LOGISTICS_TOOLS),
}

Group = Literal["billing", "invoices", "stock", "logistics"]


class Selection(BaseModel):
    groups: list[Group]
    confidence: float


def select_tools(task: str) -> list[dict]:
    summary = "\n".join(f"{name}: {desc}" for name, (desc, _) in GROUPS.items())
    sel = client.messages.parse(  # 2. roteador com modelo pequeno
        model="claude-haiku-4-5",
        max_tokens=200,
        system=f"Escolha os grupos de ferramentas que a tarefa precisa.\n{summary}",
        messages=[{"role": "user", "content": task}],
        output_format=Selection,
    ).parsed_output
    groups = sel.groups if sel.confidence >= 0.6 else ["billing"]  # 4. padrão seguro
    return [tool for g in groups for tool in GROUPS[g][1]]


def handle(task: str) -> str:
    tools = select_tools(task)
    return run_agent(task, tools)  # 5. o mesmo loop de antes, com menos ferramentas

import Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import { z } from "zod";

const client = new Anthropic();

const GROUPS = {
  billing: { desc: "Use para conciliar pagamentos com extratos e dar baixa em títulos.", tools: BILLING_TOOLS },
  invoices: { desc: "Use para emitir, cancelar ou consultar notas fiscais.", tools: INVOICE_TOOLS },
  stock: { desc: "Use para saldo, reserva e movimentação de estoque.", tools: STOCK_TOOLS },
  logistics: { desc: "Use para frete, coleta e chamados com transportadoras.", tools: LOGISTICS_TOOLS },
} as const;

type Group = keyof typeof GROUPS;

const Selection = z.object({
  groups: z.array(z.enum(["billing", "invoices", "stock", "logistics"])),
  confidence: z.number(),
});

export async function selectTools(task: string): Promise<Anthropic.Tool[]> {
  const summary = Object.entries(GROUPS).map(([k, g]) => `${k}: ${g.desc}`).join("\n");
  const { parsed_output: sel } = await client.messages.parse({
    model: "claude-haiku-4-5",
    max_tokens: 200,
    system: `Escolha os grupos de ferramentas que a tarefa precisa.\n${summary}`,
    messages: [{ role: "user", content: task }],
    output_config: { format: zodOutputFormat(Selection) },
  });
  const groups: Group[] = sel && sel.confidence >= 0.6 ? sel.groups : ["billing"];
  return groups.flatMap((g) => [...GROUPS[g].tools]);
}

from typing import Literal

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langgraph.graph import END, START, StateGraph
from pydantic import BaseModel
from typing_extensions import TypedDict

Group = Literal["billing", "invoices", "stock", "logistics"]


class Selection(BaseModel):
    groups: list[Group]
    confidence: float


class State(TypedDict):
    task: str
    groups: list[str]
    answer: str


router = init_chat_model("anthropic:claude-haiku-4-5", temperature=0)


def select(state: State) -> dict:
    # 2. o mesmo GROUPS da aba Python: nome -> (descrição, ferramentas)
    summary = "\n".join(f"{name}: {desc}" for name, (desc, _) in GROUPS.items())
    sel = router.with_structured_output(Selection).invoke(
        [("system", f"Escolha os grupos de ferramentas que a tarefa precisa.\n{summary}"),
         ("human", state["task"])]
    )
    groups = sel.groups if sel.confidence >= 0.6 else ["billing"]  # 4
    return {"groups": list(groups)}


def run(state: State) -> dict:
    tools = [tool for g in state["groups"] for tool in GROUPS[g][1]]  # 5
    agent = create_agent("anthropic:claude-opus-5-5", tools=tools,
                         system_prompt="Você é o assistente de back-office.")
    result = agent.invoke({"messages": [("human", state["task"])]}, {"recursion_limit": 16})
    return {"answer": result["messages"][-1].text}


graph = StateGraph(State)
graph.add_node("select", select)
graph.add_node("run", run)
graph.add_edge(START, "select")
graph.add_edge("select", "run")
graph.add_edge("run", END)
app = graph.compile()

Teste seu entendimento