OpenAI Agents SDK ile İlk Yapay Zeka Ajanınızı Yazın

OpenAI Agents SDK nedir, ne işe yarar?

OpenAI Agents SDK, Python'da yapay zeka ajanı geliştirmek için hafif bir çerçevedir. Belgelerinde tanıtılan temel bileşenler şunlardır: talimat ve araçlarla yapılandırılmış bir dil modeli olan Agent, ajanları çalıştıran Runner, Python fonksiyonlarından araç üreten işlev araçları, görev devri için handoff'lar ve ajan sonucunu denetleyen guardrail'ler. Bunlara oturumlar ve izleme (tracing) eklenir: oturum ajanın turlar boyunca bağlam taşımasını, izleme ise koşunun adımlarını görmeyi sağlar.

Çerçevenin yaklaşımı, çok az soyutlamayla ajan döngüsünü sizin yerinize yönetmektir. Aracı tanımlar, ajana verir, Runner'ı çağırırsınız; model çağrısı, araç çalıştırma ve sonucun modele geri beslenmesi SDK'nın işidir.

Bu sayfa yalnızca bu SDK'yı anlatır. Çerçeveler arasındaki seçim, örneğin graf tabanlı akışlar veya rol tabanlı ajan ekipleri, ayrı konulardır; LangGraph, CrewAI ve AutoGen sayfalarında ele alınır. SDK'nın sürümleri hızla gelişir, bu yüzden isim ve parametre ayrıntıları için her zaman güncel belgeye bakın.

Kurulum ve ilk ajan

Kurulum tek komuttur:

pip install openai-agents

Çalıştırmadan önce OPENAI_API_KEY ortam değişkenini tanımlamanız gerekir. Anahtarı kodun içine yazmayın; ortam değişkeni ya da gizli bilgi yöneticisi kullanın.

En küçük ajan şöyle görünür:

from agents import Agent, Runner

ajan = Agent(name="Asistan", instructions="Kısa ve net yanıt veren bir asistansın.")

sonuc = Runner.run_sync(ajan, "Özyinelemeyi bir cümleyle açıkla.") print(sonuc.final_output)

Agent nesnesi ajanın adını ve talimatını taşır. Runner.run_sync, ajanı eş zamanlı olarak çalıştırır ve sonucu döndürür; nihai yanıt final_output alanındadır. Asenkron ortamlarda Runner.run kullanılır, akış halinde olay almak için ise Runner.run_streamed vardır.

Talimat ajanın davranışını belirleyen asıl alandır. Net bir rol, çıktı biçimi ve sınırlar tarif eden talimat, belirsiz bir talimattan çok daha tutarlı sonuç verir. Talimatı kodda bir sabit olarak tutun ve değiştirdikçe aynı girdilerle yeniden deneyin.

Ajan döngüsü nasıl işler?

Runner çağrıldığında SDK bir döngü yürütür. Önce mevcut ajan için model çağrılır. Çıktı üç türden biridir. Nihai çıktı ise, yani istenen türde metin içeriyor ve araç çağrısı barındırmıyorsa, döngü biter ve sonuç döner. Araç çağrısı ise Runner aracı çalıştırır, sonucu konuşmaya ekler ve modeli yeniden çağırır. Handoff ise geçerli ajan değişir ve döngü yeni ajanla devam eder.

Döngünün sonsuza gitmesini önlemek için tur sınırı vardır. max_turns değeri aşılırsa MaxTurnsExceeded istisnası fırlatılır. Model beklenmeyen ya da geçersiz çıktı üretirse, örneğin bozuk bir JSON, ModelBehaviorError ortaya çıkar. Hata yöneticileri tanımlayarak bu durumlarda uygulamayı çökertmek yerine kontrollü bir yanıt döndürebilirsiniz.

Bu döngüyü anlamak hata ayıklamayı kolaylaştırır. Ajan takılıyorsa genellikle ya araç sürekli aynı hatayı veriyor ya da talimat modelin ne zaman duracağını söylemiyordur. İzleme özelliği, hangi turda hangi aracın çağrıldığını göstererek sorunu hızla bulmanıza yardım eder.

Ajana araç vermek

Araç, ajanın görevini yerine getirirken çağırabileceği bir işlemdir: veritabanı sorgusu, hava durumu servisi, hesaplama. SDK'da en yaygın araç türü, bir Python fonksiyonunun araca çevrilmesidir. Belgelere göre fonksiyonun adı araç adı olur, docstring araç açıklaması olarak kullanılır, girdi şeması ise fonksiyon imzasından ve tür ipuçlarından üretilir. Argüman açıklamaları docstring içinden okunur.

Basit bir araç tanımlandıktan sonra ajana şöyle verilir:

ajan = Agent(name="Asistan", instructions="Şehir sorularında araçları kullan.", tools=[hava_durumu_getir])

Burada hava_durumu_getir, SDK'nın araç dekoratörüyle işaretlenmiş bir Python fonksiyonudur; dekoratörün içe aktarma biçimi için güncel belgedeki örneği izleyin.

Araç kalitesi ajan kalitesini belirler. Adı ve açıklaması net olmayan bir araç modelin yanlış zamanda çağırmasına yol açar. Argümanları tür ipuçlarıyla ve docstring ile belgeleyin, araç hata döndürürse bunu açık bir mesajla yapın ki model durumu anlayıp yeniden deneyebilsin.

Belgeler beş araç kategorisi sıralar: OpenAI'ın barındırdığı araçlar, yerel çalışma zamanı araçları, işlev araçları, araç olarak ajanlar ve deneysel bir Codex aracı. İlk uygulamalarda işlev araçları çoğu ihtiyacı karşılar.

Handoff ve çoklu ajan

Tek bir ajan her işi iyi yapmaya çalışırsa talimatı şişer ve kararsızlaşır. Bunun yerine uzman ajanlar tanımlayıp bir yönlendirici ajanın isteği doğru uzmana devretmesini sağlayabilirsiniz. Bu mekanizma handoff'tur.

from agents import Agent, handoff

fatura_ajani = Agent( name="Fatura ajanı", handoff_description="Fatura ve tahsilat sorularını ele alır", ) iade_ajani = Agent( name="İade ajanı", handoff_description="İade taleplerini ele alır", )

yonlendirici = Agent( name="Yönlendirici", instructions="Her müşteriyi doğru uzmana yönlendir.", handoffs=[fatura_ajani, handoff(iade_ajani, tool_name_override="iade_uzmanina_aktar")], )

Belgelere göre handoff'lar modele araç olarak sunulur. Bir ajan devredildiğinde yeni ajan konuşmayı devralır ve varsayılan olarak önceki geçmişi görür; geçmişi filtrelemek için handoff nesnesinde seçenekler vardır. handoff_description alanı, modelin devir kararını verirken kullandığı açıklamadır; bu yüzden uzmanın ne işe baktığını açıkça yazın.

Handoff tek seçenek değildir. Uzmanı ana ajanın bir aracı olarak çağırmak da mümkündür; bu durumda konuşmanın kontrolü ana ajanda kalır.

Guardrail'ler, oturumlar ve izleme

Üretime yaklaşan ajanlarda üç özellik öne çıkar.

Guardrail'ler girdi ve çıktıyı doğrular. Girdi guardrail'i ilk ajanın başladığı sırada, varsayılan olarak onunla paralel çalışır; kural ihlalini gösteren bir işaret çıkarsa Runner girdi guardrail istisnasını fırlatır ve ajan işi yapmadan koşu durur. Çıktı guardrail'i ise yalnız son ajanın yanıtından sonra çalışır. Tipik kullanım: konu dışı ya da uygunsuz bir isteği ucuz bir model ile ayıklayıp pahalı ana ajana hiç iletmemek.

Oturumlar, ajanın turlar boyunca bağlam taşımasını sağlar. Aksi halde her Runner çağrısı sıfırdan başlar. Sohbet arayüzleri için oturum şarttır.

İzleme, ajanın her adımını kaydeder ve koşuyu görselleştirmeyi sağlar. Hata ayıklamada ve davranış değerlendirmede en değerli araçtır; hangi turda hangi aracın hangi argümanlarla çağrıldığını gösterir.

Güvenlik açısından da iki kural unutulmamalıdır. Araçlara en az yetkiyle erişim verin; ajan para hareketi ya da veri silme gibi geri alınamaz işlemler yapacaksa insan onayı ekleyin. Ve model çıktısını doğrulamadan başka sistemlere yazmayın.

Sık hatalar ve kontrol listesi

OpenAI Agents SDK ile çalışırken sık yapılan hatalar şunlardır.

• Belirsiz talimat yazmak; ajanın ne zaman duracağı, hangi biçimde yanıt vereceği belli değildir.
• Araç adı ve açıklamasını özensiz bırakmak.
• Tek ajana her işi yüklemek; uzmanlaşma ve handoff yerine dev bir talimat.
• Tur sınırını görmezden gelmek ve sonsuz döngü riskini yönetmemek.
• API anahtarını koda gömmek.
• Tüm araçlara geniş yetki vermek.
• Guardrail'i hiç eklememek ve uygunsuz girdinin ana ajana ulaşmasına izin vermek.
• İzlemeyi açmadan hata ayıklamaya çalışmak.

Kısa kontrol listesi: talimat net mi, araçlar belgeli mi, tur sınırı ve hata yöneticileri tanımlı mı, geri alınamaz işlemler için insan onayı var mı, girdi ve çıktı guardrail'leri eklendi mi, koşular izleniyor mu, örnek girdilerle düzenli değerlendirme yapılıyor mu?

Bu beceriyi Mindset programlarında nerede çalışırsınız?

Python ile Yapay Zekâ Ajanları (AI Agent) Geliştirme Eğitimi, tek ajanlı sistemler kurma, ajanları araçlarla donatma, çoklu ajanlarla çalışma ve ajan sistemlerinde izleme ile değerlendirme başlıklarını kapsar. Bu SDK, aynı kavramların bir uygulamasıdır; yazılımcılar ve veri ekipleri için ajan mimarisini bir çerçeveden bağımsız kavramlarla öğrenmek, çerçeve değiştiğinde de geçerli kalır.