OpenAI Agents API Tutorial: Baue einen Agenten, der in der Cloud Code schreibt und ausführt

Die meisten LLM-Apps folgen einem einfachen Muster: Du sendest einen Prompt, bekommst eine Antwort und nutzt diese in deiner Anwendung.

Für einfache Aufgaben klappt das gut. Komplexer wird es, wenn das Modell Code schreiben, ausführen, das Ergebnis prüfen, mit Dateien arbeiten, Fehler beheben und so lange weitermachen muss, bis die Aufgabe wirklich erledigt ist.

Genau hier kommt die Agents API von OpenAI ins Spiel.

Statt jeden Schritt selbst zu bauen, gibst du dem Agenten die Aufgabe, die nötigen Dateien und eine Arbeitsumgebung – und er erledigt den Rest.

In diesem Tutorial halte ich das Beispiel bewusst einfach. Wir erstellen einen kleinen fiktiven Café-Umsatzdatensatz und geben ihn dem Agenten. Der Agent schreibt und führt die Analyse aus, prüft die Ergebnisse und erstellt drei Ausgabedateien für uns.

Wenn du siehst, was im Hintergrund alles passiert, merkst du schnell, wie viel des üblichen Coding-Workflows dir abgenommen wird. 

Wenn du neu bei KI-Agenten bist, schau dir unseren AI Agents Fundamentals Skill Track an. 

Was ist die OpenAI Agents API?

Die OpenAI Agents API erlaubt dir, einem Agenten eine Aufgabe, die benötigten Dateien und die Arbeitsumgebung zu geben – und ihn dann alles Weitere übernehmen zu lassen.

Anstatt manuell eine Sandbox aufzusetzen, eine Session zu starten, Dateien hochzuladen, Code auszuführen, Fehler zu prüfen und jeden Schritt selbst zu steuern, sendest du eine API-Anfrage mit Aufgabe, Konfiguration, Umgebung und Eingabedateien.

Danach übernimmt die Agents API den Großteil der Arbeit.

Unter der Haube verwaltet OpenAI das Codex-Harness inklusive Orchestrierung, Kontext, Tooling, Ausführung und langlebigen Sessions. Du kannst es dir fast so vorstellen, als wäre OpenAI Codex in der Cloud für deine Anwendung im Einsatz. 

Du musst dich weniger um Compute, die Arbeitsumgebung, Session-Handling oder den kompletten Agent-Loop kümmern.

Das ist besonders hilfreich für komplexere, länger laufende Aufgaben, bei denen der Agent wirklich arbeiten muss – nicht nur eine Antwort zurückgeben.

In diesem Tutorial nutzen wir eine von OpenAI gehostete Sandbox:

Wir senden eine Anfrage mit der CSV-Datei, der Aufgabe und der Agenten-Konfiguration. 

Die Agents API erstellt und verwaltet für uns Session und Sandbox.

In der Sandbox kann der Agent die Datei ansehen, die Analyse planen, Python-Code erzeugen, ausführen, die Ergebnisse prüfen und bei Fehlern nachbessern.

Sind alle Schritte erledigt, werden die Ausgaben als Session-Artefakte gespeichert. 

Das können Diagramme, bereinigte Datensätze, Berichte oder andere vom Agenten erstellte Dateien sein. Diese können wir dann abrufen, zum Download anbieten und prüfen lassen.

Die Idee dahinter ist simpel: Wir senden die Aufgabe einmal – und der Agent übernimmt die eigentliche Arbeit.

OpenAI Responses API vs. Agents SDK vs. Agents API: Was solltest du nutzen?

Der Hauptunterschied zwischen den dreien ist, wie viel des Workflows du selbst steuern willst.

Nutze die Responses API für fokussierte Aufgaben wie Zusammenfassung, Extraktion, Klassifikation, Q&A, strukturierte Ausgaben oder wenige Tool-Aufrufe.

Nutze das Agents SDK, wenn du selbst eine Agenten-App baust und mehr Kontrolle über Agents, Tools, Handovers, Guardrails und Multi-Agent-Workflows brauchst.

Nutze die Agents API, wenn die Aufgabe komplexer ist und eine eigene Arbeitsumgebung benötigt. Das ist sinnvoll, wenn der Agent mit Dateien arbeiten, Code ausführen, Ergebnisse prüfen, Fehler beheben und in mehreren Schritten weitermachen muss.

Schritt-für-Schritt: Einen Data-Analysis-Agenten mit OpenAI bauen

Für dieses Tutorial nutzen wir die Agents API, weil der Agent mit einer Datei arbeiten, über die Analyse nachdenken, Code ausführen, Ergebnisse inspizieren und die finalen Artefakte für Nutzende speichern soll.

Los geht’s

1. Richte deine Python-Umgebung für die Agents API ein

Wir verwenden ein Jupyter Notebook, um die Agents API Schritt für Schritt zu testen und zu verstehen, wie jede Komponente funktioniert. 

Wir starten mit der Installation des OpenAI-Pakets und importieren die Bibliotheken für den Rest des Tutorials.

Zuerst installierst oder aktualisierst du das OpenAI-Python-Paket:

%pip install -q --upgrade openai

Dann importieren wir die benötigten Bibliotheken:

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

Jetzt erstellen wir den OpenAI-Client:

client = OpenAI()

Stelle sicher, dass dein OPENAI_API_KEY in deiner Umgebung gesetzt ist. Der OpenAI-Client erkennt ihn automatisch.

2. Beispieldaten für den KI-Agenten generieren

Wir erstellen einen kleinen Fake-Umsatzdatensatz, damit der Agent etwas Einfaches zu verarbeiten hat.

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]),
        }
    )

So entstehen 50 fiktive Bestellungen über verschiedene Produkte, Standorte, Daten und Rabatte. Wir nutzen einen festen Random-Seed, damit bei jedem Lauf derselbe Datensatz entsteht.

3. Die CSV-Datei für die Agent-Sandbox erstellen und encodieren

Als Nächstes verwandeln wir die generierten Daten in eine CSV-Datei, die wir dem Agenten übergeben können.

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]))

Ausgabe:

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

Wir Base64-encodieren die CSV außerdem, da wir die Datei direkt mit der Agenten-Anfrage senden.

4. Die Agent-Aufgabe und erwarteten Outputs definieren

Jetzt beschreiben wir, was der Agent mit der CSV-Datei tun soll.

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()

Wichtig ist, dass wir Ziel und erwartete Ausgaben beschreiben, statt die Analyse selbst zu programmieren.

Der Agent entscheidet, wie er vorgeht, führt den Code aus und prüft die Ergebnisse, bevor er abschließt.

5. Den Agenten in der von OpenAI gehosteten Sandbox ausführen

Jetzt senden wir alles in einer Anfrage an die Agents API und lassen den Agenten die eigentliche Arbeit in der Cloud erledigen.

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}")

Hier passiert der größte Teil der Arbeit.

Wir stellen eine Anfrage mit Agenten-Konfiguration, gehosteter Umgebung, CSV-Datei und Aufgabe. 

OpenAI erstellt die verwaltete Session und führt den Agenten in der gehosteten Sandbox aus. Der Agent kann dann die Datei inspizieren, analyze_sales.py schreiben, ausführen, die Ergebnisse prüfen, Probleme beheben und die finalen Dateien erzeugen. 

Der Endpoint zur Session-Erstellung unterstützt sowohl Umgebung als auch initiale Eingabe in derselben Anfrage.

Die Anfrage besteht aus drei Hauptteilen:

• agent gibt an, welches Modell OpenAI nutzen soll und wie sich der Agent verhalten soll.
• environment stellt dem Agenten den gehosteten Workspace bereit und legt unsere CSV darin ab.
• input übergibt dem Agenten die zuvor definierte Aufgabe.

Wir setzen außerdem stream=True. 

Das ändert nicht, wie die Aufgabe erledigt wird. Es erlaubt uns nur, Events während der Agent arbeitet zu empfangen, statt bis zum Ende des Turns zu warten.

In diesem Beispiel lauschen wir auf agent.session.turn.output_text.delta-Events und aktualisieren fortlaufend den Notebook-Output.

Der Text, der oben erscheint, ist der Fortschrittsbericht des Agenten und seine finale Antwort. 

Die eigentliche Aufgabe läuft in der gehosteten Umgebung weiter, bis wir das Event agent.session.turn.completed erhalten.

In meinem Durchlauf hat der Agent analyze_sales.py erstellt und ausgeführt, die Dateien geprüft und einen Gesamt-Netto-Umsatz von 600,55 verifiziert.

Entscheidend ist: Das Modell hat uns nicht nur gesagt, welchen Python-Code wir ausführen sollen. Der Agent hat den Code wirklich geschrieben, ausgeführt, die Ergebnisse inspiziert und die Ausgabe selbst verifiziert.

6. Die Dateiartefakte des Agenten abrufen und herunterladen

Nachdem der Agent fertig ist, können wir die während dieses Turns erstellten Dateien herunterladen.

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}")

Ausgabe:

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

Wir listen die Artefakte der Session auf, behalten die aus dem abgeschlossenen Turn und laden sie in unseren lokalen Ordner cloud_bean_results herunter.

7. Die Session löschen, um Sandbox-Compute-Kosten zu sparen

Sobald wir mit den Dateien fertig sind, sollten wir die Session löschen, damit die verwaltete Umgebung nicht länger als nötig läuft.

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

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

Ausgabe:

Session deleted: True

Damit wird die verwaltete Session aus der API entfernt. 

OpenAI weist darauf hin, dass die physische Bereinigung der zugrunde liegenden Ressourcen asynchron nach dem Delete-Request weiterlaufen kann.

Dieser Schritt ist besonders wichtig bei einer von OpenAI gehosteten Sandbox. 

Die Sandbox ist die Compute-Umgebung, in der der Agent Code ausführt und mit Dateien arbeitet. Gehostete Sandboxes nutzen Container-Compute, das separat zur Modelnutzung abgerechnet wird. 

Lässt du Sessions und Umgebungen länger als nötig laufen, steigen also deine Compute-Kosten.

Fazit: Lohnt sich die OpenAI Agents API kostenmäßig?

Was mich an der Agents API beeindruckt hat, ist, wie viel sie mit einem einzigen API-Call leisten kann.

Wir haben ihr die Datei, die Aufgabe, die Modellkonfiguration und die gehostete Umgebung gegeben. 

Von dort hat sie alles übernommen: Workspace erstellt, Daten inspiziert, Python-Code geschrieben, ausgeführt, Outputs geprüft, bei Bedarf korrigiert und die finalen Artefakte erzeugt.

Es fühlt sich wirklich so an, als liefe Codex für deine Anwendung in der Cloud. 

Ich musste mich nicht um Compute-Setup, den Ausführungsloop, Zwischen-Dateien oder die Nachverfolgung jedes Schritts kümmern. Ich musste die Aufgabe gut definieren – und mir das Ergebnis ansehen.

Der Lauf selbst dauerte rund zwei Minuten, aber in der Zeit hat der Agent im Hintergrund einiges erledigt.

Das unterscheidet es von einer normalen API-Anfrage. 

Du wartest nicht nur auf generierten Text, sondern darauf, dass ein Agent echte Arbeit erledigt.

In meinen Tests kosteten drei Durchläufe dieses Beispiels insgesamt etwa 1,52 $ – inklusive Modell- und Umgebungsnutzung. 

Für so eine kleine Aufgabe ist das nicht billig. Für die Produktion würde ich definitiv erst kleinere oder günstigere Modelle testen.

Bei komplexeren Jobs mit Coding, Debugging, Dateien, Reasoning und mehreren abhängigen Schritten kann sich der Aufpreis aber lohnen.