Arhitectura apelului de funcții în API-ul Responses
Pe această pagină
Actualizat la 2 noiembrie 2026 pe baza documentației OpenAI: instrumentul Code Interpreter necesită acum un parametru
container(adăugat în toate exemplele), părțile de text de intrare utilizează tipulinput_text, iar căutarea web folosește instrumentulweb_search(web_search_previeweste acum un instrument legacy fără filtre de domeniu). Fișierele generate sunt recuperate folosind funcțiilefichiers_generesșitelechargerdin Lecția 10. Surse: Code Interpreter · Web search.
Arhitectura apelului de funcții în API-ul Responses
Apelul de funcții este mecanismul central care permite modelelor OpenAI să interacționeze cu lumea exterioară. În API-ul Responses, acest mecanism a fost reproiectat pentru a fi mai robust, mai predictibil și integrat nativ cu instrumente încorporate precum Web Search și Code Interpreter.
Principiul fundamental
Modelul nu execută niciodată direct o acțiune. El emite intenții structurate pe care codul dumneavoastră le interceptează și le execută. Enunțat astfel, ar putea părea o limitare tehnică; în realitate, este alegerea de design care face posibil tot restul.
Gândiți-vă la alternativa opusă. Dacă modelul ar executa acțiuni direct, ar trebui să îi transmiteți credențialele bazei de date, cheile API și permisiunile de scriere – și nu ați avea niciun punct în care să verificați ceva. Prin decuplare, fiecare intenție trece prin codul dumneavoastră: validați argumentele, impuneți regulile de afaceri și refuzați dacă este necesar. Modelul propune, codul dumneavoastră dispune, iar această frontieră este ceea ce vă permite să puneți apelul de funcții în producție fără a pierde controlul.
from openai import OpenAI
client = OpenAI()
# Declararea unui instrument personalizat
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 unui răspuns
Un răspuns nu conține fie text fie apeluri de instrumente: output este o listă eterogenă care le poate amesteca pe ambele. Obiceiul pe care trebuie să îl adoptați încă de la prima linie de cod este să iterați peste această listă, în loc să citiți output[0] – un model care își explică raționamentul înainte de a apela o funcție produce exact acest caz, iar codul care citește primul element se va strica în ziua în care modelul începe să adauge comentarii.
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}")
Identificatorul call_id este esențial: acesta leagă apelul de rezultatul său atunci când trimiteți răspunsul înapoi la model. La un singur apel, abia îl observați; la trei apeluri paralele, este singurul lucru care vă împiedică să atribuiți vremea din Lyon unei cereri despre Marseille. Returnați întotdeauna rezultatul cu call_id pe care l-ați primit, niciodată cu un ID pe care îl reconstruiți din partea dumneavoastră.
Bucla completă
Acest ciclu în patru pași este invariant: se aplică pentru o funcție sau pentru douăzeci, pentru un apel simplu sau pentru un agent care înlănțuie zece instrumente. Toată complexitatea pe care o veți întâlni mai târziu – paralelism, erori, soluții de rezervă – constă în instrumentarea acestei bucle, niciodată în înlocuirea ei.
import json
# 1. Primul apel cu instrumentele declarate
response = client.responses.create(
model="gpt-5.6-terra",
input="What is the balance for client [email protected]?",
tools=tools
)
# 2. Detectarea și executarea apelurilor de funcții
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. Trimiterea rezultatelor înapoi la model
response_finale = client.responses.create(
model="gpt-5.6-terra",
input=response.output + resultats,
tools=tools
)
# 4. Modelul formulează răspunsul său natural
print(response_finale.output_text)
Diferențe cheie față de Chat Completions
API-ul Responses aduce mai multe îmbunătățiri arhitecturale.
Gestionarea nativă a instrumentelor încorporate
Instrumentele încorporate sunt declarate exact ca funcțiile dumneavoastră, dar se execută în partea OpenAI. Consecința practică este plăcută: nu scrieți nicio buclă pentru ele. Modelul apelează, obține rezultatul și continuă, totul într-o singură dus-întors. Bucla descrisă mai sus privește doar funcțiile dumneavoastră – cele care rulează pe mașina dumneavoastră.
# Amestecarea instrumentelor încorporate și a celor personalizate
tools = [
{"type": "web_search"},
{"type": "code_interpreter", "container": {"type": "auto"}},
{
"type": "function",
"name": "ma_fonction",
"description": "My custom function",
"parameters": {"type": "object", "properties": {}}
}
]
Identificatori de apel stabili
Fiecare apel de funcție primește un call_id unic care vă permite să urmăriți precis cărui apel îi corespunde哪个 rezultat, chiar și cu apeluri paralele.
Flux simplificat
Nu este nevoie să gestionați manual rolurile assistant și tool în mesaje. Câmpul input acceptă direct concatenarea ieșirilor anterioare cu rezultatele funcțiilor.
Când apelează modelul o funcție?
Modelul decide să apeleze o funcție atunci când cererea utilizatorului necesită informații pe care nu le deține, când descrierea funcției corespunde nevoii identificate și când parametrii necesari pot fi deduși din context.
Trebuie donc să fie îndeplinite simultan trei condiții, iar acest lucru este util pentru depanare: atunci când o funcție nu este apelată deși ar trebui, cauza este aproape întotdeauna a doua – o descriere care nu acoperă modul în care utilizatorul și-a formulat cererea. Parametrul tool_choice vă permite să forțați comportamentul atunci când descrierea nu este suficientă:
# Lăsați modelul să decidă
tool_choice = "auto"
# Forțați un apel către o funcție specifică
tool_choice = {"type": "function", "name": "rechercher_client"}
# Interziceți toate apelurile de funcții
tool_choice = "none"
# Cereți cel puțin un apel fără a specifica care
tool_choice = "required"
Puncte cheie
- Apelul de funcții este un protocol de intenție, nu un protocol de execuție
- Bucla apel-execuție-retur este modelul fundamental
- Instrumentele încorporate și cele personalizate coexistă în același tablou
tools call_idasigură trasabilitatea pentru fiecare apeltool_choicevă permite să controlați fin comportamentul modelului