Tool calling: como conectar modelos de IA às suas funções

Como o tool calling funciona na prática

O modelo gera uma solicitação. Sua aplicação executa a operação. Para quem está conectando um LLM a uma API ou a um banco de dados, entender essa separação é o passo mais importante antes de escrever código.

Pense na comanda de um restaurante. O garçom pode pedir um prato, mas a comanda não prepara a comida. A cozinha confere o pedido, prepara o que consegue e informa o resultado. Na sua aplicação, a chamada de ferramenta é a comanda, e a função é a cozinha.

Você fornece ao modelo um schema da ferramenta: uma descrição da operação disponível e dos campos de entrada que ela aceita. O modelo pode responder com o nome da função e os argumentos, ou seja, os valores desses campos. Sua aplicação verifica a solicitação, chama a função e devolve a saída para que o modelo responda ou solicite outra operação. O guia de function calling do Google atribui explicitamente a execução à sua aplicação.

Uma ferramenta pode tanto consultar quanto alterar dados. Buscar um pedido, pesquisar em uma coleção de documentos e verificar disponibilidade são operações de ferramenta, mesmo quando nada é alterado. Para a primeira integração, vale começar com uma consulta de escopo restrito: assim, você consegue inspecionar o fluxo inteiro sem introduzir uma transação que talvez precise desfazer.

Function calling e tool calling são a mesma coisa?

Quando se trata de funções personalizadas, os termos costumam descrever o mesmo mecanismo. A OpenAI usa os dois nomes, e a Anthropic explica que o uso de ferramentas também é chamado de function calling. O termo mais amplo, “ferramenta”, pode incluir tanto recursos hospedados pelo provedor quanto funções que você implementa. O local da execução importa mais que o nome: se a função acessa seu próprio banco de dados, cabe à sua aplicação executá-la.

Essa diferença fica mais clara na documentação dos três provedores a seguir. Como os formatos de mensagem variam, use sempre os formatos de solicitação e de resultado do mesmo provedor.

Um exemplo mínimo de function calling, do início ao fim

Disponibilize uma consulta de status de pedido e devolva apenas o status informado pelo banco de dados. O exemplo a seguir usa um pedido deliberadamente fictício, ORD-1042, em um banco SQLite local. É um dado de demonstração para fins didáticos, não um registro de cliente nem uma resposta real observada do modelo.

Function calling na OpenAI: o ciclo completo em código

A documentação de function calling da OpenAI mostra o ciclo da Responses API: declarar a função, receber um function_call, executar seu código e devolver um function_call_output com o mesmo call_id.

Instale o SDK de Python com python -m pip install openai, defina OPENAI_API_KEY no ambiente e salve o código abaixo como order_tool.py. O exemplo usa gpt-6-astra, o modelo presente no exemplo de Responses da documentação atual; isso não significa que ele seja o único modelo adequado. Ao executar o script, você faz requisições reais à API, enquanto o banco de dados permanece em memória.

import json
import re
import sqlite3

from openai import OpenAI

client = OpenAI()
model = "gpt-6-astra"

# Demo identity. In a web app, obtain this from your authenticated session.
tenant_id = "tenant_demo"
db = sqlite3.connect(":memory:")
db.execute("CREATE TABLE orders (tenant_id TEXT, order_id TEXT, status TEXT)")
db.execute(
    "INSERT INTO orders VALUES (?, ?, ?)",
    (tenant_id, "ORD-1042", "shipped"),
)

# The tool schema: a name, a purpose, and an input contract.
tool = {
    "type": "function",
    "name": "get_order_status",
    "description": (
        "Look up the current status of an existing order by order ID. "
        "Use for status questions, not refunds or address changes. "
        "Returns the order ID and status, or an error."
    ),
    "strict": True,
    "parameters": {
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string",
                "description": "The order ID supplied by the user, such as ORD-1042.",
            }
        },
        "required": ["order_id"],
        "additionalProperties": False,
    },
}


def execute(name, raw_arguments):
    if name != "get_order_status":
        return {"error": "unknown_tool"}
    try:
        args = json.loads(raw_arguments)
    except (json.JSONDecodeError, TypeError):
        return {"error": "invalid_arguments"}
    if not isinstance(args, dict) or set(args) != {"order_id"}:
        return {"error": "invalid_arguments"}
    order_id = args["order_id"]
    if not isinstance(order_id, str) or not re.fullmatch(r"ORD-[0-9]+", order_id):
        return {"error": "invalid_order_id"}
    row = db.execute(
        "SELECT status FROM orders WHERE tenant_id = ? AND order_id = ?",
        (tenant_id, order_id),
    ).fetchone()
    if row is None:
        return {"error": "order_not_found"}
    return {"order_id": order_id, "status": row[0]}


history = [{"role": "user", "content": "What is the status of order ORD-1042?"}]
response = client.responses.create(
    model=model,
    input=history,
    tools=[tool],
    tool_choice={"type": "function", "name": "get_order_status"},
    parallel_tool_calls=False,
)

# Keep every output item, including any reasoning items.
history.extend(response.output)
calls = [item for item in response.output if item.type == "function_call"]
if len(calls) != 1:
    raise RuntimeError("Expected one tool call; inspect the response before continuing.")
call = calls[0]
result = execute(call.name, call.arguments)
history.append({
    "type": "function_call_output",
    "call_id": call.call_id,
    "output": json.dumps(result),
})

answer = client.responses.create(
    model=model,
    input=history,
    tools=[tool],
    tool_choice="none",
    instructions="Answer from the tool result. If it contains an error, report the failure.",
)
print(answer.output_text)
db.close()

No caminho de sucesso, esse exemplo de escopo intencionalmente limitado faz 2 requisições ao modelo e 1 consulta ao banco de dados. A primeira requisição força a consulta já definida; a segunda desabilita novas chamadas de ferramenta. Isso deixa o mecanismo visível. Um assistente de uso geral também precisaria lidar com solicitações em que nenhuma ferramenta se aplica, faltam informações ou é necessário fazer outra consulta.

O tenant_id não aparece no schema da ferramenta porque a aplicação já sabe quem está autenticado. A consulta ao banco usa essa identidade confiável junto com o identificador do pedido solicitado. Transformar a identidade em um argumento fornecido pelo modelo eliminaria a separação de responsabilidades que o exemplo pretende ensinar.

A chamada do modelo e o resultado que você devolve

A solicitação e o resultado são mensagens separadas, ligadas pelo identificador da chamada. Uma chamada típica teria o formato abaixo. Os identificadores e valores são ilustrativos; não se trata de uma resposta capturada da API.

{
  "type": "function_call",
  "id": "fc_demo",
  "call_id": "call_demo",
  "name": "get_order_status",
  "arguments": "{\"order_id\":\"ORD-1042\"}"
}

Depois que o código responsável pela chamada devolve o status do pedido de demonstração, a aplicação acrescenta este resultado. Em uma resposta real, copie o valor efetivo de call.call_id; nunca invente outro identificador.

{
  "type": "function_call_output",
  "call_id": "call_demo",
  "output": "{\"order_id\":\"ORD-1042\",\"status\":\"shipped\"}"
}

Agora o modelo tem evidências para responder algo como “O pedido ORD-1042 foi enviado”. O status veio do banco de dados. A contribuição do modelo foi transformar a solicitação em argumentos e os dados devolvidos em uma resposta.

O mesmo mecanismo na documentação dos três provedores

O padrão de execução se mantém entre provedores; o formato das mensagens, não. A comparação abaixo foi verificada na documentação oficial disponível em 17 de outubro de 2026. Ela diferencia os exemplos atuais, sem tratar campos de nomes parecidos como se fossem intercambiáveis.

Como a Anthropic implementa o uso de ferramentas

A documentação de uso de ferramentas da Anthropic define as entradas da sua função com input_schema. No caso de uma ferramenta executada no cliente, seu código processa o bloco tool_use do assistente e envia um tool_result na mensagem seguinte do usuário, preservando a mensagem do assistente na conversa.

A divisão de responsabilidades está explícita nessa documentação: as ferramentas do cliente rodam na sua aplicação; as ferramentas do servidor, na infraestrutura da Anthropic. Portanto, uma ferramenta de busca hospedada pelo provedor não demonstra que o Claude consiga executar diretamente a função do seu banco de dados privado. Essa implementação continua sendo sua responsabilidade.

Como funciona a chamada de função no Gemini

A documentação de function calling do Gemini, do Google, também separa a solicitação do modelo da execução pela aplicação. O guia atual usa a Interactions API, com etapas function_call e function_result e o campo previous_interaction_id para dar continuidade à interação.

Siga o exemplo da API que você está usando. Copiar a declaração de uma API e a mensagem de resultado de outra não torna a integração portável. Preserve a operação em comum, como get_order_status, e adapte em conjunto a declaração e o formato da mensagem de resultado.

Por que as chamadas de ferramenta sustentam o ciclo de um agente

Um agente que usa ferramentas escolhe uma operação, recebe o resultado e decide o próximo passo, repetidamente. O function calling faz a ponte entre essa decisão e uma operação que seu software consegue executar.

Um assistente de pedidos, por exemplo, poderia consultar um envio, verificar a referência da transportadora no resultado e então solicitar informações de rastreamento antes de responder. A segunda operação depende do resultado da primeira. Esse ciclo de retorno é mais útil do que pedir ao modelo que invente todas as etapas de antemão.

As orientações da Anthropic sobre arquitetura de agentes distinguem fluxos de trabalho fixos de agentes que decidem como usar as próprias ferramentas. Elas também descrevem o retorno das ferramentas e as condições de parada como partes desse ciclo.

Chamar esse mecanismo de “base de todo agente” é uma simplificação que só funciona até certo ponto. A documentação não afirma que todo sistema chamado de agente use uma API específica de function calling. A ideia central é o ciclo entre modelo e ação. Uma consulta isolada pode continuar sendo um fluxo fixo; ela não exige um planejador autônomo.

Três problemas que aparecem em produção

Trate a qualidade do schema, a escolha da ferramenta e a validação dos argumentos como problemas distintos. Corrigir um deles não prova que os outros estejam resolvidos.

Schemas ruins: o contrato permite interpretações erradas

Um campo chamado id não diz ao modelo se você quer o número de um pedido, o identificador de um cliente ou a referência de um envio. Uma string sem restrições chamada action abre espaço para valores que seu código talvez não reconheça. Melhore o contrato antes de acrescentar mais instruções ao redor dele.

Dê nomes precisos aos parâmetros, descreva seu significado e use um enum quando apenas um conjunto fixo de valores for aceito. Mantenha a primeira ferramenta restrita o suficiente para que seu propósito caiba em uma frase simples. No exemplo, order_id é explícito, e a descrição exclui reembolsos e mudanças de endereço.

O modo estrito da OpenAI exige additionalProperties: false nos objetos e que todas as propriedades apareçam em required; um valor que possa estar ausente pode aceitar null. O guia documenta esses requisitos do modo estrito. O Google também documenta restrições de schema. Portanto, um schema aceito pelo seu validador local não é automaticamente aceito por toda API de modelo.

O limite: um schema pode restringir a representação dos dados, mas um identificador de pedido válido ainda pode apontar para o pedido errado. Essa verificação cabe à aplicação.

A ferramenta errada: argumentos válidos, operação inadequada

Um cliente que pergunta “Como está meu reembolso?” precisa de uma consulta de status, não de um novo reembolso. Se a descrição das duas ferramentas diz “cuida de reembolsos”, a escolha fica ambígua.

Descreva quando cada ferramenta deve ou não ser usada e disponibilize apenas operações adequadas à tarefa e ao usuário atuais. As orientações da Anthropic para definir ferramentas recomendam especificamente explicar o propósito, o significado dos parâmetros, os limites de uso e as limitações.

Quando sua aplicação já sabe qual operação precisa executar, use um controle de escolha de ferramenta compatível ou chame a operação diretamente. O exemplo força uma consulta já definida por motivos didáticos; não transforme isso na regra de que “toda mensagem do usuário deve acionar uma ferramenta”. Uma saudação ou uma pergunta incompleta sobre um pedido pode pedir apenas uma resposta na conversa.

O limite: argumentos bem formados não mostram se o modelo escolheu a ação de negócio correta. Avalie a ferramenta escolhida com solicitações representativas dos usuários, incluindo casos em que nenhuma chamada deveria ocorrer.

Argumentos sem validação: o formato está certo, mas o acesso está errado

O código que recebe a chamada é um ponto de entrada de dados. Confira se a função está em uma lista explícita de funções permitidas, interprete os argumentos, valide seu formato e significado e controle o acesso com base na identidade autenticada pela aplicação.

No exemplo dos pedidos, um teste de falha útil é tentar consultar um pedido de outro tenant, ou seja, de outra conta de cliente. A consulta não deve devolvê-lo, mesmo que o identificador seja uma string perfeitamente válida. Outros testes incluem a ausência do identificador do pedido, um campo inesperado e a solicitação de uma operação que o código não implementa.

A visão geral da Anthropic observa que a falta de informações pode levar o modelo a inferir valores de argumentos. Não presuma que um campo obrigatório prove que o usuário forneceu aquele valor. Para uma ação de impacto, compare a operação solicitada e seus dados de entrada com o que o usuário de fato autorizou.

Quando a execução falhar, devolva uma falha que possa ser reconhecida. Um timeout não prova que a operação deixou de acontecer: antes de repetir uma gravação, use um mecanismo de idempotência na aplicação, isto é, uma forma de reconhecer a mesma operação pretendida e evitar que seu efeito se repita. Essas são recomendações de implementação, não garantias oferecidas pela API do modelo.

Quando usar saídas estruturadas

Use saídas estruturadas quando precisar de uma resposta em formato definido a partir de informações já disponíveis. Use uma ferramenta quando precisar de uma operação externa. Um classificador de mensagens de suporte que devolve categoria e urgência pode gerar uma saída estruturada. Já um assistente que precisa do status atual de um pedido tem de obter esse estado por meio de uma consulta.

O guia de Structured Outputs da OpenAI diferencia a conexão com funcionalidades da aplicação da formatação da resposta do modelo. Ele também explica que os schemas estritos de função usam Structured Outputs por baixo. São recursos complementares, não produtos que se excluem mutuamente.

Suponha que você já tenha fornecido o registro de um pedido e só precise de {order_id, status, explanation} para a interface. Uma resposta estruturada basta. Se o registro estiver faltando ou precisar ser atualizado, faça a consulta primeiro. Depois, você também pode estruturar a resposta final.

Um objeto JSON dizendo que um e-mail foi enviado continua sendo apenas um objeto de saída. Enviar o e-mail exige uma operação executada e um resultado que você possa verificar.

Function calling e MCP: qual é a diferença?

O function calling trata da solicitação de execução feita pelo modelo. O Model Context Protocol (MCP) oferece uma interface comum para disponibilizar ferramentas e outros contextos a aplicações compatíveis. Você pode conectar uma função diretamente a uma aplicação antes de introduzir um servidor de ferramentas separado.

MCP e tool calling: quando vale compartilhar ferramentas?

Se várias aplicações precisam da mesma consulta de pedidos, um servidor MCP pode disponibilizar a ferramenta para descoberta e chamada. A documentação de arquitetura do MCP descreve tools/list para descoberta e tools/call para solicitações de execução. O servidor continua precisando de uma implementação e de verificações de acesso.

Para dar esse próximo passo, leia o que é MCP e como host, cliente e servidor se conectam. Depois que sua consulta direta estiver funcionando, o guia de implementação de um servidor MCP mostra como organizar essas funcionalidades para reutilizá-las. Adotar MCP não elimina a necessidade de validar a operação solicitada.

Onde está o exagero

Passar na validação do schema comprova o cumprimento de uma restrição de formato, não a conclusão de uma tarefa. A operação pode ser inadequada, o registro pode estar inacessível ou o serviço utilizado pode estar indisponível. Uma frase final bem escrita não resolve nenhuma dessas questões.

Uma lista de ferramentas também não cria um agente por si só. Você ainda precisa definir quais ferramentas ficam disponíveis, como os resultados entram na conversa, quando parar e o que fazer após um erro. Um framework pode reunir esse trabalho, mas a política de execução continua sendo uma decisão de projeto.

O primeiro marco útil é modesto: a solicitação chega ao código responsável pela operação, apenas dados permitidos são devolvidos, e a resposta reflete esse resultado. Torne esse fluxo visível antes de ampliar os poderes do sistema.

O que colocar em produção primeiro

Comece com uma operação somente de leitura que responda a uma pergunta recorrente dos usuários. A consulta de status de pedido é um bom modelo porque permite inspecionar com facilidade tanto o resultado esperado quanto os limites de acesso.

Para quem desenvolve, vale começar agora se a resposta depender de dados que a aplicação consiga buscar com confiabilidade. Mantenha um fluxo fixo quando a próxima operação já for conhecida. Espere para introduzir operações de gravação escolhidas pelo modelo até ter permissões explícitas, tratamento de falhas e uma forma de evitar efeitos repetidos.

Para quem opera o sistema, inspecione o que foi executado e o que voltou. Registre a ferramenta escolhida, o resultado da validação, o status da execução e a correlação das chamadas, sem incluir argumentos sensíveis nos logs comuns. Defina timeouts e um número máximo de rodadas de ferramentas adequado à tarefa; não deixe o ciclo da conversa continuar sem limite.

Para quem contrata, peça à equipe de implementação que demonstre uma consulta negada e uma operação com falha, além de uma resposta bem-sucedida. Se o produto apenas resume informações já fornecidas, o function calling pode ser desnecessário. Uma saída estruturada ou a geração comum de texto pode bastar.

Para começar na segunda-feira: implemente uma consulta de escopo restrito, teste um registro permitido, um registro sem acesso e uma solicitação incompleta. Depois, inspecione o resultado devolvido ao modelo em cada caso. Amplie a lista de ferramentas só quando conseguir explicar por que cada solicitação foi aceita ou rejeitada.

Perguntas frequentes

Para receber guias práticos de desenvolvimento com IA, assine a newsletter.