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

Beobachtbarkeit und Nutzung

Verfolge den Fortschritt in Echtzeit und prüfe abgeschlossene Aufgaben und den erfassten Tokenverbrauch.

Du kannst die Aktivitäten eines Agenten in Echtzeit verfolgen, abgeschlossene Aufgaben prüfen und detaillierte Traces einzelner Turns einsehen.

  1. Im Plattform-Dashboard kannst du die Sitzungsprotokolle einsehen.
  2. Anhand der Ereignisse und des gespeicherten Verlaufs kannst du den Ablauf der Sitzung nachvollziehen.
  3. Du kannst einzelne Turns prüfen und feststellen, welche Befehle ein Subagent ausgeführt hat.
  4. Du kannst den erfassten Tokenverbrauch für Turns des Hauptagenten und der Subagenten prüfen.

Sitzung im Dashboard anzeigen

Rufe platform.openai.com/logs?api=agents auf und öffne den Tab Agenten.

Suche anhand der ID nach einer Sitzung, um ihre Turns, Tool-Aufrufe und Subagenten zu prüfen.

Der Tracing-Leitfaden zeigt dir, wie du aufgezeichnete Modellantworten, Tool-Aufrufe und Aktivitäten der Subagenten im Dashboard prüfst. Über die öffentliche API kannst du auch Sitzungs-Traces exportieren. Du erhältst sie als OTLP-JSON.

Ereignisse verfolgen und Sitzungsverlauf prüfen

Jede Sitzung stellt einen Ereignisstream bereit, der in Echtzeit zeigt, was der Agent gerade tut. Setze OPENAI_API_KEY und ersetze die Sitzungs-ID in den folgenden Beispielen durch deine gespeicherte Sitzungs-ID.

Sitzungsereignisse live verfolgen
// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";

const client = new OpenAI();
const events = await client.beta.agents.sessions.events.stream("sess_123");
try {
  for await (const event of events) {
    if (
      [
        "agent.session.turn.failed",
        "agent.session.turn.cancelled",
        "agent.session.failed",
        "agent.session.environment.failed",
        "error",
      ].includes(event.type)
    ) {
      throw new Error(`Agent lifecycle failure: ${event.type}`);
    }
    console.log(JSON.stringify(event));
  }
} finally {
  events.controller.abort();
}

Der Stream bleibt auch dann geöffnet, wenn die Sitzung in den Leerlauf wechselt. So verpasst du keine Aufgaben aus der Warteschlange. Drücke Strg+C, um die Anzeige zu beenden.

Während die Sitzung läuft, siehst du unter anderem folgende Ereignisse:

agent.session.environment.connected
agent.session.turn.created
agent.session.turn.in_progress
agent.session.turn.item.added
agent.session.turn.output_text.delta
agent.session.turn.completed
agent.session.idle

Um nachzuvollziehen, was bereits geschehen ist, rufe die gespeicherten Einträge der Sitzung ab.

Gespeicherte Sitzungseinträge prüfen
// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";
const client = new OpenAI();

const sessionId = "sess_123";
const items = await client.beta.agents.sessions.items.list(sessionId, {
  order: "asc",
  limit: 100,
});
console.log(items.data);

Turns prüfen und delegierte Befehle erkennen

Du kannst die Turns einer Sitzung über die öffentliche API abrufen. Verwende die turn_id aus einem Befehlseintrag zusammen mit deiner gespeicherten Sitzungs-ID. Das Go-Beispiel durchsucht mit der integrierten Paginierung des SDK die Turns des Hauptagenten und der Subagenten. Anschließend ruft es den passenden Turn beim zugehörigen Agenten ab. Ersetze die Beispiel-IDs durch IDs aus deiner Sitzung. Für das cURL-Beispiel benötigst du jq.

Ermitteln, wer einen delegierten Befehl ausgeführt hat
// Replace the illustrative session and turn IDs with values from your command item.
import OpenAI from "openai";
const client = new OpenAI();

async function findTurn(sessionId: string, turnId: string) {
  for await (const turn of client.beta.agents.sessions.turns.list(sessionId, {
    limit: 100,
  })) {
    if (turn.id === turnId) {
      return client.beta.agents.sessions.turns.retrieve(turnId, {
        session_id: sessionId,
      });
    }
  }
  for await (const subagent of client.beta.agents.sessions.subagents.list(
    sessionId,
    { limit: 100 }
  )) {
    for await (const turn of client.beta.agents.sessions.subagents.turns.list(
      subagent.id,
      { session_id: sessionId, limit: 100 }
    )) {
      if (turn.id === turnId) {
        return client.beta.agents.sessions.subagents.turns.retrieve(turnId, {
          session_id: sessionId,
          subagent_id: subagent.id,
        });
      }
    }
  }
  throw new Error(`Turn ${turnId} not found in session ${sessionId}`);
}

const turn = await findTurn("sess_123", "turn_123");
console.log(turn.subagent_id || "main agent");

Bei manueller Paginierung verwendest du die zurückgegebene last_id als after-Wert für die nächste Seite, wenn has_more den Wert true hat. Das Go-Beispiel ruft die weiteren Seiten automatisch ab.

Jeder Befehlseintrag enthält eine turn_id. Rufe den zugehörigen Turn ab und lies subagent_id aus, um festzustellen, welcher Subagent den Befehl ausgeführt hat. Hat die Subagenten-ID den Wert null, hat der Hauptagent den Befehl ausgeführt. Ob die Befehlsausgabe gekürzt wurde, wird nicht angegeben.

Trace eines Turns prüfen

Im Plattform-Dashboard kannst du einen abgeschlossenen Turn und die Aktivitäten der beteiligten Agenten prüfen. Um aufgezeichnete Traces über die öffentliche API abzurufen, verwende den Endpunkt für den Export von Sitzungs-Traces mit einem API-Schlüssel für dein Projekt. Die Trace-Endpunkte des Dashboards sind von der offiziell unterstützten Kunden-API getrennt.

Turn-Ressourcen enthalten das Feld usage mit den verfügbaren Verbrauchsdaten sowie eine subagent_id, an der du delegierte Arbeit erkennst. Bei unbekanntem Verbrauch kann der Wert null sein. Die Angaben können sich ändern. Siehe Tokenverbrauch von Subagenten prüfen.

Um einen Shell-Befehl einem Agenten zuzuordnen, rufe den Turn über die turn_id aus dem Befehlseintrag ab und prüfe dann turn.subagent_id. Die Kunden-API gibt nicht an, ob die Befehlsausgabe gekürzt wurde.

Fehler und Wiederherstellung

Im Leitfaden Fehler und Wiederherstellung erfährst du, wie du Fehler untersuchst, eine geeignete Wiederherstellungsmaßnahme auswählst und den Vorgang sicher wiederholst.

Modellnutzung und Kosten

Ein Agent kann ein Modell mehrmals aufrufen, um eine Aufgabe zu erledigen. Wie bei der Responses API gelten für jeden Aufruf die Tokenpreise und die Regeln für das Prompt-Caching des jeweiligen Modells. Berücksichtige bei der Kostenschätzung alle Aufrufe, die für die Aufgabe nötig sind.

Wie setzen sich die Kosten zusammen?

Bei jedem Modellaufruf können folgende Token anfallen:

  • Eingabetoken: Anweisungen für den Agenten, Tool-Definitionen, Gesprächsverlauf, Nutzereingaben, Dateien oder Bilder sowie Tool-Ergebnisse.
  • Zwischengespeicherte Eingabetoken: Eingaben aus einem übereinstimmenden Prompt-Präfix, die erneut verwendet werden. Dafür gilt der Preis des Modells für zwischengespeicherte Eingaben.
  • Ausgabetoken: generierter Text, Argumente für Tool-Aufrufe und Reasoning.

Reasoning-Token werden als Ausgabetoken abgerechnet.

Auch Subagenten können Modelle aufrufen. Wenn du die Modellkosten untersuchst, prüfe neben der Arbeit des Hauptagenten auch den erfassten Tokenverbrauch pro Turn der Subagenten.

Berücksichtige die Arbeit des Hauptagenten und der Subagenten einschließlich aller Wiederholungsversuche. Hinzu kommen gegebenenfalls Gebühren für Tools, Rechenleistung in der Sandbox und Dienste von Drittanbietern. Bei Modellen mit gesonderten Preisen für Cache-Schreibvorgänge fallen auch Kosten an, wenn Eingaben in den Cache geschrieben werden. Die unten beschriebenen Verbrauchsfelder der Agents API weisen die in den Cache geschriebenen Token nicht separat aus. Bei solchen Modellen lässt sich der genaue Betrag für die Modellnutzung daher aus diesen Feldern allein nicht ermitteln.

Prompt-Caching

Agenten behalten den Kontext innerhalb einer Sitzung bei. Beginnen die Prompts aufeinanderfolgender Modellaufrufe mit demselben Präfix, kann das Modell dank Prompt-Caching auf die vorherige Verarbeitung dieses Präfixes zurückgreifen. Das Modell generiert bei jedem Aufruf eine neue Antwort. Der Cache gibt keine frühere Antwort wieder. Auch innerhalb derselben Sitzung ist ein Cache-Treffer nicht garantiert. Ob das Modell den Cache nutzen kann, hängt davon ab, ob das Präfix übereinstimmt, welche Eingaben das Modell zwischenspeichern kann und wie lange die Einträge gültig bleiben.

Lass die anfänglichen Anweisungen und Tool-Definitionen nach Möglichkeit unverändert und ergänze neue Aufgabendetails in späteren Nachrichten. Bei der Tool-Suche werden gefundene Tool-Definitionen am Ende des Gesprächs eingefügt. So bleiben frühere Inhalte für die erneute Nutzung aus dem Cache erhalten. Die Regeln für das jeweilige Modell findest du im Leitfaden zum Prompt-Caching.

An einem hohen Anteil zwischengespeicherter Eingabetoken lässt sich nicht ablesen, wie viel du bei der gesamten Aufgabe sparst. Auch zwischengespeicherte Eingaben werden abgerechnet. Bei wiederholten Aufrufen kann das Modell jedes Mal einen langen Gesprächsverlauf verarbeiten. Vergleiche die Gesamtkosten für dieselbe Aufgabe bei der Qualität und Latenz, die deine Anwendung benötigt.

Tokenverbrauch verstehen

Sitzungs- und Turn-Ressourcen geben im Feld usage den Verbrauch an, soweit er erfasst wurde. Bei unbekanntem Verbrauch kann der Wert null sein. Sobald weitere Abrechnungsdaten vorliegen, können sich die erfassten Zahlen ändern. Fehlende Angaben bedeuten nicht, dass keine Token verbraucht wurden. Die endgültige Abrechnung kann von diesen Zahlen abweichen.

Ein erfasstes Verbrauchsobjekt enthält folgende Tokenkategorien:

{
  "input_tokens": 5000,
  "input_tokens_details": {
    "cached_tokens": 1500
  },
  "output_tokens": 900,
  "output_tokens_details": {
    "reasoning_tokens": 200
  },
  "total_tokens": 5900
}

In diesem Beispiel hat der Agent 5.000 Eingabetoken verarbeitet und 900 Ausgabetoken generiert. Von den Eingabetoken stammten 1.500 aus dem Cache. Von den Ausgabetoken entfielen 200 auf das Reasoning.

Zwischengespeicherte Token sind in input_tokens enthalten, Reasoning-Token in output_tokens.

Tokenverbrauch von Subagenten prüfen

Liste die Turns einer Sitzung auf oder rufe sie einzeln ab. Prüfe für jeden Turn das Feld usage. Die subagent_id gibt an, zu welchem Subagenten der Turn gehört. Bei Turns des Hauptagenten hat sie den Wert null. Wenn has_more den Wert true hat, übergib last_id als after und behalte denselben Wert für order bei, um die restlichen Turns abzurufen.

Der Verbrauch wird angegeben, soweit er erfasst wurde. Bei unbekanntem Verbrauch kann der Wert null sein. Bereits erfasste Werte können sich ändern. Du kannst den erfassten Verbrauch jedes Agenten auch im Tracing-Dashboard prüfen.