TL;DR
OpenAI Agents API, akıl yürütme yapan, araçlar kullanan, kod çalıştıran ve çok adımlı görevleri tamamlayan yapay zekâ ajanları oluşturmak için yönetilen bir platformdur. Kendi başına tüm ajan döngüsünü uygulamadan, turlar arasında çalışmayı sürdürmesi, araçları çalıştırması ve kesintilerden kurtulması gereken uygulamalar için tasarlanmıştır. Bu kılavuz, geliştiricilerin yetenekleri, entegrasyon seçenekleri ve maliyetleri değerlendirmesine yardımcı olur.
Geleneksel bir LLM API’sinden farklı olarak OpenAI Agents API, kalıcı oturumlar, yönetilen yürütme ortamları, çoklu ajan koordinasyonu, akış hâlindeki olaylar ve artifaktları destekler. Geliştiriciler, yönetilen yürütme için yerel OpenAI Agents API uç noktalarını kullanabilir veya CometAPI üzerinden desteklenen OpenAI modellerini entegre ederek özel ajan iş akışları oluşturabilir. Bunlar birbirinden farklı entegrasyon yollarıdır.
Önemli Noktalar
- OpenAI Agents API, kalıcı oturumları ve çok adımlı yürütmeyi yöneterek geliştiricilerin üstlenmesi gereken orkestrasyonu azaltır.
- Çekirdek yetenekleri korumalı ortamda kod yürütme, araçlar ve MCP bağlantıları, alt ajanlar ve kaydedilen artifaktları içerir.
- OpenAI Agents API maliyetleri; model token’ları, uygun araçlar ve isteğe bağlı barındırılan hesaplamayı birleştirir; tamamlanan görev başına maliyeti değerlendirin.
- Müşterilerin bildirdiği kazanımlar, her uygulama için standart bir kıyas yerine iş yüküne özgü kanıt sağlar.
- Yerel yönetilen yürütme ile CometAPI kullanılarak kurulan özel ajanlar, altyapı sorumlulukları farklı olan ayrı entegrasyon tercihleridir.
OpenAI Agents API Nedir?
OpenAI Agents API, akıl yürütme modelleri ve harici araçlar kullanarak çok adımlı görevler gerçekleştiren uygulamalar için yönetilen bir yürütme hizmetidir. Codex agent harness’i hizmet olarak sunar. Model çağrılarını, araç yürütmesini, oturum durumunu ve görev kurtarmayı elle yönetmek yerine, geliştiriciler bu koordinasyonun büyük kısmını çalışma zamanına devredebilir.
Geleneksel bir sohbet botu bir yanıt üretir; bir ajan ise adımları planlayabilir, yetkilendirilmiş bir ortamda kod çalıştırabilir, hataları inceleyebilir, yeniden deneyebilir ve üretilen dosyaları teslim edebilir. Bu, API’yi yalnızca sohbetten ziyade operasyonel iş akışlarına uygun hâle getirir.
OpenAI Agents API İş Akışı
Bir ajan iş akışı dört parçayı bir araya getirir: ajan; modeli, talimatları ve kullanılabilir araçları tanımlar; ortam; hesaplama ve dosya erişimini sağlar; oturum; bağlamı ve kaydedilen çalışmayı turlar boyunca korur; ve olaylar ile öğeler; ilerlemeyi ve sonuçları sunar. Bu bileşenler birlikte, uygulamanızın bir görevi göndermesine, yürütmeyi izlemesine ve sonraki turlarda çalışmayı sürdürmesine olanak verir. Temel kavramlar için Agents API overview sayfasına bakın.
Tipik iş akışı: bir oturum oluşturun; bir hedef gönderin; modelin akıl yürütmesine ve izin verilen araçları seçmesine izin verin; bu araçları yürütün; ara sonuçları inceleyin; ilerlemeyi ve nihai artifaktları akış hâlinde alın. Oturum gerektiğinde sürdürülebilir.
Resmî diyagram, uygulamanın yönetilen harness ve sandbox ile girdi ve olay alışverişini gösterir. Mimari diyagram, OpenAI Agents API architecture documentation kaynağından; özgün görsel OpenAI tarafından.
OpenAI Agents API’nin Başlıca Özellikleri Nelerdir?
Yönetilen harness yetenekleri, kod yürütme, bağlam yönetimi, araç bağlantıları, yönlendirme ve delege etmeyi kapsar. Kullanılabilirlik ayrıca yapılandırılan ortam ve araçlara bağlıdır.
Kalıcı Oturumlar ve Bağlam Yönetimi
Oturumlar, yapılandırmayı, konuşma bağlamını ve kaydedilen çalışmayı turlar arasında korur. Geliştiriciler mevcut bir oturuma yeni bir talimat gönderebilir; bağlam yönetimi, özel transcript-sıkıştırma mantığı yazma ihtiyacını azaltırken uzun süreli görevleri sürdürmeye yardımcı olur.
Korumalı Ortamda Kod Yürütme
| Ortam | Altyapı | En iyi kullanım |
|---|---|---|
| none | Yerel yürütme yok |
Barındırılan ortamlar, izole bir çalışma alanında Python, Node.js ve komut satırı programlarını çalıştırabilir. Self-hosted bir ortam, yönetilen ajanın geliştirici kontrollü hesaplamayı kullanmasına olanak tanır. Geliştiriciler bu ortamı işletir ve güvenliğini sağlar; Agents API ise ajan harness’ini ve oturum durumunu yönetmeye devam eder.
Çoklu Ajan İşbirliği
Koordinasyon yapan bir ajan, bağımsız görevleri uzman alt ajanlara delege edebilir. Araştırma ajanları, birincil ajan kanıtları uzlaştırırken ayrı kaynakları inceleyebilir. Paralellik verimi artırabilir ancak ek model çağrıları ve koordinasyon maliyeti yükseltebilir. API, yapılandırılabilir eşzamanlılık ve alt ajan ayarlarını destekler.
OpenAI Agents API vs Agents SDK vs Responses API vs AgentKit
Agents API yönetilen yürütme sağlar; Agents SDK orkestrasyon yığınını kendisi yöneten uygulamalar için uygundur; Responses API çıkarım ve daha hafif araç iş akışları için uygundur; AgentKit ise, başka bir eşdeğer barındırılan ajan çalışma zamanı yerine tamamlayıcı geliştirme bileşenleri sunar.
OpenAI Agents API ile Nasıl Başlanır?
Adım 1: API Erişimini Yapılandırın
Quickstart gereksinimleri tarafından gerekli ajan ve çıkarım izinlerine sahip bir OpenAI Platform proje anahtarı kullanın. curl örnekleri, curl yüklü Bash uyumlu bir kabuğu hedefler; PowerShell örneği yalnızca ortam değişkenini ayarlar. Anahtarları kaynak kontrolünün dışında tutun.
Bash kod örneği: Aşağıdaki komutları Bash uyumlu bir terminalde çalıştırın.
export OPENAI_API_KEY="your-openai-api-key"
PowerShell kod örneği: API anahtarını geçerli PowerShell sürecinde ayarlayın.
$env:OPENAI_API_KEY="your-openai-api-key"
Adım 2: İlk Ajanınızı Oluşturun
Bash kod örneği: Aşağıdaki komutları Bash uyumlu bir terminalde çalıştırın.
curl --no-buffer --fail-with-body \
https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Write reliable Python code, execute it, and report observed results."
},
"environment": {"type": "openai_hosted", "container_size": "small"},
"input": "Calculate the mean and standard deviation of [12,15,19,20,24] in Python.",
"stream": true
}'
Oturum, ilk turuna başlar ve ajan araçları çalıştırıp bir yanıt hazırlarken durum olaylarını akış hâlinde iletir.
Adım 3: Çoklu Ajan Yürütmeyi Etkinleştirin
Bash kod örneği: Aşağıdaki komutları Bash uyumlu bir terminalde çalıştırın.
curl --no-buffer --fail-with-body \
https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Delegate independent analyses and reconcile the results.",
"multi_agent": {"enabled": true, "max_concurrent_subagents": 2}
},
"environment": {"type": "none"},
"input": "Compare two release changes: date filtering in search and export URL behavior.",
"stream": true
}'
Adım 4: Mevcut Bir Oturumu Sürdürün
Bash kod örneği: Aşağıdaki komutları Bash uyumlu bir terminalde çalıştırın.
curl --fail-with-body \
"https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{"events":[{"type":"agent.session.input.message","input":[{"role":"user","content":[{"type":"input_text","text":"Summarize the findings in an executive report."}]}]}]}'
Oturum tanımlayıcılarını saklayın, yeniden deneme güvenlik önlemlerini uygulayın ve yeni talimatları, aktif çalışmayı yönlendirmek için kullanılan mesajlardan ayırın.
Adım 5: Sonuçları İnceleyin ve Temizleyin
Bash kod örneği: Aşağıdaki komutları Bash uyumlu bir terminalde çalıştırın.
curl --fail-with-body \
"https://api.openai.com/v1/agents/sessions/$SESSION_ID/items?order=asc&limit=100" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1"
curl --fail-with-body -X DELETE \
"https://api.openai.com/v1/agents/sessions/$SESSION_ID" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1"
Yönetilen kaynakları kaldırmadan önce artifaktları alın. Bir akıştan bağlantıyı kesmek, devam eden çalışmayı mutlaka iptal etmez.
Oturum Yapılandırma Parametreleri
https://api.openai.com/v1/agents/sessions. adresine POST ile bir oturum oluşturun. Aşağıdaki beta örnekleri, resmî Agents API quickstart doğrultusunda OpenAI-Beta: agents=v1 kullanır.
Akıl yürütme çabası gecikmeyi, token tüketimini ve planlama derinliğini etkiler. Seçilen model ve arayüz tarafından desteklenen çabayı, resmî GPT-6 guidance kullanarak seçin; model düzeyi ayarların her uç nokta için birebir geçerli olduğu varsayılmamalıdır.
CometAPI ile Nasıl Bir Yapay Zekâ Ajanı Kurulur?
CometAPI, özel bir ajan uygulaması için model çıkarımı sağlayabilir. Uygulamanız, ajan döngüsü, araç yürütmesi, oturum durumu, kurtarma ve desteklenen modeller arasındaki yönlendirmeden sorumlu olmaya devam eder. Bu size orkestrasyon üzerinde kontrol verirken, aynı zamanda bu altyapının işletilmesi sorumluluğunu da size yükler.
Ajan yürütmesini ve oturum durumunu OpenAI’nın yönetmesini istediğinizde yerel Agents API entegrasyonunu seçin. Desteklenen model API’leri etrafında kendi orkestrasyonunuzu kurup işletmek istediğinizde CometAPI tabanlı bir uygulama seçin. CometAPI üzerinden bir modele erişim, tek başına yerel Agents API oturum uç noktalarını desteklemeyi sağlamaz; kullanmayı planladığınız arayüzü kontrol edin. Maliyet yolları da farklıdır: yerel kullanım OpenAI tarafından faturalandırılırken, özel bir uygulama CometAPI ücretlerini altyapı maliyetlerinizle birleştirir.
Adım 1: CometAPI’ye Bağlanın
Bash kod örneği: Aşağıdaki komutları Bash uyumlu bir terminalde çalıştırın.
pip install --upgrade openai
export COMETAPI_KEY="your-cometapi-key"
Python kod örneği: Bir model çıkarım isteği gönderin ve yanıtı yazdırın.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
)
response = client.responses.create(
model="gpt-6-astra",
input=(
"Analyze an API latency spike after a database migration. "
"Identify possible causes and prioritize diagnostic steps."
),
)
print(response.output_text)
Geliştiriciler GPT-6 Astra API in CometAPI erişebilir. Yukarıdaki örnek model çıkarımı yapar; aşağıda açıklanan araç döngüsünün uygulanması ayrı bir uygulama sorumluluğudur.
Adım 2: Bir Araç Yürütme Katmanı Ekleyin
Özel bir denetleyici, modeli yönlendirebilir, araç çağrısı isteklerini inceleyebilir, eylemleri yetkilendirebilir ve yürütebilir, sonuçları döndürebilir ve tamamlanana veya önceden tanımlanmış bir sınıra ulaşana kadar tekrar edebilir. Turlar, araç çağrıları, yürütme süresi ve harcama için sınırlamalar belirleyin; yıkıcı işlemler için bağımsız onay isteyin.
En İyi OpenAI Agents API Uygulamaları Nelerdir?
- Yazılım mühendisliği: Onaydan önce değişiklikleri birleştirme veya dağıtma adımlarında; sorunları analiz edin, kod değişiklikleri üretin, testleri çalıştırın ve incelemeleri hazırlayın.
- Veri analizi ve raporlama: Yüklenen veri setlerini işleyin, Python hesaplamaları çalıştırın, grafikler oluşturun ve sonuçları kararları destekleyen raporlara dönüştürün.
- BT olay müdahalesi: Uyarıları inceleyin, günlükleri ilişkilendirin, çalışma kitaplarına danışın ve riskli eylemler için insan yetkilendirmesiyle iyileştirme önerin.
- Müşteri destek otomasyonu: İlgili kayıtları alın, biletleri özetleyin, yanıt taslakları oluşturun ve çözümlenmemiş olayları izinli CRM erişimiyle yönlendirin.
- Araştırma ve belge işleme: Belgeleri karşılaştırın, iddiaları kontrol edin, gerçekleri çıkarın ve destekleyici atıflarla bulguları hazırlayın.
İş Akışınızı Değerlendirin
Kendi iş yükünüzden temsilî bir görevle başlayın ve başarılı tamamlamanın nasıl göründüğünü tanımlayın. Aynı girdiler ve kabul kriterlerini kullanarak ajanı mevcut sürecinizle karşılaştırın. Değerlendirme, ideal yolun yanı sıra kurtarmayı da test etsin diye takip isteklerini ve araç hatalarını dahil edin.
Bu ölçümleri birlikte okuyun. Daha fazla görevi tamamlayan bir iş akışı, sık sık manuel düzeltme gerektiriyorsa veya zaman ve maliyet sınırlarınızı aşıyorsa yine de kötü bir uyum olabilir. Sonuçları kullanarak nereleri otomatikleştireceğinize, nerelerde insan incelemesini sürdüreceğinize ve kullanımı genişletmeden önce hangi hataları ele alacağınıza karar verin.
OpenAI Agents API’nin Maliyeti Ne Kadar?
Ayrı bir yönetilen harness platform ücreti yoktur. Toplam kullanım maliyetini model token’ları, uygun araç çağrıları ve isteğe bağlı barındırılan hesaplama belirler. Aşağıdaki model ücretleri, kısa bağlamlı istemlerle (272K girdi token’ına kadar) Standart işlem için milyon token başına USD cinsindendir ve 21 Ekim 2026’da kontrol edilmiştir. Daha uzun istemler, diğer işlem katmanları, önbellek yazımları ve bölgesel işlem, geçerli oranı değiştirebilir.
CometAPI üzerinden model erişimi için geliştiriciler GPT-6.1 Sol ve GPT-6 Luna kullanabilir. Yukarıdaki tablo OpenAI oranlarını gösterir; CometAPI faturası kendi geçerli oranlarını izler.
Örnek: Bir Görev Maliyetini Tahmin Etme
Bu örnek $1.05 toplam, gösterilen token hacimlerini, iki aramayı, bir small konteyner için 20 dakikalık dönemi ve ek faturalandırılabilir arama-içerik token’ları veya önbellek yazımları olmadığını varsayar. Gerçek maliyet, yeniden denemelere, alt ajan kullanımına, önbellek davranışına ve oturuma uygulanan sandbox faturalama kurallarına da bağlıdır. Temsilî bir iş yükü genelinde başarılı tamamlanan görev başına maliyeti izleyin.
OpenAI Agents API’nin Sınırlamaları Nelerdir?
Veri sınırlamaları. Agents API şu anda yalnızca Amerika Birleşik Devletleri’nde veri yerleşimini destekler ve Zero Data Retention (ZDR) desteklemez. Self-hosted bir sandbox, ZDR uygunluğunu değiştirmez. Hassas materyal göndermeden önce, hizmetin saklama ve yerleşim koşullarının gereksinimlerinizi karşılayıp karşılamadığını kontrol edin.
API ve model uyumluluğu. Genel beta arayüzleri değişebilir ve desteklenen özellikler modele göre farklılık gösterebilir. Uygulamanızın kullandığı tam modeli, uç noktayı, akıl yürütme ayarlarını ve araçları test edin. Bir modeli değiştirdiğinizde veya bir API güncellemesini benimsediğinizde entegrasyon kontrollerini tekrarlayın.
Yürütme kontrolü. Çok adımlı görevler token’ları biriktirebilir, değişken süreler alabilir ve araç hatalarıyla karşılaşabilir. Turlar ve çalışma süresi üzerinde bütçeler ve sınırlar belirleyin, görevin ihtiyaç duyduğu izinleri verin ve uzun süreli çalışmayı eşzamansız olarak izleyin. Kesilen araç çağrılarından nasıl kurtulacağınızı planlayın ve önemli sonuçları olan eylemler için insan onayı talep edin.
SSS
OpenAI Agents API istemcileri takip mesajlarını nasıl yeniden denemeli?
Oturum girişi ve yeniden deneme deseni izlenerek aynı mantıksal mesajı yeniden denerken aynı gönderim anahtarını yeniden kullanın. Oturum kimliği ve gönderim anahtarını uygulama durumunda birlikte tutun. Ayrı bir kullanıcı talimatı kendi anahtarını kullanmalıdır; kayıp bir HTTP yanıtı otomatik olarak yeni bir talimat olarak değerlendirilmemelidir.
Bir OpenAI Agents API oturumu modelleri değiştirebilir mi?
Oturum ayarları uç noktası modeli, akıl yürütme çabasını ve hizmet katmanını güncellemeyi destekler. Güncellemeler sonraki turları etkiler; aktif bir tur mevcut ayarlarını korur. Ortaya çıkan yapılandırmanın seçilen model tarafından desteklendiğini doğrulayın ve bu uç noktanın kabul etmediği ayarları değiştirmeniz gerektiğinde yeni bir oturum oluşturun.
OpenAI Agents API sandbox ağ erişimini nasıl kısıtlar?
OpenAI barındırılan ortamlar etkin, devre dışı veya kısıtlı giden erişimi destekler. Kısıtlı mod, açık ana makine izin listeleri kullanır ve yönlendirmeler veya alt alan adları kendi girdilerine ihtiyaç duyabilir. Bir görevin ihtiyaç duyduğu hizmetler için sandbox ağ politikasını yapılandırın; ağ erişimi ve uygulama kimlik bilgileri ayrı denetimlerdir.
Sonuç
Birden çok araç çağrısı ve en az bir takip turu gerektiren temsilî bir görevde Agents API’yi değerlendirin. Tamamlama oranını, kurtarma davranışını, gecikmeyi ve başarılı görev başına maliyeti ölçün. Bu sonuçlar, yönetilen yürütmenin uygulamanızın gereksinimlerini karşılayıp karşılamadığını gösterecektir.