Function calling: o que é e como a IA usa ferramentas e APIs

Function calling: o que é e como a IA usa ferramentas e APIs

Function calling (chamada de função) é o recurso que permite a um modelo de IA pedir a execução de uma ferramenta, como consultar um pedido ou criar um agendamento, em vez de apenas escrever texto. O modelo não executa nada sozinho: ele devolve um pedido estruturado com o nome da ferramenta e os parâmetros, o seu sistema decide se executa, chama a API e devolve o resultado para o modelo redigir a resposta. É assim que uma IA deixa de apenas conversar e passa a trabalhar com dados e sistemas reais da empresa.

Principais pontos

• Function calling é um pedido estruturado: o modelo indica qual ferramenta usar e com quais dados, mas quem executa é o seu código.
• O ciclo tem etapas previsíveis: descrever as ferramentas, receber o pedido, validar, executar, devolver o resultado e responder.
• A qualidade do resultado depende mais do desenho das ferramentas e das permissões do que da inteligência do modelo.
• Ferramentas de leitura são o melhor ponto de partida. Ferramentas que alteram dados exigem validação, registro e, muitas vezes, aprovação humana.
• Function calling é a base de agentes de IA e conversa com padrões como o MCP, mas não os substitui nem dispensa governança.

Como funciona o ciclo de chamada de ferramentas?

Um modelo de linguagem só produz texto. Ele não acessa o seu ERP, o seu CRM nem o seu calendário. Para que isso aconteça, existe uma camada intermediária, que você controla, e o ciclo costuma seguir estas etapas:

• Descrição das ferramentas: o seu sistema envia ao modelo, junto com a conversa, uma lista de ferramentas disponíveis. Cada uma tem um nome, uma explicação em linguagem natural e os parâmetros esperados, como número do pedido ou data desejada.
• Decisão do modelo: ao ler a mensagem do usuário, o modelo avalia se precisa de alguma ferramenta. Se precisar, ele não responde ao usuário ainda. Ele devolve um pedido de chamada com o nome da ferramenta e os parâmetros preenchidos.
• Validação pelo seu sistema: o código confere se a ferramenta existe, se os parâmetros fazem sentido e se aquele usuário tem permissão para aquela ação.
• Execução: só então o seu código chama a API ou consulta o banco de dados. A credencial fica no seu sistema, nunca na conversa com o modelo.
• Devolução do resultado: a resposta da API volta ao modelo como um novo trecho da conversa.
• Resposta final: com o dado real em mãos, o modelo escreve a resposta em linguagem natural. Em alguns casos, ele pede outra ferramenta antes de responder, e o ciclo se repete.

O ponto central é que o modelo propõe e o seu sistema dispõe. A palavra chamada pode enganar: o modelo não chama a API, ele solicita que ela seja chamada. Essa separação é o que torna possível aplicar regras, limites e registros.

Exemplo de negócio: cenário ilustrativo no WhatsApp

Cenário ilustrativo: uma distribuidora de materiais de construção recebe no WhatsApp muitas perguntas do tipo meu pedido já saiu? e qual o prazo para entregar no meu bairro?. A equipe de atendimento perde tempo abrindo o sistema para copiar a mesma informação.

A empresa configura um agente com três ferramentas:

• Consultar status do pedido: recebe o número do pedido e o telefone do cliente, e devolve a situação atual (separado, em rota, entregue).
• Consultar prazo de entrega: recebe o CEP e devolve a janela estimada, conforme a regra de logística já existente.
• Encaminhar para atendente: registra um resumo da conversa e o motivo, e coloca o cliente na fila humana.

O cliente escreve: oi, meu pedido do cimento já saiu?. O modelo percebe que precisa de um dado do sistema e devolve um pedido para a ferramenta de status, mas falta o número do pedido. Em vez de inventar, ele pergunta ao cliente. Com o número informado, o modelo emite a chamada. O seu código confere se o pedido pertence ao telefone que está conversando, consulta a API do ERP e devolve o status. O modelo então responde em tom natural: o pedido saiu para entrega e está em rota.

Repare no que ficou de fora de propósito: não existe ferramenta de cancelar pedido, dar desconto ou alterar endereço. Se o cliente pedir isso, o agente usa a ferramenta de encaminhamento. A lista de ferramentas é, na prática, a lista do que a IA pode fazer. Para ver como esse tipo de fluxo se encaixa em agenda e reservas, vale ler sobre agendamento automático no WhatsApp com IA.

O que o modelo decide e o que o seu sistema decide?

Uma boa forma de pensar é dividir responsabilidades de forma explícita. Use esta lista como guia de decisão:

• O modelo decide: se a mensagem exige uma ferramenta, qual delas é a mais adequada, quais parâmetros extrair da conversa e como explicar o resultado ao usuário.
• O seu código decide: quais ferramentas existem para cada usuário, se os parâmetros são válidos, se a ação é permitida, se precisa de aprovação e quantas vezes pode ser repetida.
• O processo de negócio decide: o que é permitido automatizar, quando passar para uma pessoa e quem responde pelo resultado.

Quando essas fronteiras ficam borradas, surgem os problemas clássicos: o agente que consulta o pedido de outro cliente porque ninguém conferiu o dono do pedido, ou o que executa uma ação duas vezes porque a primeira resposta demorou. Nenhum desses erros é falha de inteligência do modelo. São falhas de desenho do sistema ao redor dele.

Como desenhar ferramentas que a IA consegue usar bem

A documentação da Anthropic sobre como escrever ferramentas eficazes para agentes destaca que ferramentas são um contrato entre um sistema determinístico e um agente que não é determinístico. Isso muda a forma de projetar. Algumas práticas que seguem essa linha:

• Nomes e descrições claros: a descrição é lida pelo modelo como instrução. Diga o que a ferramenta faz, quando usar e quando não usar.
• Poucas ferramentas, bem separadas: muitas ferramentas parecidas confundem o modelo. Prefira poucas, com propósito distinto.
• Parâmetros simples e tipados: peça número do pedido, não um texto livre. Quanto mais restrito o formato, menos espaço para erro.
• Respostas enxutas: devolva só o que o modelo precisa para responder. Retornar o cadastro inteiro do cliente gasta contexto e expõe dados sem necessidade.
• Mensagens de erro úteis: se o pedido não foi encontrado, a ferramenta deve dizer isso de forma clara, para o modelo pedir a informação certa em vez de adivinhar.
• Separar leitura de escrita: consultar e alterar devem ser ferramentas diferentes, com regras diferentes.

O guia Building effective agents, também da Anthropic, recomenda começar pela solução mais simples e só aumentar a complexidade quando ela se justificar. No contexto de ferramentas, isso significa que muitas vezes um fluxo fixo, com uma ou duas chamadas bem definidas, resolve melhor do que um agente com autonomia ampla.

Quais riscos aparecem quando a IA passa a agir?

Assim que o modelo pode acionar sistemas, o risco deixa de ser apenas uma resposta ruim e passa a ser uma ação indevida. Os pontos de atenção mais comuns:

• Permissão excessiva: a credencial usada pela ferramenta tem mais acesso do que o necessário. Aplique o princípio do menor privilégio e uma conta de serviço com escopo restrito.
• Falta de verificação de identidade: a ferramenta recebe um número de pedido, mas ninguém confere se ele pertence a quem pergunta.
• Injeção de instruções (prompt injection): textos vindos de e-mails, documentos ou mensagens podem conter comandos disfarçados que tentam fazer o modelo usar uma ferramenta de forma indevida. O material da OWASP sobre prevenção de prompt injection é uma boa referência para tratar entrada não confiável.
• Ações repetidas: se uma chamada de escrita for repetida por falha de rede, o efeito pode se duplicar. Ferramentas que alteram dados devem ser idempotentes ou ter uma chave de controle.
• Dados pessoais em excesso: o que a ferramenta devolve passa a fazer parte da conversa. Sob a LGPD, vale limitar o dado ao mínimo necessário para a finalidade e registrar o que foi acessado.
• Ausência de rastro: sem registro de qual ferramenta foi chamada, com quais parâmetros e qual foi o resultado, não há como auditar nem melhorar.

Os controles que respondem a esses riscos estão detalhados em guardrails para agentes de IA, que trata de validação na entrada, na saída e na ação. Para ações que mudam dinheiro, cadastro ou compromisso com o cliente, uma regra de aprovação humana é um complemento sensato.

Function calling, MCP e agentes: como se relacionam?

Function calling é o mecanismo básico: o modelo pede, o sistema executa. Um agente é um arranjo que repete esse ciclo, com o modelo decidindo os próximos passos até concluir uma tarefa. Já o MCP (Model Context Protocol) é um padrão aberto para conectar aplicações de IA a ferramentas e fontes de dados de forma uniforme. A introdução oficial ao MCP explica a ideia: em vez de cada integração ser feita sob medida, um servidor expõe ferramentas e dados num formato que vários clientes de IA entendem.

Na prática, a escolha entre chamar a API diretamente no seu código ou expor um servidor MCP depende de quantos sistemas e quantas aplicações de IA precisarão usar as mesmas ferramentas. Para um único fluxo, a integração direta costuma bastar. Se a empresa quer reaproveitar o acesso a um sistema interno em várias frentes, vale considerar um servidor MCP, começando por ferramentas de leitura, como descrito em como criar um servidor MCP para o sistema interno.

Como começar sem criar um problema: mapear, limitar, pilotar e transferir

O método que aplicamos a projetos desse tipo segue quatro movimentos, e cada um tem relação direta com o ciclo de ferramentas.

• Mapear: descreva o processo atual, quem pergunta o quê, em que sistema a resposta está e quanto tempo isso consome hoje. Sem esse ponto de partida, não há como saber se a IA melhorou algo.
• Limitar: escolha poucas ferramentas, de preferência de leitura, com credenciais de escopo mínimo, dados reduzidos ao necessário e regras claras de quando passar para uma pessoa.
• Pilotar: coloque um fluxo real em operação restrita, com registro de cada chamada e uma métrica de sucesso combinada antes de começar.
• Transferir: ao final do piloto, entregue a documentação, os registros e os critérios, e decida com a equipe se expande, ajusta ou encerra.

Um checklist curto antes de liberar qualquer ferramenta nova:

• A ferramenta tem um propósito único e uma descrição que um colega entenderia sem contexto?
• Ela só lê ou também altera dados? Se altera, quem aprova e como se desfaz?
• A credencial usada tem o menor acesso possível?
• O sistema confere se o usuário tem direito àquele dado antes de executar?
• Cada chamada fica registrada com parâmetros, resultado e horário?
• Existe um caminho claro de transbordo para uma pessoa, como descrito em transbordo humano em agentes de IA no WhatsApp?
• Há um limite de repetições e um tempo máximo para evitar laços e custos inesperados?

Se a resposta para alguma dessas perguntas for não sei, a ferramenta ainda não está pronta para produção.

O que muda para quem decide na empresa?

Para um gestor, o ganho de entender function calling está em fazer as perguntas certas. Em vez de perguntar se a IA é inteligente o suficiente, pergunte quais ferramentas ela terá, com que permissões, o que acontece quando uma chamada falha e quem vê o registro. Essas respostas dizem mais sobre o risco e o valor de um projeto do que a escolha do modelo.

Também ajuda separar três coisas na hora de avaliar uma proposta: o que está descrito em documentação oficial (como o formato das chamadas em cada provedor), o que vem de experiência de implementação (como desenhar ferramentas e limites) e o que ainda é hipótese a testar no piloto (como o agente se comporta com os seus clientes reais). Misturar as três leva a promessas que ninguém consegue verificar.

Perguntas frequentes

Function calling é a mesma coisa que uma API? Não. Uma API é a interface de um sistema que recebe pedidos e devolve dados. Function calling é o mecanismo pelo qual o modelo de IA indica que quer usar uma API, informando os parâmetros. A chamada real à API continua sendo feita pelo seu código, com as suas credenciais e regras.

A IA pode executar uma ação errada sozinha? Ela pode propor uma ação inadequada, por interpretar mal a conversa ou por receber instruções maliciosas dentro de um texto. Por isso a execução passa por validação no seu sistema, com permissões mínimas, limites e, para ações sensíveis, aprovação humana. Quanto menos uma ferramenta puder fazer, menor o dano possível.

Preciso de programação para usar function calling? Sim, em algum nível. Alguém precisa descrever as ferramentas, escrever o código que valida e executa as chamadas e conectar tudo ao sistema da empresa. Plataformas de automação reduzem parte desse trabalho, mas as decisões de permissão, dados e limites continuam sendo da empresa. Uma comparação entre opções está em n8n, Make ou Zapier: qual escolher.

Por onde começar na minha empresa? Escolha um fluxo repetitivo e de baixo risco, como consulta de status ou de prazo, e crie uma ou duas ferramentas apenas de leitura. Registre cada chamada, defina uma métrica de sucesso antes de começar e deixe um caminho claro para a equipe humana assumir. Depois de algumas semanas de operação observada, decida se vale expandir, ajustar ou parar.

Fontes

• Anthropic: Writing effective tools for agents
• Anthropic: Building effective agents
• OWASP: prompt injection prevention
• Model Context Protocol: introduction