Tool calling: como um agente de IA chama ferramentas externas

Sem tool calling, um modelo de linguagem só sabe fazer uma coisa: produzir texto a partir de texto. Ele não consegue consultar um banco de dados atualizado, nem enviar uma mensagem, nem disparar uma ação em um software de terceiros. O tool calling é a ponte que liga um modelo a um sistema externo. É isso que transforma um modelo que conversa em um agente de IA capaz de agir, a peça básica por trás de todo agente autônomo.

Definição detalhada

O tool calling, também chamado de function calling, designa a capacidade de um modelo de linguagem de responder a uma solicitação não apenas com texto, mas com um pedido estruturado para executar uma função precisa, com argumentos preenchidos conforme um esquema definido de antemão. A documentação da Anthropic descreve o princípio assim: o modelo determina se deve chamar uma ferramenta com base na solicitação e na descrição da ferramenta, e então retorna uma chamada estruturada que a aplicação executa (do lado do cliente) ou que o próprio provedor executa (do lado do servidor, para algumas ferramentas integradas). A documentação da OpenAI, que popularizou o termo function calling em 2023, descreve um mecanismo idêntico: o modelo responde com uma chamada de função legível por máquina em vez de texto livre, cabendo à aplicação executá-la.

Os dois provedores de referência convergem na definição de fundo: uma função é descrita por um nome, uma descrição em linguagem natural, e um esquema JSON que lista seus parâmetros esperados. O modelo se apoia apenas nesses três elementos para decidir se deve chamar a ferramenta e como preencher seus argumentos. Não há divergência significativa entre as duas abordagens quanto a esse princípio básico; as diferenças estão nos detalhes de implementação (formatos de chamada paralela, ferramentas fornecidas nativamente pelo provedor, tratamento de erros).

O tool calling é o que diferencia um simples chatbot de um sistema capaz de agir sobre o mundo real: consultar um banco de dados, buscar na web, escrever em um arquivo, enviar uma mensagem, disparar um pagamento. É também a peça básica que torna possível o protocolo MCP, criado para padronizar a forma como as ferramentas são descritas e expostas a um modelo.

Como funciona

O fluxo de uma chamada de ferramenta sempre segue o mesmo esquema em várias etapas. Primeiro, a aplicação define uma lista de ferramentas disponíveis para o modelo, cada uma com seu nome, sua descrição e seu esquema de argumentos. Depois, o modelo recebe a solicitação do usuário junto com essa lista de ferramentas, e decide, conforme o contexto, se deve responder diretamente em texto ou solicitar a execução de uma ferramenta.

Se escolher chamar uma ferramenta, o modelo retorna uma resposta estruturada que contém o nome da ferramenta e os valores de seus argumentos, sem executar nada por conta própria. É a aplicação que recebe esse pedido, executa de fato a ação (chamar uma API, ler um banco, escrever um arquivo), e devolve o resultado ao modelo em uma forma que ele consiga interpretar. O modelo então continua sua resposta apoiando-se nesse resultado, e pode encadear várias chamadas de ferramentas sucessivas se a tarefa exigir.

Essa divisão é importante para a segurança: o modelo nunca executa código por conta própria, apenas propõe uma chamada. É a aplicação que mantém o controle sobre o que é realmente executado, e que pode recusar uma chamada se as condições não estiverem reunidas.

Exemplo concreto com a Atako

Na Atako, o tool calling está no centro do funcionamento de um agente. Cada integração conectada (Slack, Notion, GitHub, HubSpot, e outras quarenta ou mais) expõe um conjunto de ações precisas, como post_message no Slack ou create_issue no GitHub, que o agente pode chamar quando julga que a tarefa exige isso.

Mas, na Atako, uma chamada de ferramenta nunca é executada diretamente. Ela primeiro passa por um controle de permissão: a plataforma verifica se existe um "grant" para aquele agente e aquela conexão específica, se a ação solicitada está de fato na lista de ações autorizadas desse grant, e se o escopo concedido (somente leitura ou leitura e escrita) cobre de fato a ação em questão. Se alguma dessas condições não for atendida, a chamada é recusada e a falha é registrada. Esse caminho de decisão, agente que propõe uma chamada e depois plataforma que verifica antes de executar, é exatamente a lógica de segurança que o tool calling permite implementar: o modelo propõe, a infraestrutura decide.

Erros comuns

Um erro comum é achar que o modelo executa ele mesmo a ferramenta que chama. Isso nunca acontece: o modelo produz um pedido estruturado, e é sempre uma aplicação ou plataforma que executa de fato a ação e que pode, a qualquer momento, recusá-la.

Segundo erro: pensar que dar acesso a uma ferramenta a um modelo equivale a lhe dar um acesso total e ilimitado a esse serviço. Um sistema de tool calling bem projetado limita com precisão as ações disponíveis, com permissões por ação e por escopo, em vez de um acesso genérico "tudo ou nada".

Terceiro erro: subestimar a importância da descrição da ferramenta. O modelo conta apenas com o nome, a descrição e o esquema de argumentos para decidir quando e como chamar uma ferramenta. Uma descrição vaga ou ambígua produz chamadas mal escolhidas ou argumentos incorretos, mesmo com um modelo de alto desempenho.

Por fim, alguns confundem tool calling com MCP. O tool calling é o mecanismo básico, presente desde 2023 nos grandes provedores de modelos. O MCP é um protocolo mais recente que padroniza a forma como as ferramentas são descritas e conectadas a um modelo, para evitar desenvolver uma integração diferente para cada ferramenta e cada provedor.