Tool calling permite oferecer funções ao modelo, como consultar bancos de dados, chamar APIs externas, buscar uma agenda ou calcular um frete. Assim, o modelo pode propor etapas em fluxos de trabalho e usar dados em tempo real sem receber permissão direta para executar ações. Quem valida e executa é a sua aplicação.
Essa fronteira é a parte mais importante do recurso. Texto probabilístico sugere uma operação; código determinístico verifica identidade, permissão, formato, limite e efeito. Tratar os argumentos do modelo como comando confiável abre o caminho para consulta indevida, cobrança duplicada ou ação diferente da que o usuário autorizou.
Este guia percorre o ciclo completo em APIs compatíveis com OpenAI e mostra onde colocar validação, confirmação, idempotência e observabilidade. Na Roteia, tools só podem ser enviadas para modelos que declaram essa capacidade no catálogo.
As quatro etapas de uma chamada de ferramenta
Primeiro, a aplicação descreve as funções disponíveis. Cada definição tem nome, finalidade e parâmetros em formato semelhante a JSON Schema. Segundo, envia essas definições junto com a conversa. Terceiro, o modelo decide responder em texto ou emitir uma ou mais tool calls com nome e argumentos. Quarto, a aplicação executa as chamadas aprovadas e devolve os resultados ao modelo, ligados pelos identificadores corretos.
Uma resposta final pode exigir duas requisições ao modelo. Na primeira ele pede buscar_pedido com um ID. Seu backend consulta o sistema. Na segunda, você envia o resultado como mensagem de ferramenta e pede ao modelo que explique ao cliente. Chamadas em sequência repetem esse ciclo; chamadas paralelas produzem mais de uma solicitação no mesmo turno.
O modelo não deve receber uma ferramenta genérica como executar_sql ou fazer_requisicao. Funções estreitas expressam intenção e deixam a autorização verificável: consultar_status_pedido, simular_frete e solicitar_cancelamento têm riscos e regras diferentes.
Descrição e schema fazem parte do produto
O nome precisa dizer o que acontece; a descrição deve explicar quando usar e quando não usar. Parâmetros obrigatórios devem ser realmente necessários. Use tipos, enumerações e limites para reduzir ambiguidades. Se status aceita apenas aberto, pago e cancelado, declare os três em vez de receber qualquer texto e tentar adivinhar depois.
Mesmo um schema estrito não comprova verdade. O modelo pode produzir um CPF com formato válido que não pertence ao cliente autenticado. Validação estrutural é a primeira camada; regras de negócio e autorização vêm depois. Recalcule preço, identidade e saldo no sistema responsável, nunca a partir do argumento sugerido.
Muitas ferramentas também ocupam janela de contexto e confundem escolha. Exponha somente as relevantes para a etapa. Um agente de suporte que precisa consultar pedido não deveria ver uma função de alterar limite financeiro. Menos opções bem descritas costumam ser mais seguras e mais fáceis de avaliar.
{
"model": "COLE_UM_ID_COM_TOOLS_DO_CATALOGO",
"messages": [{"role":"user","content":"Onde está o pedido 123?"}],
"tools": [{
"type": "function",
"function": {
"name": "consultar_status_pedido",
"description": "Consulta um pedido que pertence ao cliente autenticado",
"parameters": {
"type": "object",
"properties": {"id": {"type": "string"}},
"required": ["id"],
"additionalProperties": false
}
}
}]
}Valide como se os argumentos viessem da internet
Faça parse do JSON e valide contra um schema no servidor. Rejeite campo extra quando ele não tiver função, normalize identificadores e imponha tamanhos. Depois aplique o contexto autenticado: a pessoa pode consultar aquele pedido? A organização tem acesso ao projeto? A função está liberada naquele ambiente? O modelo não recebe o poder de responder essas perguntas.
Para leitura, aplique filtros no backend e devolva apenas os dados necessários. Para escrita, separe preparação de confirmação. Uma tool pode montar uma proposta de cancelamento e outra, chamada somente após confirmação explícita, efetivar. Valor, destinatário e consequência precisam aparecer ao usuário antes de dinheiro, mensagem ou exclusão.
Proteja também o retorno. Conteúdo vindo de página, e-mail ou banco pode conter instrução maliciosa tentando convencer o modelo a ignorar regras. Identifique o resultado como dado, limite seu tamanho e mantenha as instruções de segurança fora dele. O modelo pode resumir o resultado; não deve tratar texto recuperado como autoridade para ampliar permissão.
- Autentique a pessoa e derive tenant no servidor.
- Valide tipos, limites e relação entre campos.
- Cheque autorização por operação e por recurso.
- Peça confirmação humana para efeitos sensíveis.
Idempotência evita executar duas vezes
Rede falha, cliente repete e modelos podem pedir a mesma ação novamente. Toda operação com efeito material precisa de chave de idempotência definida pela aplicação e armazenada junto ao resultado. Se a mesma intenção chegar de novo, o serviço retorna o resultado anterior em vez de cobrar, enviar ou cancelar pela segunda vez.
Não use apenas o texto dos argumentos como chave. Duas operações legítimas podem ter valores iguais, e o modelo pode mudar ordem ou formatação. Combine identidade, operação e um identificador estável do fluxo criado no servidor. Defina também expiração e comportamento quando a primeira tentativa ficou em estado desconhecido.
Para ferramentas somente leitura, repetição costuma ser segura, mas ainda pode aumentar custo e atingir limite. Use cache quando a regra permitir e limite quantidade de chamadas por turno. Um loop em que o modelo chama a mesma consulta sem avançar precisa de condição de parada.
Devolva o resultado sem perder a ligação da chamada
A resposta do modelo traz um ID para cada tool call. Ao enviar o resultado, preserve esse ID no campo tool_call_id. Isso permite associar cada retorno à solicitação, principalmente quando há chamadas paralelas. Não invente um novo vínculo e não misture resultados em uma mensagem de usuário.
Retorne uma estrutura compacta e explícita. Em vez de despejar a linha inteira do banco, envie campos aprovados, estado e erro legível. Diferencie nao_encontrado, sem_permissao e indisponivel; dizer apenas “falhou” incentiva o modelo a preencher lacunas. Nunca esconda erro transformando-o em dado de sucesso.
Depois, o modelo pode gerar a fala final. A aplicação ainda deve validar saídas críticas. Se a ferramenta informou que o pagamento está pendente, a resposta não pode dizer que foi confirmado. Testes de integração precisam verificar esse vínculo e o efeito produzido, além de registrar qual função foi chamada.
Como testar um fluxo com tools
Crie casos em que a ferramenta deve ser chamada, não deve ser chamada e exige confirmação. Inclua argumento ausente, ID de outro cliente, retorno vazio, timeout e erro do sistema externo. Verifique nome escolhido, argumentos, autorização, número de execuções e resposta final. O teste só passa quando o efeito real corresponde à intenção permitida.
Avalie modelos com o mesmo conjunto e a mesma definição de tools. Meça taxa de escolha correta, validade dos argumentos, chamadas desnecessárias, recuperação após erro, tokens, latência e custo. Um modelo que chama mais ferramentas pode parecer ativo e ainda resolver menos tarefas.
Na Roteia, confira capabilities.tools na página do modelo antes de enviar tools. O gateway valida essa capacidade, mas não conhece as permissões do seu negócio nem executa suas funções. Essa responsabilidade continua no backend da aplicação.
Dúvidas frequentes
O modelo executa a função no tool calling?
Não. Ele produz o nome e os argumentos de uma chamada. A aplicação faz parse, valida permissão, executa o código e devolve o resultado ao modelo. Ferramentas hospedadas por um provedor são outro contrato e devem ser avaliadas separadamente.
Tool calling é a mesma coisa que structured output?
Não. Tool calling serve para pedir uma ação intermediária à aplicação. Structured output serve para formatar a resposta final conforme um schema. Os dois usam estrutura, mas têm ciclos e riscos diferentes.
Posso confiar nos argumentos se o schema for estrito?
Não. Schema prova formato, não verdade nem autorização. O servidor precisa confirmar identidade, relação com o recurso, limites e regras de negócio antes de executar.
Como evitar uma cobrança duplicada por ferramenta?
Use chave de idempotência criada no servidor, registre o resultado e devolva o mesmo estado quando a operação for repetida. Para dinheiro ou mensagem externa, separe proposta de confirmação e execução.
Todo modelo da Roteia aceita tools?
Não. O catálogo declara a capacidade por modelo. A Roteia rejeita uma chamada com tools quando o modelo escolhido não informa suporte, mas a execução e a segurança das funções continuam sob responsabilidade da sua aplicação.
Onde confirmar
Plataforma de terceiro muda de tela e de limite sem avisar. Confira na fonte oficial antes de tomar decisão baseada nesta página.