Diese Anleitung zeigt dir den kürzesten Weg zu einem lauffähigen Agenten mit dem SDK. Die Beispiele für TypeScript und Python folgen demselben Prinzip. Du definierst einen Agenten und führst ihn aus. Wenn dein Workflow wächst, ergänzt du Tools und spezialisierte Agenten.
SDK installieren
Lege ein Projekt an, installiere das SDK und setze die Umgebungsvariable für deinen API-Schlüssel.
API-Schlüssel erstellen
# TypeScript
npm install @openai/agents zod
# Python
pip install openai-agents
export OPENAI_API_KEY=sk-...
Deinen ersten Agenten erstellen und ausführen
Beginne mit einem Agenten, der eine klar umrissene Aufgabe hat, und einer einzigen Gesprächsrunde. Das SDK ruft das Modell auf und gibt ein Ergebnisobjekt zurück. Es enthält die abschließende Ausgabe und den Verlauf des Durchlaufs.
import { Agent, run } from "@openai/agents";
const agent = new Agent({
name: "History tutor",
instructions: "You answer history questions clearly and concisely.",
model: "gpt-6-astra",
});
const result = await run(agent, "When did the Roman Empire fall?");
console.log(result.finalOutput);Im Terminal solltest du eine kurze Antwort sehen. Sobald dieser Ablauf funktioniert, behalte die Struktur bei und ergänze weitere Funktionen Schritt für Schritt. So brauchst du nicht von Anfang an ein umfangreiches System mit mehreren Agenten zu entwerfen.
Den Zustand in die nächste Gesprächsrunde übernehmen
Anhand des Ergebnisses des ersten Durchlaufs entscheidest du auch, welchen Zustand die zweite Gesprächsrunde übernehmen soll.
| Dein Ziel | Was du dafür verwendest |
|---|---|
| Den vollständigen Verlauf in deiner Anwendung speichern | result.history |
| Den Verlauf vom SDK laden und speichern lassen | Eine Sitzung |
| Den Zustand für die Fortsetzung von OpenAI verwalten lassen | Eine serverseitig verwaltete ID für die Fortsetzung |
| Einen Durchlauf fortsetzen, der auf eine Genehmigung wartet oder unterbrochen wurde | result.stateinterruptions |
Soll nach einer Übergabe derselbe spezialisierte Agent das Gespräch weiterführen, verwende für die nächste Gesprächsrunde erneut lastAgent
Dem Agenten ein Tool hinzufügen
Als Erstes ergänzt du häufig ein Funktionstool oder ein von OpenAI gehostetes Tool wie die Websuche oder die Dateisuche.
import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";
const historyFunFact = tool({
name: "history_fun_fact",
description: "Return a short history fact.",
parameters: z.object({}),
async execute() {
return "Sharks are older than trees.";
},
});
const agent = new Agent({
name: "History tutor",
instructions:
"Answer history questions clearly. Use history_fun_fact when it helps.",
tools: [historyFunFact],
});
const result = await run(
agent,
"Tell me something surprising about ancient life on Earth."
);
console.log(result.finalOutput);Die übergreifende Anleitung Tools verwenden zeigt dir, wie du gehostete Tools, die Tool-Suche oder Agenten als Tools einsetzt.
Spezialisierte Agenten hinzufügen
Ein häufiger nächster Schritt ist, den Workflow in Aufgaben für spezialisierte Agenten aufzuteilen. Ein Router übergibt dann jede Aufgabe an den zuständigen Agenten.
import { Agent, run } from "@openai/agents";
const historyTutor = new Agent({
name: "History tutor",
instructions: "Answer history questions clearly and concisely.",
});
const mathTutor = new Agent({
name: "Math tutor",
instructions: "Explain math step by step and include worked examples.",
});
const triageAgent = Agent.create({
name: "Homework triage",
instructions: "Route each homework question to the right specialist.",
handoffs: [historyTutor, mathTutor],
});
const result = await run(
triageAgent,
"Who was the first president of the United States?"
);
console.log(result.finalOutput);
console.log(result.lastAgent?.name);Traces frühzeitig prüfen
Bei der üblichen serverseitigen Ausführung zeichnet das SDK Traces auf. Öffne nach dem ersten erfolgreichen Durchlauf das Traces-Dashboard. Prüfe dort Modellaufrufe, Tool-Aufrufe, Übergaben und Schutzmechanismen, bevor du deine Prompts optimierst.
Nächste Schritte
Nach dem ersten erfolgreichen Durchlauf kannst du mit der Anleitung für die Funktion weitermachen, die du als Nächstes hinzufügen möchtest.
Lege die Aufgabe eines spezialisierten Agenten klar fest, bevor du den Workflow erweiterst.
Füge gehostete Tools und Funktionstools hinzu und setze Agenten als Tools ein.
Erfahre, wie die Agentenschleife und das Streaming funktionieren und wie du einen Durchlauf fortsetzen kannst.
Entscheide, wann spezialisierte Agenten das Gespräch übernehmen sollen.