Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Checkliste für die API-Bereitstellung

Oft ungenutzte Gestaltungsmöglichkeiten, mit denen du Qualität, Geschwindigkeit und Zuverlässigkeit im Produktivbetrieb verbessern und Kosten senken kannst.

Responses API verwenden

Beginne immer mit der Responses API. Sie ist die zentrale API von OpenAI und bietet dir den besten Zugang zum neuesten Modellverhalten, zu integrierten Tools, zustandsbehafteten Workflows und Agentenfunktionen.

Modell für die Aufgabe auswählen

Teste die GPT-6-Modellfamilie für deinen Anwendungsfall. Nutze gpt-6-astra, wenn du das leistungsfähigste Modell brauchst, gpt-6.1-sol für komplexe Programmieraufgaben und professionelle Arbeit zu geringeren Kosten als mit Astra und gpt-6-luna für die effiziente Bearbeitung wiederkehrender Aufgaben. Wähle das Modell, das bei repräsentativen Aufgaben gut abschneidet, statt jede Anfrage an das leistungsfähigste Modell zu leiten.

Behalte beim Wechsel zu GPT-6 die Rolle deines bisherigen Modells im Workflow und seinen tatsächlich verwendeten Reasoning-Aufwand bei, soweit das neue Modell dies unterstützt. Verwende für Reasoning mit Tools die Responses API. GPT-6 Astra und GPT-6.1 Sol benötigen Responses für Tool-Aufrufe. GPT-6 Sol und GPT-6 Luna unterstützen Funktionsaufrufe in Chat Completions nur mit reasoning_effort: "none". Hat der Reasoning-Aufwand einen anderen Wert als none, entferne temperature, top_p und top_logprobs. Entferne außerdem logprobs aus Chat-Completions-Anfragen und message.output_text.logprobs aus dem Responses-Array include. Prüfe vor der Wahl eines Modells oder einer Verarbeitungsstufe, welche Optionen für Datenresidenz infrage kommen. Weitere Kompatibilitätsprüfungen findest du im Leitfaden zur Modellmigration. Führe repräsentative Evaluierungen durch, bevor du Prompts änderst oder neue Funktionen hinzufügst. Vergleiche die Erfolgsquote, die Latenz, die Anzahl der Eingabe-, Ausgabe-, Reasoning- und Cache-Schreibtoken sowie die Kosten pro erfolgreich erledigter Aufgabe.

reasoning.effort konfigurieren

Mit reasoning.effort legst du fest, wie viel Aufwand das Modell in das Reasoning investiert, bevor es antwortet.

GPT-6 Astra, GPT-6.1 Sol, GPT-6 Sol und GPT-6 Luna unterstützen low, medium, high, xhigh und max. GPT-6 Sol und GPT-6 Luna unterstützen zusätzlich none, GPT-6 Astra und GPT-6.1 Sol hingegen nicht. Bei geringerem Reasoning-Aufwand antwortet das Modell schneller und benötigt weniger Reasoning-Token. Bei höherem Aufwand hat es mehr Zeit, um zu planen, Fehler zu finden, Erkenntnisse zusammenzuführen und in mehreren Schritten Alternativen abzuwägen.

Verwende low, wenn es hauptsächlich darum geht, Informationen zu extrahieren, Anfragen weiterzuleiten, Inhalte zu klassifizieren oder Texte nach einem bekannten Muster umzuformulieren. Verwende medium oder high, wenn das Modell ein Problem diagnostizieren, Optionen vergleichen, einen Plan erstellen oder Code analysieren muss. Verwende xhigh oder max nur, wenn repräsentative Evaluierungen zeigen, dass der Qualitätsgewinn die zusätzliche Latenz und die Mehrkosten rechtfertigt. Wenn du von minimal wechselst oder bisher none verwendest und zu GPT-6 Astra oder GPT-6.1 Sol migrierst, beginne mit low und vergleiche die Ergebnisse. Behalte andernfalls den bisherigen effektiven Reasoning-Aufwand bei und prüfe Änderungen anhand deiner Ziele für Qualität, Latenz und Kosten.

Vergleiche bei besonders anspruchsvollen Aufgaben, bei denen die Qualität Vorrang hat, auch reasoning.mode: "pro" mit dem Standardmodus bei gleichem Reasoning-Aufwand. Reasoning-Modus und Reasoning-Aufwand lassen sich unabhängig voneinander einstellen. Im Pro-Modus investiert das Modell mehr Rechenarbeit, bevor es eine einzige abschließende Antwort liefert. Das kann die Zuverlässigkeit verbessern, erhöht aber die Latenz und den Token-Verbrauch.

Reasoning-Aufwand an die Aufgabe anpassen
from openai import OpenAI

client = OpenAI()

prompt = """
Our CI job started failing after a dependency bump.

Error:
TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'

Identify the likeliest root cause and the smallest safe fix.
"""

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "xhigh", "mode": "pro"},
    input=prompt,
)

print(response.output_text)

Reasoning-Aufwand im Gespräch ändern

Bei GPT-6-Modellen im Standardmodus mit einem einzelnen Agenten kannst du den Reasoning-Aufwand zwischen zwei Antworten ändern. Füge dazu vor der nächsten Nutzernachricht ein Eingabeelement vom Typ configuration_update ein. Lass reasoning.effort auf Anfrageebene unverändert, damit das ursprüngliche Prompt-Präfix weiterhin für das Caching infrage kommt. Die Änderung gilt ab der nächsten Antwort, bis eine weitere Aktualisierung sie überschreibt. Konfigurationsaktualisierungen lassen sich weder mit automatischer Kontextverdichtung noch mit automatischer Kürzung kombinieren. /responses/compact lehnt Gesprächsverläufe ab, die solche Aktualisierungen enthalten. Um den Verlauf zu verdichten, füge ein Element vom Typ compaction_trigger ein und füge anschließend eine neue Konfigurationsaktualisierung hinzu.

text.verbosity konfigurieren

Mit text.verbosity steuerst du vor allem, wie knapp oder ausführlich eine Antwort ausfällt. Wähle einen niedrigeren Wert, wenn dein Produkt eine schnelle, kompakte Antwort benötigt. Wähle einen höheren Wert, wenn die Antwort mehr erklären, klarer gegliedert sein oder den vollständigen Kontext enthalten soll. Bei einem niedrigeren Wert generiert das Modell weniger Ausgabetoken und liefert die Antwort schneller.

Bei Programmieraufgaben führen medium und high in der Regel zu längeren, besser gegliederten Ausgaben. Mit low fällt die Antwort knapper aus und konzentriert sich auf das Wesentliche.

Prüfe bei der Migration, ob allgemeine Anweisungen wie „Fasse dich kurz“ weiterhin hilfreich sind. Lege den standardmäßigen Detailgrad vorzugsweise mit text.verbosity fest. Gib dann im Prompt die erforderlichen Inhalte, die Struktur und die Länge vor.

Auch Prompts beeinflussen Qualität, Token-Verbrauch, Kosten und Latenz. Berücksichtige bei der Wahl des Detailgrads die Prompt-Empfehlungen für das neueste Modell, einschließlich der Hinweise zum Testen und Überprüfen von Ergebnissen bei Coding-Agenten.

Für kompakte Ausgaben einen niedrigeren Detailgrad wählen
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    text={"verbosity": "low"},
    input="""
    Summarize this incident for the next on-call engineer.
    - checkout latency spiked from 220 ms to 4.8 s
    - only us-east-1 was affected
    - rollback is complete
    - likely trigger: cache stampede after deploy
    """,
)

print(response.output_text)

Parameter phase für den Assistenten konfigurieren

phase kennzeichnet Nachrichten des Assistenten im Gesprächsverlauf. Daran erkennt das Modell, ob eine frühere Nachricht des Assistenten ein Zwischenkommentar oder die abschließende Antwort war. Verwende phase: "commentary" für Fortschrittsmeldungen, Hinweise vor Tool-Aufrufen und andere Zwischennachrichten. Verwende phase: "final_answer" für die fertige Antwort.

Der Assistent könnte beispielsweise folgende Nachricht ausgeben:

Zwischenkommentar des Assistenten
{
  "role": "assistant",
  "phase": "commentary",
  "content": "I'm checking the logs and comparing them to the last successful deploy."
}

Diese Nachricht informiert über den Fortschritt. Die eigentliche Antwort des Assistenten könnte später so aussehen:

Abschließende Antwort des Assistenten
{
  "role": "assistant",
  "phase": "final_answer",
  "content": "The deploy failed because the migration referenced a column that does not exist in production."
}

Die Kennzeichnung hilft bei langen Workflows oder bei vielen Tool-Aufrufen, wenn der Assistent vor Abschluss der Aufgabe sichtbare Fortschrittsmeldungen ausgibt. Wenn du diesen Verlauf bei Folgeanfragen an gpt-5.3-codex oder neuere Modelle übermittelst, behalte phase in den Nachrichten des Assistenten bei und sende den Wert erneut mit. So kann das Modell Fortschrittsmeldungen vom Endergebnis unterscheiden. Der Agent bricht dadurch seltener vorzeitig ab und arbeitet mit höherer Wahrscheinlichkeit bis zur abschließenden Antwort weiter.

tool_search verwenden

Statt bei jeder Anfrage den gesamten Tool-Katalog zu laden, nutze die Tool-Suche. Füge {"type": "tool_search"} hinzu und kennzeichne Tool-Definitionen, deren Laden viele Token kostet, mit defer_loading: true. Das Modell kann dann zur Laufzeit die benötigte Teilmenge laden. Zu Beginn der Anfrage sieht das Modell nur den Namen und die Beschreibung des Suchtools. Braucht es ein zurückgestelltes Tool, führt es die Tool-Suche aus. Erst dann werden die zurückgestellten Tool-Definitionen in den Kontext geladen und das Modell kann die Tools aufrufen. Das spart Token und erhält die Cache-Leistung.

Die Tool-Suche bietet zwei Modi:

  • Gehostete Tool-Suche ist die einfachere Option. Verwende sie, wenn du bereits weißt, welche Tools für die Anfrage infrage kommen.
  • Clientseitige Tool-Suche eignet sich, wenn deine App selbst bestimmen muss, welche Tools verfügbar sind, etwa anhand des Mandanten, des Projekts, der Berechtigungen oder eines internen Verzeichnisses.

Beginne mit der gehosteten Tool-Suche, sofern deine App die Suche nicht selbst steuern muss.

Gruppiere Tools danach, was die nutzende Person erreichen möchte. Verwende nach Möglichkeit einen Namespace oder einen MCP-Server. Dem Modell fällt die Auswahl zwischen wenigen klar abgegrenzten Gruppen leichter als die Auswahl aus einer langen, ungegliederten Funktionsliste. Für einen effizienten Token-Einsatz und eine gute Modellleistung empfehlen wir, pro Namespace unter etwa zehn Funktionen zu bleiben.

Beschreibe jeden Namespace kurz und so, dass er sich klar von den anderen unterscheidet. Hinterlege detaillierte Anweisungen in den zurückgestellten Tool-Definitionen. Vermeide einen einzigen großen Namespace für alle Tools.

Gehostete Tool-Suche mit verzögert geladenen Tools verwenden
from openai import OpenAI

client = OpenAI()

billing_namespace = {
    "type": "namespace",
    "name": "billing",
    "description": "Billing tools for invoices, payments, taxes, and credits.",
    "tools": [
        {
            "type": "function",
            "name": "lookup_invoice",
            "description": "Look up invoice state, taxes, credits, and payment attempts.",
            "parameters": {
                "type": "object",
                "properties": {
                    "invoice_id": {"type": "string"},
                },
                "required": ["invoice_id"],
                "additionalProperties": False,
            },
            "strict": True,
            "defer_loading": True,
        }
    ],
}

crm_namespace = {
    "type": "namespace",
    "name": "crm",
    "description": "CRM tools for account ownership, plans, health, and payment history.",
    "tools": [
        {
            "type": "function",
            "name": "get_account",
            "description": "Fetch account owner, plan, health, and payment history.",
            "parameters": {
                "type": "object",
                "properties": {
                    "account_id": {"type": "string"},
                },
                "required": ["account_id"],
                "additionalProperties": False,
            },
            "strict": True,
            "defer_loading": True,
        }
    ],
}

response = client.responses.create(
    model="gpt-6-astra",
    input=(
        "Find the right billing tool and explain why invoice INV-1043 still "
        "shows overdue after a payment yesterday."
    ),
    tools=[billing_namespace, crm_namespace, {"type": "tool_search"}],
)

print(response.output)

Tools programmgesteuert aufrufen

Mit programmgesteuerten Tool-Aufrufen können unterstützte Modelle JavaScript schreiben, das in einer gehosteten Laufzeitumgebung geeignete Tools aufruft und deren Zwischenergebnisse verdichtet. Nutze diese Möglichkeit für klar abgegrenzte Arbeitsschritte, in denen Code umfangreiche Tool-Ergebnisse filtern, verknüpfen, nach Rang ordnen, von Duplikaten bereinigen, kombinieren oder prüfen kann, bevor er ein kleineres, strukturiertes Ergebnis an das Modell zurückgibt.

Füge das Tool programmatic_tool_calling hinzu und aktiviere programmgesteuerte Aufrufe für jedes geeignete Tool einzeln. Verwende allowed_callers: ["programmatic"] für Tools, die nur von Programmen aufgerufen werden dürfen, oder allowed_callers: ["direct", "programmatic"], wenn das Modell das Tool auch direkt aufrufen darf. Bleibe bei direkten Aufrufen, wenn jedes Ergebnis die nächste Entscheidung des Modells beeinflussen kann, eine Aktion eine Genehmigung erfordert oder die abschließende Antwort Quellenverweise oder native Artefakte beibehalten muss. Dokumentiere die Rückgabefelder der Tools und ihr Verhalten bei Fehlern, damit das Modell ein korrektes Programm schreiben kann, ohne zuerst ein Ergebnis untersuchen zu müssen.

Deine Verarbeitungsschleife für Tool-Aufrufe muss Elemente vom Typ program und program_output verarbeiten, ebenso die vom Programm ausgelösten function_call-Elemente und die zugehörigen function_call_output-Elemente. Behalte jede call_id bei und kopiere den Wert von caller aus dem Funktionsaufruf in die zugehörige Ausgabe, damit der Dienst das richtige Programm fortsetzen kann.

Teste sowohl program_output als auch die abschließende Nachricht des Assistenten. Selbst bei einem korrekten Programmergebnis kann die abschließende Antwort unvollständig sein. Vergleiche die Erfolgsquote, die erforderlichen Belege, die Gesamtzahl der Token, die Latenz und die Kosten mit demselben Workflow bei direkten Tool-Aufrufen.

Mit mehreren Agenten parallel arbeiten

Im Multi-Agenten-Modus können unterstützte Modelle, darunter die GPT-6-Modelle, voneinander unabhängige Arbeiten an Subagenten delegieren und deren Ergebnisse zusammenführen. Nutze diesen Modus, wenn du Recherche, Analyse oder Implementierung in konkrete, klar abgegrenzte Aufgaben aufteilen kannst, die jeweils mit eigenem Kontext parallel laufen.

Setze multi_agent.enabled in der Anfrage auf true. Verwende für HTTP das Responses-SDK in der Betaversion mit client.beta.responses und übergib responses_multi_agent=v1 in betas. Sende bei direkten HTTP- oder WebSocket-Verbindungen OpenAI-Beta: responses_multi_agent=v1. Während der Betaphase des Multi-Agenten-Modus können sich die Schemas der Elemente ändern.

Verwende vorzugsweise einen einzelnen Agenten für kurze Aufgaben, für Abläufe, in denen jeder Schritt vom vorherigen abhängt, oder wenn mehrere Arbeitsschritte auf dieselbe veränderliche Ressource schreiben. Subagenten können den Token-Verbrauch erhöhen. Beginne deshalb für max_concurrent_subagents mit dem Standardwert 3 und miss Qualität, Latenz und Kosten für den gesamten Ablauf. Bei langen Multi-Agenten-Workflows oder vielen Tool-Aufrufen kann der WebSocket-Modus den Aufwand für die Fortsetzung reduzieren.

Berücksichtige vor dem Aktivieren des Multi-Agenten-Modus die aktuellen Einschränkungen. Der Modus unterstützt weder /responses/compact noch reasoning.summary noch max_tool_calls. Der Server verdichtet den Kontext des Hauptagenten und jedes Subagenten automatisch.

Tools asynchron aufrufen

Setze bei GPT-6-Modellen für eine Funktion oder ein benutzerdefiniertes Tool async: true, wenn das Modell weiterarbeiten kann, während deine Anwendung den Aufruf ausführt. Starte langsame Tool-Aufrufe früh und lass das Modell unabhängige Aufgaben bearbeiten. Deine Anwendung führt den Aufruf weiterhin aus, verfolgt seinen Status und gibt das Ergebnis in einer späteren Responses-Anfrage mit der ursprünglichen call_id zurück. Die asynchrone Ausführung steht für integrierte Tools und programmgesteuerte Tool-Aufrufe nicht zur Verfügung. Kombiniere im Multi-Agenten-Modus asynchrone Tools nicht mit parallelen Tool-Aufrufen. Den vollständigen Ablauf findest du im Leitfaden zu asynchronen Tool-Aufrufen.

Integrierte Tools nutzen

Integrierte Tools gehören zum Funktionsumfang der API. Statt jedes Tool selbst zu entwickeln, kannst du dem Modell Zugriff auf Tools geben, die bereits in der Responses API verfügbar sind. Das Modell kann dann entscheiden, wann es sie verwendet.

OpenAI ergänzt laufend weitere integrierte Tools. Beginne mit diesen Tools, wenn sie zu deinem Workflow passen. Entwickle eigene Tools, wenn die integrierten Optionen deine Aufgabe nicht abdecken. Aktuell stehen unter anderem folgende Tools und ergänzende Optionen zur Verfügung:

  • Websuche: Suche im Web nach aktuellen Informationen.
  • Dateisuche: Durchsuche hochgeladene Dateien oder Vektorspeicher.
  • Code Interpreter: Führe Python-Code für Analysen, Berechnungen, Diagramme und die Dateiverarbeitung aus.
  • Shell: Führe Shell-Befehle in einem gehosteten Container oder in deiner eigenen Laufzeitumgebung aus.
  • Computernutzung: Bediene eine Benutzeroberfläche mithilfe von Screenshots, Klicks, Tastatureingaben und Scrollen.
  • Bildgenerierung: Erstelle oder bearbeite Bilder.
  • MCP/Konnektoren: Verbinde das Modell mit externen Diensten und Tools.
  • Skills: Binde wiederverwendbare Anweisungspakete und Workflow-Dateien ein.
  • Patches anwenden: Nimm strukturierte Codeänderungen vor.

Auch die Modellqualität spricht für integrierte Tools. Ihre Formate, ihr Verhalten und ihre Ausgaben sind Teil des Nachtrainings und der Evaluierung unserer Modelle. OpenAI-Modelle wählen integrierte Tools daher treffender aus und führen sie sauberer und mit weniger Fehlern aus als neue Tools.

Kontextverdichtung nutzen

Mit der Kontextverdichtung steuerst du, welche Informationen das Modell über viele Gesprächsrunden hinweg mitnimmt. Bei Agenten mit langer Laufzeit geht es um mehr als die Frage „Erreiche ich das Kontextlimit?“. Alte Nachrichten, Tool-Protokolle, Wiederholungsversuche und überholte Details verdrängen Informationen, die das Modell zum Weiterarbeiten braucht.

Mit der Kontextverdichtung kannst du den Kontext gezielt verkleinern und dabei den Zustand erhalten, der für die nächsten Gesprächsrunden nötig ist. Nach einem wichtigen Zwischenschritt, etwa wenn die Fehlersuche abgeschlossen oder die Ursache eingegrenzt ist, kannst du das bisherige Kontextfenster verdichten und mit der verdichteten Ausgabe weiterarbeiten. Das Modell bleibt so auf die Aufgabe konzentriert. Für die nächste Runde stehen die relevanten Informationen im Vordergrund. Einzelne Zwischenschritte im Reasoning, fehlgeschlagene Befehle und überholte Lösungsansätze beanspruchen keinen unnötigen Platz.

Du kannst die Kontextverdichtung auf zwei Arten nutzen:

  • Dem Server überlassen: Wenn du previous_response_id verwendest, aktiviere context_management und lege mit compact_threshold einen Schwellenwert fest. Der Server verdichtet das Gespräch automatisch, sobald es zu umfangreich wird. Du sendest weiterhin nur die jeweils neueste Nutzernachricht.
  • Selbst steuern: Wenn du das gesamte Eingabearray selbst verwaltest, rufe client.responses.compact() auf. Du erhältst ein kleineres Kontextfenster. Verwende die zurückgegebene Ausgabe direkt im nächsten Aufruf von responses.create().

Bearbeite die verdichtete Ausgabe nicht. Sie enthält den Maschinenzustand, mit dem das Modell weiterarbeitet, und ist keine Zusammenfassung für Menschen. Gib die Ausgabe unverändert weiter und füge dann die nächste Nutzernachricht hinzu.

Mit dem verdichteten Antwortzustand weiterarbeiten
from openai import OpenAI

client = OpenAI()

# Full window collected from a long debugging session:
# user messages, assistant outputs, tool calls, and tool outputs.
long_window = session_items

compacted = client.responses.compact(
    model="gpt-6-astra",
    input=long_window,
)

next_response = client.responses.create(
    model="gpt-6-astra",
    store=False,
    input=[
        *compacted.output,  # Use compact output as-is.
        {
            "type": "message",
            "role": "user",
            "content": (
                "We found the bad cache invalidation path. Write the fix plan "
                "and the verification checklist."
            ),
        },
    ],
)

print(next_response.output_text)

Prompt-Caching optimieren

Prompt-Caching senkt automatisch Latenz und Kosten, wenn Anfragen dasselbe lange Präfix verwenden. Stelle gleichbleibende Anweisungen, Beispiele und Referenzmaterial an den Anfang. Füge danach dynamische, nutzerspezifische Inhalte ein. Behalte die Tool-Definitionen und ihre Reihenfolge bei. Hänge neue Gesprächsrunden an, ohne den bisherigen Kontext umzuschreiben.

GPT-5.6 hat explizites Prompt-Caching eingeführt. Implizites Caching bleibt der Standard. GPT-5.6-Modelle und spätere Modellfamilien unterstützen zusätzlich explizite Cache-Haltepunkte und eine Cache-Richtlinie für die gesamte Anfrage. Wenn auf ein stabiles Präfix ein veränderliches Suffix folgt, füge am Ende des wiederverwendbaren Teils einen expliziten prompt_cache_breakpoint ein. Setze prompt_cache_options.mode nur dann auf explicit, wenn die Anfrage ausschließlich die von dir angegebenen Haltepunkte und keinen impliziten Haltepunkt verwenden soll. Frühere Modelle verwenden weiterhin ausschließlich automatisches Prompt-Caching.

Ersetze bei der Migration von GPT-5.5 oder früher prompt_cache_retention durch prompt_cache_options.ttl: "30m". Informiere dich über die Modellunterschiede beim Prompt-Caching, bevor du Cache-Einstellungen änderst.

Bei GPT-5.6-Modellen und späteren Modellfamilien kostet jedes in den Cache geschriebene Token das 1,25-Fache eines nicht zwischengespeicherten Eingabetokens. Protokolliere cached_tokens und cache_write_tokens. Vergleiche die Anzahl der geschriebenen Token mit der Anzahl der später aus dem Cache gelesenen Token, um die Nettokosten zu ermitteln und die Platzierung der Haltepunkte zu optimieren.

Verwende für Anfragen mit demselben wiederverwendbaren Präfix einen stabilen prompt_cache_key. So können zusammengehörige Anfragen leichter an denselben Cache geleitet werden und du optimierst die Cache-Trefferquote bei Modellen vor GPT-5.6. Beachte bei Gruppen mit hohem Anfragevolumen die Hinweise zur Verteilung der Anfragen auf mehr Schlüssel.

Ab GPT-5.6 ist prompt_cache_key optional. Eine optimale Cache-Trefferquote ist auch ohne Schlüssel möglich. Mit dem Schlüssel kannst du die Cache-Nutzung für einzelne Kundenkonten, Personen oder Workspaces getrennt erfassen. So lassen sich Nutzung und Abrechnung zwischengespeicherter Token für jede Gruppe leichter erklären. Weise jedem Kundenkonto einen eigenen Schlüssel zu und verwende ihn für alle zusammengehörigen Anfragen dieses Kontos. Separate Schlüssel helfen auch zu verhindern, dass sich Cache-Treffer anderer Kundenkonten durch gezielte Anfragen ermitteln lassen. Weitere Informationen findest du im Abschnitt Cache-Nutzung mit Schlüsseln getrennt erfassen.

Cache-Nutzung für ein Kundenkonto getrennt erfassen
from openai import OpenAI

client = OpenAI()

instructions = """
You are the support agent for Acme.
Follow the Acme support policy and escalation rubric.
Use the same tone, safety rules, and tool plan for each ticket.
"""

response = client.responses.create(
    model="gpt-6-astra",
    prompt_cache_key="tenant-acme-support-agent",
    instructions=instructions,
    input="Summarize the current escalation for the on-call lead.",
)

print(response.output_text)

reasoning.encrypted_content verwenden

Unterstützte Modelle, darunter die GPT-6-Modelle, können Reasoning über mehrere Aufrufe hinweg beibehalten. Verwende reasoning.context: "all_turns", wenn Ziele, Annahmen und Prioritäten der Aufgabe gleich bleiben. Verwende current_turn, wenn frühere Überlegungen nicht mehr relevant sind und das Modell auf einen überholten Ansatz festlegen könnten. Wenn du reasoning.context weglässt oder auf auto setzt, prüfe in der Antwort das Feld reasoning.context, um den tatsächlich verwendeten Modus zu bestätigen.

Früheres Reasoning weiterverwenden kannst du nur, wenn die früheren Reasoning-Elemente verfügbar sind. Verwende previous_response_id für gespeicherte Antworten. Wenn die Vorgabe „keine Datenaufbewahrung“ (ZDR) das Speichern von Antwortdaten ausschließt, ermöglichen verschlüsselte Reasoning-Inhalte eine zustandslose Übergabe.

Reasoning-Elemente in der Antwort enthalten standardmäßig verschlüsselte Reasoning-Inhalte. Du kannst über die Eigenschaft encrypted_content jedes Reasoning-Elements auf dessen verschlüsselten Inhalt zugreifen. Deine App muss diesen Wert nicht interpretieren. Sie übernimmt jedes Reasoning-Element unverändert und sendet es in der nächsten Gesprächsrunde zurück, damit das Modell den Workflow fortsetzen kann.

Verschlüsseltes Reasoning zwischen zustandslosen Aufrufen übergeben
from openai import OpenAI

client = OpenAI()

history = [
    {
        "role": "user",
        "content": "Investigate why invoice INV-1043 has mismatched tax totals.",
    }
]

first = client.responses.create(
    model="gpt-6-astra",
    store=False,
    reasoning={"effort": "medium", "context": "current_turn"},
    input=history,
)

history.extend(item.to_dict() for item in first.output)
history.append(
    {
        "role": "user",
        "content": "Now write the customer-facing explanation in plain English.",
    }
)

second = client.responses.create(
    model="gpt-6-astra",
    store=False,
    reasoning={"effort": "medium", "context": "all_turns"},
    input=history,
)

print(second.output_text)

Detailstufe für Bilder gezielt wählen

Bei Bildern ist detail standardmäßig auf auto gesetzt. Wie die Bildgröße angepasst wird, hängt vom Modell ab. Große Bilder können mehr Eingabetoken beanspruchen und die Latenz erhöhen. Prüfe die Tabelle zur Bildgrößenanpassung für die aufgeführten Modelle. Ermittle vor der Bereitstellung den Token-Verbrauch für Bilder und die Grenzen des gewählten Modells.

Wähle detail passend zur Aufgabe. Passe die Bildgröße an, verwende low, wenn feine Bilddetails unwichtig sind, oder nutze high für die übliche Bildanalyse mit hoher Detailtreue. Verwende original, sofern das Modell diese Stufe unterstützt und zusätzliche Details die Qualität verbessern. Das gilt etwa für große oder informationsreiche Bilder, Aufgaben mit präzisen Koordinaten, OCR, die Lokalisierung von Objekten oder die visuelle Prüfung. Ermittle vor der Bereitstellung, wie viele Bildtoken im ungünstigsten Fall anfallen und wie hoch die Latenz dann ist.

Sicherheitskennung senden

Wenn einzelne Personen deine Anwendung nutzen, sende mit jeder Anfrage eine stabile, datenschutzfreundliche Kennung als safety_identifier. Sie hilft OpenAI, Missbrauch zu erkennen, und deinem Team, Richtlinienverstöße zuverlässig nachzuverfolgen. Sie verringert außerdem das Risiko, dass der Missbrauch durch eine einzelne Person den Zugriff für die gesamte Organisation beeinträchtigt.

Bilde einen Hashwert aus dem Anmeldenamen oder der E-Mail-Adresse, statt identifizierende Informationen zu senden. Verwende für die Nutzung ohne Anmeldung eine stabile Sitzungs-ID.

Auf erkannte Abweichungen vom vorgesehenen Verhalten reagieren

Plane bei Agenten-Workflows mit GPT-6 Astra die Überwachung auf Abweichungen vom vorgesehenen Verhalten ein. Gibt eine Anfrage 403 mit misalignment_policy_violation zurück, löse für dieses Gespräch keine weiteren Aktionen aus und starte den blockierten Workflow nicht automatisch erneut. Behandle auch Fehler während des Streamings und prüfe alle Aktionen, die möglicherweise schon ausgeführt wurden. Abonniere safety.alert.created, wenn dein Team projektbezogene Warnmeldungen benötigt. Der Webhook ersetzt die Fehlerbehandlung für einzelne Anfragen nicht. Prüfe im Leitfaden, welche Responses-Anfragen automatisch gestoppt werden können.

Auf einen raschen Anstieg der Anfragerate und auf Modellüberlastung reagieren

Prüfe den HTTP-Status und error.code, bevor du entscheidest, wie du den Fehler behandelst. Ein 429 mit slow_down bedeutet, dass die Anfragerate zu schnell gestiegen ist. Beachte Retry-After, sofern der Header vorhanden ist, reduziere die Anfragerate und erhöhe sie anschließend schrittweise. Ein 503 mit server_is_overloaded bedeutet, dass das angeforderte Modell vorübergehend überlastet ist. Beachte Retry-After, sofern vorhanden, und versuche es anschließend erneut. Fehlt der Header, verlängere die Wartezeit zwischen Versuchen exponentiell mit einer zufälligen Streuung und begrenze die Anzahl der Versuche. Fehler bei Abrechnung, Ausgaben oder Kontingenten musst du beheben, bevor du die Anfrage erneut sendest. Behandle nicht jeden 429 als vorübergehendes Ratenlimit. Weitere Informationen findest du unter Ratenlimits und Fehlercodes.

background=True verwenden

Verwende background=True für Anfragen, die lange dauern können. Statt die Clientverbindung offen zu halten, startet die API einen Auftrag und gibt eine ID zurück. Deine App kann den Status des Auftrags regelmäßig abfragen, bis er abgeschlossen ist, fehlschlägt oder abgebrochen wird. Nutze den Hintergrundmodus für umfangreiche Analysen, lange Tool-Ausführungen oder Aufgaben, für die du Statusabfragen und Wiederholungsversuche brauchst.

Antwort im Hintergrund starten und Status abfragen
# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI
import time

client = OpenAI()
log_bundle_file_id = "file_123"

job = client.responses.create(
    model="gpt-6-astra",
    background=True,
    store=False,
    input="Analyze this large log bundle and cluster the primary failure modes.",
    tools=[
        {
            "type": "code_interpreter",
            "container": {
                "type": "auto",
                "file_ids": [log_bundle_file_id],
            },
        }
    ],
)

while job.status in {"queued", "in_progress"}:
    time.sleep(2)
    job = client.responses.retrieve(job.id)

print(job.output_text)

Du kannst den Hintergrundmodus mit stream=True kombinieren, um Fortschrittsereignisse zu erhalten. Das erste Ereignis kann allerdings länger auf sich warten lassen als bei einer normalen Anfrage.

In der Benutzeroberfläche lässt sich der Hintergrundmodus so vermitteln: „Die Aufgabe läuft. Hier siehst du den aktuellen Status. Sobald das Ergebnis vorliegt, erscheint es hier.“

WebSocket-Modus verwenden

Der WebSocket-Modus eignet sich für lange Workflows mit vielen Tool-Aufrufen. Du hältst eine dauerhafte Verbindung offen und sendest zum Fortsetzen nur neue Eingabeelemente zusammen mit previous_response_id. Bei Workflows mit mindestens 20 Tool-Aufrufen haben wir eine um bis zu rund 40 % schnellere Ausführung des gesamten Ablaufs beobachtet.

So funktioniert es: Die erste Nachricht sieht aus wie eine normale Responses-Anfrage mit Modell, Anweisungen, Tools und Nutzereingabe. Der Server sendet Ereignisse als Stream zurück. Fordert das Modell ein Tool an, führt deine App es aus. Anschließend sendest du statt einer neuen HTTP-Anfrage über denselben Socket ein weiteres response.create-Ereignis mit der bisherigen previous_response_id und dem neuen Element. Dadurch sinkt die Latenz. Bei reinem HTTP ist für jede Fortsetzung eine neue Anfrage nötig. Im WebSocket-Modus bleibt die Verbindung offen und der jüngste Antwortzustand liegt für diese Verbindung weiterhin im Arbeitsspeicher. Knüpft die nächste Gesprächsrunde an diese Antwort an, braucht der Dienst weniger Vorbereitungszeit.

Besteht dein Workflow aus einer Anfrage und einer Antwort, bleib bei HTTP. Verhält sich dein Workflow wie ein Agent mit langer Laufzeit, probiere den WebSocket-Modus aus.

Verwende für parallele Gespräche auf derselben Verbindung unterschiedliche stream_id-Werte. Ordne die Ereignisse, die aus verschiedenen Streams gemischt eintreffen, anhand von stream_id dem jeweiligen Stream zu. Eine Verbindung unterstützt bis zu 16 aktive Antworten. Anfragen innerhalb desselben Streams laufen der Reihe nach. Verbindungen bleiben bis zu 60 Minuten bestehen. Für die Fortsetzung hat previous_response_id dieselbe Bedeutung wie im HTTP-Modus. Die Verbindung hält die jeweils letzte Antwort jedes Streams in einem lokalen Cache vor.

Hinweis: Der WebSocket-Modus ist mit ZDR kompatibel, da deine Daten ausschließlich im Arbeitsspeicher liegen und nicht auf einen Datenträger geschrieben werden.

Das Python-Beispiel verwendet pip install "openai[realtime]>=3.8.0". Das TypeScript-Beispiel verwendet npm install openai@^7.10.0 ws. Das Ruby-Beispiel verwendet gem install openai async-websocket.

Führe für Go go get github.com/openai/openai-go/v3@v3.98.0 aus. Füge für Java die Maven-Abhängigkeit com.openai:openai-java:4.101.0 hinzu. Diese Versionen der Go- und Java-SDKs unterstützen WebSocket-Verbindungen zu Responses nativ.

WebSocket-Sitzung mit der Responses API starten
from openai import OpenAI
from openai.types.responses import FunctionToolParam

test_log_tool: FunctionToolParam = {
    "type": "function",
    "name": "search_test_logs",
    "description": "Search test logs.",
    "parameters": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
        "additionalProperties": False,
    },
    "strict": True,
}
code_search_tool: FunctionToolParam = {
    "type": "function",
    "name": "search_code",
    "description": "Search source code.",
    "parameters": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
        "additionalProperties": False,
    },
    "strict": True,
}

client = OpenAI()

with client.responses.connect() as connection:
    # Use the same typed parameters as client.responses.create(...).
    connection.response.create(
        model="gpt-6-astra",
        store=False,
        input=[
            {
                "type": "message",
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Find the flaky test in this run, call the tools "
                            "you need, and keep going until you can explain "
                            "the root cause."
                        ),
                    }
                ],
            }
        ],
        tools=[test_log_tool, code_search_tool],
    )
    for event in connection:
        if event.type == "response.completed":
            print(event.response.output)
            break
        if event.type in {"response.failed", "response.incomplete", "error"}:
            raise RuntimeError(event.to_json())
    else:
        raise RuntimeError("Connection closed before the response finished.")

Während einer laufenden Antwort nachsteuern

Wenn Personen zusätzliche Anforderungen eingeben können, während ein GPT-6-Modell arbeitet, verwende eine WebSocket-Verbindung zur Responses API. Sende response.steer mit der ID der aktiven Antwort in previous_response_id und der neuen Nutzereingabe. Lies die Ereignisse für die Fortsetzung weiter. response.steer.accepted bedeutet, dass die Aktualisierung in der Warteschlange steht. Das Nachsteuern ändert keine bereits an deine Anwendung gesendete Ausgabe und macht bereits gestartete Tool-Aufrufe nicht rückgängig. Der Leitfaden zum Nachsteuern während einer laufenden Antwort beschreibt die Abfolge der Ereignisse und den Umgang mit Tool-Ergebnissen.

Fazit

Die Responses API bildet die Grundlage für intelligentere, leistungsfähigere Anwendungen mit OpenAI. Mit ihr kannst du über einzelne Prompts hinausgehen und dauerhafte Workflows entwickeln, die Tools nutzen, den Kontext berücksichtigen und sich an die Komplexität der Aufgabe anpassen. Nutze die Empfehlungen in diesem Leitfaden, um die Leistung deiner Anwendungen im Produktivbetrieb zu verbessern.