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 definieren

Konfiguriere zunächst einen einzelnen Agenten, bevor du deinen Workflow erweiterst.

Ein Agent ist die Grundeinheit eines SDK-basierten Workflows. Er verbindet ein Modell mit Anweisungen und optionalen Laufzeitfunktionen wie Tools, Schutzmechanismen, MCP-Servern, Übergaben und strukturierten Ausgaben.

Was zur Konfiguration eines Agenten gehört

Lege in der Agentenkonfiguration fest, was für die jeweilige Spezialisierung gilt.

Eigenschaft Zweck Weitere Informationen
name Lesbarer Name, an dem du den Agenten in Traces sowie bei Toolaufrufen und Übergaben erkennst Diese Seite
instructions Aufgabe, Einschränkungen und Stil des Agenten festlegen Diese Seite
prompt Eine gespeicherte Prompt-Konfiguration für Ausführungen mit der Responses API verwenden Modelle und Anbieter
model und Modelleinstellungen Das Modell auswählen und sein Verhalten anpassen Modelle und Anbieter
tools Funktionen bereitstellen, die der Agent direkt aufrufen kann Tools verwenden
handoffDescription Angeben, wann ein anderer Agent eine Aufgabe an diesen Agenten übergeben sollte Orchestrierung und Übergaben
handoffs Aufgaben an einen anderen Agenten übergeben Orchestrierung und Übergaben
outputType Eine strukturierte Ausgabe anstelle von reinem Text zurückgeben Diese Seite
Schutzmechanismen und Genehmigungen Abläufe für Validierung, Sperren und Überprüfungen festlegen Schutzmechanismen und Überprüfung durch Menschen
MCP-Server und gehostete MCP-Tools Funktionen über MCP anbinden Integrationen und Observability

Mit einem Agenten für eine klar umrissene Aufgabe beginnen

Definiere den einfachsten Agenten, der eine klar umrissene Aufgabe eigenständig übernehmen kann. Füge weitere Agenten erst hinzu, wenn du Zuständigkeiten trennen musst oder unterschiedliche Anweisungen, Tools oder Genehmigungsrichtlinien brauchst.

Einen einzelnen Agenten definieren
import { Agent, tool } from "@openai/agents";
import { z } from "zod";

const getWeather = tool({
  name: "get_weather",
  description: "Return the weather for a given city.",
  parameters: z.object({ city: z.string() }),
  async execute({ city }) {
    return `The weather in ${city} is sunny.`;
  },
});

const agent = new Agent({
  name: "Weather bot",
  instructions: "You are a helpful weather bot.",
  model: "gpt-6-astra",
  tools: [getWeather],
});

Anweisungen, Übergaben und Ausgaben gestalten

Achte bei der Konfiguration besonders auf diese drei Entscheidungen.

  • Beginne mit statischen instructions. Wenn die Anweisungen davon abhängen, wer den Agenten nutzt, um welchen Mandanten es geht oder welcher Laufzeitkontext vorliegt, erzeuge sie dynamisch mit einem Callback. So musst du am Aufrufort keine Zeichenketten zusammensetzen.
  • Formuliere handoffDescription kurz und konkret, damit Agenten beim Weiterleiten einer Aufgabe erkennen, wann sie diesen spezialisierten Agenten auswählen sollen.
  • Verwende outputType, wenn der nachgelagerte Code typisierte Daten statt frei formulierten Texts benötigt.
Eine strukturierte Ausgabe zurückgeben
import { Agent, run } from "@openai/agents";
import { z } from "zod";

const calendarEvent = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const agent = new Agent({
  name: "Calendar extractor",
  instructions: "Extract calendar events from text.",
  outputType: calendarEvent,
});

const result = await run(agent, "Dinner with Priya and Sam on Friday.");

console.log(result.finalOutput);

Mit prompt kannst du auf eine gespeicherte Prompt-Konfiguration der Responses API verweisen, statt den gesamten System-Prompt in den Code einzubetten.

Lokalen Kontext vom Modellkontext trennen

Mit dem SDK kannst du den Anwendungszustand und Abhängigkeiten für eine Ausführung bereitstellen, ohne sie an das Modell zu senden. Das eignet sich etwa für Angaben zur angemeldeten Person, Datenbankclients, Logger und Hilfsfunktionen.

Lokalen Kontext an Tools übergeben
import { Agent, run, tool, type RunContext } from "@openai/agents";
import { z } from "zod";

const fetchUserAge = tool({
  name: "fetch_user_age",
  description: "Return the age of the current user.",
  parameters: z.object({}),
  async execute(
    _args: unknown,
    runContext: RunContext<{ name: string; uid: number }> | undefined
  ) {
    return `User ${runContext?.context.name} is 47 years old`;
  },
});

const agent = new Agent({
  name: "Assistant",
  tools: [fetchUserAge],
});

const result = await run(agent, "What is the age of the user?", {
  context: { name: "John", uid: 123 },
});

console.log(result.finalOutput);

Entscheidend ist, wer auf welche Informationen zugreifen kann.

  • Das Modell sieht den Gesprächsverlauf.
  • Dein Code hat Zugriff auf den Ausführungskontext.

Wenn das Modell eine Information braucht, stelle sie über die Anweisungen, die Eingabe, einen Datenabruf oder ein Tool bereit. Braucht nur deine Laufzeitumgebung die Information, behalte sie im lokalen Kontext.

Wann du Aufgaben auf mehrere Agenten aufteilen solltest

Teile die Aufgaben eines Agenten auf, wenn ein spezialisierter Agent nicht für die gesamte Antwort zuständig sein soll oder wenn sich die benötigten Funktionen wesentlich unterscheiden. Typische Gründe sind folgende.

  • Ein spezialisierter Agent benötigt Zugriff auf andere Tools oder eine andere MCP-Schnittstelle.
  • Ein spezialisierter Agent benötigt eine andere Genehmigungsrichtlinie oder einen anderen Schutzmechanismus.
  • Ein Zweig des Workflows benötigt ein anderes Modell oder einen anderen Ausgabestil.
  • Du möchtest die Weiterleitung von Aufgaben in Traces nachvollziehen können, statt sie über einen einzigen umfangreichen Prompt zu steuern.

Nächste Schritte

Sobald du den ersten spezialisierten Agenten klar definiert hast, wähle den Leitfaden, der deine nächste Frage zum Workflow beantwortet.