Uso de Ferramentas

Intenção

Dar ao modelo funções bem descritas para buscar dados e executar ações, num loop em que o seu código executa cada pedido, devolve o resultado e decide quando parar. Serve para assistentes que precisam responder com dado real e agir no mundo, e não só conversar.

Problema

A loja do Marcos tinha um bot que respondia dúvidas gerais muito bem. Os clientes, porém, queriam outra coisa: “cadê o meu pedido?”, “quero cancelar”, “o reembolso já caiu?”. Para essas, o bot só sabia dizer “entre em contato com o suporte”.

O primeiro remendo foi colar no prompt os dados do cliente antes de cada conversa: últimos pedidos, status, endereço. O prompt inchou, os dados ficavam velhos no meio da conversa, e o bot continuava sem conseguir cancelar nada.

O segundo remendo foi pior: o bot respondia “pedido cancelado” quando o cliente pedia, mas ninguém cancelava de verdade. O modelo estava só escrevendo o texto mais provável.

Essa classe de erro já saiu do laboratório. Em 2023, o chatbot de uma concessionária Chevrolet em Watsonville, na Califórnia, “aceitou” vender um Tahoe por 1 dólar depois de um prompt injection (injeção de instrução). A loja teve de explicar em público que o bot não fechava negócio. Texto do modelo não é ação. Ação é o seu código chamando o sistema de pedidos.

A pergunta que este padrão responde: como deixar o modelo consultar e agir no seu sistema, com o seu código no controle de cada passo?

Solução

Declare as ações possíveis como ferramentas: nome, descrição de quando usar e schema dos argumentos. O modelo recebe a conversa e a lista, e pode responder pedindo uma ferramenta. Isso é function calling (chamada de função): o modelo não executa nada, só pede. O seu código executa, devolve o resultado como mensagem, e o modelo continua até ter a resposta.

Três regras fazem o padrão funcionar em produção. Ferramentas de leitura rodam direto. Ferramentas que mudam algo (cancelar, pagar, enviar) passam por um portão: confirmação do usuário, aprovação humana ou regra de negócio. E o loop tem um teto de voltas, porque um modelo pode pedir ferramentas para sempre.

O guia “Building effective agents” da Anthropic (dezembro de 2024) coloca ferramentas no centro do agente, com o código como executor. A OWASP, no Top 10 for LLM Applications, trata efeito sem controle e injeção via dado como riscos padrão, não como caso raro.

Exemplo trabalhado

O cliente escreve: “cancela o pedido 4521, comprei errado”. O modelo não responde “cancelado”. Ele pede:

{ "name": "cancel_order", "arguments": { "id": "4521", "reason": "compra errada" } }

O código não chama orders.cancel ainda. Mostra o resumo no app: “Cancelar o pedido 4521? Essa ação não tem volta.” O cliente toca em confirmar. Aí a ferramenta roda e devolve:

{ "id": "4521", "status": "canceled", "refund": "pending" }

O modelo lê o JSON e explica em português: o pedido foi cancelado, o reembolso entra na fila. Se o cliente não confirma, a ferramenta devolve {"error": "o cliente não confirmou o cancelamento"} e o modelo não finge que cancelou.

Compare com a leitura. “Cadê o pedido 4521?” chama get_order sem portão e devolve JSON curto, não HTML da página de rastreio. Se a ferramenta responder só "ok", o modelo não sabe o status e pede de novo: é o mesmo sinal do Loop Sem Fim.

A conta, ilustrativa. Colar os 20 pedidos do cliente no prompt, a 200 tokens cada, são 4.000 tokens em toda volta. Com ferramenta, a primeira volta leva a definição (uns 200 tokens) e a segunda leva o JSON de um pedido (uns 150). Em mil conversas por dia, a diferença é de milhões de tokens, e o status deixa de ficar velho no meio do chat.

Estrutura

flowchart TD
  IN(["1. Mensagem + ferramentas"]):::io --> M(["2. Modelo decide"]):::llm
  M --> D{"3. Pediu ferramenta?"}
  D -->|"não"| OUT(["7. Resposta"]):::io
  D -->|"leitura"| R["4. Executa buscar_pedido"]:::tool
  D -->|"efeito"| G((("5. Portão: confirma?"))):::human
  G -->|"sim"| W["4. Executa cancelar_pedido"]:::tool
  G -->|"não"| X["Resultado: recusado"]:::tool
  R --> B{"6. Dentro do orçamento?"}
  W --> B
  X --> B
  B -->|"sim"| M
  B -->|"não"| OUT

1. A chamada leva a conversa e a lista de ferramentas.
2. O modelo decide se responde ou se pede uma ferramenta, e com quais argumentos.
3. O código olha o pedido.
4. Ferramentas permitidas são executadas pelo seu código, com as permissões do seu código.
5. Ferramentas com efeito colateral passam por um portão antes de rodar.
6. Cada volta conta contra um orçamento de passos. Estourou, o loop para.
7. Quando o modelo responde sem pedir ferramenta, a resposta segue para o usuário.

Pseudocódigo

tool get_order(id: string) -> Order                  # leitura
tool cancel_order(id: string, reason: string) -> Ok  # efeito colateral

function answer(conversation):
    state = conversation
    while budget.check(max_steps=8):                 # 6
        step = llm_with_tools(PROMPT, [get_order, cancel_order], state)   # 2
        if step.is_text:
            return step.text                         # 7

        for call in step.tool_calls:                 # 3
            if call.name == "cancel_order" and not human.approve(call):   # 5
                result = error("o cliente não confirmou o cancelamento")
            else:
                result = run(call)                   # 4
            trace.span("tool", call, result)
            state.append(call, result)

    return "Vou passar para uma pessoa do time."     # orçamento estourado

Cenários reais

• Bot de suporte com escalonamento humano. O bot consulta pedidos e rastreio com ferramentas de leitura. Troca e cancelamento passam por confirmação explícita do cliente, e reembolso acima de um valor vai para uma pessoa.
• Assistente financeiro com aprovação. Consultar saldo e extrato é livre. Agendar um Pix é uma ferramenta de efeito, e só roda depois de o usuário ver o resumo e aprovar no app.
• Perguntas em linguagem natural para SQL. A ferramenta executa consultas num usuário de banco só leitura, com tempo limite. O modelo vê o resultado e ajusta a consulta se der erro.

Aplicabilidade

• A resposta depende de dados que mudam: pedidos, saldos, estoque, agenda.
• O assistente precisa executar ações em sistemas que você controla.
• Você não sabe antes quais dados vão ser necessários; depende da conversa.
• Você quer que o modelo consiga se corrigir lendo o erro de uma ferramenta.

Quando não usar

• O dado necessário é sempre o mesmo e cabe no prompt. Buscar antes e mandar junto é mais simples e mais barato.
• A sequência de passos é fixa. Chame as funções no código e use o modelo só onde precisa, como em Encadeamento de Prompts.
• A conta é determinística. Se o modelo só chamaria uma calculadora, faça a conta no código: veja o smell LLM Fazendo Conta.

Como implementar

1. Liste as ações que o assistente precisa. Comece com poucas: de três a cinco ferramentas.
2. Separe leitura de efeito colateral. Ferramentas de efeito ganham um portão desde o primeiro dia.
3. Escreva cada descrição dizendo o que a ferramenta faz e quando usar. Regras de uso moram na descrição, não espalhadas no system prompt. Veja Mover Instrução para a Descrição da Ferramenta.
4. Use schemas estreitos: enum para tipos e descrição clara do formato de identificadores. Ative o modo estrito para o modelo não inventar campos, e valide o formato no código.
5. Devolva resultados curtos, em JSON limpo. Erros com mensagem clara (“pedido não encontrado”) ajudam o modelo a se corrigir. HTML cru vira o smell Ferramenta que Cospe HTML.
6. Rode as ferramentas com as permissões do usuário da conversa, nunca com permissão de administrador.
7. Coloque um orçamento de passos no loop e um caminho de saída quando ele estoura. O destino é Condições de Parada.
8. Registre cada pedido e resultado no trace, e monte um eval que confere se a ferramenta certa foi chamada com os argumentos certos.

Armadilhas comuns

• Duas ferramentas quase iguais. get_order e get_order_status brigam. Consolide antes de pensar em roteador.
• Resultado vago. "ok" não diz o que mudou. O modelo repete a chamada.
• Portão só no prompt. “Só cancele se o cliente pedir” é uma sugestão. O portão é código. Sem ele, você tem Efeito Sem Portão.
• Permissão de administrador. A ferramenta herda a identidade do usuário. Senão vira Ferramenta Superpoderosa.

Variações

• Loop manual. Você escreve o while e controla tudo. É a aba Python abaixo.
• Runner do SDK. O SDK roda o loop e chama as suas funções. Menos código, e o portão fica dentro da função da ferramenta. É a aba TypeScript.
• Ferramentas paralelas. O modelo pede várias leituras numa volta só, e o código executa todas ao mesmo tempo. Devolva todos os resultados juntos, numa mensagem.
• Muitas ferramentas. Passou de algumas dezenas, o modelo começa a errar a escolha. A saída é o Roteador de Ferramentas.

Custo, latência e falhas

Como avaliar

Avalie a escolha separada da resposta final.

• Ferramenta certa: para cada caso, qual ferramenta deveria ser chamada (ou nenhuma)?
• Argumentos certos: os argumentos batem com o esperado?
• Passos por tarefa: quantas voltas o loop deu. Subir de repente costuma indicar uma descrição confusa.
• Portão respeitado: em 100% dos casos com efeito, houve aprovação antes.

Um caso de eval:

{ "input": "cancela o pedido 4521, comprei errado", "expected_tool": "cancel_order", "expected_args": { "id": "4521" }, "requires_approval": true }

Monte casos em que nenhuma ferramenta deve ser chamada, como perguntas gerais. Eles pegam o modelo que chama ferramenta por reflexo.

Em produção

• Span por chamada de ferramenta com nome, argumentos, resultado resumido, duração e erro.
• Alerta para loops que batem no teto de passos.
• Taxa de erro por ferramenta. Uma ferramenta que falha muito costuma ter descrição ou schema ruins.
• Log de auditoria separado para toda ferramenta de efeito: quem pediu, quem aprovou, o que mudou.

Segurança

Resultado de ferramenta é texto que o modelo lê. Se ele vem de fora (um e-mail, uma página, um comentário de cliente), pode conter instruções escondidas tentando fazer o modelo chamar outra ferramenta. Greshake et al. (2023) chamaram isso de injeção indireta. Por isso: portão em todo efeito, permissões mínimas por ferramenta e atenção ao smell Ordem Vinda do Dado.

Em 2023, funcionários da Samsung colaram código interno no ChatGPT. A lição para ferramenta é a inversa: a ferramenta não deve devolver segredo que o modelo não precisa, e o resultado não deve ir para um provedor fora da política. Corte campos, mascare dados pessoais (LGPD) e rode com a conta do usuário.

Prós e contras

Relações

• Smells que cura: respostas inventadas sobre dado vivo, Efeito Sem Portão quando a ação era só texto, e parte de Prompt Inchado quando o remendo era colar dados no prompt.
• Refatorações: Mover Instrução para a Descrição da Ferramenta, Dividir Ferramenta Deus, Adicionar Aprovação antes do Efeito.
• Vizinhos: Roteador de Ferramentas quando a lista cresce. Humano no Circuito é o portão. Trocar Chamada de LLM por Código quando a ferramenta esconde uma conta determinística.

Código

As abas montam o mesmo assistente: uma ferramenta de leitura, uma de efeito com portão e um teto de passos. Python escreve o loop. TypeScript usa o runner da Anthropic. Python + LangChain, Python + OpenAI Agents, Python + Pydantic AI e TypeScript + AI SDK são o mesmo loop em outra stack. O portão fica dentro da ferramenta de efeito em todas.

import json

import anthropic

client = anthropic.Anthropic()
MAX_STEPS = 8

TOOLS = [
    {
        "name": "get_order",
        "description": "Busca status, itens e previsão de entrega de um pedido. Use quando o cliente citar um número de pedido.",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {"id": {"type": "string", "description": "Número do pedido, só dígitos"}},
            "required": ["id"],
            "additionalProperties": False,
        },
    },
    {
        "name": "cancel_order",
        "description": "Cancela um pedido ainda não enviado. Só use depois de o cliente pedir o cancelamento de forma explícita.",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {"id": {"type": "string", "description": "Número do pedido, só dígitos"}, "reason": {"type": "string"}},
            "required": ["id", "reason"],
            "additionalProperties": False,
        },
    },
]


def run_tool(name: str, args: dict, approve) -> str:
    # 5. portão para efeitos colaterais
    if name == "cancel_order" and not approve(args):
        return json.dumps({"error": "o cliente não confirmou o cancelamento"})
    # 4. execução com as permissões do seu sistema (orders é o seu serviço de pedidos)
    handler = {"get_order": orders.get, "cancel_order": orders.cancel}[name]
    return json.dumps(handler(**args))


def answer(messages: list, approve) -> str:
    for _ in range(MAX_STEPS):  # 6. orçamento de passos
        reply = client.messages.create(
            model="claude-opus-5-5", max_tokens=4096,
            system="Você é o assistente de pedidos da loja.", tools=TOOLS, messages=messages,
        )
        if reply.stop_reason != "tool_use":  # 7. resposta final
            return next(b.text for b in reply.content if b.type == "text")

        messages.append({"role": "assistant", "content": reply.content})
        results = [
            {"type": "tool_result", "tool_use_id": b.id, "content": run_tool(b.name, b.input, approve)}
            for b in reply.content if b.type == "tool_use"
        ]
        messages.append({"role": "user", "content": results})  # todos os resultados juntos

    return "Vou passar para uma pessoa do time."

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

const client = new Anthropic();

export async function answer(question: string, approve: (args: unknown) => Promise<boolean>) {
  const getOrder = betaZodTool({
    name: "get_order",
    description: "Busca status, itens e previsão de entrega de um pedido. Use quando o cliente citar um número de pedido.",
    inputSchema: z.object({ id: z.string().regex(/^[0-9]+$/) }),
    run: async ({ id }) => JSON.stringify(await orders.get(id)), // 4. leitura
  });

  const cancelOrder = betaZodTool({
    name: "cancel_order",
    description: "Cancela um pedido ainda não enviado. Só use depois de o cliente pedir o cancelamento de forma explícita.",
    inputSchema: z.object({ id: z.string().regex(/^[0-9]+$/), reason: z.string() }),
    run: async (args) => {
      // 5. portão para efeitos colaterais
      if (!(await approve(args))) return JSON.stringify({ error: "o cliente não confirmou o cancelamento" });
      return JSON.stringify(await orders.cancel(args.id, args.reason));
    },
  });

  // 2 a 7. o runner chama o modelo, executa as ferramentas e repete até a resposta final
  const final = await client.beta.messages.toolRunner({
    model: "claude-opus-5-5",
    max_tokens: 4096,
    system: "Você é o assistente de pedidos da loja.",
    tools: [getOrder, cancelOrder],
    messages: [{ role: "user", content: question }],
  });
  return final.content.find((b) => b.type === "text")?.text ?? "";
}

import json

from langchain.agents import create_agent
from langchain.tools import tool


@tool
def get_order(id: str) -> str:
    """Busca status, itens e previsão de entrega de um pedido. Use quando o cliente citar um número de pedido."""
    return json.dumps(orders.fetch(id))  # 4. leitura


@tool
def cancel_order(id: str, reason: str) -> str:
    """Cancela um pedido ainda não enviado. Só use depois de o cliente pedir o cancelamento de forma explícita."""
    # 5. portão para efeitos colaterais
    if not approve({"id": id, "reason": reason}):
        return json.dumps({"error": "o cliente não confirmou o cancelamento"})
    return json.dumps(orders.cancel(id, reason))


# "provedor:modelo". create_agent devolve um grafo LangGraph.
agent = create_agent(
    "openai:gpt-4o-mini",
    tools=[get_order, cancel_order],
    system_prompt="Você é o assistente de pedidos da loja.",
)


def answer(question: str) -> str:
    # 2 a 7. o agente chama o modelo, executa as ferramentas e para na resposta
    result = agent.invoke(
        {"messages": [{"role": "user", "content": question}]},
        {"recursion_limit": 16},  # 6. cada passo do grafo conta
    )
    return result["messages"][-1].text

from agents import Agent, Runner, function_tool

@function_tool
def get_order(id: str) -> str:
    """Busca status, itens e previsão de entrega de um pedido."""
    return json.dumps(orders.fetch(id))

@function_tool
def cancel_order(id: str, reason: str) -> str:
    """Cancela um pedido ainda não enviado."""
    # 5. portão
    if not approve({"id": id, "reason": reason}):
        return json.dumps({"error": "o cliente não confirmou o cancelamento"})
    return json.dumps(orders.cancel(id, reason))

agent = Agent(
    name="orders",
    instructions="Você é o assistente de pedidos da loja.",
    tools=[get_order, cancel_order],
    model="gpt-4o-mini",
)

def answer(question: str) -> str:
    result = Runner.run_sync(agent, question, max_turns=8)  # 6
    return str(result.final_output)

from pydantic_ai import Agent
from pydantic_ai.usage import UsageLimits

agent = Agent("openai:gpt-4o-mini", system_prompt="Você é o assistente de pedidos da loja.")

@agent.tool_plain
def get_order(id: str) -> str:
    """Busca status, itens e previsão de entrega de um pedido."""
    return json.dumps(orders.fetch(id))

@agent.tool_plain
def cancel_order(id: str, reason: str) -> str:
    """Cancela um pedido ainda não enviado."""
    if not approve({"id": id, "reason": reason}):  # 5
        return json.dumps({"error": "o cliente não confirmou o cancelamento"})
    return json.dumps(orders.cancel(id, reason))

def answer(question: str) -> str:
    return agent.run_sync(question, usage_limits=UsageLimits(request_limit=8)).output

import { generateText, stepCountIs, tool } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

export async function answer(question: string): Promise<string> {
  const result = await generateText({
    model: openai("gpt-4o-mini"),
    system: "Você é o assistente de pedidos da loja.",
    prompt: question,
    stopWhen: stepCountIs(8),
    tools: {
      get_order: tool({
        description: "Busca status, itens e previsão de entrega de um pedido.",
        inputSchema: z.object({ id: z.string() }),
        execute: async ({ id }) => JSON.stringify(await orders.fetch(id)),
      }),
      cancel_order: tool({
        description: "Cancela um pedido ainda não enviado.",
        inputSchema: z.object({ id: z.string(), reason: z.string() }),
        execute: async ({ id, reason }) => {
          if (!(await approve({ id, reason }))) {
            return JSON.stringify({ error: "o cliente não confirmou o cancelamento" });
          }
          return JSON.stringify(await orders.cancel(id, reason));
        },
      }),
    },
  });
  return result.text;
}

Suporte por framework

Conferido em outubro de 2026: LangChain 1.x (create_agent no lugar de create_react_agent), OpenAI Agents (Runner.run_sync, max_turns), Pydantic AI (UsageLimits) e AI SDK (stepCountIs).

Teste seu entendimento