Tutorial API OpenAI Agents: Construiește un agent care scrie și rulează cod în cloud

Majoritatea aplicațiilor cu LLM urmează un tipar simplu: trimiți un prompt, primești un răspuns și folosești acel răspuns în aplicația ta.

Asta funcționează bine pentru sarcini simple, dar lucrurile se complică atunci când modelul trebuie să scrie cod, să-l ruleze, să verifice rezultatul, să lucreze cu fișiere, să repare erorile și să continue până când sarcina chiar este terminată.

Aici devine cu adevărat utilă Agents API de la OpenAI.

În loc să construiești tu fiecare pas, poți să-i dai agentului sarcina, fișierele de care are nevoie și un mediu de lucru, iar el se ocupă de restul.

În acest tutorial, voi păstra exemplul simplu. Vom crea un mic set de date fictiv despre vânzările unui cafe-bar și îl vom da agentului. Agentul va scrie și rula analiza, va verifica rezultatele și va crea trei fișiere de ieșire pentru noi.

După ce vezi întregul flux funcționând în culise, vei începe să realizezi cât de mult din fluxul obișnuit de programare este automatizat pentru tine. 

Dacă ești nou în agenții AI, îți recomand să consulți parcursul de competențe AI Agents Fundamentals. 

Ce este OpenAI Agents API?

Prin OpenAI Agents API poți oferi unui agent o sarcină, fișierele de care are nevoie și mediul în care să lucreze, apoi îl lași să se ocupe de restul.

În loc să creezi manual un sandbox, să pornești o sesiune, să încarci fișiere, să rulezi cod, să verifici erori și să gestionezi fiecare pas, poți trimite o singură cerere API cu sarcina, configurația, mediul și fișierele de intrare.

După aceea, cea mai mare parte a muncii este gestionată de Agents API.

Sub capotă, OpenAI gestionează harness-ul Codex, inclusiv orchetrarea, contextul, folosirea uneltelor, execuția și sesiunile de lungă durată. Te poți gândi aproape ca la OpenAI Codex care rulează în cloud pentru aplicația ta. 

Nu trebuie să te mai îngrijorezi atât de mult de configurarea resurselor de calcul, gestionarea mediului de lucru, urmărirea sesiunii sau construirea întregii bucle a agentului de unul singur.

Acest lucru este util mai ales pentru sarcini mai complexe și de lungă durată, în care agentul chiar trebuie să facă munca, nu doar să returneze un răspuns.

Pentru acest tutorial, vom folosi un sandbox găzduit de OpenAI:

Trimitem o singură cerere cu fișierul CSV, sarcina și configurația agentului. 

Agents API apoi creează și gestionează pentru noi sesiunea și sandbox-ul.

În interiorul sandbox-ului, agentul poate să se uite la fișier, să decidă cum să abordeze analiza, să genereze cod Python, să îl ruleze, să verifice rezultatele și să repare lucrurile dacă apare ceva în neregulă.

După ce totul este gata, ieșirile sunt salvate ca artefacte ale sesiunii. 

Acestea pot fi grafice, seturi de date curățate, rapoarte sau orice alte fișiere create de agent. Le putem apoi prelua și oferi utilizatorului posibilitatea să le descarce și să le analizeze.

Așadar, ideea principală e simplă: trimitem sarcina o singură dată, iar agentul se ocupă de munca propriu-zisă de acolo.

OpenAI Responses API vs Agents SDK vs Agents API: Ce ar trebui să folosești?

Principala diferență dintre acestea trei este cât de mult din fluxul de lucru vrei să gestionezi tu însuți.

Folosește Responses API când ai nevoie ca modelul să finalizeze o sarcină focalizată, cum ar fi rezumare, extragere, clasificare, întrebări-răspunsuri, ieșiri structurate sau câteva apeluri de unelte.

Folosește Agents SDK când construiești singur o aplicație cu agenți și vrei mai mult control asupra agenților, uneltelor, handoff-urilor, guardrails și fluxurilor cu mai mulți agenți.

Folosește Agents API când sarcina este mai complexă și are nevoie de propriul mediu de lucru. Este util când agentul trebuie să lucreze cu fișiere, să ruleze cod, să inspecteze rezultatele, să repare erori și să continue pe parcursul mai multor pași.

Ghid pas cu pas: construirea unui agent de analiză de date cu OpenAI

Pentru acest tutorial, folosim Agents API pentru că agentul trebuie să lucreze cu un fișier, să gândească analiza, să ruleze cod, să inspecteze rezultatele și să salveze artefactele finale pentru utilizator.

Să începem

1. Configurează-ți mediul Python pentru Agents API

Pentru acest tutorial, vom folosi un Jupyter Notebook ca să testăm pas cu pas Agents API și să înțelegem cum funcționează fiecare parte. 

Vom începe prin a instala pachetul OpenAI și a importa bibliotecile necesare pentru restul tutorialului.

Mai întâi, instalează sau actualizează pachetul OpenAI pentru Python:

%pip install -q --upgrade openai

Apoi importă bibliotecile pe care le vom folosi:

import base64
import csv
import io
import os
import random
from datetime import date, timedelta
from pathlib import Path

from IPython.display import Markdown, display
from openai import OpenAI

Acum creează clientul OpenAI:

client = OpenAI()

Asigură-te că OPENAI_API_KEY este deja setată în mediul tău. Clientul OpenAI o va prelua automat.

2. Generează date de exemplu pentru agentul AI

Vom crea un mic set de date false despre vânzări ca să avem ceva simplu de dat agentului.

random.seed(42)

products = {
    "Latte": 4.50,
    "Tea": 3.00,
    "Cookie": 2.50,
    "Sandwich": 7.00
}

locations = ["Downtown", "Airport", "Campus"]
first_day = date(2026, 1, 1)
orders = []

for order_id in range(1, 51):
    product = random.choice(list(products))

    orders.append(
        {
            "order_id": order_id,
            "date": first_day + timedelta(days=random.randint(0, 89)),
            "location": random.choice(locations),
            "product": product,
            "units": random.randint(1, 5),
            "unit_price": products[product],
            "discount_rate": random.choice([0, 0, 0, 0.10]),
        }
    )

Acest lucru creează 50 de comenzi fictive pentru cafe-bar, pe produse, locații, date și reduceri diferite. Folosim o sămânță aleatoare fixă astfel încât același set de date este generat de fiecare dată când rulăm notebook-ul.

3. Creează și encodează fișierul CSV pentru sandbox-ul agentului

În continuare, vom transforma datele generate într-un fișier CSV care poate fi transmis agentului.

csv_buffer = io.StringIO()

writer = csv.DictWriter(
    csv_buffer,
    fieldnames=orders[0].keys()
)

writer.writeheader()
writer.writerows(orders)

csv_text = csv_buffer.getvalue()

csv_base64 = base64.b64encode(
    csv_text.encode()
).decode()

print("Preview:")
print("\n".join(csv_text.splitlines()[:6]))

Output:

Preview:
order_id,date,location,product,units,unit_price,discount_rate
1,2026-01-04,Campus,Latte,3,4.5,0
2,2026-01-18,Campus,Tea,1,3.0,0
3,2026-01-05,Downtown,Sandwich,1,7.0,0
4,2026-03-06,Campus,Tea,1,3.0,0
5,2026-01-29,Airport,Sandwich,5,7.0,0

Încodăm și CSV-ul în Base64 pentru că vom trimite fișierul direct odată cu cererea către agent.

4. Definește sarcina agentului și rezultatele așteptate

Acum vom descrie ce vrem ca agentul să facă cu fișierul CSV.

task = """
Analyze /workspace/cafe_sales.csv. Write /workspace/analyze_sales.py and run it.

Your job:
1. Check that the required columns exist and numeric values are valid.
2. Calculate gross_sales = units * unit_price.
3. Calculate net_sales = gross_sales * (1 - discount_rate).
4. Summarize net sales by location, product, and month.
5. Find the best-selling location and product by net sales.
6. Write these files:
   - /workspace/outputs/summary.json
   - /workspace/outputs/location_sales.csv
   - /workspace/outputs/morning_brief.md
7. Make the Morning Brief friendly and include three evidence-based insights.
8. Read the files back and verify that location totals equal total net sales.
9. Finish by reporting the verified total and the three output filenames.

Use only Python's standard library. Do not invent or silently change data.
""".strip()

Partea importantă este că descriem obiectivul și ieșirile așteptate, în loc să scriem noi înșine codul de analiză.

Agentul poate decide cum să facă munca, să ruleze codul și să verifice rezultatele înainte să finalizeze.

5. Rulează agentul în sandbox-ul găzduit de OpenAI

Acum vom trimite totul către Agents API într-o singură cerere și vom lăsa agentul să facă efectiv munca în cloud.

session_id = None
turn_id = None
response_parts = []

live_output = display(
    Markdown(""),
    display_id=True
)

with client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": (
            "You are a careful data analyst. "
            "Write simple code, run it, and verify the results."
        ),
    },
    environment={
        "type": "openai_hosted",
        "network": {"access": "disabled"},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/cafe_sales.csv",
                "data": csv_base64,
            }
        ],
    },
    input=task,
    stream=True,
) as events:

    for event in events:

        if hasattr(event, "session_id"):
            session_id = event.session_id

        if event.type == "agent.session.turn.output_text.delta":
            response_parts.append(event.delta)

            live_output.update(
                Markdown("".join(response_parts))
            )

        elif event.type == "agent.session.turn.completed":
            turn_id = event.turn.id

        elif event.type.endswith(("failed", "cancelled")):
            raise RuntimeError(
                event.model_dump_json(indent=2)
            )

assert session_id and turn_id

live_output.update(
    Markdown("".join(response_parts))
)

print("✅ Analysis complete")
print(f"Session: {session_id}")
print(f"Turn: {turn_id}")

Aici are loc cea mai mare parte a muncii.

Facem o singură cerere care conține configurația agentului, mediul găzduit, fișierul CSV și sarcina. 

OpenAI creează sesiunea gestionată și rulează agentul în interiorul sandbox-ului găzduit. Agentul poate apoi să inspecteze fișierul, să scrie analyze_sales.py, să îl execute, să verifice rezultatele, să repare orice problemă și să creeze fișierele finale de ieșire. 

Endpoint-ul de creare a sesiunii acceptă atât mediul, cât și intrarea inițială în aceeași cerere.

Există trei părți principale ale cererii:

• agent îi spune lui OpenAI ce model să folosească și cum ar trebui să se comporte agentul.
• environment oferă agentului spațiul său de lucru găzduit și plasează fișierul nostru CSV înăuntru.
• input oferă agentului sarcina pe care am definit-o în secțiunea anterioară.

Setăm și stream=True. 

Asta nu schimbă felul în care sarcina este finalizată. Doar ne permite să primim evenimente în timp ce agentul lucrează, în loc să așteptăm ca întregul tur să se termine înainte să vedem ceva.

În acest exemplu, ascultăm evenimentele agent.session.turn.output_text.delta și actualizăm constant notebook-ul cu cel mai recent text.

Așadar, textul pe care îl vedem apărând mai sus este modul în care agentul își raportează progresul și răspunsul final. 

Sarcina propriu-zisă continuă să ruleze în mediul găzduit până când primim evenimentul agent.session.turn.completed.

În rularea mea, agentul a creat și a rulat analyze_sales.py, a verificat fișierele generate și a confirmat vânzări nete totale de 600.55.

Partea importantă este că modelul nu ne-a spus doar ce cod Python să rulăm. Agentul a scris efectiv codul, l-a executat, a inspectat rezultatul și a verificat singur ieșirea.

6. Preia și descarcă artefactele de fișiere ale agentului

Acum că agentul a terminat, putem descărca fișierele pe care le-a creat în acel tur.

download_dir = Path("cloud_bean_results")
download_dir.mkdir(exist_ok=True)

downloaded = []

for artifact in client.beta.agents.sessions.artifacts.list(
    session_id
):
    if artifact.turn_id == turn_id:

        destination = (
            download_dir / Path(artifact.path).name
        )

        with (
            client.beta.agents.sessions.artifacts
            .with_streaming_response
            .content(
                artifact.id,
                session_id=session_id
            )
        ) as response:
            response.stream_to_file(destination)

        downloaded.append(destination)

assert downloaded

print("Downloaded:")

for path in downloaded:
    print(f"- {path}")

Output:

Downloaded:
- cloud_bean_results/summary.json
- cloud_bean_results/morning_brief.md
- cloud_bean_results/location_sales.csv

Aici listăm artefactele din sesiune, le păstrăm pe cele create de turul finalizat și le descărcăm în folderul nostru local cloud_bean_results.

7. Șterge sesiunea pentru a economisi costuri de calcul în sandbox

După ce am terminat cu fișierele, ar trebui să ștergem sesiunea ca să nu păstrăm mediul gestionat mai mult decât e necesar.

result = client.beta.agents.sessions.delete(
    session_id
)

print(f"Session deleted: {result.deleted}")

Output:

Session deleted: True

Acest lucru elimină sesiunea gestionată din API. 

OpenAI notează că eliberarea fizică a resurselor de dedesubt poate continua asincron după ce cererea de ștergere a fost returnată.

Acest pas este deosebit de important când folosești un sandbox găzduit de OpenAI. 

Sandbox-ul este mediul de calcul unde agentul rulează cod și lucrează cu fișiere, iar sandbox-urile găzduite folosesc resurse containerizate care sunt facturate separat de utilizarea modelului. 

Deci, dacă păstrezi sesiunile și mediile active mai mult decât e nevoie, poți acumula costuri de calcul.

Gânduri finale: Merită costul OpenAI Agents API?

Ce mi-a atras atenția la Agents API este cât de multe poate face din un singur apel API simplu.

I-am dat fișierul, sarcina, configurația modelului și mediul găzduit. 

De acolo, el s-a ocupat de restul: a creat spațiul de lucru, a inspectat datele, a scris codul Python, l-a rulat, a verificat ieșirile, a reparat dacă a fost nevoie și a produs artefactele finale.

Chiar se simte ca și cum ai avea Codex care rulează în cloud pentru aplicația ta. 

Nu a trebuit să mă îngrijorez de configurarea resurselor, gestionarea buclei de execuție, manipularea fișierelor intermediare sau urmărirea fiecărui pas. În mare, a trebuit doar să definesc bine sarcina și apoi să mă uit la rezultat.

Rularea în sine a durat aproximativ două minute, dar în acest timp, agentul a făcut destul de multe în culise.

Asta îl diferențiază de o cerere API obișnuită. 

Nu doar aștepți ca un model să genereze text. Aștepți ca un agent să finalizeze efectiv o bucată de muncă.

În testele mele, trei rulari ale acestui exemplu au costat în total în jur de 1,52 $, incluzând utilizarea modelului și a mediului găzduit. 

Pentru o sarcină atât de mică, nu e ieftin, deci pentru producție aș testa cu siguranță mai întâi modele mai mici sau mai ieftine.

Dar pentru muncă mai complexă, care implică programare, depanare, fișiere, raționament și mai mulți pași dependenți, costul suplimentar poate avea mult mai mult sens.