Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Arquitetura de chamada de funções na API de Respostas

Aula 1 de 20 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Arquitetura de chamada de funções na API de Respostas
  2. O princípio fundamental
  3. Anatomia de uma resposta
  4. O ciclo completo
  5. Diferenças chave face às Chat Completions
  6. Quando é que o modelo chama uma função?
  7. Pontos-chave

Atualizado em 2 de novembro de 2026 com base na documentação da OpenAI: a ferramenta Code Interpreter requer agora um parâmetro container (adicionado a todos os exemplos), as partes de texto de entrada utilizam o tipo input_text e a pesquisa na web usa a ferramenta web_search (web_search_preview é agora uma ferramenta legada sem filtros de domínio). Os ficheiros gerados são recuperados através das funções fichiers_generes e telecharger da Lição 10. Fontes: Code Interpreter · Web search.

Arquitetura de chamada de funções na API de Respostas

A chamada de funções é o mecanismo central que permite aos modelos da OpenAI interagir com o mundo exterior. Na API de Respostas, este mecanismo foi redesenhado para ser mais robusto, mais previsível e nativamente integrado com ferramentas incorporadas como a Pesquisa na Web e o Code Interpreter.

O princípio fundamental

O modelo nunca executa nada diretamente. Emite intenções estruturadas que o seu código intercepta e executa. Dito desta forma, pode parecer uma limitação técnica; na realidade, é a escolha de conceção que torna todo o resto possível.

Considere a alternativa. Se o modelo executasse ações por si próprio, teria de lhe entregar as credenciais da sua base de dados, chaves de API e permissões de escrita — e não teria qualquer ponto para verificar seja o que fosse. Com o desacoplamento, cada intenção passa pelo seu código: valida argumentos, impõe regras de negócio e recusa, se necessário. O modelo propõe, o seu código dispõe, e é essa fronteira que lhe permite colocar a chamada de funções em produção sem perder o controlo.

from openai import OpenAI

client = OpenAI()

# Declare a custom tool
tools = [{
    "type": "function",
    "name": "rechercher_client",
    "description": "Search for a client in the CRM by name or email",
    "parameters": {
        "type": "object",
        "properties": {
            "terme": {
                "type": "string",
                "description": "Client name, email, or ID"
            },
            "champ": {
                "type": "string",
                "enum": ["nom", "email", "id"],
                "description": "Field to search in"
            }
        },
        "required": ["terme"]
    }
}]

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Find the client Jean Dupont",
    tools=tools
)

Anatomia de uma resposta

Uma resposta não contém apenas texto ou chamadas de ferramentas: output é uma lista heterogénea que pode misturar ambos. O hábito a criar desde a sua primeira linha de código é iterar sobre esta lista em vez de ler output[0] — um modelo que explica o seu raciocínio antes de chamar uma função produz exatamente esse caso, e um código que lê apenas o primeiro elemento falhará no dia em que começar a adicionar comentários.

for item in response.output:
    if item.type == "function_call":
        print(f"Call ID  : {item.call_id}")
        print(f"Function : {item.name}")
        print(f"Args     : {item.arguments}")

O call_id é essencial: liga a chamada ao seu resultado quando envia a resposta de volta ao modelo. Numa única chamada, mal se nota; em três chamadas paralelas, é a única coisa que o impede de atribuir o tempo de Lyon a um pedido sobre Marselha. Devolva sempre o resultado com o call_id que recebeu, nunca com um ID que reconstrua do seu lado.

O ciclo completo

Este ciclo de quatro passos é invariante: aplica-se a uma função ou a vinte, a uma chamada simples ou a um agente que encadeia dez ferramentas. Toda a complexidade que encontrará mais tarde — paralelismo, erros, alternativas — consiste em instrumentar este ciclo, nunca em substituí-lo.

import json

# 1. First call with declared tools
response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the balance for client [email protected]?",
    tools=tools
)

# 2. Detect and execute function calls
resultats = []
for item in response.output:
    if item.type == "function_call":
        if item.name == "rechercher_client":
            args = json.loads(item.arguments)
            resultat = votre_crm.rechercher(args["terme"])
            resultats.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(resultat)
            })

# 3. Send results back to the model
response_finale = client.responses.create(
    model="gpt-5.6-terra",
    input=response.output + resultats,
    tools=tools
)

# 4. The model formulates its natural response
print(response_finale.output_text)

Diferenças chave face às Chat Completions

A API de Respostas traz várias melhorias arquiteturais.

Gestão nativa de ferramentas incorporadas

As ferramentas incorporadas são declaradas exatamente como as suas funções, mas são executadas no lado da OpenAI. A consequência prática é agradável: não escreve nenhum ciclo para elas. O modelo chama, obtém o resultado e continua, tudo numa única ida e volta. O ciclo descrito acima diz respeito apenas às suas funções — aquelas que correm na sua máquina.

# Mix built-in and custom tools
tools = [
    {"type": "web_search"},
    {"type": "code_interpreter", "container": {"type": "auto"}},
    {
        "type": "function",
        "name": "ma_fonction",
        "description": "My custom function",
        "parameters": {"type": "object", "properties": {}}
    }
]

Identificadores de chamada estáveis

Cada chamada de função recebe um call_id único que lhe permite rastrear com precisão qual o resultado que corresponde a qual chamada, mesmo com chamadas paralelas.

Fluxo simplificado

Não é necessário gerir manualmente as funções assistant e tool nas mensagens. O campo input aceita diretamente a concatenação de saídas anteriores com resultados de funções.

Quando é que o modelo chama uma função?

O modelo decide chamar uma função quando o pedido do utilizador requer informações que ele não possui, quando a descrição da função corresponde à necessidade identificada e quando os parâmetros necessários podem ser inferidos a partir do contexto.

Três condições devem, portanto, ser satisfeitas simultaneamente, e isso é útil para a depuração: quando uma função não é chamada mesmo devendo sê-lo, a causa é quase sempre a segunda — uma descrição que não abrange a forma como o utilizador formulou o seu pedido. O parâmetro tool_choice permite forçar o comportamento quando a descrição não é suficiente:

# Let the model decide
tool_choice = "auto"

# Force a call to a specific function
tool_choice = {"type": "function", "name": "rechercher_client"}

# Prohibit all function calls
tool_choice = "none"

# Require at least one call without specifying which
tool_choice = "required"

Pontos-chave

  • A chamada de funções é um protocolo de intenção, não um protocolo de execução
  • O ciclo chamada-execução-retorno é o padrão fundamental
  • Ferramentas incorporadas e personalizadas coexistem no mesmo array tools
  • O call_id garante a rastreabilidade de cada chamada
  • O tool_choice permite controlar finamente o comportamento do modelo