OpenAI Function Calling: Exemplos para Começar

Name

Viktor Zinchenko

Updated on 14/11/2025

No cenário em constante evolução da inteligência artificial (AI), o function calling da OpenAI (agora exposto via tools) se tornou um dos blocos de construção mais importantes para aplicações reais. Ele permite conectar modelos de linguagem poderosos como gpt-4.1 e gpt-4.1-mini às suas próprias APIs, bancos de dados e lógica de negócio.

Em vez de pedir ao modelo para “escrever um JSON” e torcer para que siga o formato, você descreve funções em JSON Schema, e o modelo retorna uma chamada de função estruturada que você pode executar com segurança no seu código.

Neste guia, você vai aprender:

• O que é o OpenAI function calling e como ele funciona hoje
• Como definir tools/funções com JSON Schema
• Exemplos práticos: agendar reuniões, obter preços de ações, reservar viagens
• Como usar recursos modernos como Structured Outputs para tornar o function calling mais confiável
• Boas práticas, armadilhas comuns e FAQs

O que é OpenAI Function Calling (Tools)?

Function calling permite que um modelo responda com chamadas de função legíveis por máquina em vez de texto puro. Na API moderna, isso é representado como tools:

• Você define tools com:
  • type: "function"
  • function.name, function.description
  • function.parameters (um JSON Schema descrevendo os argumentos)
• Você envia essas tools junto com o prompt.
• O modelo decide se deve chamar uma tool e retorna uma tool call com o nome da função e argumentos em JSON.
• Sua aplicação:
  1. Faz o parse da tool call,
  2. Executa a função correspondente no seu backend,
  3. Opcionalmente envia o resultado de volta ao modelo para gerar uma resposta final para o usuário.

Por baixo dos panos, function calling é suportado em:

• A Responses API (POST /v1/responses) – a forma recomendada para novas aplicações.
• A clássica Chat Completions API (POST /v1/chat/completions) – ainda amplamente usada e suportada.

Historicamente, function calling usava os parâmetros functions e function_call. Eles agora estão obsoletos em favor de tools e tool_choice, então todo código novo deve usar o estilo moderno.

Exemplo Básico: Agendar uma Reunião (Chat Completions API)

Vamos começar com um exemplo simples usando a Chat Completions API. Vamos pedir ao modelo para agendar uma reunião e deixá‑lo retornar argumentos estruturados para uma função schedule_meeting.

Requisição JSON (conceitual)

{
    "model": "gpt-4.1-mini",
    "messages": [
        {
            "role": "user",
            "content": "Schedule a meeting with John Doe next Tuesday at 3 PM."
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "schedule_meeting",
                "description": "Schedule a meeting in the calendar.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "attendee": {
                            "type": "string",
                            "description": "Name of the attendee for the meeting."
                        },
                        "date": {
                            "type": "string",
                            "description": "Date of the meeting in ISO 8601 format."
                        },
                        "time": {
                            "type": "string",
                            "description": "Time of the meeting, including time zone."
                        }
                    },
                    "required": ["attendee", "date", "time"],
                    "additionalProperties": false
                },
                "strict": true
            }
        }
    ],
    "tool_choice": "auto"
}

A resposta do modelo conterá algo como:

{
    "role": "assistant",
    "tool_calls": [
        {
            "id": "call_123",
            "type": "function",
            "function": {
                "name": "schedule_meeting",
                "arguments": "{\"attendee\":\"John Doe\",\"date\":\"2025-11-18\",\"time\":\"15:00 Europe/Berlin\"}"
            }
        }
    ]
}

Seu backend pode fazer o parse de arguments, chamar sua função real schedule_meeting (por exemplo, usando Google Calendar ou Outlook) e então, opcionalmente, enviar o resultado de volta ao modelo para uma mensagem de confirmação mais amigável.

Exemplo: Consulta de Preço de Ação

Aqui vai um exemplo mais “estilo API”: chamar uma função get_stock_price com base em linguagem natural.

Requisição com uma tool get_stock_price

{
    "model": "gpt-4.1-mini",
    "messages": [
        {
            "role": "user",
            "content": "What's the current price of Apple stock?"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_stock_price",
                "description": "Get the current stock price for a ticker symbol.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "ticker_symbol": {
                            "type": "string",
                            "description": "Ticker symbol of the stock, e.g. AAPL."
                        },
                        "currency": {
                            "type": "string",
                            "enum": ["USD", "EUR", "GBP"],
                            "description": "Currency for the price."
                        }
                    },
                    "required": ["ticker_symbol"],
                    "additionalProperties": false
                },
                "strict": true
            }
        }
    ],
    "tool_choice": "auto"
}

Quando o usuário pergunta “What’s the current price of Apple stock?”, o modelo produzirá uma chamada de tool como:

{
    "type": "function",
    "function": {
        "name": "get_stock_price",
        "arguments": "{\"ticker_symbol\":\"AAPL\",\"currency\":\"USD\"}"
    }
}

Você então:

1. Chama sua API real de preços de ações.
2. Retorna o resultado para o modelo em uma requisição de continuação.
3. Deixa o modelo gerar uma explicação em linguagem natural.

Exemplo: Reserva de Viagem com Function Calling

Function calling se destaca quando os prompts são bagunçados e humanos, mas seu backend precisa de parâmetros limpos e estruturados.

Considere esta frase:

“I need to book a trip from Bonn to Amsterdam for my wife, mother, my two sons, my daughter, and me. The airline must fly direct.”

Queremos que o modelo extraia:

• departure
• destination
• number_people
• travel_mode (por exemplo, avião / trem)

Definição da tool book_travel

{
    "model": "gpt-4.1-mini",
    "messages": [
        {
            "role": "user",
            "content": "I need to book a trip from Bonn to Amsterdam for my wife, mother, my two sons and daughter, and me. The airline must fly direct."
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "book_travel",
                "description": "Search or book transportation for a group of travelers.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "departure": {
                            "type": "string",
                            "description": "City or airport you are traveling from."
                        },
                        "destination": {
                            "type": "string",
                            "description": "City or airport you are traveling to."
                        },
                        "number_people": {
                            "type": "integer",
                            "description": "How many people are traveling."
                        },
                        "travel_mode": {
                            "type": "string",
                            "enum": ["plane", "train", "bus", "car"],
                            "description": "Preferred mode of travel."
                        },
                        "non_stop_only": {
                            "type": "boolean",
                            "description": "Whether only non-stop options are allowed."
                        }
                    },
                    "required": ["departure", "destination", "number_people"],
                    "additionalProperties": false
                },
                "strict": true
            }
        }
    ],
    "tool_choice": "auto"
}

O modelo pode emitir:

{
    "name": "book_travel",
    "arguments": "{\"departure\":\"Bonn\",\"destination\":\"Amsterdam\",\"number_people\":6,\"travel_mode\":\"plane\",\"non_stop_only\":true}"
}

A partir daí, você pode conectar isso diretamente ao seu serviço de busca de voos.

Usando os SDKs Modernos da OpenAI (Python & JavaScript)

Normalmente você não enviará JSON bruto manualmente. Em vez disso, usará os SDKs oficiais e trabalhará com respostas tipadas.

Exemplo em Python (Chat Completions + tools)

from openai import OpenAI
 
client = OpenAI()
 
tools = [
    {
        "type": "function",
        "function": {
            "name": "schedule_meeting",
            "description": "Schedule a meeting in the calendar.",
            "parameters": {
                "type": "object",
                "properties": {
                    "attendee": {"type": "string"},
                    "date": {"type": "string"},
                    "time": {"type": "string"},
                },
                "required": ["attendee", "date", "time"],
                "additionalProperties": False,
            },
            "strict": True,
        },
    }
]
 
completion = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[
        {
            "role": "user",
            "content": "Schedule a meeting with John Doe next Tuesday at 3 PM.",
        }
    ],
    tools=tools,
    tool_choice="auto",
)
 
tool_calls = completion.choices[0].message.tool_calls
if tool_calls:
    call = tool_calls[0]
    args = client.responses._client._utils.json.loads(call.function.arguments)
    # Sua implementação real:
    # result = schedule_meeting(**args)

Exemplo em JavaScript (Node.js)

import OpenAI from "openai";
 
const client = new OpenAI();
 
const tools = [
    {
        type: "function",
        function: {
            name: "get_stock_price",
            description: "Get the current price for a given ticker symbol.",
            parameters: {
                type: "object",
                properties: {
                    ticker_symbol: {
                        type: "string",
                        description: "Stock ticker symbol, e.g. AAPL",
                    },
                },
                required: ["ticker_symbol"],
                additionalProperties: false,
            },
            strict: true,
        },
    },
];
 
const response = await client.chat.completions.create({
    model: "gpt-4.1-mini",
    messages: [
        { role: "user", content: "What's the current price of Apple stock?" },
    ],
    tools,
    tool_choice: "auto",
});
 
const toolCalls = response.choices[0].message.tool_calls;

Structured Outputs: Function Calling Mais Confiável

JSON Mode garante que o modelo retorne um JSON válido, mas não necessariamente um JSON que corresponda ao seu schema. Structured Outputs é um recurso mais recente que reforça isso, aplicando seu JSON Schema quando o modelo chama tools:

• Configure "strict": true na definição function da sua tool.
• Os argumentos do modelo passam a ser garantidamente compatíveis com seu schema (tipos, campos obrigatórios, sem propriedades extras), reduzindo drasticamente erros de parsing e validação.

Isso é especialmente útil quando:

• Você extrai dados complexos e aninhados de texto não estruturado
• Constrói fluxos de múltiplas etapas em que cada passo depende de dados estruturados precisos
• Gera parâmetros para sistemas posteriores como SQL, pipelines de analytics ou visualizações de dados

Mesmo com Structured Outputs, você ainda deve tratar valores como entrada não confiável (por exemplo, checar intervalos, lidar com IDs ausentes, validar regras de negócio).

Padrões de Design & Boas Práticas

1. Mantenha as tools pequenas e focadas

Em vez de uma única função gigante do_everything, defina tools pequenas e componíveis:

• get_user_profile
• get_user_orders
• create_support_ticket
• schedule_meeting

Isso torna os schemas mais fáceis de manter e melhora a capacidade do modelo de escolher a tool certa.

2. Use nomes e descrições claros

• Nomes de função devem ser verbos: create_invoice, fetch_weather, book_travel.
• Descrições devem dizer quando usar a função, não apenas o que ela faz.

Ruim:

“Get data from the system.”

Bom:

“Use this function whenever the user asks about their recent orders or order history.”

3. Seja rigoroso com schemas

• Use campos required e additionalProperties: false.
• Use enums para opções conhecidas ("enum": ["plane", "train"]).
• Adicione restrições simples quando útil (formatos de string, inteiros mínimos, etc.).

4. Valide e registre tudo

• Sempre valide os argumentos das tools no servidor antes de executar.
• Registre tool calls e prompts em linguagem natural para depuração.
• Considere re‑tentativas (possivelmente com uma pequena mensagem de sistema corretiva) quando a validação falhar.

5. Encadeie tools quando necessário

Para fluxos mais complexos (por exemplo, buscar usuário → buscar pedidos → resumir), você pode:

1. Deixar o modelo chamar múltiplas tools em uma única resposta (tool calls em paralelo), ou
2. Orquestrar passo a passo no seu backend, alimentando o modelo com os resultados de tools anteriores.

Um Exemplo Concreto Multi‑Etapas: Matemática com Formatos Mistos

Vamos revisitar um exemplo clássico que mostra por que function calling é mais que um truque.

“What’s the result of 22 plus 5 in decimal added to the hexadecimal number A?”

Podemos resolver isso definindo duas tools:

• add_decimal(a: number, b: number)
• add_hex(a: string, b: string)

O fluxo:

1. O modelo chama add_decimal com argumentos { "a": 22, "b": 5 } → seu código retorna 27.
2. Você envia o resultado e a pergunta original de volta ao modelo.
3. O modelo então chama add_hex com argumentos { "a": "27", "b": "A" }.
4. Seu código retorna 31, e o modelo explica o resultado final ao usuário.

Esse padrão se generaliza para qualquer domínio: finanças, analytics, data viz, DevOps, dashboards de BI, etc. Function calling + suas próprias tools = um assistente de IA flexível e consciente do domínio.

Quer gerar qualquer tipo de gráfico facilmente com o poder do ChatGPT? Experimente o VizGPT (opens in a new tab) — descreva seus dados e gráfico em linguagem natural e obtenha visualizações bonitas sem código.

(opens in a new tab)

(opens in a new tab)

Atualizações Relacionadas da OpenAI (Visão Geral)

A OpenAI vem melhorando continuamente a experiência de function calling e tools com:

• Janelas de contexto maiores nos modelos modernos, facilitando trabalhar com conversas, documentos ou schemas longos.
• Structured Outputs para tools e formatos de resposta, garantindo que a saída do modelo siga seu JSON Schema.
• Uma Responses API mais rica e um ecossistema de tools (web search, file search, code execution e mais), tornando mais fácil construir fluxos “agentes” completos com os mesmos conceitos de function calling.

Para preços e a lista mais recente de modelos, consulte sempre a documentação oficial da OpenAI e a página de pricing.

Conclusão

Function calling é uma das formas mais poderosas de transformar LLMs em componentes práticos e confiáveis do seu stack:

• Você descreve o que suas funções podem fazer, em JSON Schema.
• O modelo decide quando e como chamá‑las.
• Seu backend executa as chamadas e, junto com o modelo, constrói experiências ricas para os usuários.

Seja para agendar reuniões, consultar preços de ações, reservar viagens ou alimentar um dashboard de BI completo com ferramentas como PyGWalker e VizGPT, function calling é a cola entre linguagem natural e ações reais.

Comece simples com uma única função, valide tudo e, depois, evolua para fluxos agentes de múltiplas etapas à medida que sua aplicação amadurece.

Perguntas Frequentes

1. O que é o recurso de function calling da OpenAI?

   Function calling permite descrever funções (tools) com JSON Schema para que o modelo possa retornar uma chamada de função estruturada em vez de texto puro. O modelo não executa nada por conta própria; sua aplicação faz o parse da tool call e roda a função real.

2. Quais modelos suportam function calling?

   Modelos modernos GPT-4, GPT-4.1, GPT-4o, GPT-4o-mini e os modelos mais novos da série GPT-5/o suportam tools/function calling através das APIs Chat Completions e Responses. Consulte a documentação da OpenAI para a lista mais atualizada de modelos suportados.

3. Devo usar os parâmetros antigos functions / function_call?

   Não. Eles foram a primeira geração de parâmetros para function calling e agora são considerados legados. Código novo deve usar tools e tool_choice, que são mais flexíveis e funcionam melhor com modelos e APIs mais recentes.

4. Em que isso é diferente de JSON Mode ou Structured Outputs?

   • JSON Mode (response_format: { "type": "json_object" }) garante que o modelo retorne JSON válido, mas não aplica seu schema.
   • Function calling com Structured Outputs (strict: true na definição da tool) garante que os argumentos correspondam ao JSON Schema que você forneceu.
   • Você pode combinar function calling com JSON Mode para ter ainda mais controle.

5. Quais são alguns casos de uso comuns?

   • Chatbots que chamam APIs externas (clima, CRM, ticketing, ferramentas internas)
   • Linguagem natural → chamadas de API, consultas SQL, filtros de busca
   • Pipelines de extração de dados que transformam texto não estruturado em registros estruturados
   • Fluxos “agentes” de múltiplas etapas para automação, analytics e BI