For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Hauptnavigation

Beobachtbarkeit und Nutzung

Sieh dir den Fortschritt in Echtzeit, abgeschlossene Arbeiten und den erfassten Tokenverbrauch an.

Verfolge die Aktivitäten von Agenten in Echtzeit, sieh dir abgeschlossene Arbeiten an und prüfe detaillierte Traces einzelner Turns:

  1. Du kannst die Sitzungsprotokolle im Platform-Dashboard einsehen.
  2. Du kannst die Sitzung anhand ihrer Ereignisse und ihres gespeicherten Verlaufs nachverfolgen.
  3. Du kannst Turns prüfen und erkennen, welche Befehle delegiert ausgeführt wurden.
  4. Du kannst den erfassten Tokenverbrauch für Turns des Hauptagenten und der Subagenten einsehen.

Sitzung im Dashboard ansehen

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

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

Nutze den Tracing-Leitfaden, um aufgezeichnete Modellantworten, Werkzeugaufrufe und Aktivitäten von Subagenten im Dashboard zu prüfen, oder exportiere Sitzungs-Traces über die öffentliche API im Format 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 beispielhafte Sitzungs-ID in diesen Beispielen durch deine gespeicherte Sitzungs-ID:

Sitzungsereignisse in Echtzeit 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 bei Leerlaufereignissen geöffnet, damit dir keine eingereihten Aufgaben entgehen. Drücke Ctrl+C , um die Beobachtung zu beenden.

Während die Sitzung läuft, siehst du Ereignisse wie diese:

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 bereits ausgeführte Arbeiten zu prüfen, rufe die gespeicherten Elemente der Sitzung ab:

Gespeicherte Sitzungselemente 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

Die Turns einer Sitzung sind über die öffentliche API verfügbar. Verwende die turn_id aus einem Befehlselement zusammen mit deiner gespeicherten Sitzungs-ID. Für das cURL-Beispiel benötigst du jq:

Delegierte Befehlsausführung erkennen
// 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 turns = await client.beta.agents.sessions.turns.list(sessionId, {
  limit: 20,
  order: "desc",
});
console.log(turns.data);
const turnId = "turn_123";
const turn = await client.beta.agents.sessions.turns.retrieve(turnId, {
  session_id: sessionId,
});
console.log(turn.subagent_id);

Verwende die zurückgegebene last_id als Wert für after auf der nächsten Seite, wenn has_more den Wert true hat.

Befehlselemente enthalten turn_id. Rufe den zugehörigen Turn ab und lies subagent_id aus, um den beauftragten Agenten zu ermitteln, der den Befehl ausgeführt hat. Eine Subagenten-ID mit dem Wert null kennzeichnet Arbeiten des Hauptagenten. Ob die Befehlsausgabe gekürzt wurde, wird nicht angegeben.

Trace eines Turns prüfen

Nutze das Platform-Dashboard, um einen abgeschlossenen Turn und die zugehörigen Agentenaktivitäten zu prüfen. Um aufgezeichnete Traces über die öffentliche API abzurufen, verwende den Endpunkt zum Exportieren von Sitzungs-Traces mit einem API-Schlüssel für das Projekt. Die Trace-Endpunkte des Dashboards bleiben von der unterstützten Kunden-API getrennt.

Turn-Ressourcen enthalten nach dem Best-Effort-Prinzip erfasste Verbrauchsdaten in usage sowie eine subagent_id, die delegierte Arbeiten kennzeichnet. Ist der Verbrauch unbekannt, 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 ab, auf den die turn_id im zugehörigen Befehlselement verweist. Prüfe anschließend turn.subagent_id. Die API für die Kundennutzung gibt nicht an, ob die Befehlsausgabe gekürzt wurde.

Modellnutzung und Kosten

Ein Agent kann beim Bearbeiten einer Aufgabe mehrere Modellaufrufe ausführen. Für jeden Aufruf gelten wie in der Responses API die Tokenpreise und Regeln für Prompt-Caching des Modells. Berücksichtige bei der Kostenschätzung alle Aufrufe, die zum Abschließen der Aufgabe erforderlich sind.

Welche Faktoren tragen zu den Kosten bei?

Bei jedem Modellaufruf können folgende Token anfallen:

  • Eingabetoken: Agentenanweisungen, Werkzeugdefinitionen, Gesprächsverlauf, Nutzereingaben, Dateien oder Bilder sowie Werkzeugergebnisse.
  • Gecachte Eingabetoken: Eingaben, die aus einem übereinstimmenden Prompt-Präfix wiederverwendet und zum Tarif des Modells für gecachte Eingaben abgerechnet werden.
  • Ausgabetoken: generierter Text, Argumente für Werkzeugaufrufe und Reasoning-Aufwand.

Reasoning-Token werden als Ausgabetoken abgerechnet.

Auch Subagenten können Modellaufrufe ausführen. Prüfe bei der Analyse der Modellkosten neben den Arbeiten des Hauptagenten auch den erfassten Verbrauch pro Turn der Subagenten.

Berücksichtige die Arbeiten des Hauptagenten und der Subagenten einschließlich erneuter Versuche sowie gegebenenfalls anfallende Gebühren für Werkzeuge, Rechenleistung in der Sandbox und Dienste von Drittanbietern. Bei Modellen, die das Schreiben in den Cache berechnen, verursacht auch das Speichern von Eingaben im Cache Kosten. Die unten aufgeführten Verbrauchsfelder der Agents API weisen die Anzahl der in den Cache geschriebenen Token nicht gesondert aus. Wenn dieser Tarif gilt, lässt sich die genaue Modellgebühr daher nicht anhand dieser Felder ermitteln.

Prompt-Caching

Agenten führen den Kontext innerhalb einer Sitzung fort. Wenn aufeinanderfolgende Modellaufrufe dasselbe Prompt-Präfix verwenden, kann Prompt-Caching die Ergebnisse seiner bisherigen Verarbeitung wiederverwenden. Das Modell generiert eine neue Antwort; durch Caching wird keine alte Antwort erneut ausgegeben. Eine fortlaufende Sitzung garantiert keinen Cache-Treffer. Die Wiederverwendung hängt von einem übereinstimmenden Präfix und den Regeln des Modells dazu ab, welche Inhalte gecacht werden können und wie lange sie im Cache bleiben.

Lass die anfänglichen Anweisungen und Werkzeugdefinitionen nach Möglichkeit unverändert und ergänze neue Aufgabendetails in Folgenachrichten. Bei der Tool-Suche werden gefundene Definitionen am Ende des Gesprächs hinzugefügt. So bleiben frühere Inhalte für die Wiederverwendung aus dem Cache erhalten. Modellspezifische Regeln findest du unter Prompt-Caching.

Ein hoher Anteil gecachter Eingaben sagt nichts darüber aus, wie viel du bei den Gesamtkosten der Aufgabe sparst. Gecachte Eingaben werden weiterhin berechnet, und wiederholte Aufrufe können einen umfangreichen Verlauf verarbeiten. Vergleiche die Kosten für das Abschließen derselben Aufgabe bei der Qualität und Latenz, die deine Anwendung benötigt.

Tokenverbrauch verstehen

Sitzungs- und Turn-Ressourcen stellen nach dem Best-Effort-Prinzip erfasste Verbrauchsdaten in usage bereit. Ist der Verbrauch unbekannt, kann der Wert null sein. Erfasste Tokenzahlen können sich ändern, sobald weitere Abrechnungsdaten eintreffen. Fehlende Verbrauchsdaten bedeuten nicht, dass kein Verbrauch angefallen ist. Diese Zahlen stellen keine endgültige Abrechnung dar.

Ein erfasstes Verbrauchsobjekt enthält diese 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 waren 1.500 gecacht. Von den Ausgabetoken waren 200 Reasoning-Token.

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

Tokenverbrauch von Subagenten prüfen

Liste Turns einer Sitzung auf oder rufe sie ab und prüfe usage für jeden Turn. Die subagent_id identifiziert den Subagenten; bei Turns des Hauptagenten hat sie den Wert null. Wenn has_more den Wert true hat, übergib last_id als after mit demselben Wert für order, um die verbleibenden Turns zu lesen.

Der Verbrauch wird nach dem Best-Effort-Prinzip erfasst: Ist er unbekannt, kann der Wert null sein, und erfasste Werte können sich ändern. Du kannst den erfassten Verbrauch jedes Agenten auch im Tracing-Dashboard prüfen.