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.
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
kurz und konkret, damit Agenten beim Weiterleiten einer Aufgabe erkennen, wann sie diesen spezialisierten Agenten auswählen sollen.handoffDescription - Verwende
, wenn der nachgelagerte Code typisierte Daten statt frei formulierten Texts benötigt.outputType
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.
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.
Wähle Modelle, Standardeinstellungen und die Transportstrategie für diesen Agenten.
Füge Funktionen hinzu, die der Agent direkt aufrufen kann.
Lege fest, wie spezialisierte Agenten zusammenarbeiten, sobald ein einzelner Agent nicht mehr ausreicht.
Erfahre, wie die Ausführungsschleife funktioniert, wie das SDK den Zustand verwaltet und wie das Streaming abläuft.