Uso de Ferramentas e Orquestração

Visão geral

Uso de ferramentas é a capacidade de um agente de IA (frequentemente um agente baseado em LLM (large language model)) de chamar funções externas — APIs, bancos de dados, interpretadores de código, mecanismos de busca, serviços internos — para realizar tarefas que excedem o que o modelo consegue fazer de forma confiável apenas em texto. Orquestração é a camada de controle que decide quais ferramentas usar, quando usá-las, como se recuperar de falhas e como coordenar múltiplas etapas (ou múltiplos agentes) em um fluxo de trabalho coerente.

Em sistemas agênticos modernos, o modelo é melhor entendido como um componente de raciocínio e decisão incorporado dentro de um sistema de software maior. A orquestração é o que torna esse sistema confiável: ela lida com roteamento, seleção de ferramentas, tentativas (retries), proteções (guardrails) e padrões de execução que transformam “um modelo esperto” em “um produto confiável”.

Este artigo se concentra em quatro temas centrais:

  • Roteamento: determinar qual caminho/fluxo de trabalho adotar para uma solicitação (frequentemente incluindo se deve chamar alguma ferramenta).
  • Seleção de ferramentas: escolher a(s) melhor(es) ferramenta(s) entre candidatas e fornecer entradas válidas.
  • Tentativas e recuperação: lidar com falhas de ferramentas, timeouts, resultados parciais e incerteza.
  • Padrões de orquestração: designs reutilizáveis (loops, planejadores, fluxos de trabalho, coordenação multiagente) para tarefas de longo horizonte.

Tópicos relacionados: Agentes de LLM, Memória e Estado, Sistemas Multiagente.

Por que o uso de ferramentas é essencial para agentes de LLM

LLMs são aprendizes de padrões poderosos, mas têm limitações estruturais:

  • Elas não têm, inerentemente, acesso a dados atuais ou privados. Ferramentas permitem recuperar dados de bancos de dados, índices de busca ou bases de conhecimento internas (frequentemente junto com Geração Aumentada por Recuperação (Retrieval-Augmented Generation)).
  • Elas não são garantidamente corretas sobre fatos ou aritmética. Ferramentas fornecem verdade fundamental (por exemplo, contagens de estoque, direitos do usuário) e cálculo verificável.
  • Elas não conseguem tomar ações reais por conta própria. Ferramentas podem enviar e-mails, criar tickets, implantar código, cobrar pagamentos — ações que exigem autenticação e gerenciamento de efeitos colaterais.
  • Elas têm janelas de contexto finitas e memória imperfeita. Orquestração e armazenamentos externos (ver Memória e Estado) gerenciam persistência, compressão e contexto de longo prazo.

Sob a perspectiva de IA, o uso de ferramentas transforma uma LLM em uma política sobre um espaço de ações expandido: “responder em texto” é uma ação, “chamar uma ferramenta com argumentos” é outra. A orquestração é o ambiente de execução da política, garantindo que as ações sejam válidas, seguras e eficientes.

Conceitos fundamentais

Ferramentas como interfaces: esquemas, contratos e efeitos colaterais

Uma “ferramenta” pode ser qualquer capacidade chamável:

  • Ferramentas de informação: busca, recuperação, consultas a banco de dados, parsers de documentos
  • Ferramentas de computação: execução de código, calculadoras, solucionadores de otimização
  • Ferramentas de ação: enviar mensagem, atualizar CRM, criar PR, agendar reunião
  • Ferramentas de controle: “pedir a um humano”, “solicitar esclarecimento”, “escalar”

Uma definição prática de ferramenta inclui:

  • Nome e descrição: o que faz e quando usá-la
  • Esquema de entrada: tipos, campos obrigatórios, restrições
  • Esquema de saída: resultado estruturado e formato de erro
  • Propriedades operacionais: latência, custo, limites de taxa, idempotência, permissões
  • Propriedades de segurança: quais efeitos colaterais ocorrem e como restringi-los

Duas propriedades importam muito na orquestração:

  1. Idempotência: É possível tentar novamente com segurança sem duplicar efeitos colaterais?
  2. Determinismo: A ferramenta retorna resultados estáveis, ou varia com tempo/estado?

Para ferramentas com efeitos colaterais (cobrar um cartão, criar um ticket), chaves de idempotência fortes e modos explícitos de “simulação” (“dry run”) podem simplificar drasticamente tentativas e segurança.

Roteamento vs seleção de ferramentas (e por que são diferentes)

Embora sejam relacionados, ajuda separar:

  • Roteamento: escolher um caminho de alto nível (por exemplo, “fluxo de problema de cobrança” vs “fluxo de suporte técnico” vs “responder a partir do FAQ sem ferramentas”).
  • Seleção de ferramentas: escolher as chamadas específicas de ferramentas dentro de uma rota (por exemplo, “consultar assinatura”, depois “calcular reembolso proporcional”, depois “criar solicitação de reembolso”).

O roteamento é frequentemente formulado como um problema de classificação (“qual intenção?”), enquanto a seleção de ferramentas é mais próxima de planejamento/seleção de ações sob restrições.

O loop de orquestração como um sistema de controle

Um loop de controle comum se parece com:

  1. Observar: solicitação do usuário + estado atual
  2. Decidir: rotear, escolher ferramenta ou produzir resposta
  3. Agir: chamar ferramenta(s)
  4. Atualizar: armazenar resultados em estado/memória
  5. Recuperar: lidar com erros/tentativas/fallbacks
  6. Responder: finalizar saída ou continuar

Isso se assemelha a loops clássicos de agentes em aprendizado por reforço e planejamento (ver Aprendizado por Reforço (Reinforcement Learning) e Algoritmos de Planejamento (Planning Algorithms)), mas na prática a “política” é parcialmente aprendida (a LLM) e parcialmente projetada (o orquestrador).

Estratégias de roteamento

O roteamento responde: Que tipo de problema é este, e qual fluxo de trabalho deve tratá-lo?

Estratégias comuns:

  1. Roteamento baseado em regras

    • Prós: previsível, barato, fácil de auditar
    • Contras: frágil, baixa cobertura para linguagem confusa
    • Exemplo: se a mensagem contém “reembolso” ou “estorno”, enviar para o fluxo de cobrança.

  2. LLM como roteador (classificação via prompt)

    • Prós: flexível, boa cobertura semântica
    • Contras: precisa de avaliação cuidadosa; pode ser inconsistente sem restrições
    • Frequentemente implementado como uma saída estruturada (“route”: um de N rótulos) com confiança.

  3. Roteamento baseado em embeddings (embedding-based routing)

    • Calcular embeddings para a solicitação; comparar com exemplares de rotas ou descrições de rotas.
    • Prós: rápido, estável; bom para similaridade semântica
    • Contras: menos expressivo que uma LLM para políticas sutis; requer exemplares curados.

  4. Roteador aprendido (classificador supervisionado)

    • Treinar um modelo leve (ou fazer ajuste fino (fine-tune)) em rotas rotuladas.
    • Prós: consistente, rápido, mensurável
    • Contras: requer dados; retreinamento periódico conforme as rotas evoluem

  5. Roteamento híbrido

    • Usar regras para casos críticos de segurança (“cancelar conta” exige verificação).
    • Usar roteamento aprendido/por LLM para casos gerais.
    • Adicionar uma rota de fallback: “fazer pergunta de esclarecimento” ou “transferir para humano”.

Dica prática: o roteamento deve considerar custo e risco, não apenas semântica. “Redefinição de senha” e “excluir conta” podem parecer semelhantes textualmente, mas exigem autenticação e salvaguardas diferentes.

Estratégias de seleção de ferramentas

A seleção de ferramentas responde: Qual ferramenta devo chamar a seguir, com quais argumentos, dado o objetivo e o estado?

Geração e filtragem de candidatos

Antes de pedir para uma LLM escolher ferramentas, muitos sistemas reduzem o conjunto de ferramentas:

  • Filtrar por permissões (o que o usuário/sessão atual pode fazer)
  • Filtrar por contexto (apenas ferramentas relevantes para esta rota)
  • Filtrar por disponibilidade (serviços degradados, limites de taxa)
  • Filtrar por orçamento de custo/latência

Isso importa porque menus grandes de ferramentas aumentam confusão e chamadas alucinadas.

Abordagens de seleção

  1. Chamada de função em etapa única (single-step function calling)

    • O modelo seleciona uma chamada de ferramenta (ou nenhuma) a partir de um conjunto fornecido.
    • Melhor para tarefas simples: “consultar status do pedido”, “buscar docs”.

  2. Seleção iterativa (multietapas)

    • O modelo decide uma sequência de chamadas de ferramentas, atualizando-se com base nos resultados.
    • Útil quando a coleta de informações é adaptativa.

  3. Divisão planejador + executor (planner + executor split)

    • O planejador produz um plano (etapas); o executor roda as ferramentas e lida com erros.
    • Melhora a controlabilidade e permite inspeção.

  4. Heurística + LLM

    • Heurísticas escolhem a “melhor” fonte de recuperação; a LLM formata consultas e sintetiza a resposta final.
    • Frequentemente entrega melhor confiabilidade do que dar liberdade total à LLM.

Construção e validação de argumentos

Um grande modo de falha não é a ferramenta errada, mas argumentos errados. Boas práticas:

  • Usar esquemas estruturados (por exemplo, restrições tipo JSON Schema).
  • Validar argumentos antes da execução.
  • Se a validação falhar, então:
    • pedir ao modelo para reparar argumentos usando o erro de validação, ou
    • pedir ao usuário uma pergunta de esclarecimento.

Tentativas, recuperação e robustez

Tentativas não são apenas “tentar de novo”. Uma boa política de tentativas distingue tipos de falha:

Taxonomia de falhas

  • Erros transitórios de infraestrutura: timeouts, 503s, falhas de rede
    → tentar novamente com recuo exponencial e jitter
  • Limites de taxa / cotas: 429s
    → tentar novamente após atraso; trocar para modelo de menor custo; reduzir concorrência
  • Argumentos inválidos / incompatibilidade de esquema: 400s, erros de validação
    → não tentar novamente cegamente; reparar entradas
  • Erros de domínio no nível da ferramenta: “order_id não encontrado”, “fundos insuficientes”
    → tratar logicamente; perguntar ao usuário; escolher ferramenta ou rota alternativa
  • Resultados parciais: algumas páginas recuperadas, outras falharam
    → degradar com elegância; citar o que você tem; opcionalmente continuar

Padrões de confiabilidade

  • Recuo exponencial + jitter: previne efeito manada
  • Disjuntor (circuit breaker): parar de chamar uma ferramenta que falha e rotear para fallback
  • Orçamentos de timeout: limitar o tempo total gasto em tentativas
  • Chaves de idempotência: tentativas seguras para ações com efeitos colaterais
  • Ferramentas de fallback: por exemplo, se a busca primária falhar, tentar índice secundário
  • Escalonamento com humano no loop (human-in-the-loop): para ações de alto risco ou falhas repetidas

Um ponto sutil, mas importante: tentativas de LLM também existem. Se o modelo produz argumentos de ferramenta inválidos, você pode “tentar novamente” com um prompt de reparo que inclui o erro de esquema — frequentemente mais eficaz do que apenas amostrar novamente às cegas.

Padrões de orquestração

A seguir estão padrões comuns e reutilizáveis para construir agentes que usam ferramentas.

Chamada direta de ferramenta (etapa única)

Melhor quando o mapeamento de solicitação → chamada de ferramenta é direto.

  • Rota: “status do pedido”
  • Ferramenta: get_order_status(order_id)
  • Resposta: renderizar resultado

Isso pode ser altamente confiável quando combinado com extração determinística (ou decodificação restrita) e validação forte.

Loop no estilo ReAct (razão + ação)

Em um loop similar ao ReAct, o agente alterna entre:

  • gerar um pensamento/decisão (“Eu deveria pesquisar a documentação”)
  • chamar uma ferramenta
  • observar o resultado
  • continuar até conseguir responder

Em produção, muitas equipes evitam expor “pensamentos” e, em vez disso, tratam o loop como transições internas de estado. A ideia-chave é a intercalação entre raciocínio e resultados de ferramentas.

Planejar e executar (plan-and-execute)

Abordagem em duas fases:

  1. Planejar: produzir um plano estruturado (etapas, ferramentas necessárias)
  2. Executar: rodar as etapas de forma determinística com checagens, tentativas e atualizações de estado

Esse padrão é útil quando:

  • as tarefas são de longo horizonte,
  • auditabilidade importa,
  • você quer restringir ações permitidas.

Orquestração por workflow / DAG

Representar o processo como um grafo direcionado:

  • nós = chamadas de ferramentas ou chamadas ao modelo
  • arestas = dependências
  • ramificações condicionais = decisões de roteamento

Isso é comum em ambientes corporativos onde confiabilidade e observabilidade importam mais do que autonomia aberta.

Orquestração gerente–trabalhador (hierárquica)

Um agente “gerente” delega a agentes ou módulos “trabalhadores” especializados:

  • Trabalhador de pesquisa (recuperação, citações)
  • Trabalhador de dados (SQL, analytics)
  • Trabalhador de ação (tickets, CRM)
  • Trabalhador de segurança (checagens de política)

Isso se sobrepõe a Sistemas Multiagente, mas também pode ser implementado como um único processo com múltiplos prompts/modelos.

Loops de crítico / verificador

Adicionar uma etapa explícita de verificação:

  • Gerar chamada de ferramenta candidata ou resposta final
  • Crítico verifica restrições (política, formato, indícios de correção)
  • Se falhar, revisar

A verificação é especialmente valiosa para:

  • ações críticas de segurança
  • chamadas de ferramentas caras
  • domínios de alta precisão (finanças, triagem médica — tipicamente com supervisão humana)

Exemplos práticos

Exemplo 1: Um agente de suporte ao cliente com roteamento

Cenário: um assistente de suporte precisa lidar com perguntas de cobrança, problemas técnicos e FAQs gerais. Ele tem ferramentas:

  • search_kb(query) → artigos/trechos
  • get_subscription(user_id) → plano, status
  • create_ticket(category, summary, metadata) → id do ticket
  • issue_refund(user_id, invoice_id, amount, idempotency_key) → status do reembolso

Um esboço mínimo de orquestração:

from dataclasses import dataclass
import time, random

@dataclass
class ToolResult:
    ok: bool
    data: dict | None = None
    error_type: str | None = None   # "timeout", "rate_limit", "validation", "domain"
    error_message: str | None = None

def backoff(attempt: int) -> float:
    base = min(2 ** attempt, 20)
    return base + random.random()

def call_with_retries(tool_fn, args: dict, *, max_attempts=3, timeout_s=10) -> ToolResult:
    for attempt in range(max_attempts):
        result = tool_fn(args, timeout_s=timeout_s)
        if result.ok:
            return result

        if result.error_type in ("timeout", "rate_limit"):
            time.sleep(backoff(attempt))
            continue

        # Non-transient: don't retry blindly
        return result

    return ToolResult(ok=False, error_type="timeout", error_message="exhausted retries")

def route_intent(user_message: str) -> str:
    # In practice: LLM router or classifier; keep deterministic here for illustration
    msg = user_message.lower()
    if "refund" in msg or "charged" in msg or "invoice" in msg:
        return "billing"
    if "error" in msg or "bug" in msg or "crash" in msg:
        return "technical"
    return "faq"

def handle_message(user_id: str, user_message: str) -> str:
    route = route_intent(user_message)

    if route == "faq":
        kb = call_with_retries(search_kb, {"query": user_message})
        if kb.ok and kb.data.get("snippets"):
            return synthesize_answer(user_message, kb.data["snippets"])
        return "I couldn't find a relevant article. Can you share more details?"

    if route == "billing":
        sub = call_with_retries(get_subscription, {"user_id": user_id})
        if not sub.ok:
            return "I’m having trouble accessing your subscription details. Please try again shortly."

        # If refund requested, collect required identifiers safely
        needs_invoice = "invoice" in user_message.lower() or "refund" in user_message.lower()
        if needs_invoice and "invoice_id:" not in user_message:
            return "Which invoice is this about? Please provide the invoice ID."

        # Example: side-effecting call requires idempotency key
        refund = call_with_retries(issue_refund, {
            "user_id": user_id,
            "invoice_id": extract_invoice_id(user_message),
            "amount": None,  # let tool compute or require explicit amount
            "idempotency_key": make_idempotency_key(user_id, user_message),
        })
        if refund.ok:
            return f"Refund initiated: {refund.data['status']} (ref: {refund.data['refund_id']})"

        if refund.error_type == "domain":
            return f"I can't issue that refund: {refund.error_message}"

        return "Refund service is temporarily unavailable. I can create a ticket for follow-up if you want."

    if route == "technical":
        kb = call_with_retries(search_kb, {"query": user_message})
        if kb.ok and kb.data.get("snippets"):
            return synthesize_answer(user_message, kb.data["snippets"])

        ticket = call_with_retries(create_ticket, {
            "category": "technical",
            "summary": user_message[:200],
            "metadata": {"user_id": user_id},
        })
        if ticket.ok:
            return f"I created a support ticket: {ticket.data['ticket_id']}"
        return "I couldn't create a ticket right now. Please try again later."

    return "Unsupported route."

O que este exemplo ilustra:

  • Roteamento escolhe um fluxo de trabalho cedo.
  • Seleção de ferramentas é restringida pela rota (cobrança vs técnico).
  • Tentativas são aplicadas apenas a erros transitórios.
  • Efeitos colaterais (reembolso) exigem chaves de idempotência e controle cuidadoso.
  • A LLM pode ser usada dentro de synthesize_answer(...) e, opcionalmente, no roteamento e na extração de argumentos — mas o orquestrador mantém o controle de segurança e confiabilidade.

Exemplo 2: Orquestração de análise de dados (recuperar → computar → explicar)

Cenário: “Quais foram os 5 principais fatores de churn no último trimestre?” Ferramentas:

  • run_sql(query) → tabela
  • fit_model(data, target) → resumo do modelo
  • plot(data, spec) → artefato de gráfico

Uma orquestração robusta frequentemente:

  1. Usa a LLM para rascunhar uma consulta SQL em um dialeto restrito
  2. Valida a consulta (sem instruções destrutivas)
  3. Executa com timeouts e limites de linhas
  4. Alimenta os resultados em uma ferramenta de computação
  5. Gera uma explicação narrativa com citações dos outputs computados

Esse estilo de “pipeline” é frequentemente mais confiável do que deixar a LLM fazer tudo de uma vez, porque cada etapa é verificável e limitada.

Boas práticas de design de ferramentas e orquestrador

Projete ferramentas para agentes (não apenas para humanos)

  • Torne entradas explícitas e tipadas: evite strings “query” sobrecarregadas quando existirem campos estruturados.
  • Retorne erros estruturados: inclua tipo de erro, mensagem e dicas de reparo.
  • Forneça identificadores estáveis: IDs em vez de nomes quando possível.
  • Ofereça modos de “dry run” / “apenas validar” para ações perigosas.
  • Adicione chaves de idempotência para operações com efeitos colaterais.

Gerencie estado explicitamente

A orquestração de ferramentas é stateful: identidade do usuário, outputs anteriores de ferramentas, orçamentos e progresso importam.

  • Mantenha um objeto de estado da tarefa com resultados de ferramentas e decisões.
  • Persista o que importa entre turnos (ver Memória e Estado).
  • Evite colocar tudo no prompt; armazene estado estruturado fora da LLM e resuma quando necessário.

Restrinja e verifique saídas do modelo

Para reduzir alucinações e chamadas inválidas:

  • Use restrições de saída estruturada (esquemas, enums).
  • Valide e repare em vez de “executar no melhor esforço”.
  • Considere um modelo “verificador” ou um checador baseado em regras para etapas de alto risco.

Observabilidade e avaliação

Trate o uso de ferramentas como um sistema de produção:

  • Trace cada etapa: rota → seleção de ferramenta → args → latência da ferramenta → resultado
  • Acompanhe métricas:
    • taxa de sucesso de chamadas de ferramentas
    • taxa de falhas de validação de argumentos
    • contagens de tentativas
    • sucesso de tarefa ponta a ponta (com rótulos humanos quando possível)
    • orçamentos de custo e latência
  • Avalie sistematicamente (ver Métricas de Avaliação (Evaluation Metrics)) usando suítes de teste reproduzíveis e falhas de ferramentas simuladas.

Modos comuns de falha (e mitigações)

  • Rota errada (classificação incorreta): adicionar uma rota “esclarecer”; calibrar confiança; usar roteamento híbrido.
  • Ferramentas ou parâmetros alucinados: restringir lista de ferramentas; validação de esquema; impor enums.
  • Loops infinitos / thrashing de ferramentas: limites de etapas; condições de término; checagens de novidade (“não repetir chamada idêntica”).
  • Injeção de prompt via outputs de ferramentas: tratar texto de ferramentas como não confiável; isolar conteúdo recuperado; aplicar filtragem de conteúdo antes de realimentar.
  • Falhas em cascata durante indisponibilidades: disjuntores; fallbacks; degradação graciosa.
  • Falha parcial silenciosa: exigir sinais explícitos de completude; rastrear dependências faltantes no estado.

Quando usar qual padrão de orquestração

  • Chamada direta de ferramenta: tarefas transacionais de etapa única (consulta, atualizações simples)
  • Loop ReAct: exploração aberta com ferramentas limitadas (assistentes de pesquisa)
  • Planejar e executar: tarefas longas que exigem auditabilidade e execução previsível
  • Workflow/DAG: pipelines corporativos, processos com alta exigência de conformidade
  • Gerente–trabalhador / multiagente: especialização, paralelismo, domínios complexos (ver Sistemas Multiagente)

Na prática, a maioria dos sistemas reais são híbridos: um fluxo de trabalho roteado com um pequeno loop tipo ReAct dentro de etapas específicas, além de tentativas e verificação explícitas.

Checklist: construindo agentes confiáveis que usam ferramentas

  • Roteie cedo e inclua um fallback seguro (esclarecer/escalar)
  • Reduza o menu de ferramentas por rota; filtre por permissões e disponibilidade
  • Use esquemas + validação para argumentos de ferramentas; implemente loops de reparo
  • Trate tentativas como uma política (por tipo de erro), não como um instrumento bruto
  • Adicione idempotência para ferramentas com efeitos colaterais; prefira opções de “dry run”
  • Rastreie estado fora do modelo; resuma em prompts conforme necessário
  • Instrumente tudo: traces, métricas e avaliações reproduzíveis
  • Projete para degradação: disjuntores, fallbacks e transferência para humano

Uso de ferramentas e orquestração é onde sistemas agênticos viram engenharia. Quando bem feitos, transformam LLMs de geradores de texto impressionantes em componentes confiáveis que podem recuperar, computar, agir e se recuperar — sob restrições do mundo real.