OpenAI Agents SDK-tutorial: AI-systemen bouwen die actie ondernemen

Vereisten voor werken met de OpenAI Agents SDK

Voordat je in de OpenAI Agents SDK duikt, is het belangrijk om een aantal basisconcepten te begrijpen en je omgeving goed in te richten. Deze sectie behandelt alles wat je moet weten voordat je je eerste agent schrijft.

Benodigde voorkennis

Om het meeste uit deze tutorial te halen, is het handig als je je prettig voelt bij:

• Gemiddeld niveau Python-programmeren: Je begrijpt functies, classes, async/await-patronen en type hints
• Basisgebruik van de OpenAI API: Bekendheid met het versturen van requests naar OpenAI-modellen en het afhandelen van responses
• Grote taalmodellen (LLM’s): Inzicht in hoe LLM’s conceptueel werken en hun mogelijkheden/beperkingen
• Pydantic: Basiskennis van Pydantic voor datavalidatie is nuttig, omdat de Agents SDK hier intensief gebruik van maakt
• Asynchroon programmeren: Bekendheid met async/await-patronen in Python, omdat de Agents SDK draait op asynchrone uitvoering

Als je je kennis in sommige van deze gebieden wilt bijspijkeren, biedt DataCamp verschillende uitstekende bronnen:

• Werken met de OpenAI API — Leer de basis van interactie met de modellen van OpenAI.
• OpenAI Fundamentals Track — Een uitgebreid leerpad voor OpenAI-technologieën.
• GPT-4.5-overzicht — Leer over de nieuwste mogelijkheden van GPT-modellen.
• Function calling met GPT-4.5 — Essentiële achtergrond voor het begrijpen van toolgebruik in agents.
• De GPT-4.5 API gebruiken — Praktische gids voor het werken met geavanceerde modellen.

Kernconcepten voor agents

Voordat we gaan coderen, verhelderen we een paar kernconcepten die centraal staan in de Agents SDK:

1. Agents: AI-systemen die tools kunnen gebruiken en beslissingen nemen om taken te voltooien
2. Tools: Functies die agents kunnen aanroepen om acties uit te voeren, zoals het web doorzoeken of databases benaderen
3. Handoffs: Mechanismen om de controle over te dragen tussen gespecialiseerde agents
4. Guardrails: Veiligheidsmaatregelen die input en output valideren om passend gedrag te garanderen

Als je deze concepten en hun relaties begrijpt, kun je effectievere agentgerichte toepassingen bouwen. Je kunt meer leren in onze gids over AI-agents begrijpen. 

OpenAI Agents-omgevingssetup

Laten we onze ontwikkelomgeving inrichten met alles wat je nodig hebt om met de OpenAI Agents SDK te werken:

Vereiste packages installeren

Maak eerst een virtuele omgeving aan en activeer deze:

# 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

Installeer vervolgens de OpenAI Agents SDK en python-dotenv:

pip install openai-agents python-dotenv

python-dotenv gebruiken voor API-sleutelbeheer

Bij het werken met API-sleutels is het best practice om ze buiten je code te houden. De python-dotenv-package biedt een veilige manier om omgevingsvariabelen te beheren:

1. Maak een bestand met de naam .env in je projectmap
2. Voeg je OpenAI API-sleutel toe aan dit bestand:

OPENAI_API_KEY=your-api-key-here

3. Laad en gebruik de omgevingsvariabelen in je code:

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")

Deze aanpak houdt gevoelige informatie buiten je code, wat vooral belangrijk is als je je werk deelt of publiceert.

Werken met async-functies

De OpenAI Agents SDK gebruikt asynchroon programmeren intensief. Zo werk je met async-functies in verschillende omgevingen:

In Python-scripts (.py-bestanden)

In reguliere Python-scripts moet je asyncio.run() gebruiken om async-functies uit te voeren:

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 hebben al een event loop draaien, dus je moet asyncio.run() NIET gebruiken. In plaats daarvan kun je async-functies direct 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)

Als je probeert asyncio.run() in een notebook te gebruiken, krijg je fouten zoals:

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

Dit is een van de meest voorkomende aanpassingen die je moet maken bij het kopiëren van code tussen scripts en notebooks. In deze tutorial gebruik ik vooral de notebookvriendelijke syntax, omdat de meeste lezers Jupyter gebruiken.

Je installatie testen

Laten we controleren of alles correct is ingesteld:

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?

Met deze setup ben je klaar om toepassingen te bouwen met de OpenAI Agents SDK.

Aan de slag met de OpenAI Agents SDK

De kern van de OpenAI Agents SDK is de Agent-klasse, jouw primaire interface om AI-systemen te creëren die instructies begrijpen en erop kunnen handelen. Laten we bekijken hoe je agents maakt en configureert voor verschillende scenario’s.

Een agent in deze SDK vertegenwoordigt een AI-systeem dat instructies kan opvolgen en optioneel tools kan gebruiken om taken te voltooien. Een basisagent maken vereist slechts een paar essentiële parameters:

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
)

De drie primaire componenten van een agent zijn:

1. Naam: Een identificatie voor je agent die helpt bij logging en debuggen
2. Instructies: De kern-“system prompt” die het gedrag en doel van de agent bepaalt
3. Model: Het onderliggende taalmodel dat de agent aanstuurt (standaard GPT-4o)

Hoewel deze basisopzet genoeg is om te starten, biedt de Agent-klasse verschillende aanvullende modelconfiguratieopties waarmee je meer controle hebt over het gedrag van de LLM:

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
)

Instructies en configuratie

De parameter instructions is misschien wel het belangrijkste aspect van agentontwerp. Het fungeert als een “system prompt” die het gedrag, de toon en de mogelijkheden van de agent stuurt. Effectieve instructies schrijven is zowel een kunst als een wetenschap:

Best practices voor het schrijven van instructies

1. Wees specifiek: Definieer duidelijk de rol, persoonlijkheid en beperkingen van de agent
2. Stel grenzen: Geef expliciet aan welke onderwerpen of acties de agent moet vermijden
3. Definieer interactiepatronen: Leg uit hoe de agent met verschillende soorten input moet omgaan
4. Stel kennisgrenzen vast: Maak duidelijk wat de agent moet weten en wanneer die onzekerheid moet erkennen

De Agent bevat ook een description-parameter: een menselijk leesbare beschrijving van de agent, gebruikt wanneer de agent binnen tools/handoffs wordt ingezet.

Configuratie-opties

Naast instructies kun je het gedrag van de agent verfijnen met verschillende configuratieparameters:

• temperature: Bepaalt de willekeur in responses (0,0–2,0)
• Lagere waarden (0,1–0,4) leveren meer deterministische, gefocuste antwoorden op
• Hogere waarden (0,7–1,0) zorgen voor creatievere, gevarieerde outputs
• max_tokens: Beperkt de lengte van agentantwoorden
• Handig om compacte outputs te garanderen of kosten te beheersen
• De standaard verschilt per model maar is meestal hoog genoeg voor de meeste use-cases
• model: Selecteert de onderliggende LLM
• “gpt-4o” biedt de beste prestaties voor de meeste use-cases
• “gpt-4o-mini” biedt een goede balans tussen prestaties en kosten
• “gpt-3.5-turbo” is beschikbaar voor minder complexe taken waar snelheid en kosten prioriteit hebben

Met deze configuratie-opties kun je het gedrag van een agent krachtig afstemmen op verschillende toepassingen. We moedigen je aan om met verschillende instellingen te experimenteren om te ontdekken hoe ze de responses van je agent beïnvloeden en om de optimale configuratie voor jouw specifieke use-case te vinden.

Open AI Agents SKD-voorbeeld: een gespecialiseerde weerassistent bouwen

Laten we deze concepten samenbrengen met een praktisch voorbeeld: een gespecialiseerde assistent voor weerminformatie. Dit voorbeeld laat zien hoe je een agent maakt met duidelijke expertise, mogelijkheden en beperkingen:

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
   )
)

Je eerste agent uitvoeren

Als je eenmaal een agent hebt gemaakt, kun je deze uitvoeren met de Runner-klasse. Deze klasse verzorgt de uitvoering van agenttaken en beheert de conversatiestroom:

# 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

Voor Python-scripts moet je de asyncio-aanpak gebruiken:

# 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 deze sectie hebben we de basis behandeld van het maken en uitvoeren van agents met de OpenAI Agents SDK. In de volgende sectie breiden we deze concepten uit door tools aan onze agents toe te voegen, waardoor hun mogelijkheden aanzienlijk worden vergroot.

Werken met tools

De echte kracht van de OpenAI Agents SDK komt naar voren wanneer je je agents uitrust met tools. Tools stellen agents in staat om met externe systemen te interageren, data te benaderen en acties uit te voeren die verder gaan dan alleen tekstopwekking. De Agents SDK ondersteunt drie hoofdtypen tools: hosted tools, function tools en agents als tools.

Hosted tools

Hosted tools draaien op de servers van OpenAI naast de taalmodellen. Deze tools bieden ingebouwde mogelijkheden zonder dat jij complexe functionaliteit hoeft te implementeren.

WebSearchTool: een onderzoeksassistent bouwen

De WebSearchTool geeft je agent de mogelijkheid om het web te doorzoeken voor actuele informatie. Dit is vooral waardevol voor taken die actuele kennis vereisen buiten de trainingsdata van het model.

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 dit voorbeeld hebben we een onderzoeksassistent gemaakt die het web kan doorzoeken en informatie kan samenvatten tot een samenhangende samenvatting. De WebSearchTool heeft geen parameters nodig om te functioneren, maar je kunt het gedrag naar wens aanpassen:

# 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
)

De parameter user_location is vooral nuttig voor zoekopdrachten die baat hebben bij geografische context, zoals lokale diensten of regionale informatie. Met de parameter search_context_size kun je bepalen hoeveel zoekresultaten het model meeneemt bij het formuleren van zijn antwoord.

Function tools

Met function tools kun je je agent uitbreiden met elke Python-functie. Hier komt de echte flexibiliteit van de Agents SDK naar voren: integratie met elke API, database of lokale service.

Weersvoorspellingstool

Laten we een praktisch voorbeeld maken dat integreert met een externe weer-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)}"

Deze weer-API function tool fungeert als brug tussen de OpenWeatherMap API en onze agent. Hij haalt realtime weerd gegevens op via geografische coördinaten en formatteert die tot een leesbaar rapport. 

De code definieert een WeatherInfo-dataklasse om de data te structureren met getypeerde velden (temperatuur, luchtvochtigheid, enz.), wat het overzichtelijk en onderhoudbaar maakt. De @function_tool-decorator transformeert onze Python-functie in een tool die de agent kan gebruiken en maakt automatisch een schema op basis van de functiedeclaratie en docstring.

Bij aanroep haalt de functie veilig een API-sleutel op uit omgevingsvariabelen, doet een HTTP-request naar OpenWeatherMap en verwerkt de JSON-response. 

Optionele velden zoals neerslag worden veilig afgehandeld en alles wordt geformatteerd tot een duidelijk weerbericht, inclusief foutafhandeling als de API-aanvraag faalt. Zo kan onze agent actuele weersinformatie leveren in een consistent, menselijk leesbaar formaat zonder API-details te hoeven begrijpen.

# 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]
)

Zo voer je de weerassistent uit:

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!

De response bewijst dat de agent de weertool succesvol gebruikte. De agent haalde de stadsnaam uit de prompt, gebruikte zijn eigen kennisbasis om de coördinaten te bepalen en gaf die door als lat en lon aan de tool.

Agents als tools

De Agents SDK stelt je in staat agents zelf als tools te gebruiken, waardoor je een hiërarchische structuur kunt opzetten waarin specialisten onder een coördinator werken. Dit is een krachtig patroon voor complexe workflows.

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 dit voorbeeld:

1. We maken twee specialistische agents, elk met een gefocust domein van expertise.
2. We maken vervolgens een coördinatoragent die naar deze specialisten kan delegeren.
3. We converteren elke specialist naar een tool met de methode .as_tool(), waarbij we specificeren:

• Een tool_name die de coördinator gebruikt om naar de tool te verwijzen.
• Een tool_description die de coördinator helpt te begrijpen wanneer deze tool te gebruiken.

Met dit patroon kun je complexe agentsystemen creëren terwijl je de scheiding van verantwoordelijkheden behoudt. Elke specialist kan zijn eigen set tools en expertise hebben, terwijl de coördinator de gebruikersinteractie beheert en de juiste specialist inschakelt.

Zo gebruik je de productiviteitsassistent:

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 transformeren agents van eenvoudige conversatie-assistenten naar krachtige systemen die betekenisvolle acties in de echte wereld kunnen uitvoeren. Hoewel we de basis hebben behandeld van het maken en gebruiken van tools, is dit nog maar het begin van wat mogelijk is. Voor geavanceerder gebruik, inclusief foutafhandeling in function tools, raadpleeg de officiële documentatie.

Nu we begrijpen hoe we onze agents kunnen uitrusten met tools, is de volgende uitdaging het verwerken en structureren van hun outputs. In de volgende sectie verkennen we technieken voor het verwerken van agentantwoorden, van basistekst tot complexe gestructureerde data, zodat we precies het informatieformaat krijgen dat onze toepassingen nodig hebben.

OpenAI Agent-outputs begrijpen

Bij het werken met agents kan het verkrijgen van gestructureerde informatie in plaats van vrije tekst je toepassingen betrouwbaarder maken. De OpenAI Agents SDK biedt een nette, ingebouwde manier om direct gestructureerde outputs van agents te ontvangen.

Gestructureerde outputs met Pydantic-modellen

Met de SDK kun je exact definiëren welke datastructuur je agent moet retourneren door een output_type-parameter op te geven bij het aanmaken van een agent:

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]

Deze modellen definiëren de structuur die we willen dat onze geëxtraheerde data volgt. Elke klasse vertegenwoordigt een specifiek type informatie dat we uit een e-mail willen halen.

Nu maken we een agent die data in ons gestructureerde formaat zal outputten door de parameter output_type in te stellen:

# 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
)

Wanneer je output_type opgeeft, produceert de agent automatisch gestructureerde data in plaats van platte tekst. Dit elimineert de noodzaak voor handmatige JSON-parsing of regex-extractie.

Laten we deze extractor gebruiken met een voorbeeldmail:

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
"""

Het verwerken van de e-mail wordt nu veel eenvoudiger omdat de SDK de conversie afhandelt:

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

Deze code is veel schoner dan onze eerdere aanpak omdat:

1. We niet handmatig JSON uit de response hoeven te halen en te parsen.
2. De SDK de conversie van de agentoutput naar ons Pydantic-model afhandelt.
3. We direct toegang hebben tot de gestructureerde dataprops (zoals result.final_output.subject).
4. Typevalidatie automatisch plaatsvindt, dus we weten dat de data overeenkomt met ons model.

Werken met verschillende outputtypes

De output_type-parameter werkt met elk type dat in een Pydantic-TypeAdapter kan worden verpakt:

# 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
)

Voordelen van gestructureerde outputs

Het gebruik van de output_type-parameter biedt verschillende voordelen:

1. Directe integratie: De outputs van je agent zijn automatisch beschikbaar als Python-objecten.
2. Typeveiligheid: De SDK zorgt ervoor dat outputs overeenkomen met je gedefinieerde structuur.
3. Eenvoudigere code: Geen handmatige JSON-parsing of foutafhandeling nodig.
4. Betere prestaties: De SDK verzorgt de conversie efficiënt.
5. IDE-ondersteuning: Je IDE kan autocompletion bieden voor de eigenschappen van de gestructureerde output.

Door duidelijke datamodellen te definiëren en de output_type-parameter te gebruiken, kunnen je agents precies de datastructuren produceren die je toepassing nodig heeft, wat integratie naadloos maakt en de complexiteit van je code vermindert.

In de volgende sectie verkennen we handoffs tussen agents, zodat je gespecialiseerde agents kunt maken die samenwerken aan complexe taken. Deze handoffs kunnen gestructureerde outputs gebruiken om informatie consistent en type-safe tussen agents door te geven.

Handoffs: delegeren tussen agents

In complexe toepassingen vereisen verschillende taken vaak verschillende expertisegebieden. De OpenAI Agents SDK ondersteunt “handoffs”, waarmee een agent de controle kan overdragen aan een andere gespecialiseerde agent. Deze functie is vooral waardevol bij het bouwen van systemen die uiteenlopende gebruikersverzoeken afhandelen, zoals klantenondersteuning waar verschillende agents bijvoorbeeld factureringsvragen, technische support of accountbeheer behandelen.

Basis-handoffs maken

In de eenvoudigste vorm kun je met handoffs meerdere agents verbinden zodat ze waar nodig de controle kunnen overdragen. Laten we een eenvoudig klantenservicesysteem maken met een triageagent die kan doorschakelen naar specialisten:

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 dit voorbeeld hebben we een systeem met drie agents gemaakt:

• Twee specialistische agents met gerichte expertise
• Eén triageagent die kan delegeren aan de specialisten

Merk op dat we de specialistische agents simpelweg opnemen in de parameter handoffs van de triageagent. De Agents SDK maakt automatisch geschikte handoff-tools die de triageagent indien nodig kan gebruiken.

Laten we het systeem in actie zien:

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}")

Wanneer de triageagent een factureringsvraag ontvangt, zal die herkennen dat de Billing Agent dit beter kan afhandelen en een handoff uitvoeren. Technische vragen worden overgedragen aan de technische agent. Algemene vragen beantwoordt de triageagent binnen zijn eigen mogelijkheden. Hier is de output:

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 aanpassen

Voor meer controle over handoffs kun je de functie handoff() gebruiken in plaats van agents direct door te geven aan de handoffs-parameter:

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."
)

Output:

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

Met de functie handoff() kun je:

• Een aangepaste callback opgeven met on_handoff
• De standaardtoolnaam overschrijven (normaal “transfer_to_[agent_name]”)
• Een aangepaste toolbeschrijving meegeven
• Inputafhandeling configureren (hieronder meer)

Data doorgeven tijdens handoffs

Soms wil je dat de eerste agent extra context of metadata meegeeft bij het overdragen aan een andere agent. De Agents SDK ondersteunt dit via de 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,
       )
   ],
)

Met deze setup zal, wanneer de serviceagent besluit over te dragen aan de escalatieagent, gestructureerde data worden meegegeven over waarom de escalatie plaatsvindt. Het systeem valideert deze data tegen het EscalationData-model voordat het aan de process_escalation-callback wordt doorgegeven.

Wanneer handoffs gebruiken vs. agent-als-tool

De Agents SDK biedt twee manieren waarop agents kunnen samenwerken: handoffs en agents als tools (zoals we in de vorige sectie zagen). Dit is wanneer je welke aanpak gebruikt:

Gebruik handoffs wanneer:

• Je de controle volledig wilt overdragen aan een andere agent
• Het gesprek moet doorgaan met een specialist
• Je een workflow bouwt waarin verschillende agents verschillende fasen afhandelen

Gebruik agents-als-tools wanneer:

• De primaire agent een specialist moet raadplegen maar de controle wil behouden
• Je de reactie van een specialist wilt opnemen als onderdeel van een groter antwoord
• Je een hiërarchisch systeem bouwt waarin een coördinator subtaken delegeert

Beide benaderingen kunnen worden gecombineerd in geavanceerde systemen, met een hoofdagent die soms specialisten raadpleegt (als tools) en soms de controle volledig overdraagt wanneer dat gepast is.

Handoffs bieden een krachtig mechanisme om complexe agentsystemen te bouwen waarin de verantwoordelijkheid verschuift tussen verschillende specialisten. Denk bij het ontwerpen van je agentarchitectuur na over welke aanpak het beste past bij jouw specifieke use-case om de meest effectieve gebruikerservaring te creëren.

Conclusie en vervolgstappen

We hebben de kerncomponenten van de OpenAI Agents SDK verkend, van het maken van basisagents tot het implementeren van function tools en het beheren van handoffs tussen specialistische agents. We hebben gezien hoe gestructureerde outputs met Pydantic-modellen onze toepassingen betrouwbaarder en onderhoudbaarder maken, en hoe je agentsystemen ontwerpt die complexe taken aankunnen via delegatie en specialisatie.

Toch hebben we nog maar een tipje van de sluier opgelicht van wat er mogelijk is met dit krachtige framework. Voor ontwikkelaars die hun agentsystemen naar een hoger niveau willen tillen, wachten er verschillende geavanceerde onderwerpen: streaming responses voor realtime-updates, tracing en observability voor debugging, multi-agent orkestratie voor complexe workflows, contextbeheer voor het behouden van conversatiestatus, en guardrails om veilig en passend agentgedrag te waarborgen.

Naarmate AI-agents centraler komen te staan in moderne toepassingen, bieden de vaardigheden die je in deze tutorial hebt ontwikkeld een solide basis om geavanceerde AI-systemen te bouwen. Zet je leerreis voort met bronnen zoals DataCamp’s gids om AI te leren, en onthoud dat effectief agentontwerp net zo goed kunst als wetenschap is — het vergt iteratie, testen en een diep begrip van zowel gebruikersbehoeften als AI-mogelijkheden.