OpenAI Agents SDK Eğitimi: Eyleme Geçen Yapay Zekâ Sistemleri Oluşturma

OpenAI Agents SDK ile Çalışmak için Önkoşullar

OpenAI Agents SDK’ya dalmadan önce bazı temel kavramları anlamak ve ortamınızı doğru şekilde kurmak önemlidir. Bu bölüm, ilk ajanınızı yazmadan önce bilmeniz gereken her şeyi kapsar.

Gerekli bilgi birikimi

Bu eğitimden en iyi şekilde yararlanmak için şu konularda rahat olmalısınız:

• Orta düzey Python programlama: Fonksiyonlar, sınıflar, async/await desenleri ve tür ipuçlarını anlamalısınız
• Temel OpenAI API kullanımı: OpenAI modellerine istek gönderme ve yanıtları işleme konusunda aşinalık
• Büyük dil modelleri (LLM’ler): LLM’lerin kavramsal olarak nasıl çalıştığını ve yetenek/sınırlamalarını anlama
• Pydantic: Agents SDK yoğunlukla kullandığı için veri doğrulamada Pydantic’e dair temel bilgi faydalı olacaktır
• Eşzamanlı olmayan programlama: Agents SDK eşzamanlı olmayan yürütme etrafında inşa edildiğinden, Python’da async/await desenlerine aşinalık

Bu alanlardaki bilginizi güçlendirmeniz gerekiyorsa DataCamp’in birkaç mükemmel kaynağı bulunuyor:

• OpenAI API ile Çalışmak — OpenAI’nin modelleriyle etkileşime geçmenin temellerini öğrenin.
• OpenAI Fundamentals Yolu — OpenAI teknolojileri için kapsamlı bir öğrenme yolu.
• GPT-4.5 genel bakış — GPT modellerinin en yeni yetenekleri hakkında bilgi edinin.
• GPT-4.5 ile fonksiyon çağırma — Ajanlarda araç kullanımını anlamak için temel arka plan.
• GPT-4.5 API kullanımı — Gelişmiş modellerle çalışmaya yönelik pratik rehber.

Ajanlar için temel kavramlar

Kod yazmaya başlamadan önce, Agents SDK’nın merkezindeki birkaç temel kavramı netleştirelim:

1. Ajanlar: Görevleri başarmak için araç kullanabilen ve karar verebilen yapay zekâ sistemleri
2. Araçlar: Ajanların web’de arama yapmak veya veritabanlarına erişmek gibi eylemleri gerçekleştirmek için çağırabileceği fonksiyonlar
3. Devirler (handoff): Kontrolün uzmanlaşmış ajanlar arasında devredilmesini sağlayan mekanizmalar
4. Korkuluklar (guardrails): Uygun davranışı sağlamak için girdi ve çıktıları doğrulayan güvenlik önlemleri

Bu kavramları ve aralarındaki ilişkileri anlamak, daha etkili ajan tabanlı uygulamalar oluşturmanıza yardımcı olur. Daha fazlasını yapay zekâ ajanlarını anlama rehberimizde öğrenebilirsiniz. 

OpenAI Ajan Ortam Kurulumu

OpenAI Agents SDK ile çalışmak için gereken her şeyle geliştirme ortamımızı kuralım:

Gerekli paketlerin kurulumu

Önce bir sanal ortam oluşturup etkinleştirin:

# 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

Sonra OpenAI Agents SDK ve python-dotenv’i kurun:

pip install openai-agents python-dotenv

API anahtarı yönetimi için python-dotenv kullanma

API anahtarlarıyla çalışırken, onları kodunuzun dışında tutmak en iyi uygulamadır. python-dotenv paketi, ortam değişkenlerini yönetmek için güvenli bir yol sağlar:

1. Proje dizininizde .env adlı bir dosya oluşturun
2. OpenAI API anahtarınızı bu dosyaya ekleyin:

OPENAI_API_KEY=your-api-key-here

3. Ortam değişkenlerini kodunuzda yükleyip kullanın:

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

Bu yaklaşım, özellikle çalışmanızı paylaşıyor ya da yayımlıyorsanız, hassas bilgileri kodunuzun dışında tutar.

Async fonksiyonlarla çalışma

OpenAI Agents SDK, kapsamlı şekilde eşzamanlı olmayan programlama kullanır. Farklı ortamlarda async fonksiyonlarla nasıl çalışılacağı şöyledir:

Python betiklerinde (.py dosyaları)

Normal Python betiklerinde, async fonksiyonları yürütmek için asyncio.run() kullanmanız gerekir:

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

Jupyter defterlerinde

Jupyter defterlerinde bir olay döngüsü zaten çalıştığı için asyncio.run() KULLANMAMALISINIZ. Bunun yerine, async fonksiyonları doğrudan await edebilirsiniz:

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)

Bir defterde asyncio.run() kullanmaya çalışırsanız şu gibi hatalarla karşılaşırsınız:

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

Bu, betikler ile defterler arasında kod kopyalarken yapmanız gereken en yaygın uyarlamalardan biridir. Bu eğitim boyunca, okuyucuların çoğu Jupyter kullanacağından ağırlıklı olarak defter dostu söz dizimini kullanacağım.

Kurulumu test etme

Her şeyin doğru kurulduğundan emin olalım:

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?

Bu kurulumla, OpenAI Agents SDK ile uygulamalar oluşturmaya başlamaya hazırsınız.

OpenAI Agents SDK’ya Başlangıç

OpenAI Agents SDK’nın kalbinde, talimatları anlayıp bunlara göre hareket edebilen yapay zekâ sistemleri oluşturmak için birincil arayüzünüz olan Agent sınıfı bulunur. Farklı senaryolar için ajanların nasıl oluşturulup yapılandırılacağını inceleyelim.

Bu SDK’daki bir ajan, talimatları izleyebilen ve isteğe bağlı olarak görevleri başarmak için araçları kullanabilen bir yapay zekâ sistemini temsil eder. Temel bir ajan oluşturmak yalnızca birkaç zorunlu parametre gerektirir:

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
)

Bir ajanın üç ana bileşeni şunlardır:

1. Ad: Günlükleme ve hata ayıklamaya yardımcı olan tanımlayıcı
2. Talimatlar: Ajanın davranışını ve amacını tanımlayan çekirdek “sistem istemi”
3. Model: Ajana güç veren temel dil modeli (varsayılan GPT-4o)

Bu temel kurulum başlamak için yeterli olsa da, Agent sınıfı LLM davranışı üzerinde daha fazla kontrol sağlayan birkaç ek model yapılandırma seçeneği sunar:

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
)

Talimatlar ve yapılandırma

Talimatlar parametresi, ajan tasarımının belki de en önemli yönüdür. Ajanın davranışını, tonunu ve yeteneklerini yönlendiren bir “sistem istemi” olarak işlev görür. Etkili talimatlar yazmak hem bir sanat hem de bir bilimdir:

Talimat yazımı için en iyi uygulamalar

1. Spesifik olun: Ajanın rolünü, kişiliğini ve sınırlamalarını açıkça tanımlayın
2. Sınırlar koyun: Ajanın kaçınması gereken konu veya eylemleri açıkça belirtin
3. Etkileşim örüntülerini tanımlayın: Ajanın farklı girdi türlerini nasıl ele alması gerektiğini açıklayın
4. Bilgi sınırlarını belirleyin: Ajanın neyi bilmesi gerektiğini ve belirsizlik durumunda bunu ne zaman kabul etmesi gerektiğini netleştirin

Agent ayrıca, ajan araçlar/devirler içinde kullanıldığında başvurulan, insan tarafından okunabilir bir açıklama olan description parametresini de içerir.

Yapılandırma seçenekleri

Talimatların ötesinde, birkaç yapılandırma parametresi kullanarak ajan davranışını ince ayar yapabilirsiniz:

• temperature: Yanıtlardaki rastgeleliği kontrol eder (0.0–2.0)
• Düşük değerler (0.1–0.4) daha deterministik, odaklı yanıtlar üretir
• Yüksek değerler (0.7–1.0) daha yaratıcı, çeşitli çıktılar üretir
• max_tokens: Ajan yanıtlarının uzunluğunu sınırlar
• Kısa çıktıları garanti etmek veya maliyetleri kontrol etmek için kullanışlıdır
• Varsayılan değer modele göre değişir, ancak çoğu kullanım için genellikle yeterince yüksektir
• model: Temel LLM’i seçer
• “gpt-4o” çoğu kullanım için en iyi performansı sunar
• “gpt-4o-mini” performans ve maliyet arasında iyi bir denge sağlar
• “gpt-3.5-turbo” hız ve maliyetin öncelik olduğu daha az karmaşık görevler için uygundur

Bu yapılandırma seçenekleri, çeşitli uygulamalara uygun şekilde ajan davranışını özelleştirmek için güçlü bir çerçeve sunar. Ajanınızın yanıtlarını nasıl etkilediklerini görmek ve özgün kullanımınıza en uygun ayarı bulmak için farklı değerlerle deney yapmanızı öneririz.

Open AI Agents SKD Örneği: Uzman bir hava durumu asistanı oluşturma

Şimdi bu kavramları bir araya getirerek pratik bir örnek oluşturalım: uzmanlaşmış bir hava durumu bilgi asistanı. Bu örnek, iyi tanımlanmış uzmanlık, yetenek ve sınırlamalara sahip bir ajanın nasıl oluşturulacağını gösterir:

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

İlk ajanınızı çalıştırma

Bir ajan oluşturduktan sonra, Runner sınıfını kullanarak çalıştırabilirsiniz. Bu sınıf, ajan görevlerinin yürütülmesini ve konuşma akışının yönetimini üstlenir:

# 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

Python betikleri için asyncio yaklaşımını kullanmanız gerekir:

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

Bu bölümde, OpenAI Agents SDK ile ajan oluşturmanın ve çalıştırmanın temellerini ele aldık. Bir sonraki bölümde, ajanlarımıza araçlar ekleyerek bu kavramları genişleteceğiz; bu, yeteneklerini önemli ölçüde artıracaktır.

Araçlarla Çalışma

OpenAI Agents SDK’nın gerçek gücü, ajanlarınıza araçlar sağladığınızda ortaya çıkar. Araçlar, ajanların haricî sistemlerle etkileşime girmesine, verilere erişmesine ve basit metin üretiminin ötesinde eylemler gerçekleştirmesine olanak tanır. Agents SDK üç ana araç türünü destekler: barındırılan araçlar, fonksiyon araçları ve araç olarak ajanlar.

Barındırılan araçlar

Barındırılan araçlar, OpenAI’nin sunucularında dil modelleriyle birlikte çalışır. Bu araçlar, karmaşık işlevleri sizin uygulamanıza gerek kalmadan yerleşik yetenekler sağlar.

WebSearchTool: Araştırma asistanı oluşturma

WebSearchTool, ajanınza güncel bilgileri bulmak için web’de arama yapma yeteneği kazandırır. Bu, modelin eğitim verisinin ötesinde güncel bilgi gerektiren görevler için özellikle değerlidir.

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

Bu örnekte, web’de arama yapıp bilgileri tutarlı bir özete dönüştürebilen bir araştırma asistanı oluşturduk. WebSearchTool çalışması için herhangi bir parametre gerektirmez, ancak gerekirse davranışını özelleştirebilirsiniz:

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

user_location parametresi, yerel hizmetler veya bölgesel bilgiler gibi coğrafi bağlamdan fayda sağlayan sorgular için özellikle kullanışlıdır. search_context_size parametresi, modelin yanıtı formüle ederken kaç arama sonucunu dikkate alacağını kontrol etmenize yardımcı olur.

Fonksiyon araçları

Fonksiyon araçları, ajanınızı herhangi bir Python fonksiyonuyla genişletmenize olanak tanır. Agents SDK’nın gerçek esnekliği burada ortaya çıkar; herhangi bir API, veritabanı veya yerel hizmetle entegrasyonu mümkün kılar.

Hava durumu tahmini aracı

Üçüncü taraf bir hava durumu API’siyle entegre olan pratik bir örnek oluşturalım:

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

Bu hava durumu API fonksiyon aracı, OpenWeatherMap API ile ajanımız arasında bir köprü görevi görür. Coğrafi koordinatlara göre gerçek zamanlı hava durumu verilerini alır ve okunabilir bir rapora dönüştürür. 

Kod, verileri yazımlı alanlarla (sıcaklık, nem vb.) yapılandırmak için bir WeatherInfo veri sınıfı tanımlar; bu da düzenli ve bakımı kolay bir yapı sağlar. @function_tool dekoratörü, Python fonksiyonumuzu ajanın kullanabileceği bir araca dönüştürür; fonksiyonun imzası ve docstring’inden otomatik olarak bir şema oluşturur.

Çağrıldığında fonksiyon, API anahtarını ortam değişkenlerinden güvenle alır, OpenWeatherMap’e bir HTTP isteği yapar ve JSON yanıtını işler. 

Yağış gibi isteğe bağlı alanları güvenli şekilde ele alır ve API isteği başarısız olursa hata yönetimi dahil olmak üzere her şeyi net bir hava durumu raporuna biçimlendirir. Bu sayede ajanımız, API ayrıntılarını bilmesine gerek kalmadan, tutarlı ve insan tarafından okunabilir bir biçimde güncel hava durumu bilgisi sunabilir.

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

Hava durumu asistanını çalıştırmak için:

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!

Yanıt, ajanın hava durumu aracını başarıyla kullandığını gösterir. İstemden şehir adını ayrıştırmış, kendi bilgi tabanını kullanarak koordinatlarını bulmuş ve bunları araca lat ve lon olarak iletmiştir.

Araç olarak ajanlar

Agents SDK, ajanların kendilerini araç olarak kullanmanıza da izin verir; böylece uzman ajanların bir koordinatörün altında çalıştığı hiyerarşik bir yapı mümkün olur. Bu, karmaşık iş akışları için güçlü bir örüntüdür.

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

Bu örnekte:

1. Her biri odaklı bir uzmanlık alanına sahip iki uzman ajan oluşturuyoruz.
2. Ardından bu uzmanlara görev devredebilen bir koordinatör ajan oluşturuyoruz.
3. Her uzman ajanı .as_tool() yöntemiyle bir araca dönüştürüyoruz ve şu bilgileri belirtiyoruz:

• Koordinatörün araca referans vermek için kullanacağı bir tool_name.
• Koordinatöre bu aracın ne zaman kullanılacağını anlatan bir tool_description.

Bu örüntü, kaygıların ayrımını korurken karmaşık ajan sistemleri oluşturmanıza olanak tanır. Her uzman ajanın kendi araç ve uzmanlık seti olabilirken, koordinatör kullanıcı etkileşimini yönetir ve uygun uzmana delege eder.

Verimlilik asistanını kullanmak için:

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

Araçlar, ajanları basit konuşma asistanlarından dünyada anlamlı eylemler gerçekleştirebilen güçlü sistemlere dönüştürür. Araç oluşturma ve kullanmanın temellerini ele almış olsak da bu, mümkün olanların yalnızca başlangıcıdır. Fonksiyon araçlarında hata yönetimi dahil daha gelişmiş kullanımlar için resmî belgelere bakın.

Artık ajanlarımızı araçlarla donatmayı anladığımıza göre, sıradaki zorluk çıktıları ele almak ve yapılandırmaktır. Bir sonraki bölümde, temel metin çıktılarından karmaşık yapılandırılmış verilere kadar ajan yanıtlarını işleme tekniklerini inceleyerek uygulamalarımızın ihtiyaç duyduğu bilgi biçimini tam olarak nasıl elde edeceğimizi göreceğiz.

OpenAI Ajan Çıktılarını Anlama

Ajanlarla çalışırken serbest biçimli metin yerine yapılandırılmış bilgi almak, uygulamalarınızı daha güvenilir kılabilir. OpenAI Agents SDK, ajanlardan doğrudan yapılandırılmış çıktılar almanın temiz ve yerleşik bir yolunu sunar.

Pydantic modelleriyle yapılandırılmış çıktılar

SDK, bir ajan oluştururken output_type parametresini belirterek ajanın döndürmesini istediğiniz veri yapısını tam olarak tanımlamanıza olanak tanır:

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]

Bu modeller, çıkarılmasını istediğimiz verilerin izleyeceği yapıyı tanımlar. Her sınıf, bir e-postadan çıkarmak istediğimiz belirli bir bilgi türünü temsil eder.

Şimdi output_type parametresini ayarlayarak verileri yapılandırılmış biçimde çıktı verecek bir ajan oluşturalım:

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

output_type belirttiğinizde ajan, düz metin yanıtlar yerine otomatik olarak yapılandırılmış veri üretir. Bu, el ile JSON ayrıştırma veya regex çıkarımı ihtiyacını ortadan kaldırır.

Bu çıkarıcıyı örnek bir e-postayla kullanalım:

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

Artık SDK dönüşümü ele aldığı için e-postayı işlemek çok daha basittir:

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

Bu kod, önceki yaklaşıma göre çok daha temizdir çünkü:

1. Yanıttan JSON’u elle çıkarmaya ve ayrıştırmaya gerek yoktur.
2. SDK, ajanın çıktısını Pydantic modelimize dönüştürmeyi üstlenir.
3. Yapılandırılmış veri özelliklerine (ör. result.final_output.subject) doğrudan erişebiliriz.
4. Tür doğrulaması otomatik olarak gerçekleşir; böylece verinin modelimize uyduğunu biliriz.

Farklı çıktı türleriyle çalışma

output_type parametresi, bir Pydantic TypeAdapter içine sarılabilen herhangi bir türle çalışır:

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

Yapılandırılmış çıktıların faydaları

output_type parametresini kullanmanın birkaç avantajı vardır:

1. Doğrudan entegrasyon: Ajan çıktıları otomatik olarak Python nesneleri olarak kullanılabilir.
2. Tür güvenliği: SDK, çıktıların tanımladığınız yapıyla eşleşmesini sağlar.
3. Daha basit kod: Elle JSON ayrıştırma veya hata yönetimi gerekmez.
4. Daha iyi performans: Dönüşümü SDK verimli şekilde ele alır.
5. IDE desteği: IDE’niz yapılandırılmış çıktı özellikleri için otomatik tamamlama sağlayabilir.

Açık veri modelleri tanımlayıp output_type parametresini kullanarak, ajanlarınız uygulamanızın ihtiyaç duyduğu veri yapılarını tam olarak üretebilir; bu da entegrasyonu sorunsuz hale getirir ve kodunuzun karmaşıklığını azaltır.

Bir sonraki bölümde, ajanlar arasında devirleri (handoff) inceleyeceğiz; böylece karmaşık görevlerde birlikte çalışabilen uzman ajanlar oluşturabilirsiniz. Bu devirlerde, ajanlar arasında bilgiyi tutarlı ve tür güvenli şekilde aktarmak için yapılandırılmış çıktılar kullanılabilir.

Devirler: Ajanlar Arasında Görev Devri

Karmaşık uygulamalarda farklı görevler genellikle farklı uzmanlık alanları gerektirir. OpenAI Agents SDK, bir ajanın kontrolü başka bir uzman ajana devretmesine olanak tanıyan “handoff”ları destekler. Bu özellik, farklı ajanların faturalandırma sorguları, teknik destek veya hesap yönetimi gibi çeşitli kullanıcı taleplerini ele aldığı müşteri destek uygulamaları gibi sistemler kurarken özellikle değerlidir.

Temel devirler oluşturma

En basit hâliyle devirler, gerektiğinde kontrol aktarımı yapabilecek şekilde birden fazla ajanı birbirine bağlamanıza izin verir. Uzmanlara devredebilen basit bir müşteri hizmetleri sistemi oluşturalım:

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
)

Bu örnekte üç ajanlı bir sistem oluşturduk:

• Odaklı uzmanlığa sahip iki uzman ajan
• Uzmanlara delege edebilen bir triyaj ajanı

Triyaj ajanının handoffs parametresine uzman ajanları eklemiş olmamıza dikkat edin. Agents SDK, triyaj ajanın ihtiyaç duyduğunda kullanabileceği uygun devir araçlarını otomatik olarak oluşturur.

Sistemi çalışırken görelim:

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

Triyaj ajanı bir faturalandırma sorusu aldığında, Biling Ajanı’nın bunu ele almak için daha uygun olduğunu tanır ve bir devir çağırır. Teknik sorular teknik ajana devredilir. Genel soruları ise kendi yetenekleri dahilinde doğrudan yanıtlar. Çıktı şöyledir:

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?

Devirleri özelleştirme

Devirler üzerinde daha fazla denetim için, ajanları doğrudan handoffs parametresine geçirmek yerine handoff() fonksiyonunu kullanabilirsiniz:

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

Çıktı:

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

handoff() fonksiyonu şunları yapmanıza olanak tanır:

• on_handoff ile özel bir geri çağırım (callback) belirtmek
• Varsayılan araç adını geçersiz kılmak (normalde “transfer_to_[agent_name]”)
• Özel bir araç açıklaması sağlamak
• Girdi işlemesini yapılandırmak (aşağıda daha fazlası)

Devir sırasında veri aktarma

Bazen, ilk ajanın devrederken başka bir ajana ek bağlam veya meta veri sağlamasını isteyebilirsiniz. Agents SDK bunu input_type parametresiyle destekler:

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

Bu kurulumla, hizmet ajanı devir yapmaya karar verdiğinde, devrin nedenine ilişkin yapılandırılmış veriler sağlayacaktır. Sistem, bu verileri EscalationData modeline göre doğrular ve ardından process_escalation geri çağırımına iletir.

Ne zaman devir, ne zaman araç olarak ajan kullanmalı?

Agents SDK, ajanların birlikte çalışması için iki yol sunar: devirler ve (önceki bölümde gördüğümüz gibi) ajanları araç olarak kullanma. Her bir yaklaşımı şu durumlarda kullanın:

Şunlarda devir kullanın:

• Kontrolü tamamen başka bir ajana devretmek istediğinizde
• Konuşmanın bir uzmanla devam etmesi gerektiğinde
• Farklı aşamaları farklı ajanların ele aldığı bir iş akışı kurduğunuzda

Şunlarda araç olarak ajan kullanın:

• Birincil ajanın bir uzmana danışıp kontrolü elinde tutması gerektiğinde
• Uzmanın yanıtını daha büyük bir cevabın parçası olarak dahil etmek istediğinizde
• Bir koordinatörün alt görevlere delege ettiği hiyerarşik bir sistem kurduğunuzda

Her iki yaklaşım da sofistike sistemlerde birleştirilebilir; ana ajan bazen uzmanlara danışır (onları araç olarak kullanır) ve bazen de uygun olduğunda kontrolü tamamen devreder.

Devirler, sorumluluğun farklı uzmanlar arasında el değiştirdiği karmaşık ajan sistemleri kurmak için güçlü bir mekanizma sağlar. Ajan mimarinizi tasarlarken, en etkili kullanıcı deneyimini oluşturmak için hangi yaklaşımın kullanımınıza en uygun olduğunu değerlendirin.

Sonuç ve Sonraki Adımlar

OpenAI Agents SDK’nın temel bileşenlerini; temel ajanlar oluşturmaktan fonksiyon araçlarını uygulamaya ve uzman ajanlar arasında devirleri yönetmeye kadar inceledik. Pydantic modelleriyle yapılandırılmış çıktıların uygulamalarımızı nasıl daha güvenilir ve sürdürülebilir kılabildiğini ve delege etme ile uzmanlaşma yoluyla karmaşık görevleri ele alabilen ajan sistemlerini nasıl tasarlayacağımızı gördük.

Bununla birlikte, bu güçlü çerçeveyle mümkün olanların yalnızca yüzeyine dokunduk. Ajan sistemlerini bir üst seviyeye taşımaya hazır geliştiriciler için keşfedilmeyi bekleyen birkaç ileri konu vardır: gerçek zamanlı güncellemeler için akış yanıtları, izleme ve gözlemlenebilirlik ile hata ayıklama, çoklu-ajan orkestrasyonu ile karmaşık iş akışları, bağlam yönetimi ile konuşma durumunu koruma ve korkuluklar ile güvenli ve uygun ajan davranışını sağlama.

Yapay zekâ ajanları modern uygulamaların merkezinde giderek daha fazla yer alırken, bu eğitim boyunca geliştirdiğiniz beceriler, sofistike yapay zekâ sistemleri oluşturmak için sağlam bir temel sunar. Öğrenme yolculuğunuza DataCamp’in yapay zekâ öğrenme rehberi gibi kaynaklarla devam edin ve etkili ajan tasarımının, kullanıcı ihtiyaçlarını ve yapay zekâ yeteneklerini derinlemesine anlamayı, yinelemeyi ve test etmeyi gerektiren bir bilim kadar bir sanat olduğunu unutmayın.