Tool / function calling: o modelo chamando o mundo
Como o modelo deixa de só falar e passa a AGIR, a base de todo agente.
6 min de leitura
Escolha como aprender
combine como quiserDica: o vídeo é um resumo visual rápido; o áudio e o texto trazem a aula completa. Terminar o áudio ou o vídeo, ou passar no quiz, já conta a aula como concluída.
Até agora o modelo só fala, ele gera texto, responde perguntas, resume documentos. Mas aplicações reais precisam que ele aja: consulte um banco de dados, chame uma API, execute um cálculo. Tool calling é o mecanismo que transforma linguagem em ação, e é a fundação sobre a qual todo agente de IA é construído.
O problema: o modelo vive numa caixa de texto
Um LLM, por si só, é uma função pura: recebe tokens, devolve tokens. Ele não tem relógio, não acessa a internet, não lê o seu banco de dados, não sabe o que aconteceu ontem. Tudo que ele "sabe" foi fixado no treinamento, e o treinamento tem uma data de corte.
Isso cria um limite claro: o modelo pode raciocinar muito bem sobre o mundo, mas não pode observá-lo em tempo real nem modificá-lo. Para uma aplicação de produção, um assistente que verifica estoque, um agente que cria tickets, um chatbot que consulta o histórico do cliente, isso é um bloqueio fundamental.
A saída óbvia seria deixar o modelo executar código arbitrário. Mas isso é perigoso e incontrolável. A solução elegante é outra: você define um conjunto de ferramentas com contratos explícitos, e o modelo aprende a pedir para usá-las, sem executar nada diretamente. Quem executa é o seu código. O modelo apenas declara a intenção.
Como tool calling funciona: intenção, execução e retorno
O fluxo tem três atores: o modelo, o runtime (seu código) e a ferramenta (qualquer sistema externo). Veja o ciclo completo:
- Você descreve as ferramentas no prompt do sistema, nome, descrição em linguagem natural e um schema JSON dos parâmetros. O modelo não vê código; ele vê um contrato.
- O usuário faz uma pergunta que requer dados externos: "Qual o saldo atual da conta 42?"
- O modelo decide que precisa de uma ferramenta e emite um bloco JSON estruturado, não uma resposta em prosa, mas uma intenção de chamada:
{ "tool": "get_account_balance", "parameters": { "account_id": "42" } }. - O runtime intercepta essa intenção, valida os parâmetros, chama o sistema real (banco de dados, API, serviço) e captura o resultado.
- O resultado é devolvido ao modelo como uma nova mensagem no contexto. O modelo lê o resultado e gera a resposta final para o usuário.
O ponto crítico: o modelo nunca executa nada. Ele produz texto estruturado que parece uma chamada de função. Quem decide se executa, com quais permissões e em qual ambiente é sempre o seu runtime. Esse design é o que torna o mecanismo seguro por construção, desde que você respeite o princípio do menor privilégio, que veremos na Lição 10.
Ciclo completo de tool calling
Um único passo de tool calling, não é um agente ainda, é a unidade atômica de ação.
- System Prompt · + tool schemas
- LLM · inferência / inference
- Tool Intent · { JSON estruturado }
- Runtime · valida + despacha
- Autorização · menor privilégio
- API / Serviço · externo
- Banco de Dados · DB / Storage
- Resultado · da ferramenta
Na prática, o erro mais comum que vejo é tratar o JSON de intenção do modelo como se fosse uma chamada de função verificada. Não é. O modelo pode alucinar parâmetros, escolher a ferramenta errada ou ser induzido por prompt injection a chamar algo que não deveria. Seu runtime precisa validar o schema, verificar permissões e, em ferramentas destrutivas (DELETE, transferência financeira), exigir confirmação explícita antes de executar. O modelo sugere; o runtime decide.
Ordene um passo de tool calling
Como uma única chamada de ferramenta acontece.
- 1O seu runtime executa a ferramenta de verdade
- 2O resultado volta ao modelo, que continua o raciocínio
- 3Você descreve as ferramentas (nome, descrição, schema)
- 4O modelo decide chamar uma e emite os argumentos em JSON
A ponte entre linguagem e ação, e o que vem depois
Tool calling resolve um problema de interface: como fazer um sistema que raciocina em linguagem natural interagir com sistemas que falam em APIs e schemas. A resposta é elegante, você usa o próprio modelo para traduzir intenção humana em chamadas estruturadas, sem treinar um classificador separado para cada ferramenta.
Isso tem implicações profundas. Primeiro, é composável: você pode adicionar ou remover ferramentas sem retreinar o modelo, só muda o contrato no prompt. Segundo, é auditável: cada intenção é um JSON explícito que você pode logar, validar e inspecionar. Terceiro, é a unidade atômica do agente: o que chamamos de "agente" na Lição 11 é basicamente um loop que repete esse ciclo, o modelo chama uma ferramenta, recebe o resultado, decide se precisa de mais informação ou se já pode responder.
Um detalhe importante que separa tool calling de RAG (Lição 06): RAG injeta contexto antes do modelo responder, é uma busca passiva. Tool calling é uma ação durante a geração, o modelo para, pede dados, e continua. São complementares: muitos sistemas usam RAG para recuperar documentos e tool calling para buscar dados em tempo real ou executar ações com efeitos colaterais.
A descrição da ferramenta importa tanto quanto o código dela. Se a descrição for vaga, o modelo vai escolher a ferramenta errada ou preencher parâmetros incorretos. Trate o schema de cada tool como uma API pública: nomeie bem, documente os parâmetros, indique o que a ferramenta não faz.
O que fixar desta lição
Como definir uma boa ferramenta
- 1
Nome inequívoco
Use verbos e substantivos claros:
get_order_status, nãocheckouquery. O modelo usa o nome para decidir quando chamar. - 2
Descrição honesta do escopo
Diga o que a ferramenta faz E o que ela não faz. "Retorna o status de um pedido pelo ID. Não retorna histórico de pagamentos." Isso evita chamadas erradas.
- 3
Schema de parâmetros tipado
Use JSON Schema com tipos, required e descrições por campo. O modelo preenche melhor quando sabe o tipo esperado e o que cada campo significa.
- 4
Resultado previsível e conciso
Retorne apenas o que o modelo precisa para continuar o raciocínio. Payloads grandes consomem contexto e aumentam custo. Filtre no runtime, não no modelo.
- 5
Permissões mínimas no runtime
Cada ferramenta deve ter acesso apenas ao que precisa. Uma tool de consulta não deve ter permissão de escrita. Isso limita o raio de explosão se o modelo for manipulado.
Perguntas frequentes
O modelo pode chamar várias ferramentas ao mesmo tempo?
Depende do modelo e da implementação. Alguns modelos suportam chamadas paralelas (parallel tool calls) numa única resposta, o runtime executa todas e devolve os resultados juntos. Outros chamam uma de cada vez. Verifique a documentação do modelo que você está usando.
Qual a diferença entre tool calling e function calling?
São o mesmo conceito com nomes diferentes. A OpenAI popularizou "function calling"; a indústria convergiu para "tool calling" porque uma "tool" pode ser mais que uma função, pode ser um serviço, uma API, um agente subordinado. Na prática, o mecanismo é idêntico.
O que acontece se o modelo preencher um parâmetro errado?
Seu runtime deve validar o JSON contra o schema antes de executar. Se a validação falhar, devolva o erro ao modelo como resultado da tool, ele geralmente consegue se corrigir na próxima iteração. Nunca execute com parâmetros inválidos.
Quantas ferramentas posso definir?
Tecnicamente muitas, mas há um custo: cada schema de tool consome tokens de contexto e aumenta a chance de o modelo escolher errado. Em sistemas com dezenas de tools, considere carregar apenas as relevantes para o contexto atual, uma técnica chamada tool routing ou dynamic tool selection.