Arquitetura de chamada de funções na API de Respostas
Nesta página
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 tipoinput_texte a pesquisa na web usa a ferramentaweb_search(web_search_previewé agora uma ferramenta legada sem filtros de domínio). Os ficheiros gerados são recuperados através das funçõesfichiers_generesetelechargerda 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_idgarante a rastreabilidade de cada chamada - O
tool_choicepermite controlar finamente o comportamento do modelo