OpenAI Agents SDK – Ein Leitfaden für Finanzinstitute
Einleitung
Agentische KI verspricht, komplexe Aufgaben vollständig autonom auszuführen. Die OpenAI Agents SDK bietet seit 2025 einen standardisierten Rahmen, um solche Agenten zu entwickeln. Sie reduziert den Integrationsaufwand erheblich, indem sie Anweisungen, Werkzeuge, Speicher und Sicherheit in einer einzigen Bibliothek kombiniert. In diesem Beitrag fassen wir die wichtigsten Bausteine der SDK zusammen und erläutern neue Entwicklungen bis Anfang 2026.
Kernbaustein „Agent“
Ein Agent ist ein System, das auf einem großen Sprach-Transformer basiert und ihn zusammen mit Anweisungen, Tools und Logik nutzt. Für einen funktionsfähigen Agenten sind lediglich zwei Eigenschaften erforderlich: ein eindeutiger Name und Anweisungen, die sein Verhalten festlegen. Die Anweisungen dienen als System‑Prompt und bestimmen, ob der Agent zum Beispiel als „hilfreicher Assistent“ oder „finanzieller Rechercheur“ antwortet. Erweiterungen wie Werkzeuge, Handoffs, Guardrails, Kontext oder Metadaten können je nach Anwendungsfall ergänzt werden.
Synchronous vs. Asynchronous
Agenten können entweder synchron oder asynchron ausgeführt werden. run_sync() führt den Agenten blockierend aus, das bedeutet, dass das Programm an dieser Stelle anhält und keine weiteren Anweisungen ausführt, bis das Ergebnis vollständig berechnet wurde. In Umgebungen mit bestehendem asyncio-Loop (z. B. Jupyter) kann run() als asynchroner, also nicht-blockierender, Aufruf genutzt werden. Nicht-blockierend heißt, dass der Agent im Hintergrund ausgeführt wird, während das Programm parallel andere Aufgaben weiterverarbeiten kann, anstatt auf das Ergebnis warten zu müssen.
Werkzeuge (Tools)
Werkzeuge erlauben Agenten, mehr als nur Text zu generieren. Sie können Python‑Funktionen ausführen, auf andere Agenten delegieren oder auf gehostete Dienste zugreifen. Die SDK unterscheidet drei Klassen von Werkzeugen:
| Werkzeugklasse | Beschreibung |
| Function Tools | Python‑Funktionen, die als Werkzeug bereitgestellt werden. Sie müssen mit dem Dekorator `@function_tool` versehen sein. Der Agent nutzt den Funktionsnamen und die Docstring als Metadaten, um zu entscheiden, wann er die Funktion aufruft |
| Agent-Tools | Statt einer Funktion kann ein anderer Agent als Werkzeug genutzt werden. Das ermöglicht die Delegation komplexer Aufgaben an spezialisierte Unteragenten. |
| Gehostete Tools | Von OpenAI bereitgestellte Werkzeuge wie WebSearchTool, FileSearchTool, ComputerTool oder CodeInterpreter. Diese Dienste laufen in der Cloud und müssen nicht selbst implementiert werden. |
Die Beschreibung der Werkzeuge ist zentral: Der Agent liest nur die Metadaten und entscheidet anhand der Docstring, ob ein Werkzeug erforderlich ist. Klare, ausführliche Beschreibungen erhöhen daher die Wahrscheinlichkeit, dass das richtige Werkzeug aufgerufen wird.
Tool‑Nutzung steuern
In manchen Situationen muss man die Werkzeugnutzung erzwingen oder einschränken. Über die `ModelSettings.tool_choice`‑Option kann man festlegen, ob der Agent ein bestimmtes Werkzeug nutzen muss, vermeiden oder die Entscheidung dem Modell überlassen soll. Zudem lässt sich mit `tool_use_behavior` definieren, ob das Ergebnis eines Tools direkt zurückgegeben oder erneut vom Modell verarbeitet werden soll.
Beispiel: Funktion als Werkzeug
Ein häufiges Szenario ist, dass ein Agent auf Python‑Funktionen zurückgreifen kann. Das folgende Beispiel definiert eine Funktion `get_weather()`, markiert sie mit `@function_tool` und übergibt sie als Werkzeug an einen Agenten:
Der Code in Figure 1 demonstriert, wie der Agent die Wetterfunktion über ihre Beschreibung erkennt und bei Bedarf aufruft.
Beispiel: Werkzeugnutzung erzwingen
Manchmal ist es sinnvoll, das Modell zur Nutzung eines Werkzeugs zu zwingen. Im folgenden Beispiel wird mittels `ModelSettings` festgelegt, dass das `get_weather`‑Werkzeug zwingend genutzt werden soll:
Die Option `tool_choice` auf den Namen des Werkzeugs zu setzen (siehe Figure 2) führt dazu, dass das Modell die Funktion stets aufruft.
Handoffs – Delegation an andere Agenten
Handoffs ermöglichen es einem Agenten, Aufgaben an spezialisierte Unteragenten zu übergeben. Ein Agent kann entweder eine endgültige Antwort liefern oder eine Handoff-Instruktion erzeugen. Die Runner-Klasse fungiert dabei als zentrale Ausführungs- und Steuerinstanz: Sie startet den Agenten, überwacht dessen Ausgabe und erkennt, ob eine normale Antwort oder eine Handoff-Anweisung erzeugt wurde. Falls ein Handoff vorliegt, übernimmt die Runner-Klasse die Koordination und übergibt automatisch die Kontrolle sowie den aktuellen Kontext an den angegebenen Unteragenten, sodass der Ablauf ohne manuelles Eingreifen fortgesetzt wird.
Die Handoff‑Funktion lässt sich fein anpassen. Sie bietet Parameter wie `tool_name_override` zum Umbenennen des Unteragenten, `tool_description_override` für eine alternative Beschreibung, `on_handoff` für Callback‑Logik sowie `input_type` und `input_filter` für die Definition der Eingabedaten. Solche Optionen sind wichtig, wenn Agenten etwa zwischen verschiedenen Fachgebieten wechseln – zum Beispiel von der Bearbeitung mathematischer Fragen zur Reisekostenberatung.
Beispiel: Delegation via Handoffs
Im folgenden Beispiel fungiert ein Triage‑Agent als Router: Er entscheidet anhand der Sprache der Benutzeranfrage, ob an einen spanischsprachigen oder englischsprachigen Unteragenten übergeben werden soll. Die Handoff‑Mechanik wird automatisch von der SDK verarbeitet; der Entwickler muss lediglich die Unteragenten in der `handoffs`‑Liste angeben:
Dieses Beispiel (in Figure 3) zeigt, wie durch Handoffs komplexe multiagentische Workflows orchestriert werden können. Der Triage‑Agent erkennt automatisch, dass die Anfrage auf Spanisch ist, und übergibt die Kontrolle an den entsprechenden Unteragenten.
Kontext und dynamische Instruktionen
Der Kontext ist ein Objekt, das pro Ausführung an den Agenten übergeben wird. Er dient als „Dependency Injection“ und stellt zustandsabhängige Informationen bereit, die nicht im Benutzerprompt enthalten sind. Das kann z. B. der Name und das Alter eines Nutzers sein oder Funktionen zum Abfragen interner Datenbanken. Der Kontext wird in einem `RunContextWrapper` verpackt, der als erstes Argument an alle Werkzeug‑Funktionen und Hooks übergeben wird.
Der Kontext wird nicht automatisch an das Sprachmodell gesendet. Wenn diese Informationen Teil des Prompts werden sollen, verwendet man dynamische Instruktionen. Dabei übergibt man dem Agenten statt eines statischen Strings eine Funktion, die den Kontext aus dem Wrapper liest und daraus einen Prompt generiert. So lässt sich etwa ein personalisierter Gruss erstellen, indem der Benutzername zur Laufzeit in die Anweisungen eingefügt wird.
Beispiel: Verwendung des Kontext‑Wrappers
Das folgende Beispiel definiert eine Pydantic‑Dataklasse `UserInfo`, übergibt sie als Kontext und implementiert ein Werkzeug, das den Namen des Benutzers aus dem `RunContextWrapper` ausliest. Die SDK sorgt dafür, dass der Kontext automatisch an die Werkzeugfunktion übergeben wird:
Dieses Code‑Snippet (siehe Figure 4) veranschaulicht, wie Kontextdaten über `RunContextWrapper` an Werkzeuge weitergereicht werden.
Beispiel: Dynamische Instruktionen
Anstatt statische Instruktionen zu verwenden, können diese zur Laufzeit auf Basis des Kontextes generiert werden. Im folgenden Beispiel ist `dynamic_instructions` eine Funktion, die den Namen des Nutzers aus dem Kontext liest und in den System‑Prompt einbettet:
Der Agent verwendet in Figure 5 die Funktion `dynamic_instructions`, um den System‑Prompt zur Laufzeit aus dem Kontext zu generieren.
Sessions – Gedächtnis für Unterhaltungen
Ein Session‑Objekt fungiert als persistenten Speicher und merkt sich vergangene Dialoge. Ohne Session ist der Agent zustandslos und vergisst vorangegangene Nachrichten. Sessions sind besonders für Chat‑Anwendungen relevant, da sie Zusammenhänge zwischen mehreren Anfragen herstellen können. Die SDK unterstützt verschiedene Speicherorte:
- SQLite‑Session: Speichert Gesprächsverläufe lokal in einer SQLite‑Datei und lädt sie bei jedem neuen Run automatisch.
- In‑Memory‑Session: Behält die Historie nur im Arbeitsspeicher, nützlich für temporäre Chats.
- OpenAI Conversations API‑Session: Speichert die Historie in der Cloud von OpenAI, sodass keine eigene Datenbank benötigt wird.
Beispiel: Verwendung einer Session
Die folgende Sequenz zeigt, wie eine `SQLiteSession` verwendet wird, um den Gesprächsverlauf über mehrere Aufrufe hinweg zu speichern. Der Agent merkt sich die Antworten aus vorherigen Fragen:
Die SDK übernimmt das Speichermanagement (siehe Figure 6). Der Agent erhält bei jedem Run automatisch die Historie und kann daraus schlüssige Antworten ableiten.
Guardrails – Sicherheit und Compliance
Guardrails sind Sicherheitsmechanismen, die Eingaben und Ausgaben eines Agenten prüfen. Die SDK unterscheidet Input‑ und Output‑Guardrails:
Input Guardrails: Prüfen die Benutzeranfrage, bevor der Agent sie verarbeitet. Das Beispiel in der Abbildung 7 nutzt ein Input‑Guardrail, um zu verhindern, dass der Agent Mathe‑Hausaufgaben löst.
Output Guardrails: Evaluieren die Antwort des Agenten, etwa um gewaltsame Inhalte zu blockieren.
Guardrail‑Funktionen liefern strukturierte Ergebnisse und lösen bei Verstössen Ausnahmen aus. Für Banken sind solche Sicherheitsmechanismen essenziell, um regulatorische Anforderungen einzuhalten und sensible Daten zu schützen.
Beispiel: Input‑Guardrail zum Blockieren von Mathematik‑Anfragen
Um zu verhindern, dass ein Support‑Agent mit Mathe‑Hausaufgaben überlastet wird, kann ein Input‑Guardrail definiert werden. Der Guardrail wird vor der Agentenausführung ausgeführt und bricht bei unerwünschten Inhalten ab:
In diesem Beispiel (siehe Figure 7) prüft `math_guardrail` die Benutzeranfrage und wirft bei Zahlenerkennung eine `InputGuardrailTripwireTriggered`‑Exception. Dies entspricht der Verwendung eines Input‑Guardrails in der SDK.
Hooks – Einblick in den Agentenlebenszyklus
Hooks sind Ereignislistener, die es erlauben, Logik vor, während oder nach einer Agentenausführung einzubinden. Es gibt AgentHooks, die an einen spezifischen Agenten gebunden sind, und RunHooks, die für einen gesamten Ausführungslauf gelten. Über Methoden wie `on_start` und `on_tool_end` lassen sich z. B. Protokolle schreiben oder zusätzliche Validierungen durchführen.
Neue Entwicklungen bis 2026
Seit der Erstveröffentlichung im März 2025 wird die Agents SDK kontinuierlich erweitert. Laut OpenAI‑Blog liegt der Schwerpunkt auf vier Bereichen: leicht konfigurierbare Agenten, intelligente Handoffs, konfigurierbare Guardrails und integrierte Tracing‑/Observability‑Funktionen. Diese Funktionen erleichtern das Debugging und die Qualitätskontrolle bei komplexen Workflows.
Im Sommer 2025 kündigte OpenAI weitere Verbesserungen an. Die SDK unterstützt nun TypeScript und bringt damit bekannte Features wie Guardrails, Handoffs und das Model Context Protocol in die JavaScript‑Welt. Zudem wurden human‑in‑the‑loop‑Approvals eingeführt, mit denen Entwickler Toolaufrufe anhalten und manuell genehmigen oder ablehnen können. Für Sprachagenten gibt es ein verbessertes Speech‑to‑Speech‑Modell mit besserer Instruktionsbefolgung und der Möglichkeit, die Sprechgeschwindigkeit zu steuern.
Fazit
Die OpenAI Agents SDK markiert einen wichtigen Schritt hin zu praktischer, agentischer KI. Sie reduziert die Komplexität beim Bau von Agenten durch Werkzeuge, Handoffs und Guardrails – und erlaubt dennoch eine fein abgestimmte Steuerung. Für Finanzinstitute eröffnen sich damit vielfältige Möglichkeiten, die Kundenbetreuung zu verbessern, Prozesse zu automatisieren und regulatorische Anforderungen einzuhalten.
Mit einem akademischen Hintergrund in Mathematik (MSc, Universität Zürich) und Berufserfahrung als IT Consultant in Zürich verbindet er analytische Stärke mit praxisnaher Umsetzung. In verschiedenen Projekten bei Schweizer Grossbanken verantwortete er die Entwicklung und Implementierung von Lösungen in den Bereichen Datenmigration, Reconciliation und Automatisierung. Dabei setzte er Python und SQL ein, um komplexe Prozesse zu optimieren und Daten als messbaren Wert für das Business nutzbar zu machen.
Durch die Kombination aus Forschung, Lehre und Beratung arbeitet er daran, skalierbare, datenbasierte Lösungen für das Banking der Zukunft zu gestalten.