Ao final deste guia, você será capaz de definir uma ferramenta, enviá-la para o OpenAI, ler a chamada de ferramenta que o modelo retorna e executar sua própria função com os argumentos estruturados que ele devolve. Você também ativará o modo estrito e chamadas paralelas, para então asserir e simular o lado da ferramenta com o Apidog para que você confie na saída antes que ela chegue à produção. Mantenha a documentação de chamada de função do OpenAI aberta em outra aba como fonte da verdade, e veja nosso guia sobre construção de agentes com o SDK de Agentes do OpenAI para ter uma visão de nível superior.
O que você precisa antes de começar
Chamada de função (frequentemente chamada de chamada de ferramenta) é como um modelo se conecta ao seu código e sistemas externos. Você descreve as funções que seu aplicativo expõe, o modelo lê a solicitação do usuário e, quando uma função se encaixa, ele retorna o nome da função mais um objeto JSON de argumentos. O modelo nunca executa nada por si mesmo. Ele entrega a você uma solicitação estruturada, e seu código faz o trabalho.
Essa divisão é o que você deve ter em mente ao construir. O modelo escolhe a intenção e preenche os parâmetros. Você mantém o controle da execução. Uma mensagem como "obter o clima em Paris" se transforma em uma chamada limpa get_weather({"location": "Paris, France"}) em vez de um parágrafo que você teria que analisar manualmente.
Para acompanhar, você precisa de uma chave de API do OpenAI e de uma função em seu próprio código que você deseja que o modelo possa acionar. Mais uma coisa para decidir de antemão: em qual endpoint você está. O mesmo recurso funciona em dois lugares. A API Chat Completions mais antiga o suporta, assim como a API Responses mais recente, que unifica o que costumava ser dividido entre Chat Completions e a API Assistants. As formas diferem ligeiramente, e os passos abaixo cobrem ambos.
Passo 1: Defina sua ferramenta
Uma ferramenta é uma definição de função que o modelo pode ler. Você dá a ela um nome, uma descrição e um JSON Schema para os argumentos. A descrição está fazendo um trabalho real aqui. Ela informa ao modelo quando deve buscar a função, então escreva-a como uma instrução, não como um rótulo.
Aqui está uma definição de ferramenta no formato Chat Completions, onde a função reside sob um wrapper function:
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city. Use when the user asks about temperature or conditions.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and country, e.g. Bogotá, Colombia"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"],
"additionalProperties": false
}
}
}
A API Responses simplifica isso. Os campos name, description, parameters e strict ficam no nível superior do objeto da ferramenta, sem uma chave function aninhada. Mesma informação, menos camadas.
Se você já mantém uma especificação OpenAPI para o serviço subjacente, os formatos dos parâmetros são transferidos quase diretamente. Nosso guia sobre gerar coleções de testes a partir de especificações OpenAPI mostra como esse trabalho de esquema compensa duas vezes.
Passo 2: Faça sua primeira solicitação
Envie sua ferramenta para o modelo junto com a mensagem do usuário. Uma solicitação completa do Chat Completions que faz isso se parece com isto:
curl https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4.1",
"messages": [
{"role": "user", "content": "What is the weather in Paris right now?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"],
"additionalProperties": false
}
}
}
]
}'
O array tools contém todas as funções que você deseja expor para esta vez. O modelo lê a mensagem do usuário, decide se alguma ferramenta se encaixa e responde. Quando ele escolhe uma, você recebe uma chamada de ferramenta em vez de texto, que é o que você lerá na próxima etapa.
Passo 3: Leia a chamada de ferramenta que o modelo retorna
Quando o modelo decide chamar uma função, ele não retorna texto. Ele retorna uma chamada de ferramenta que você lê da resposta.
Em Chat Completions, a mensagem do assistente contém um array tool_calls. Cada entrada possui um id, um type de function e um objeto function com o name e uma string arguments:
{
"id": "call_12345xyz",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\":\"Paris, France\"}"
}
}
Na API Responses, a chamada aparece no array output com um formato mais plano: um type de function_call, um call_id, um name e arguments:
{
"type": "function_call",
"call_id": "call_12345xyz",
"name": "get_weather",
"arguments": "{\"location\":\"Paris, France\"}"
}
Um detalhe que confunde as pessoas: arguments é uma string codificada em JSON, não um objeto analisado. Você a analisa por conta própria, executa sua função e, em seguida, envia o resultado de volta para que o modelo possa finalizar sua resposta.
Passo 4: Retorne o resultado para o modelo
Depois de executar sua função, devolva o resultado para que o modelo possa produzir uma resposta final. Em Chat Completions, você anexa uma mensagem com o papel tool associada ao id da chamada. Na API Responses, você envia um item function_call_output associado ao call_id. De qualquer forma, o ciclo é o mesmo: o modelo pergunta, você executa, você retorna o resultado, o modelo responde.
Passo 5: Adicione chamadas paralelas e modo estrito
Duas configurações mudam o quão confiável e rápido isso se torna, e você as adiciona assim que o ciclo básico funciona.
Chamadas de ferramenta paralelas. Por padrão, o modelo pode retornar mais de uma chamada de ferramenta em uma única vez. Se um usuário perguntar sobre o tempo em três cidades, você pode receber três chamadas de uma vez e executá-las juntas. Quando você preferir forçar no máximo uma chamada por vez, defina parallel_tool_calls como false.
Modo estrito. Defina strict: true na definição da função e os argumentos do modelo terão garantia de corresponder ao seu JSON Schema em vez de serem um "melhor esforço". O OpenAI recomenda sempre habilitá-lo. O modo estrito possui regras: todo objeto precisa de additionalProperties: false, e todo campo em properties deve aparecer em required. Para tornar um campo opcional, você não o remove de required; você adiciona null à sua lista de tipos permitidos.
| Configuração | O que controla | Padrão | Quando alterar |
|---|---|---|---|
parallel_tool_calls |
Se múltiplas chamadas de ferramenta podem retornar em uma única vez | true |
Defina como false quando as chamadas dependem umas das outras ou devem ser executadas em ordem |
strict |
Se os argumentos são forçados a corresponder ao esquema | melhor esforço, a menos que definido; recomendado ativar | Ative para qualquer chamada que você analise sem código defensivo |
tool_choice |
Se e qual função o modelo pode chamar | auto |
required para forçar uma chamada, none para desabilitar, ou nomeie uma para fixá-la |
A regra de campo opcional pega as pessoas de surpresa. Digamos que unit seja opcional em get_weather. No modo estrito, você ainda o lista em required, e então o marca como anulável no esquema, como "unit": {"type": ["string", "null"], "enum": ["celsius", "fahrenheit"]}. O modelo pode agora passar uma unidade real ou um null explícito, mas nunca pode omitir a chave. Essa previsibilidade é o objetivo principal: seu código de análise sabe exatamente quais chaves esperar todas as vezes.
O modo estrito reduz JSON malformado, mas não verifica se os valores fazem sentido para o negócio. Uma localização pode ser válida para o esquema e ainda assim ser uma cidade que você não atende. É aí que entra o teste.
Como testar no Apidog
O modelo fornece uma chamada de ferramenta. Antes de conectá-la a uma função ativa, você deseja duas garantias: os argumentos correspondem ao formato que você espera, e a API downstream que sua função atingiria se comporta da maneira que você assume. O Apidog cobre ambos os lados disso, e vale a pena ser preciso sobre qual.
O Apidog valida e simula o lado da API. Ele não executa as funções do seu aplicativo. O que ele faz bem é o contrato em torno delas.
Afirme a estrutura dos argumentos. Pegue a string arguments de uma chamada de ferramenta real, trate-a como um corpo de solicitação e execute asserções nela no Apidog. Verifique se location existe e é uma string, se um campo enum sempre contém um valor permitido, se os campos obrigatórios estão presentes. Extrair campos específicos do payload é fácil com expressões JSONPath, e para verificações estruturais mais profundas há validação contra um JSON Schema, que espelha o mesmo esquema que você entregou ao OpenAI no modo estrito. Se a saída do modelo passar pelo mesmo esquema que sua função espera, você fechou o ciclo.
Simule a API downstream que a função chamaria. Sua função get_weather provavelmente chama um provedor de clima. Durante o desenvolvimento, esse provedor pode ter limites de taxa, ser pago ou ainda não ter sido construído. Crie uma API mock no Apidog que retorna um payload de clima realista, aponte sua função para o mock e exercite todo o caminho da chamada sem gastar uma solicitação no serviço real. Você controla a resposta, incluindo casos de erro que a API real raramente produz sob demanda, para que você possa confirmar se seu código lida com um timeout ou um 429 antes que um usuário o encontre.
Em conjunto, o fluxo de trabalho é: capture uma chamada de ferramenta do OpenAI, afirme seus argumentos contra seu esquema no Apidog, e então execute sua função contra um mock do Apidog da API real. Você verifica o contrato em ambas as extremidades sem gastar chamadas ao vivo ou adivinhar casos de borda.
Perguntas frequentes
A chamada de função funciona tanto em Chat Completions quanto na API Responses? Sim. Ambos os endpoints a suportam. A API Responses unifica recursos que antes eram divididos entre Chat Completions e a API Assistants. A principal diferença é a forma: Chat Completions aninha a função sob uma chave function e retorna tool_calls, enquanto a API Responses usa uma definição de ferramenta plana e retorna itens function_call no array output.
Por que o modelo retorna os argumentos como uma string em vez de um objeto? O campo arguments é texto codificado em JSON. Você o analisa em seu código antes de usá-lo. Isso é consistente em ambas as APIs, então sempre passe-o pelo seu analisador JSON e valide o resultado em vez de confiar cegamente. Passar esses argumentos pela validação de JSON Schema detecta um payload malformado antes que ele chegue à sua função.
O modo estrito garante que a função será bem-sucedida? Não. O modo estrito garante que os argumentos correspondam ao seu JSON Schema, portanto a estrutura é confiável. Ele não verifica se os valores estão corretos para sua lógica de negócios e não executa sua função. Você ainda valida os valores e lida com as falhas da chamada downstream por conta própria.
O Apidog pode executar minha função real? Não, e ele nem tenta. O Apidog valida os argumentos produzidos pelo modelo e simula a API da qual sua função depende. Seu aplicativo ainda executa suas próprias funções. O Apidog cobre o contrato em ambos os lados para que você confie nas entradas e nas dependências antes de entrar em produção.
Conclusão
Agora você tem o ciclo completo: defina suas ferramentas claramente, envie-as com a solicitação, leia a saída tool_calls ou function_call, retorne o resultado, então ative o modo estrito e decida se chamadas paralelas ajudam ou prejudicam. Finalize com testes, afirmando que os argumentos correspondem ao seu esquema e simulando a API downstream para que você tenha confiança antes da produção.
Quer experimentar o lado dos testes? Baixe o Apidog para afirmar os argumentos de chamada de ferramenta contra seu esquema e simular as APIs das quais suas funções dependem, tudo em um só lugar.