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

Agenten ausführen

So funktionieren die Agentenschleife, die Fortsetzung von Gesprächen und das Streaming.

Einen Agenten zu definieren ist der erste Schritt. Zur Laufzeit kommt es darauf an, was in einem einzelnen Lauf passiert, wie das Gespräch in der nächsten Runde weitergeht und wie sich der Workflow verhält, wenn er auf eine Genehmigung oder das Ergebnis eines Tool-Aufrufs wartet.

Die Agentenschleife

Ein SDK-Lauf entspricht einer Gesprächsrunde auf Anwendungsebene. Der Runner durchläuft die folgenden Schritte, bis er einen Haltepunkt erreicht:

  1. Er ruft das Modell des aktuellen Agenten mit der vorbereiteten Eingabe auf.
  2. Er prüft die Modellausgabe.
  3. Enthält die Ausgabe Tool-Aufrufe, führt er sie aus und setzt die Schleife fort.
  4. Übergibt das Modell die Aufgabe an einen anderen spezialisierten Agenten, wechselt der Runner zu diesem Agenten und setzt die Schleife fort.
  5. Liefert das Modell eine abschließende Antwort und sind keine weiteren Tool-Aufrufe nötig, gibt der Runner das Ergebnis zurück.

Diese Schleife bildet den Kern des SDK. Tools, Übergaben, Genehmigungen und Streaming bauen auf ihr auf.

Eine Strategie für den Gesprächszustand wählen

Es gibt vier gängige Möglichkeiten, den Gesprächszustand in die nächste Runde zu übernehmen:

Strategie Wo der Zustand gespeichert ist Besonders geeignet für Was du in der nächsten Runde übergibst
result.history In deiner Anwendung Einfache Chat-Schleifen und maximale Kontrolle Den für die erneute Eingabe aufbereiteten Verlauf
session In deinem Speicher, verwaltet mit dem SDK Dauerhaft gespeicherte Chat-Zustände, fortsetzbare Läufe und Speicher, den du selbst verwaltest Dieselbe Sitzung
conversationId In der OpenAI Conversations API Mehrere Worker oder Dienste, die einen serverseitig verwalteten Zustand gemeinsam nutzen Dieselbe Gesprächs-ID und nur die neue Runde
previousResponseId In der OpenAI Responses API Serverseitige Fortsetzung von einer Antwort zur nächsten mit möglichst wenig Aufwand Die ID der letzten Antwort und nur die neue Runde

In den meisten Anwendungen solltest du pro Gespräch eine Strategie wählen. Wenn du den lokalen Verlauf erneut übergibst und zugleich den serverseitig verwalteten Zustand nutzt, kann Kontext doppelt vorkommen. Das lässt sich vermeiden, indem du beide Ebenen gezielt abgleichst.

Gesprächszustand mit Sitzungen über mehrere Runden speichern
import { Agent, MemorySession, run } from "@openai/agents";

const agent = new Agent({
  name: "Tour guide",
  instructions: "Answer with compact travel facts.",
});

const session = new MemorySession();

const firstTurn = await run(agent, "What city is the Golden Gate Bridge in?", {
  session,
});
console.log(firstTurn.finalOutput);

const secondTurn = await run(agent, "What state is it in?", { session });
console.log(secondTurn.finalOutput);

Sitzungen sind die beste Standardwahl, wenn du Informationen dauerhaft speichern, Genehmigungsabläufe nach einer Unterbrechung fortsetzen oder den Speicher in deiner Anwendung selbst verwalten möchtest.

Gespräch mit serverseitig verwaltetem Zustand fortsetzen
import { Agent, run } from "@openai/agents";
import OpenAI from "openai";

const agent = new Agent({
  name: "Assistant",
  instructions: "Reply very concisely.",
});

const client = new OpenAI();
const { id: conversationId } = await client.conversations.create({});

const first = await run(agent, "What city is the Golden Gate Bridge in?", {
  conversationId,
});
console.log(first.finalOutput);

const second = await run(agent, "What state is it in?", {
  conversationId,
});
console.log(second.finalOutput);

Verwende conversationId, wenn mehrere Systeme dasselbe benannte Gespräch nutzen sollen. Verwende previousResponseId, wenn du mit möglichst geringem Aufwand an die vorherige Antwort anknüpfen möchtest.

Ausgaben während eines Laufs streamen

Beim Streaming nutzt du dieselbe Agentenschleife und dieselben Strategien für den Gesprächszustand. Der einzige Unterschied besteht darin, dass du Ereignisse schon während des Laufs verarbeitest.

Text streamen, sobald er eintrifft
import { Agent, run } from "@openai/agents";

const agent = new Agent({
  name: "Planet guide",
  instructions: "Answer with short facts.",
});

const stream = await run(agent, "Give me three short facts about Saturn.", {
  stream: true,
});

for await (const event of stream) {
  if (
    event.type === "raw_model_stream_event" &&
    event.data.type === "output_text_delta"
  ) {
    process.stdout.write(event.data.delta);
  }
}

await stream.completed;
console.log("\nFinal:", stream.finalOutput);

Beachte dabei drei Regeln:

  • Warte, bis der Stream endet, bevor du den Lauf als abgeschlossen behandelst.
  • Wartet der Lauf auf eine Genehmigung, bearbeite die ausstehenden Anfragen in interruptions und setze den Lauf mit state fort. Damit bleibst du in derselben Gesprächsrunde.
  • Wenn du einen Stream mitten in einer Runde abbrichst und dieselbe Runde später fortsetzen möchtest, nimm sie mit state wieder auf.

Pausen und Fehler gezielt behandeln

Wenn ein Lauf vom regulären Ablauf abweicht, unterscheide zwei Fälle:

  • Laufzeit- oder Validierungsfehler treten etwa auf, wenn die Höchstzahl an Runden erreicht ist, eine Schutzprüfung eine Ausnahme auslöst oder ein Tool einen Fehler meldet.
  • Erwartete Pausen entstehen etwa, wenn eine Person eine Aktion genehmigen soll. Der Lauf wird dazu gezielt unterbrochen und soll später mit demselben Zustand fortgesetzt werden.

Behandle eine ausstehende Genehmigung als Pause im aktuellen Lauf. Setze anschließend dieselbe Gesprächsrunde fort. So bleiben die Anzahl der Runden, der Verlauf und die serverseitig verwalteten IDs zur Fortsetzung des Gesprächs konsistent.

Nächste Schritte

Wenn du mit der Agentenschleife vertraut bist, wähle den Leitfaden für den Teil deines Workflows, den du als Nächstes gestalten möchtest.