OpenAI Agents SDK'sını Nasıl Kullanılır?

OpenAI Agents SDK, OpenAI'nin dil modelleri tarafından desteklenen yapay zeka (YZ) ajanlarının geliştirilmesini basitleştirmek için tasarlanmış bir Python kütüphanesidir. Geliştiricilere, göreve özel ajanlar oluşturma, harici işlevleri entegre etme, ajanlar arası görev delegasyonunu yönetme, girdi/çıktı doğrulamasını uygulama ve yürütme akışlarını izleme araçları sağlar. Bu kılavuz, SDK'yı etkili bir şekilde kurma, yapılandırma ve kullanma konusunda ayrıntılı, teknik bir yol gösterici sunarak, hassasiyet ve pratik uygulamaya odaklanarak en az 2000 kelime sağlar.

💡

İşe başlamadan önce, işte hızlı bir ipucu: Bu kılavuzda çok fazla API ile çalışacağımız için, Apidog'u almak isteyebilirsiniz. API'leri test etmeyi ve hatalarını ayıklamayı süper kolaylaştıran ücretsiz bir araçtır ve OpenAI Agents SDK ile denemeler yapmak için mükemmeldir. Apidog'u buradan ücretsiz indirebilirsiniz. İnanın bana, ileride baş ağrılarınızdan kurtaracaktır!

button

Giriş

OpenAI Agents SDK , her bir ajanın belirli görevleri yerine getirmek üzere tasarlandığı çoklu ajan sistemleri oluşturmak için yapılandırılmış bir çerçeve sağlar. Bu ajanlar, kullanıcılarla etkileşime girebilir, entegre araçlar aracılığıyla eylemler gerçekleştirebilir ve görevleri diğer ajanlara aktararak işbirliği yapabilir. SDK'nın temel bileşenleri şunlardır:

Ajanlar: Belirli talimatlar ve rollerle yapılandırılmış dil modellerinin örnekleri.
Araçlar: Ajan yeteneklerini genişleten işlevler veya hizmetler (örneğin, web araması, özel Python kodu).
Devirler: Ajanların görevleri diğer ajanlara sorunsuz bir şekilde devretmesini sağlayan mekanizmalar.
Koruma Rayları: Girdilerin ve çıktıların tanımlanan kriterleri karşıladığından emin olmak için doğrulama katmanları.
İzleme: Hata ayıklama ve performans analizi için yürütme günlükleri.

Bu kılavuz, Python ve API etkileşimleri hakkında temel bir anlayışa sahip geliştiriciler için tasarlanmıştır ve sağlam ve kapsamlı bir kaynak oluşturmak için ayrıntılı açıklamalar, kod örnekleri ve en iyi uygulamalar sunmaktadır.

Kurulum ve Yapılandırma

OpenAI Agents SDK'sını etkili bir şekilde kullanmak için doğru kurulum kritik öneme sahiptir. Bu bölüm, önkoşulları, ortam kurulumunu, kurulumu ve doğrulamayı kapsar.

Önkoşullar

Devam etmeden önce, aşağıdakilerden emin olun:

Python 3.8+: python --version ile Python sürümünüzü doğrulayın. Gerekirse python.org adresinden yükleyin.

OpenAI API Anahtarı: Hesabınızın ayarları altında platform.openai.com adresinden anahtarınızı edinin. Bu anahtar, OpenAI'nin sunucularına yapılan istekleri doğrular.

Adım 1: Sanal Bir Ortam Kurun

Sanal bir ortam, proje bağımlılıklarını izole ederek diğer Python projeleriyle çakışmaları önler. Bir tane oluşturmak ve etkinleştirmek için:

Linux/macOS:

python -m venv agents_env
source agents_env/bin/activate

Windows:

python -m venv agents_env
agents_env\Scripts\activate

Etkinleştirildikten sonra, terminal isteminiz ortamı yansıtmalıdır (örneğin, (agents_env)). Bu adım, temiz bir çalışma alanı sağlamak için Python geliştirme için en iyi uygulamadır.

Adım 2: SDK'yı Yükleyin

Sanal ortam etkin durumdayken, pip kullanarak SDK'yı yükleyin:

pip install openai-agents

Bu komut, SDK'nın en son sürümünü ve bağımlılıklarını PyPI'den getirir. Kurulumu doğrulamak için şunu çalıştırın:

pip show openai-agents-python

Bu, sürüm numarası dahil olmak üzere meta verileri görüntüler ve paketin yüklü olduğunu doğrular.

Adım 3: API Anahtarını Yapılandırın

SDK'nın çalışması için bir OpenAI API anahtarı gerekir. Bunu, kodunuza gömülmesini önlemek için bir ortam değişkeni olarak ayarlayın, bu da güvenliği artırır:

Linux/macOS:

export OPENAI_API_KEY='your-api-key'

Windows:

set OPENAI_API_KEY='your-api-key'

Bunun oturumlar arasında kalıcı olmasını sağlamak için, komutu kabuk yapılandırma dosyanıza (örneğin, Unix sistemlerinde .bashrc veya .zshrc) ekleyin. Alternatif olarak, bunu Python'da programlı olarak ayarlayabilirsiniz, ancak bu daha az güvenlidir:

import os
os.environ["OPENAI_API_KEY"] = "your-api-key"

Adım 4: Kurulumu Doğrulayın

Her şeyin çalıştığından emin olmak için minimum bir ajanla kurulumu test edin:

from agents import Agent, Runner

agent = Agent(name="TestAgent", instructions="Setup successful'ı döndür")
result = Runner.run_sync(agent, "Testi çalıştır")
print(result.final_output)  # Beklenen çıktı: "Setup successful"

Bu "Setup successful" yazdırırsa, kurulumunuz işlevseldir. Yaygın sorunlar şunlardır:

Geçersiz API Anahtarı: Anahtarı iki kez kontrol edin ve fazladan boşluk veya yazım hatası olmadığından emin olun.
Ağ Hataları: İnternet bağlantınızı ve OpenAI'nin sunucu durumunu doğrulayın.

Ajan Oluşturma

Ajanlar, SDK'nın temel yapı taşlarıdır ve her biri benzersiz bir rol ve davranışla tanımlanır.

Ajan Başlatma

Agent sınıfı, ajanları örneklendirmek için kullanılır. Temel parametreler şunlardır:

name: Bir dize tanımlayıcı (örneğin, "MathAgent").
instructions: Ajanın amacını belirten bir dize (örneğin, "Matematik problemlerini çöz").
model: Kullanılacak OpenAI modeli (varsayılan: gpt-4).
temperature: Çıktı rastgeleliğini kontrol eden 0 ile 1 arasında bir kayan sayı (varsayılan: 0.7).

Örnek: Temel Ajan

İşte aritmetik için basit bir ajan:

from agents import Agent, Runner

agent = Agent(
    name="MathAgent",
    instructions="Aritmetik ifadeleri çöz."
)
result = Runner.run_sync(agent, "10 * 2'yi hesapla")
print(result.final_output)  # Çıktı: "20"

Runner.run_sync yöntemi, ajanı eşzamanlı olarak yürütür ve final_output özniteliğiyle bir sonuç nesnesi döndürür.

Gelişmiş Yapılandırma

Parametreleri ayarlayarak ajanları belirli ihtiyaçlar için özelleştirin:

agent = Agent(
    name="CreativeWriter",
    instructions="İstem üzerine kısa bir hikaye yaz.",
    model="gpt-4",
    temperature=0.9
)
result = Runner.run_sync(agent, "Uzak bir galakside bir robot")
print(result.final_output)  # Çıktı: Yaratıcı bir hikaye

Model: gpt-4 üstün muhakeme sunarken, gpt-3.5-turbo daha hızlıdır ve daha basit görevler için daha ucuzdur.
Temperature: Daha düşük değerler (örneğin, 0.2) tahmin edilebilir çıktılar verir; daha yüksek değerler (örneğin, 0.9) yaratıcılığı artırır.

Çoklu Ajan Örneği

Farklı görevler için farklı ajanlar oluşturun:

support_agent = Agent(
    name="SupportBot",
    instructions="Teknik destek sorularını yanıtlayın."
)
code_agent = Agent(
    name="CodeHelper",
    instructions="Python kod parçacıkları oluşturun."
)

support_result = Runner.run_sync(support_agent, "Python'ı nasıl kurarım?")
code_result = Runner.run_sync(code_agent, "İki sayıyı toplamak için bir fonksiyon yazın")
print(support_result.final_output)  # Çıktı: Kurulum talimatları
print(code_result.final_output)     # Çıktı: "def add(a, b): return a + b"

Bu, SDK'nın çeşitli rolleri ele alma esnekliğini gösterir.

Araçları Entegre Etme

Araçlar, ajanların harici eylemler gerçekleştirmesini sağlayarak onları geliştirir. SDK, barındırılan araçları, özel işlev araçlarını ve ajan tabanlı araçları destekler.

Barındırılan Araçları Kullanma

web_search gibi barındırılan araçlar, önceden oluşturulmuştur ve kullanıma hazırdır:

from agents import Agent, Runner, web_search

agent = Agent(
    name="ResearchAgent",
    instructions="Web araması kullanarak soruları yanıtlayın.",
    tools=[web_search]
)
result = Runner.run_sync(agent, "Fransa'nın başkenti neresidir?")
print(result.final_output)  # Çıktı: "Fransa'nın başkenti Paris'tir."

Ajan, gerçek zamanlı verileri getirmek için otomatik olarak web_search'ü çağırır.

Özel İşlev Araçları Oluşturma

@function_tool dekoratörü ile özel araçlar tanımlayın. Araçlar dizeleri kabul etmeli ve döndürmelidir.

Örnek: Veri Getirme Aracı

from agents import Agent, Runner, function_tool

@function_tool
def fetch_data(id: str) -> str:
    """Verilen ID için verileri döndür."""
    # Simüle edilmiş veritabanı araması
    return f"ID {id} için veri: aktif"

agent = Agent(
    name="DataAgent",
    instructions="Aracı kullanarak veri alın.",
    tools=[fetch_data]
)
result = Runner.run_sync(agent, "ID 123 için veri getir")
print(result.final_output)  # Çıktı: "ID 123 için veri: aktif"

Harici API'leri Entegre Etme

Araçlar, harici hizmetlere bağlanabilir. İşte bir hava durumu aracı örneği:

import requests
from agents import function_tool, Agent, Runner

@function_tool
def get_weather(city: str) -> str:
    """Bir şehir için mevcut hava durumunu alın."""
    api_key = "your-weather-api-key"  # Gerçek bir anahtarla değiştirin
    url = f"http://api.weatherapi.com/v1/current.json?key={api_key}&q={city}"
    response = requests.get(url)
    if response.status_code == 200:
        data = response.json()
        return f"{city} şehrindeki hava durumu {data['current']['condition']['text']}."
    return "Hava durumu verileri mevcut değil."

agent = Agent(
    name="WeatherAgent",
    instructions="Aracı kullanarak hava durumu güncellemeleri sağlayın.",
    tools=[get_weather]
)
result = Runner.run_sync(agent, "Tokyo'da hava durumu nasıl?")
print(result.final_output)  # Çıktı: "Tokyo'da hava durumu Güneşli." (örnek)

Bunu test etmek için weatherapi.com adresinden ücretsiz bir API anahtarı için kaydolun.

Birden Fazla Aracı Birleştirme

Ajanlar, birden fazla aracı aynı anda kullanabilir:

@function_tool
def log_entry(text: str) -> str:
    """Bir mesajı günlüğe kaydet."""
    return f"Günlüğe kaydedildi: {text}"

agent = Agent(
    name="MultiToolAgent",
    instructions="Arama yapmak ve günlüğe kaydetmek için araçları kullanın.",
    tools=[web_search, log_entry]
)
result = Runner.run_sync(agent, "YZ trendlerini arayın ve sorguyu günlüğe kaydedin")
print(result.final_output)  # Çıktı, arama sonuçlarını ve günlük onayını içerir

Ajan Devirleri

Devirler, ajanların görevleri devretmesine izin vererek karmaşık iş akışlarını sağlar.

Devirleri Kurma

handoffs parametresi aracılığıyla ikincil ajanlara erişimi olan birincil bir ajan tanımlayın:

from agents import Agent, Runner

english_agent = Agent(
    name="EnglishHelper",
    instructions="Yalnızca İngilizce yanıt verin."
)
spanish_agent = Agent(
    name="SpanishHelper",
    instructions="Yalnızca İspanyolca yanıt verin."
)
triage_agent = Agent(
    name="LanguageRouter",
    instructions="Dili algılayın ve uygun ajana devredin.",
    handoffs=[english_agent, spanish_agent]
)

result = Runner.run_sync(triage_agent, "Hola, ¿qué tal?")
print(result.final_output)  # Çıktı: "¡Bien, gracias!" (veya benzeri)

triage_agent, girdiyi analiz eder ve uygun dile özgü ajana devreder.

Devir Mantığı

Devir kararı, birincil ajanın talimatlarına bağlıdır. Örneğin:

"Girdi İspanyolca kelimeler içeriyorsa, SpanishHelper'a devredin."
"İngilizce girdiler için EnglishHelper'ı kullanın."

Bir İngilizce girdi ile test edin:

result = Runner.run_sync(triage_agent, "How are you?")
print(result.final_output)  # Çıktı: "I'm good, thanks!"

İç İçe Devirler

Daha derin iş akışları için, ajanlar devirlerle diğer ajanlara devredebilir:

analysis_agent = Agent(
    name="AnalysisBot",
    instructions="Verileri analiz edin ve raporlama için devredin."
)
report_agent = Agent(
    name="ReportBot",
    instructions="Analizden bir rapor oluşturun."
)
main_agent = Agent(
    name="WorkflowManager",
    instructions="Analiz ile başlayın.",
    handoffs=[analysis_agent, report_agent]
)

result = Runner.run_sync(main_agent, "Satış verilerini analiz et")
print(result.final_output)  # Çıktı: Oluşturulmuş bir rapor

Koruma Raylarını Uygulama

Koruma rayları, Pydantic modellerini kullanarak girdiler ve çıktılar üzerinde kısıtlamalar uygular.

Bir Koruma Rayı Tanımlama

Çıktı yapısını doğrulamak için bir model oluşturun:

from pydantic import BaseModel
from agents import Agent, Runner

class QuestionCheck(BaseModel):
    is_question: bool
    reason: str

guard_agent = Agent(
    name="QuestionGuard",
    instructions="Girdinin bir soru olup olmadığını belirleyin.",
    output_type=QuestionCheck
)

result = Runner.run_sync(guard_agent, "Fransa'nın başkenti neresidir?")
print(result.final_output)  # Çıktı: {"is_question": true, "reason": "Soru işaretiyle biter"}

İş Akışı Entegrasyonu

Girdileri filtrelemek için koruma raylarını kullanın:

task_agent = Agent(
    name="TaskProcessor",
    instructions="Yalnızca soruları işleyin.",
    handoffs=[guard_agent]
)
result = Runner.run_sync(task_agent, "Bana bir hikaye anlat")
print(result.final_output)  # Çıktı, bunun bir soru olmadığını gösterir

İzleme ve Hata Ayıklama

İzleme, ajan yürütme ayrıntılarını günlüğe kaydeder ve OpenAI Kontrol Paneli aracılığıyla erişilebilir.

İzlemeyi Etkinleştirme

İzleme otomatiktir. Her çalıştırma şunları içeren bir iz oluşturur:

Girdi/çıktı verileri
Araç çağrıları
Devir olayları
Hatalar

Hata Ayıklama Örneği

Bir ajan başarısız olursa, şunları belirlemek için izi inceleyin:

Yanlış araç parametreleri
Devir yönlendirme hatası
API hataları

En İyi Uygulamalar

Performans Optimizasyonu

Model Seçimi: Hız için gpt-3.5-turbo, karmaşık muhakeme için gpt-4 kullanın.
Temperature: Hassasiyet için 0.2, yaratıcılık için 0.9.
Eşzamansız Yürütme: Paralel görevler için Runner.run_async kullanın.

Hata İşleme

Araçlar: Açık hata mesajları döndürün (örneğin, "Geçersiz Kimlik").
Devirler: Başarısızlıklar için bir yedek ajan ekleyin.

İş Akışı Tasarımı

Modülerlik: Görevleri ajanlar arasında bölün.
Açıklık: Belirsiz olmayan talimatlar yazın.
Doğrulama: Kilit aşamalarda koruma rayları uygulayın.

Sonuç

OpenAI Agents SDK, geliştiricilere, özel ajanlar, entegre araçlar ve işbirlikçi iş akışları ile gelişmiş YZ sistemleri oluşturma olanağı sağlar. Bu kılavuz, örnekler ve en iyi uygulamalarla birlikte, tüm potansiyelinden yararlanmak için teknik bir temel sağlar.

Peki, sırada ne var? Denemelere başlayın! Farklı talimatlar, araçlar ve iş akışları ile oynayın. Ve bir sorunla karşılaşırsanız, Apidog gibi araçlar API testinde yardımcı olabilir, ücretsiz alın.

button