OpenAI Agents SDK Tutorial: KI-Systeme bauen, die handeln

Voraussetzungen für die Arbeit mit dem OpenAI Agents SDK

Bevor du ins OpenAI Agents SDK einsteigst, solltest du einige Grundlagen verstehen und deine Umgebung richtig einrichten. Dieser Abschnitt deckt alles ab, was du vor deinem ersten Agenten wissen musst.

Erforderliches Wissen

Um das meiste aus diesem Tutorial herauszuholen, solltest du dich auskennen mit:

• Fortgeschrittener Python-Programmierung: Du verstehst Funktionen, Klassen, async/await-Muster und Type Hints
• Grundlegender Nutzung der OpenAI API: Vertrautheit mit dem Senden von Anfragen an OpenAI-Modelle und dem Verarbeiten von Antworten
• Großen Sprachmodellen (LLMs): Verständnis ihrer Funktionsweise, Möglichkeiten und Grenzen
• Pydantic: Grundkenntnisse in Datenvalidierung mit Pydantic sind hilfreich, da das Agents SDK es intensiv nutzt
• Asynchroner Programmierung: Vertrautheit mit async/await-Mustern in Python, da das Agents SDK auf asynchroner Ausführung basiert

Wenn du eines dieser Themen auffrischen willst, bietet DataCamp starke Ressourcen:

• Working with the OpenAI API — Lerne die Grundlagen der Arbeit mit OpenAI-Modellen.
• OpenAI Fundamentals Track — Ein umfassender Lernpfad zu OpenAI-Technologien.
• GPT-4.5 overview — Erfahre mehr über die neuesten Fähigkeiten der GPT-Modelle.
• Function calling with GPT-4.5 — Essenzieller Hintergrund, um Tool-Nutzung in Agenten zu verstehen.
• Using the GPT-4.5 API — Praxisguide für die Arbeit mit fortgeschrittenen Modellen.

Zentrale Konzepte für Agenten

Bevor wir mit dem Code starten, klären wir einige Schlüsselkonzepte, die im Agents SDK eine zentrale Rolle spielen:

1. Agenten: KI-Systeme, die Tools nutzen und Entscheidungen treffen können, um Aufgaben zu erledigen
2. Tools: Funktionen, die Agenten aufrufen können, um z. B. im Web zu suchen oder auf Datenbanken zuzugreifen
3. Handoffs: Mechanismen, um die Kontrolle zwischen spezialisierten Agenten zu übergeben
4. Guardrails: Sicherheitsmechanismen, die Ein- und Ausgaben validieren, um angemessenes Verhalten sicherzustellen

Dieses Verständnis und das Zusammenspiel der Konzepte helfen dir, wirkungsvollere Agenten-Anwendungen zu bauen. Mehr dazu in unserem Guide Understanding AI agents. 

OpenAI Agents: Umgebung einrichten

Richten wir die Entwicklungsumgebung so ein, dass alles für das OpenAI Agents SDK bereitsteht:

Erforderliche Pakete installieren

Lege zuerst eine virtuelle Umgebung an und aktiviere sie:

# Create and activate a virtual environment (run in your terminal)
python -m venv agents-env
source agents-env/bin/activate  # On Windows: agents-env\Scripts\activate

Installiere anschließend das OpenAI Agents SDK und python-dotenv:

pip install openai-agents python-dotenv

python-dotenv für API-Keys verwenden

API-Keys sollten nicht im Code stehen. Das Paket python-dotenv bietet einen sicheren Weg, Umgebungsvariablen zu verwalten:

1. Erstelle eine Datei namens .env im Projektverzeichnis
2. Füge deinen OpenAI API-Key in diese Datei ein:

OPENAI_API_KEY=your-api-key-here

3. Lade die Umgebungsvariablen im Code und nutze sie:

import os
from dotenv import load_dotenv
from agents import Agent, Runner

# Load environment variables from .env file
load_dotenv()

# Access your API key
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
   raise ValueError("OPENAI_API_KEY not found in .env file")

So bleibt Sensibles aus dem Code heraus — besonders wichtig, wenn du deine Arbeit teilst oder veröffentlichst.

Mit async-Funktionen arbeiten

Das OpenAI Agents SDK setzt stark auf asynchrone Programmierung. So arbeitest du mit async-Funktionen in verschiedenen Umgebungen:

In Python-Skripten (.py-Dateien)

In normalen Python-Skripten musst du asyncio.run() verwenden, um async-Funktionen auszuführen:

import asyncio
from agents import Agent, Runner

async def main():
   agent = Agent(
       name="Test Agent",
       instructions="You are a helpful assistant that provides concise responses."
   )
   result = await Runner.run(agent, "Hello! Are you working correctly?")
   print(result.final_output)

if __name__ == "__main__":
   asyncio.run(main())  # Run the async function

In Jupyter-Notebooks

Jupyter-Notebooks haben bereits eine Event-Loop, daher solltest du asyncio.run() NICHT verwenden. Stattdessen kannst du async-Funktionen direkt awaiten:

from agents import Agent, Runner

# No need for asyncio.run() in notebooks
agent = Agent(
   name="Test Agent",
   instructions="You are a helpful assistant that provides concise responses."
)
result = await Runner.run(agent, "Hello! Are you working correctly?")
print(result.final_output)

Wenn du asyncio.run() im Notebook nutzt, erhältst du Fehler wie:

RuntimeError: asyncio.run() cannot be called from a running event loop

Das ist eine der häufigsten Anpassungen beim Kopieren von Code zwischen Skripten und Notebooks. In diesem Tutorial nutze ich überwiegend die Notebook-spezifische Syntax, da viele mit Jupyter arbeiten.

Installation testen

Stellen wir sicher, dass alles korrekt eingerichtet ist:

from agents import Agent, Runner
from dotenv import load_dotenv

load_dotenv()

# For Jupyter notebooks:
agent = Agent(
   name="Test Agent",
   instructions="You are a helpful assistant that provides concise responses."
)
result = await Runner.run(agent, "Hello! Are you working correctly?")
print(result.final_output)

# For Python scripts, you'd use:
# async def test_installation():
#     agent = Agent(
#         name="Test Agent",
#         instructions="You are a helpful assistant that provides concise responses."
#     )
#     result = await Runner.run(agent, "Hello! Are you working correctly?")
#     print(result.final_output)
#
# if __name__ == "__main__":
#     asyncio.run(test_installation())

# Hello! Yes, I'm here and ready to help. How can I assist you today?

Mit dieser Einrichtung bist du bereit, Anwendungen mit dem OpenAI Agents SDK zu bauen.

Erste Schritte mit dem OpenAI Agents SDK

Das Herzstück des OpenAI Agents SDK ist die Klasse Agent. Sie ist deine primäre Schnittstelle, um KI-Systeme zu erstellen, die Anweisungen verstehen und darauf basierend handeln. Schauen wir uns an, wie du Agenten für verschiedene Szenarien erstellst und konfigurierst.

Ein Agent in diesem SDK ist ein KI-System, das Anweisungen folgen und optional Tools nutzen kann, um Aufgaben zu erledigen. Für einen Basis-Agenten brauchst du nur wenige Parameter:

from agents import Agent

basic_agent = Agent(
   name="My First Agent",
   instructions="You are a helpful assistant that provides factual information.",
   model="gpt-4o"  # Optional: defaults to "gpt-4o" if not specified
)

Die drei zentralen Bestandteile eines Agenten sind:

1. Name: Ein Bezeichner, der beim Logging und Debugging hilft
2. Instructions: Der Kern-„System Prompt“, der Verhalten und Zweck des Agenten definiert
3. Model: Das zugrunde liegende Sprachmodell (Standard: GPT-4o)

Dieses Basis-Setup reicht für den Start. Die Klasse Agent bietet darüber hinaus Modell-Optionen, mit denen du das Verhalten des LLMs feiner steuerst:

from agents import ModelSettings


advanced_agent = Agent(
   name="Advanced Assistant",
   instructions="""You are a professional, concise assistant who always provides
   accurate information. When you don't know something, clearly state that.
   Focus on giving actionable insights when answering questions.""",
   model="gpt-4o",
   model_settings=ModelSettings(
       temperature=0.3,  # Lower for more deterministic outputs (0.0-2.0)
       max_tokens=1024,  # Maximum length of response
   ),
   tools=[]  # We'll cover tools in a later section
)

Instructions und Konfiguration

Der Parameter instructions ist vermutlich der wichtigste Hebel im Agent-Design. Er fungiert als „System Prompt“, der Verhalten, Tonalität und Fähigkeiten steuert. Gute Instructions zu schreiben ist Kunst und Handwerk zugleich:

Best Practices für Instructions

1. Werde konkret: Rolle, Persönlichkeit und Grenzen des Agenten klar definieren
2. Setze Leitplanken: Explizit festlegen, welche Themen oder Aktionen zu vermeiden sind
3. Interaktionsmuster festlegen: Beschreiben, wie der Agent unterschiedliche Eingaben behandeln soll
4. Wissensgrenzen definieren: Klarstellen, was der Agent wissen sollte und wann er Unsicherheit benennt

Der Agent unterstützt außerdem einen description-Parameter, eine menschenlesbare Beschreibung des Agenten, die genutzt wird, wenn der Agent in Tools/Handoffs eingesetzt wird.

Konfigurationsoptionen

Über die Instructions hinaus kannst du das Verhalten mit weiteren Parametern feinsteuern:

• temperature: Steuert die Zufälligkeit der Antworten (0,0–2,0)
• Niedrige Werte (0,1–0,4) liefern deterministischere, fokussierte Antworten
• Höhere Werte (0,7–1,0) erzeugen kreativere, variablere Ausgaben
• max_tokens: Begrenzt die Länge der Antworten
• Nützlich für prägnante Ausgaben oder zur Kostenkontrolle
• Der Standard variiert je Modell, ist aber meist ausreichend hoch
• model: Wählt das zugrunde liegende LLM
• „gpt-4o“ bietet in den meisten Fällen die beste Leistung
• „gpt-4o-mini“ balanciert Leistung und Kosten
• „gpt-3.5-turbo“ eignet sich für weniger komplexe Aufgaben mit Fokus auf Tempo und Kosten

Diese Optionen geben dir ein starkes Framework, um Agenten passgenau zu konfigurieren. Experimentiere mit den Einstellungen und finde die optimale Konfiguration für deinen Anwendungsfall.

OpenAI Agents SDK-Beispiel: Ein spezialisierter Wetter-Assistent

Führen wir die Konzepte in einem praktischen Beispiel zusammen: ein spezialisierter Assistent für Wetterinformationen. So definierst du Expertise, Fähigkeiten und klare Grenzen:

from agents import Agent, Runner
from dotenv import load_dotenv

# Load environment variables (API key)
load_dotenv()

# Define detailed instructions for our weather assistant
weather_instructions = """
You are a weather information assistant who helps users understand weather patterns and phenomena.

YOUR EXPERTISE:
- Explaining weather concepts and terminology
- Describing how different weather systems work
- Answering questions about climate and seasonal patterns
- Explaining the science behind weather events

LIMITATIONS:
- You cannot provide real-time weather forecasts for specific locations
- You don't have access to current weather data
- You should not make predictions about future weather events

STYLE:
- Use clear, accessible language that non-meteorologists can understand
- Include interesting weather facts when relevant
- Be enthusiastic about meteorology and climate science
"""

# Create our specialized weather assistant
weather_assistant = Agent(
   name="WeatherWise",
   instructions=weather_instructions,
   model="gpt-3.5-turbo",
   model_settings=ModelSettings(
       temperature=0.5,  # Balanced temperature for natural but focused responses
       max_tokens=256,  # Maximum length of response
   )
)

Deinen ersten Agenten ausführen

Sobald du einen Agenten erstellt hast, kannst du ihn mit der Klasse Runner ausführen. Sie steuert die Abarbeitung der Aufgaben und das Gesprächs-Handling:

# For Jupyter notebooks:
result = await Runner.run(
   weather_assistant, "Can you tell me about the relationship between climate change and extreme weather events?"
)

print(result.final_output)

—--------

Absolutely! Climate change is closely linked to the increase in frequency and intensity of extreme weather events. As the Earth's climate warms due to the buildup of greenhouse gases in the atmosphere, it disrupts the balance of our planet's climate systems.

Here's how climate change influences extreme weather events:
1. **Heatwaves**: Rising global temperatures lead to more frequent and severe heatwaves. These events can have serious impacts on human health, agriculture, and ecosystems.

2. **Intense Storms**: Warmer oceans provide more energy to fuel hurricanes, typhoons, and other tropical storms, leading to stronger and more destructive events.

3. **Heavy Rainfall**: A warmer atmosphere can hold more moisture, resulting in heavier rainfall during storms. This can lead to flooding and landslides.

4. **Droughts**: Climate change can exacerbate drought conditions in certain regions, impacting water resources, agriculture, and ecosystems.

5. **Wildfires**: Higher temperatures and drier conditions increase the likelihood of wildfires, which can be more frequent and intense.

It's important to note that while climate change doesn't directly cause specific weather events, it can increase the likelihood and severity of extreme weather occurrences. Scientists continue to study these connections to better understand and prepare for the impacts of

Für Python-Skripte nutzt du den asyncio-Ansatz:

# For Python scripts:
import asyncio

async def run_agent_example():
   result = await Runner.run(weather_assistant, "Can you tell me about the relationship between climate change and extreme weather events?")
   print(result.final_output)

if __name__ == "__main__":
   asyncio.run(run_agent_example())

In diesem Abschnitt hast du die Grundlagen zum Erstellen und Ausführen von Agenten mit dem OpenAI Agents SDK kennengelernt. Im nächsten Schritt statten wir unsere Agenten mit Tools aus — das erweitert ihre Möglichkeiten drastisch.

Mit Tools arbeiten

Die eigentliche Stärke des OpenAI Agents SDK zeigt sich, wenn du Agenten mit Tools ausrüstest. Tools ermöglichen Interaktionen mit externen Systemen, Datenzugriff und Aktionen jenseits reiner Textgenerierung. Das SDK unterstützt drei Haupttypen: Hosted Tools, Function Tools und „Agents as Tools“.

Hosted Tools

Hosted Tools laufen auf OpenAIs Servern neben den Sprachmodellen. Sie liefern eingebaute Fähigkeiten, ohne dass du komplexe Funktionen selbst implementieren musst.

WebSearchTool: Einen Research-Assistenten bauen

Das WebSearchTool ermöglicht deinem Agenten Websuche für aktuelle Informationen — besonders wertvoll, wenn Wissen über den Trainingsstand des Modells hinaus erforderlich ist.

from agents import Agent, Runner, WebSearchTool
from dotenv import load_dotenv

load_dotenv()

# Create a research assistant with web search capability
research_assistant = Agent(
   name="Research Assistant",
   instructions="""You are a research assistant that helps users find and summarize information.
   When asked about a topic:
   1. Search the web for relevant, up-to-date information
   2. Synthesize the information into a clear, concise summary
   3. Structure your response with headings and bullet points when appropriate
   4. Always cite your sources at the end of your response
  
   If the information might be time-sensitive or rapidly changing, mention when the search was performed.
   """,
   tools=[WebSearchTool()]
)

async def research_topic(topic):
   result = await Runner.run(research_assistant, f"Please research and summarize: {topic}. Only return the found links with very minimal text.")
   return result.final_output

# Usage example (in Jupyter notebook)
summary = await research_topic("Latest developments in personal productivity apps.")
print(summary[:512])

—----------------

Here are some recent developments in personal productivity apps:

- **AI Integration in Productivity Tools**: Startups like Anthropic are developing AI agents capable of performing routine tasks across different applications, aiming to streamline workflows and reduce the need for multiple apps. ([ft.com](https://www.ft.com/content/a0e54dd5-b270-42cc-8c4c-18a0b8b3e6cc?utm_source=openai))

- **Read AI's Expansion**: Read AI, a productivity startup, secured $50 million in funding, valuing the company at $450 m

In diesem Beispiel haben wir einen Research-Assistenten erstellt, der das Web durchsuchen und Informationen zu einer stimmigen Zusammenfassung verdichten kann. Das WebSearchTool funktioniert ohne Parameter, lässt sich aber anpassen:

# Customized search tool with location context
location_aware_search = WebSearchTool(
   user_location="San Francisco, CA",  # Provides geographic context for local search queries
   search_context_size=3  # Number of search results to consider in the response
)

Der Parameter user_location ist nützlich für Anfragen mit regionalem Bezug, etwa lokale Services. Mit search_context_size steuerst du, wie viele Treffer das Modell für seine Antwort berücksichtigt.

Function Tools

Mit Function Tools erweiterst du deinen Agenten um beliebige Python-Funktionen. Hier zeigt das SDK seine ganze Flexibilität: Du kannst jede API, Datenbank oder lokalen Dienst integrieren.

Wettervorhersage-Tool

Erstellen wir ein Praxisbeispiel mit einer externen Wetter-API:

import os
import requests
from datetime import datetime
from typing import Optional, List
from dataclasses import dataclass

from agents import Agent, Runner, function_tool
from dotenv import load_dotenv

load_dotenv()


@dataclass
class WeatherInfo:
   temperature: float
   feels_like: float
   humidity: int
   description: str
   wind_speed: float
   pressure: int
   location_name: str
   rain_1h: Optional[float] = None
   visibility: Optional[int] = None


@function_tool
def get_weather(lat: float, lon: float) -> str:
   """Get the current weather for a specified location using OpenWeatherMap API.

   Args:
       lat: Latitude of the location (-90 to 90)
       lon: Longitude of the location (-180 to 180)
   """
   # Get API key from environment variables
   WEATHER_API_KEY = os.getenv("OPENWEATHERMAP_API_KEY")

   # Build URL with parameters
   url = f"https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={WEATHER_API_KEY}&units=metric"

   try:
       response = requests.get(url)
       response.raise_for_status()
       data = response.json()

       # Extract weather data from the response
       weather_info = WeatherInfo(
           temperature=data["main"]["temp"],
           feels_like=data["main"]["feels_like"],
           humidity=data["main"]["humidity"],
           description=data["weather"][0]["description"],
           wind_speed=data["wind"]["speed"],
           pressure=data["main"]["pressure"],
           location_name=data["name"],
           visibility=data.get("visibility"),
           rain_1h=data.get("rain", {}).get("1h"),
       )

       # Build the response string
       weather_report = f"""
       Weather in {weather_info.location_name}:
       - Temperature: {weather_info.temperature}°C (feels like {weather_info.feels_like}°C)
       - Conditions: {weather_info.description}
       - Humidity: {weather_info.humidity}%
       - Wind speed: {weather_info.wind_speed} m/s
       - Pressure: {weather_info.pressure} hPa
       """
       return weather_report

   except requests.exceptions.RequestException as e:
       return f"Error fetching weather data: {str(e)}"

Dieses Wetter-Tool dient als Brücke zur OpenWeatherMap-API. Es holt aktuelle Wetterdaten anhand von Koordinaten und formatiert sie zu einem lesbaren Bericht. 

Die Datenklasse WeatherInfo strukturiert die Daten mit Typfeldern (Temperatur, Luftfeuchte etc.) — übersichtlich und wartbar. Der Decorator @function_tool macht aus der Python-Funktion ein Tool für den Agenten und erzeugt Schema und Beschreibung automatisch aus Signatur und Docstring.

Beim Aufruf liest die Funktion sicher den API-Key aus Umgebungsvariablen, stellt eine HTTP-Anfrage an OpenWeatherMap und verarbeitet die JSON-Antwort. 

Optionale Felder wie Niederschlag werden robust behandelt, und alles wird zu einem klaren Wetterbericht formatiert — inklusive Fehlerrückgabe, falls der API-Call scheitert. So liefert der Agent aktuelle Infos in konsistenter, gut lesbarer Form, ohne selbst API-Details kennen zu müssen.

# Create a weather assistant
weather_assistant = Agent(
   name="Weather Assistant",
   instructions="""You are a weather assistant that can provide current weather information.
  
   When asked about weather, use the get_weather tool to fetch accurate data.
   If the user doesn't specify a country code and there might be ambiguity,
   ask for clarification (e.g., Paris, France vs. Paris, Texas).
  
   Provide friendly commentary along with the weather data, such as clothing suggestions
   or activity recommendations based on the conditions.
   """,
   tools=[get_weather]
)

So führst du den Wetter-Assistenten aus:

async def main():
   runner = Runner()
  
   simple_request = await runner.run(weather_assistant, "What are your capabilities?")
  
   request_with_location = await runner.run(weather_assistant, "What's the weather like in Tashkent right now?")
  
   print(simple_request.final_output)
   print("-"*70)
   print(request_with_location.final_output)

await main()

Output:

I can provide you with the current weather conditions for any location around the world. Just give me the location details, and I'll fetch the weather data for you. I can also offer tips on activities or clothing based on the weather. If you have a specific city in mind, let me know, and I'll get to work!
----------------------------------------------------------------------
The weather in Tashkent is currently lovely with a clear sky. It's around 19.8°C, but it might feel slightly cooler at 18.6°C. The humidity is quite low at 26%, making it a pleasant day to be outdoors. A gentle breeze is blowing at 3.09 m/s, and the air pressure is steady at 1023 hPa.

It's a great time for a picnic in the park or a leisurely walk. Light clothing should be perfect for this weather. Enjoy your day in Tashkent!

Die Antwort zeigt, dass der Agent das Wetter-Tool erfolgreich genutzt hat. Er hat den Stadtnamen isoliert, die Koordinaten ermittelt und sie als lat und lon an das Tool übergeben.

Agenten als Tools

Mit dem Agents SDK kannst du Agenten selbst als Tools nutzen und damit Hierarchien aufbauen, in denen Spezialisten unter einem Koordinator arbeiten. Dieses Muster ist für komplexe Workflows sehr wirkungsvoll.

from agents import Agent, Runner
from dotenv import load_dotenv

load_dotenv()

# Specialist agents
note_taking_agent = Agent(
   name="Note Manager",
   instructions="You help users take and organize notes efficiently.",
   # In a real application, this agent would have note-taking tools
)

task_management_agent = Agent(
   name="Task Manager",
   instructions="You help users manage tasks, deadlines, and priorities.",
   # In a real application, this agent would have task management tools
)

# Coordinator agent that uses specialists as tools
productivity_assistant = Agent(
   name="Productivity Assistant",
   instructions="""You are a productivity assistant that helps users organize their work and personal life.
  
   For note-taking questions or requests, use the note_taking tool.
   For task and deadline management, use the task_management tool.
  
   Help the user decide which tool is appropriate based on their request,
   and coordinate between different aspects of productivity.
   """,
   tools=[
       note_taking_agent.as_tool(
           tool_name="note_taking",
           tool_description="For taking, organizing, and retrieving notes and information"
       ),
       task_management_agent.as_tool(
           tool_name="task_management",
           tool_description="For managing tasks, setting deadlines, and tracking priorities"
       )
   ]
)

In diesem Beispiel:

1. Erstellen wir zwei spezialisierte Agenten mit fokussierter Expertise.
2. Erstellen wir einen Koordinator, der an diese Spezialisten delegieren kann.
3. Wandeln wir jeden Spezialisten per .as_tool() in ein Tool um und definieren:

• Einen tool_name, über den der Koordinator das Tool anspricht.
• Eine tool_description, die erklärt, wann das Tool sinnvoll ist.

Dieses Muster erlaubt komplexe Agentensysteme bei klarer Trennung der Verantwortlichkeiten. Jeder Spezialist kann eigene Tools und Expertise haben, während der Koordinator die Nutzerinteraktion managt und passend delegiert.

So nutzt du den Productivity Assistant:

async def main():
   runner = Runner()
  
   result = await runner.run(productivity_assistant, "I need to keep track of my project deadlines")
   print(result.final_output)

await main()

Tools machen aus reinen Chat-Assistenten leistungsfähige Systeme, die sinnvolle Aktionen ausführen. Wir haben die Grundlagen abgedeckt — für fortgeschrittene Nutzung, inkl. Fehlerbehandlung in Function Tools, lies die offizielle Dokumentation.

Jetzt, da wir Agenten mit Tools ausstatten können, geht es um die Ausgaben. Im nächsten Abschnitt schauen wir uns an, wie wir Antworten strukturiert verarbeiten — von einfachem Text bis zu komplexen Datenstrukturen, damit deine Anwendung genau das gewünschte Format erhält.

OpenAI-Agent-Antworten verstehen

Bei der Arbeit mit Agenten machen strukturierte Informationen Anwendungen robuster als Freitext. Das OpenAI Agents SDK bietet einen sauberen, integrierten Weg, strukturierte Ausgaben direkt von Agenten zu erhalten.

Strukturierte Ausgaben mit Pydantic-Modellen

Du kannst exakt festlegen, welche Datenstruktur dein Agent zurückgeben soll, indem du beim Erstellen eines Agenten den Parameter output_type angibst:

from pydantic import BaseModel
from typing import List, Optional
from agents import Agent, Runner
from dotenv import load_dotenv

load_dotenv()
True
First, we define our data models using Pydantic:
# Define person data model
class Person(BaseModel):
   name: str
   role: Optional[str]
   contact: Optional[str]


# Define meeting data model
class Meeting(BaseModel):
   date: str
   time: str
   location: Optional[str]
   duration: Optional[str]


# Define task data model
class Task(BaseModel):
   description: str
   assignee: Optional[str]
   deadline: Optional[str]
   priority: Optional[str]


# Define the complete email data model
class EmailData(BaseModel):
   subject: str
   sender: Person
   recipients: List[Person]
   main_points: List[str]
   meetings: List[Meeting]
   tasks: List[Task]
   next_steps: Optional[str]

Diese Modelle definieren die Struktur der zu extrahierenden Daten. Jede Klasse repräsentiert einen Informationstyp, den wir aus einer E-Mail ziehen möchten.

Nun erstellen wir einen Agenten, der Daten in unserem strukturierten Format ausgibt, indem wir output_type setzen:

# Create an email extraction agent with structured output
email_extractor = Agent(
   name="Email Extractor",
   instructions="""You are an assistant that extracts structured information from emails.
  
   When given an email, carefully identify:
   - Subject and main points
   - People mentioned (names, roles, contact info)
   - Meetings (dates, times, locations)
   - Tasks or action items (with assignees and deadlines)
   - Next steps or follow-ups
  
   Extract this information as structured data. If something is unclear or not mentioned,
   leave those fields empty rather than making assumptions.
   """,
   output_type=EmailData,  # This tells the agent to return data in EmailData format
)

Wenn du output_type angibst, erzeugt der Agent automatisch strukturierte Daten statt reinem Text. Manuelles JSON-Parsen oder Regex-Extraktion entfällt.

Wenden wir den Extractor auf eine Beispiel-E-Mail an:

sample_email = """
From: Alex Johnson <alex.j@techcorp.com>
To: Team Development <team-dev@techcorp.com>
CC: Sarah Wong <sarah.w@techcorp.com>, Miguel Fernandez <miguel.f@techcorp.com>
Subject: Project Phoenix Update and Next Steps

Hi team,

I wanted to follow up on yesterday's discussion about Project Phoenix and outline our next steps.

Key points from our discussion:
- The beta testing phase has shown promising results with 85% positive feedback
- We're still facing some performance issues on mobile devices
- The client has requested additional features for the dashboard

Let's schedule a follow-up meeting this Friday, June 15th at 2:00 PM in Conference Room B. The meeting should last about 1.5 hours, and we'll need to prepare the updated project timeline.

Action items:
1. Sarah to address the mobile performance issues by June 20th (High priority)
2. Miguel to create mock-ups for the new dashboard features by next Monday
3. Everyone to review the beta testing feedback document and add comments by EOD tomorrow

If you have any questions before Friday's meeting, feel free to reach out.

Best regards,
Alex Johnson
Senior Project Manager
(555) 123-4567
"""

Dank SDK wird die Verarbeitung deutlich einfacher, da die Konvertierung übernommen wird:

async def process_email(email_text):
   runner = Runner()
   result = await runner.run(
       email_extractor,
       f"Please extract information from this email:\n\n{email_text}"
   )

   # The result is already a structured EmailData object
   return result


# Process the sample email
result = await process_email(sample_email)

# Display the extracted information
result = result.final_output

print(f"Subject: {result.subject}")
print(f"From: {result.sender.name} ({result.sender.role})")
print("\nMain points:")
for point in result.main_points:
   print(f"- {point}")

print("\nMeetings:")
for meeting in result.meetings:
   print(f"- {meeting.date} at {meeting.time}, Location: {meeting.location}")

print("\nTasks:")
for task in result.tasks:
   print(f"- {task.description}")
   print(
       f"  Assignee: {task.assignee}, Deadline: {task.deadline}, Priority: {task.priority}"
   )
—----------

Subject: Project Phoenix Update and Next Steps
From: Alex Johnson (Senior Project Manager)

Main points:
- 85% positive feedback from beta testing
- Performance issues on mobile devices
- Client requested additional dashboard features

Meetings:
- June 15th at 2:00 PM, Location: Conference Room B

Tasks:
- Address mobile performance issues
 Assignee: Sarah, Deadline: June 20th, Priority: High
- Create mock-ups for new dashboard features
 Assignee: Miguel, Deadline: Next Monday, Priority: None
- Review beta testing feedback document and add comments
 Assignee: Everyone, Deadline: EOD tomorrow, Priority: None

Der Code ist deutlich sauberer, weil:

1. Wir kein JSON mehr manuell extrahieren und parsen müssen.
2. Das SDK die Konvertierung vom Agenten-Output zu unserem Pydantic-Modell übernimmt.
3. Wir direkt auf strukturierte Eigenschaften zugreifen können (z. B. result.final_output.subject).
4. Typvalidierung automatisch passiert — die Daten passen zum Modell.

Mit unterschiedlichen Ausgabe-Typen arbeiten

Der Parameter output_type funktioniert mit jedem Typ, den Pydantic via TypeAdapter verarbeiten kann:

# For simple lists
agent_with_list_output = Agent(
   name="List Generator",
   instructions="Generate lists of items based on the user's request.",
   output_type=list[str],  # Returns a list of strings
)

# For dictionaries
agent_with_dict_output = Agent(
   name="Dictionary Generator",
   instructions="Create key-value pairs based on the input.",
   output_type=dict[
       str, int
   ],  # Returns a dictionary with string keys and integer values
)

# For simple primitive types
agent_with_bool_output = Agent(
   name="Decision Maker",
   instructions="Answer yes/no questions with True or False.",
   output_type=bool,  # Returns a boolean
)

Vorteile strukturierter Ausgaben

Die Nutzung von output_type bietet mehrere Pluspunkte:

1. Direkte Integration: Agenten-Ausgaben liegen sofort als Python-Objekte vor.
2. Typsicherheit: Das SDK stellt sicher, dass Ausgaben der definierten Struktur entsprechen.
3. Einfacherer Code: Kein manuelles JSON-Parsen oder Fehlerhandling nötig.
4. Bessere Performance: Die Konvertierung erfolgt effizient.
5. IDE-Support: Autovervollständigung für Eigenschaften der strukturierten Ausgaben.

Mit klaren Datenmodellen und output_type liefern deine Agenten exakt die Datenstrukturen, die deine Anwendung braucht — nahtlos integrierbar und mit weniger Komplexität im Code.

Im nächsten Abschnitt schauen wir uns Handoffs zwischen Agenten an. Damit erstellst du spezialisierte Agenten, die gemeinsam komplexe Aufgaben bearbeiten. Handoffs können strukturierte Ausgaben nutzen, um Informationen konsistent und typsicher zu übergeben.

Handoffs: Zwischen Agenten delegieren

In komplexen Anwendungen erfordern unterschiedliche Aufgaben oft spezifische Expertise. Das OpenAI Agents SDK unterstützt „Handoffs“, mit denen ein Agent die Kontrolle an einen Spezialisten übergeben kann. Besonders wertvoll ist das bei Systemen mit vielfältigen Anfragen, etwa im Kundensupport für Abrechnung, Technik oder Kontoverwaltung.

Einfache Handoffs erstellen

Im einfachsten Fall verbindest du mehrere Agenten, die bei Bedarf die Kontrolle übergeben. Erstellen wir ein kleines Customer-Service-System mit einem Triage-Agenten, der an Spezialisten übergibt:

from agents import Agent, handoff, Runner
from dotenv import load_dotenv

load_dotenv()

# Create specialist agents
billing_agent = Agent(
   name="Billing Agent",
   instructions="""You are a billing specialist who helps customers with payment issues.
   Focus on resolving billing inquiries, subscription changes, and refund requests.
   If asked about technical problems or account settings, explain that you specialize
   in billing and payment matters only.""",
)

technical_agent = Agent(
   name="Technical Agent",
   instructions="""You are a technical support specialist who helps with product issues.
   Assist users with troubleshooting, error messages, and how-to questions.
   Focus on resolving technical problems only.""",
)

# Create a triage agent that can hand off to specialists
triage_agent = Agent(
   name="Customer Service",
   instructions="""You are the initial customer service contact who helps direct
   customers to the right specialist.
  
   If the customer has billing or payment questions, hand off to the Billing Agent.
   If the customer has technical problems or how-to questions, hand off to the Technical Agent.
   For general inquiries or questions about products, you can answer directly.
  
   Always be polite and helpful, and ensure a smooth transition when handing off to specialists.""",
   handoffs=[billing_agent, technical_agent],  # Direct handoff to specialist agents
)

In diesem System haben wir drei Agenten:

• Zwei Spezialisten mit fokussierter Expertise
• Einen Triage-Agenten, der an die Spezialisten delegiert

Wir fügen die Spezialisten einfach in den handoffs-Parameter des Triage-Agenten ein. Das SDK erzeugt automatisch passende Handoff-Tools, die der Triage-Agent bei Bedarf nutzt.

So sieht das System in Aktion aus:

async def handle_customer_request(request):
   runner = Runner()
   result = await runner.run(triage_agent, request)
   return result


# Example customer inquiries
billing_inquiry = (
   "I was charged twice for my subscription last month. Can I get a refund?"
)
technical_inquiry = (
   "The app keeps crashing when I try to upload photos. How can I fix this? Give me the shortest solution possible."
)
general_inquiry = "What are your business hours?"

# Process the different types of inquiries
billing_response = await handle_customer_request(billing_inquiry)
print(f"Billing inquiry response:\n{billing_response.final_output}\n")

technical_response = await handle_customer_request(technical_inquiry)
print(f"Technical inquiry response:\n{technical_response.final_output}\n")

general_response = await handle_customer_request(general_inquiry)
print(f"General inquiry response:\n{general_response.final_output}")

Bei Abrechnungsfragen gibt der Triage-Agent an den Billing Agent ab, technische Fragen gehen an den Technical Agent. Allgemeine Fragen beantwortet er selbst. Beispielausgabe:

Billing inquiry response:
I can help with that. Could you please provide the transaction details or the date of the charges? This will help me locate the duplicate charge and process a refund for you.

Technical inquiry response:
Try these steps:

1. Restart the app.
2. Update to the latest app version.
3. Clear the app cache.
4. Restart your device.

If it persists, reinstall the app.

General inquiry response:
Our business hours are Monday to Friday, 9 AM to 5 PM. If you need assistance outside these hours, feel free to reach out and we'll get back to you as soon as possible. Is there anything else I can help you with?

Handoffs anpassen

Für mehr Kontrolle nutzt du die Funktion handoff() statt Agenten direkt in handoffs zu übergeben:

from agents import Agent, handoff, RunContextWrapper
from datetime import datetime

# Create an agent that handles account-related questions
account_agent = Agent(
   name="Account Management",
   instructions="""You help customers with account-related issues such as
   password resets, account settings, and profile updates.""",
)


# Custom handoff callback function
async def log_account_handoff(ctx: RunContextWrapper[None]):
   print(
       f"[LOG] Account handoff triggered at {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}"
   )
   # In a real app, you might log to a database or alert a human supervisor


# Create a triage agent with customized handoffs
enhanced_triage_agent = Agent(
   name="Enhanced Customer Service",
   instructions="""You are the initial customer service contact who directs
   customers to the right specialist.
  
   If the customer has billing or payment questions, hand off to the Billing Agent.
   If the customer has technical problems, hand off to the Technical Agent.
   If the customer needs to change account settings, hand off to the Account Management agent.
   For general inquiries, you can answer directly.""",
   handoffs=[
       billing_agent,  # Basic handoff
       handoff(  # Customized handoff
           agent=account_agent,
           on_handoff=log_account_handoff,  # Callback function
           tool_name_override="escalate_to_account_team",  # Custom tool name
           tool_description_override="Transfer the customer to the account management team for help with account settings, password resets, etc.",
       ),
       technical_agent,  # Basic handoff
   ],
)

result = await Runner.run(
   enhanced_triage_agent, "I need to change my password."
)

Ausgabe:

[LOG] Account handoff triggered at 2025-03-16 17:45:48

Mit handoff() kannst du:

• Einen Custom-Callback über on_handoff setzen
• Den Standard-Toolnamen überschreiben (normalerweise „transfer_to_[agent_name]“)
• Eine eigene Tool-Beschreibung hinterlegen
• Das Input-Handling konfigurieren (siehe unten)

Daten während Handoffs übergeben

Manchmal soll der erste Agent beim Handoff Zusatzkontext oder Metadaten mitgeben. Das geht über den Parameter input_type:

from pydantic import BaseModel
from typing import Optional
from agents import Agent, handoff, RunContextWrapper


# Define the data structure to pass during handoff
class EscalationData(BaseModel):
   reason: str
   priority: Optional[str]
   customer_tier: Optional[str]


# Handoff callback that processes the escalation data
async def process_escalation(ctx: RunContextWrapper, input_data: EscalationData):
   print(f"[ESCALATION] Reason: {input_data.reason}")
   print(f"[ESCALATION] Priority: {input_data.priority}")
   print(f"[ESCALATION] Customer tier: {input_data.customer_tier}")

   # You might use this data to prioritize responses, alert human agents, etc.


# Create an escalation agent
escalation_agent = Agent(
   name="Escalation Agent",
   instructions="""You handle complex or sensitive customer issues that require
   special attention. Always address the customer's concerns with extra care and detail.""",
)

# Create a service agent that can escalate with context
service_agent = Agent(
   name="Service Agent",
   instructions="""You are a customer service agent who handles general inquiries.
  
   For complex issues, escalate to the Escalation Agent and provide:
   - The reason for escalation
   - Priority level (Low, Normal, High, Urgent)
   - Customer tier if mentioned (Standard, Premium, VIP)""",
   handoffs=[
       handoff(
           agent=escalation_agent,
           on_handoff=process_escalation,
           input_type=EscalationData,
       )
   ],
)

So liefert der Service-Agent beim Handoff strukturierte Daten zum Eskalationsgrund mit. Das System validiert sie gegen EscalationData, bevor sie an den Callback process_escalation übergeben werden.

Wann Handoffs vs. Agents-as-Tools?

Das SDK bietet zwei Wege für Zusammenarbeit: Handoffs und „Agents as Tools“ (wie zuvor gezeigt). Nutze sie jeweils so:

Handoffs einsetzen, wenn:

• Die Kontrolle vollständig an einen anderen Agenten übergehen soll
• Das Gespräch mit einem Spezialisten fortgeführt werden muss
• Du einen Workflow mit klaren Phasen und Zuständigkeiten aufbaust

Agents-as-Tools einsetzen, wenn:

• Der Hauptagent einen Spezialisten konsultieren, aber die Kontrolle behalten soll
• Du die Spezialistenantwort in eine übergeordnete Antwort einbetten möchtest
• Du ein hierarchisches System mit Koordinator und Subtasks baust

Beide Ansätze lassen sich kombinieren: Ein Hauptagent konsultiert manchmal Spezialisten (als Tools) und übergibt in anderen Fällen die Kontrolle vollständig per Handoff.

Handoffs sind ein starker Baustein für komplexe Agentensysteme mit klaren Verantwortungsübergaben. Wähle je nach Use Case den passenden Ansatz für die beste User Experience.

Fazit und nächste Schritte

Wir haben die Kernbausteine des OpenAI Agents SDK erkundet — vom Erstellen einfacher Agenten über Function Tools bis zu Handoffs zwischen Spezialisten. Du hast gesehen, wie strukturierte Ausgaben mit Pydantic-Modellen Anwendungen zuverlässiger und wartbarer machen und wie du Agentensysteme durch Delegation und Spezialisierung für komplexe Aufgaben entwirfst.

Damit hast du erst an der Oberfläche dieses mächtigen Frameworks gekratzt. Wenn du deine Agentensysteme weiter ausbauen willst, warten fortgeschrittene Themen wie Streaming-Antworten für Echtzeit-Updates, Tracing und Observability fürs Debugging, Multi-Agent-Orchestrierung für komplexe Workflows, Kontextmanagement zur Sitzungsverwaltung und Guardrails zur Sicherstellung von sicherem, angemessenem Verhalten.

Da KI-Agenten in modernen Anwendungen immer zentraler werden, liefern dir die in diesem Tutorial aufgebauten Fähigkeiten eine solide Basis für anspruchsvolle Systeme. Setze dein Lernen fort mit Ressourcen wie DataCamps Guide zum Lernen von KI. Denke daran: Gutes Agenten-Design ist Kunst und Wissenschaft zugleich — es braucht Iteration, Tests und ein tiefes Verständnis für Nutzerbedürfnisse und KI-Fähigkeiten.