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:
- Er ruft das Modell des aktuellen Agenten mit der vorbereiteten Eingabe auf.
- Er prüft die Modellausgabe.
- Enthält die Ausgabe Tool-Aufrufe, führt er sie aus und setzt die Schleife fort.
- Übergibt das Modell die Aufgabe an einen anderen spezialisierten Agenten, wechselt der Runner zu diesem Agenten und setzt die Schleife fort.
- 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.
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.
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
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.
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
interruptionsund setze den Lauf mitstatefort. 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
statewieder 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.
Erfahre, welche Teile des Ergebnisses deine Anwendung in die nächste Gesprächsrunde übernehmen sollte.
Lege fest, wie mehrere spezialisierte Agenten innerhalb derselben Schleife zusammenarbeiten.
Integriere Validierungen und Pausen für Genehmigungen so, dass der Lauf in derselben Gesprächsrunde weitergehen kann.