OpenAI Agents API Eğitimi: Bulutta Kod Yazıp Çalıştıran Bir Aracı (Agent) Oluşturun

Çoğu LLM uygulaması basit bir deseni izler: bir istem (prompt) gönderin, bir yanıt alın ve bu yanıtı uygulamanızda kullanın.

Bu, basit görevler için iyi çalışır; ancak modelin kod yazması, çalıştırması, sonucu kontrol etmesi, dosyalarla çalışması, hataları düzeltmesi ve görev gerçekten bitene kadar devam etmesi gerektiğinde işler karmaşıklaşır.

İşte bu noktada OpenAI'nin Agents API'si gerçekten kullanışlı hale gelir.

Her adımı kendiniz inşa etmek yerine, aracıya görevi, ihtiyaç duyduğu dosyaları ve çalışacağı ortamı verip gerisini ona bırakabilirsiniz.

Bu eğitimde örneği basit tutacağım. Küçük, kurgusal bir kafe satış veri kümesi oluşturup aracıya vereceğiz. Aracı, analizi yazıp çalıştıracak, sonuçları doğrulayacak ve bizim için üç çıktı dosyası oluşturacak.

Perde arkasında tüm sürecin nasıl işlediğini gördüğünüzde, alışılmış kodlama iş akışının ne kadarının sizin için otomatikleştirildiğini fark etmeye başlayacaksınız. 

Yapay zekâ aracılara yeniyseniz, AI Agents Fundamentals Yetenek yolumuzu incelemenizi öneririm. 

OpenAI Agents API nedir?

OpenAI Agents API, bir aracıya bir görev, ihtiyaç duyduğu dosyalar ve çalışması gereken ortamı verip gerisini ona bırakmanıza olanak tanır.

Elle bir sandbox oluşturmak, bir oturum başlatmak, dosya yüklemek, kod çalıştırmak, hataları kontrol etmek ve her adımı kendiniz yönetmek yerine, görevi, yapılandırmayı, ortamı ve girdi dosyalarını içeren tek bir API isteği gönderebilirsiniz.

Bundan sonra işin çoğunu Agents API üstlenir.

Arka planda, OpenAI orkestrasyon, bağlam, araç kullanımı, yürütme ve uzun süreli oturumlar dahil olmak üzere Codex düzeneğini yönetir. Bunu, neredeyse OpenAI Codex'in uygulamanız için bulutta çalışması gibi düşünebilirsiniz. 

Hesaplama kurma, çalışma ortamını yönetme, oturumu takip etme veya tüm aracı döngüsünü kendiniz inşa etme konusunda bu kadar endişelenmeniz gerekmez.

Bu, aracıdan sadece bir yanıt değil, gerçekten işi yapmasının gerektiği daha karmaşık ve uzun süreli görevler için özellikle kullanışlıdır.

Bu eğitim için, OpenAI barındırmalı bir sandbox kullanacağız:

CSV dosyası, görev ve aracı yapılandırmasıyla tek bir istek gönderiyoruz. 

Agents API daha sonra bizim için oturumu ve sandbox'ı oluşturup yönetiyor.

Sandbox içinde aracı dosyaya bakabilir, analize nasıl yaklaşacağını belirleyebilir, Python kodu üretebilir, çalıştırabilir, sonuçları kontrol edebilir ve bir şeyler ters giderse düzeltebilir.

Her şey bittiğinde çıktılar oturum eserleri (session artifacts) olarak kaydedilir. 

Bunlar grafikler, temizlenmiş veri kümeleri, raporlar veya aracının oluşturduğu başka dosyalar olabilir. Sonrasında bu dosyaları alıp kullanıcının indirmesine ve incelemesine sunabiliriz.

Yani temel fikir basit: görevi bir kez gönderiyoruz ve aracı bundan sonrasındaki gerçek işi üstleniyor.

OpenAI Responses API vs Agents SDK vs Agents API: Hangisini Kullanmalısınız?

Bu üçü arasındaki temel fark, iş akışının ne kadarını kendiniz yönetmek istediğinizdir.

Modelden özetleme, çıkarım, sınıflandırma, soru yanıtlama, yapılandırılmış çıktı veya birkaç araç çağrısı gibi odaklı bir görevi tamamlamasını istediğinizde Responses API'yi kullanın.

Bir aracı uygulamasını kendiniz geliştiriyor ve aracılar, araçlar, devirler (handoff), korkuluklar ve çoklu aracı iş akışları üzerinde daha fazla denetim istiyorsanız Agents SDK'yı kullanın.

Görev daha karmaşıksa ve kendi çalışma ortamına ihtiyaç duyuyorsa Agents API'yi kullanın. Aracının dosyalarla çalışması, kod çalıştırması, sonuçları incelemesi, hataları düzeltmesi ve birden çok adım boyunca devam etmesi gerektiğinde bu yaklaşım faydalıdır.

Adım Adım Rehber: OpenAI ile Bir Veri Analizi Aracısı (Agent) Oluşturma

Bu eğitimde, aracı bir dosyayla çalışacağı, analizi kurgulayacağı, kod çalıştıracağı, sonuçları inceleyeceği ve son eserleri (artifacts) kullanıcı için kaydedeceği için Agents API'yi kullanıyoruz.

Hadi başlayalım

1. Agents API için Python ortamınızı kurun

Bu eğitimde, Agents API'yi adım adım test etmek ve her parçanın nasıl çalıştığını anlamak için bir Jupyter Notebook kullanacağız. 

Önce OpenAI paketini kurup geri kalan adımlarda ihtiyaç duyacağımız kütüphaneleri içe aktaracağız.

Önce OpenAI Python paketini kurun veya yükseltin:

%pip install -q --upgrade openai

Ardından kullanacağımız kütüphaneleri içe aktarın:

import base64
import csv
import io
import os
import random
from datetime import date, timedelta
from pathlib import Path

from IPython.display import Markdown, display
from openai import OpenAI

Şimdi OpenAI istemcisini oluşturun:

client = OpenAI()

OPENAI_API_KEY değişkeninizin ortamınızda ayarlı olduğundan emin olun. OpenAI istemcisi bunu otomatik olarak alacaktır.

2. Yapay zekâ aracısı için örnek veri üretin

Aracıya verecek basit bir şeyimiz olsun diye küçük bir sahte satış veri kümesi oluşturacağız.

random.seed(42)

products = {
    "Latte": 4.50,
    "Tea": 3.00,
    "Cookie": 2.50,
    "Sandwich": 7.00
}

locations = ["Downtown", "Airport", "Campus"]
first_day = date(2026, 1, 1)
orders = []

for order_id in range(1, 51):
    product = random.choice(list(products))

    orders.append(
        {
            "order_id": order_id,
            "date": first_day + timedelta(days=random.randint(0, 89)),
            "location": random.choice(locations),
            "product": product,
            "units": random.randint(1, 5),
            "unit_price": products[product],
            "discount_rate": random.choice([0, 0, 0, 0.10]),
        }
    )

Bu, farklı ürünler, konumlar, tarihler ve indirimler arasında 50 sahte kafe siparişi oluşturur. Defalarca çalıştırdığımızda aynı veri kümesinin üretilmesi için sabit bir rastgele tohum kullanıyoruz.

3. Aracı sandbox'ı için CSV dosyasını oluşturup kodlayın

Şimdi üretilen verileri aracıya aktarılabilecek bir CSV dosyasına dönüştüreceğiz.

csv_buffer = io.StringIO()

writer = csv.DictWriter(
    csv_buffer,
    fieldnames=orders[0].keys()
)

writer.writeheader()
writer.writerows(orders)

csv_text = csv_buffer.getvalue()

csv_base64 = base64.b64encode(
    csv_text.encode()
).decode()

print("Preview:")
print("\n".join(csv_text.splitlines()[:6]))

Çıktı:

Preview:
order_id,date,location,product,units,unit_price,discount_rate
1,2026-01-04,Campus,Latte,3,4.5,0
2,2026-01-18,Campus,Tea,1,3.0,0
3,2026-01-05,Downtown,Sandwich,1,7.0,0
4,2026-03-06,Campus,Tea,1,3.0,0
5,2026-01-29,Airport,Sandwich,5,7.0,0

Ayrıca dosyayı aracı isteğiyle doğrudan göndereceğimiz için CSV'yi Base64 ile kodluyoruz.

4. Aracı görevi ve beklenen çıktıları tanımlayın

Şimdi aracıdan CSV dosyasıyla ne yapmasını istediğimizi tarif edeceğiz.

task = """
Analyze /workspace/cafe_sales.csv. Write /workspace/analyze_sales.py and run it.

Your job:
1. Check that the required columns exist and numeric values are valid.
2. Calculate gross_sales = units * unit_price.
3. Calculate net_sales = gross_sales * (1 - discount_rate).
4. Summarize net sales by location, product, and month.
5. Find the best-selling location and product by net sales.
6. Write these files:
   - /workspace/outputs/summary.json
   - /workspace/outputs/location_sales.csv
   - /workspace/outputs/morning_brief.md
7. Make the Morning Brief friendly and include three evidence-based insights.
8. Read the files back and verify that location totals equal total net sales.
9. Finish by reporting the verified total and the three output filenames.

Use only Python's standard library. Do not invent or silently change data.
""".strip()

Önemli olan, analizi kendimiz yazmak yerine hedefi ve beklenen çıktıları tarif etmemizdir.

Aracı işi nasıl yapacağına karar verip kodu çalıştırabilir ve bitirmeden önce sonuçları doğrulayabilir.

5. Aracıyı OpenAI barındırmalı sandbox'ta çalıştırın

Şimdi her şeyi tek bir istekle Agents API'ye göndereceğiz ve gerçek işi bulutta aracıya bırakacağız.

session_id = None
turn_id = None
response_parts = []

live_output = display(
    Markdown(""),
    display_id=True
)

with client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": (
            "You are a careful data analyst. "
            "Write simple code, run it, and verify the results."
        ),
    },
    environment={
        "type": "openai_hosted",
        "network": {"access": "disabled"},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/cafe_sales.csv",
                "data": csv_base64,
            }
        ],
    },
    input=task,
    stream=True,
) as events:

    for event in events:

        if hasattr(event, "session_id"):
            session_id = event.session_id

        if event.type == "agent.session.turn.output_text.delta":
            response_parts.append(event.delta)

            live_output.update(
                Markdown("".join(response_parts))
            )

        elif event.type == "agent.session.turn.completed":
            turn_id = event.turn.id

        elif event.type.endswith(("failed", "cancelled")):
            raise RuntimeError(
                event.model_dump_json(indent=2)
            )

assert session_id and turn_id

live_output.update(
    Markdown("".join(response_parts))
)

print("✅ Analysis complete")
print(f"Session: {session_id}")
print(f"Turn: {turn_id}")

Asıl işin çoğu burada gerçekleşiyor.

Aracı yapılandırması, barındırılan ortam, CSV dosyası ve görevden oluşan tek bir istek yapıyoruz. 

OpenAI yönetilen oturumu oluşturuyor ve aracıyı barındırılan sandbox içinde çalıştırıyor. Aracı ardından dosyayı inceleyebilir, analyze_sales.py dosyasını yazabilir, çalıştırabilir, sonuçları kontrol edebilir, bir şeyler ters giderse düzeltebilir ve son çıktı dosyalarını oluşturabilir. 

Oturum oluşturma uç noktası aynı istekte hem ortamı hem de ilk girdiyi destekler.

İsteğin üç ana bölümü vardır:

• agent OpenAI'ye hangi modelin kullanılacağını ve aracının nasıl davranacağını söyler.
• environment aracıya barındırılan çalışma alanını verir ve CSV dosyamızı bunun içine yerleştirir.
• input önceki bölümde tanımladığımız görevi aracıya verir.

Ayrıca stream=True ayarını da yaptık. 

Bu, görevin nasıl tamamlandığını değiştirmez. Sadece aracının çalışması sırasında olayları almamızı sağlar; böylece tüm turun bitmesini beklemek yerine ilerlemeyi görebiliriz.

Bu örnekte, agent.session.turn.output_text.delta olaylarını dinleyip not defterini en güncel metinle güncelliyoruz.

Yukarıda gördüğümüz akan metin, aracının ilerlemeyi ve nihai yanıtını raporlamasıdır. 

Asıl görev, agent.session.turn.completed olayını alana kadar barındırılan ortamda çalışmaya devam eder.

Benim çalıştırmamda aracı analyze_sales.py dosyasını oluşturup çalıştırdı, üretilen dosyaları kontrol etti ve toplam net satışı 600.55 olarak doğruladı.

Önemli olan, modelin bize sadece hangi Python kodunu çalıştırmamız gerektiğini söylememiş olmasıdır. Aracı, kodu gerçekten yazıp çalıştırdı, sonucu inceledi ve çıktıyı kendisi doğruladı.

6. Aracının dosya eserlerini (artifacts) alın ve indirin

Aracı tamamladığına göre, o turda oluşturduğu dosyaları indirebiliriz.

download_dir = Path("cloud_bean_results")
download_dir.mkdir(exist_ok=True)

downloaded = []

for artifact in client.beta.agents.sessions.artifacts.list(
    session_id
):
    if artifact.turn_id == turn_id:

        destination = (
            download_dir / Path(artifact.path).name
        )

        with (
            client.beta.agents.sessions.artifacts
            .with_streaming_response
            .content(
                artifact.id,
                session_id=session_id
            )
        ) as response:
            response.stream_to_file(destination)

        downloaded.append(destination)

assert downloaded

print("Downloaded:")

for path in downloaded:
    print(f"- {path}")

Çıktı:

Downloaded:
- cloud_bean_results/summary.json
- cloud_bean_results/morning_brief.md
- cloud_bean_results/location_sales.csv

Burada oturumdan eserleri listeliyor, tamamlanan turda oluşturulanları tutuyor ve bunları yerel cloud_bean_results klasörümüze indiriyoruz.

7. Sandbox hesaplama maliyetlerini azaltmak için oturumu silin

Dosyalarla işimiz bittiğinde, yönetilen ortamı gerekenden uzun süre açık tutmamak için oturumu silmeliyiz.

result = client.beta.agents.sessions.delete(
    session_id
)

print(f"Session deleted: {result.deleted}")

Çıktı:

Session deleted: True

Bu, yönetilen oturumu API'den kaldırır. 

OpenAI, temel kaynakların fiziksel temizliğinin silme isteğinin ardından eşzamansız olarak devam edebileceğini belirtir.

Bu adım, OpenAI barındırmalı bir sandbox kullanırken özellikle önemlidir. 

Sandbox, aracının kod çalıştırdığı ve dosyalarla çalıştığı hesaplama ortamıdır ve barındırılan sandbox'lar, model kullanımından ayrı faturalandırılan konteyner hesaplamasını kullanır. 

Dolayısıyla, oturumları ve ortamları gerekenden uzun süre açık tutarsanız hesaplama maliyetleri artmaya devam edebilir.

Son Söz: OpenAI Agents API maliyete değer mi?

Agents API hakkında beni en çok etkileyen şey, tek bir basit API çağrısıyla ne kadar çok şey yapabilmesiydi.

Dosyayı, görevi, model yapılandırmasını ve barındırılan ortamı verdik. 

Bundan sonrası onun elindeydi: çalışma alanını oluşturdu, veriyi inceledi, Python kodunu yazdı, çalıştırdı, çıktıları kontrol etti, gerekirse hataları düzeltti ve son eserleri üretti.

Bu gerçekten, Codex'in uygulamanız için bulutta çalışması gibi hissettiriyor. 

Hesaplama kurmak, yürütme döngüsünü yönetmek, ara dosyalarla uğraşmak veya her adımı takip etmek zorunda kalmadım. Esas olarak görevi iyi tanımlayıp sonuca baktım.

Çalıştırma yaklaşık iki dakika sürdü; ancak bu süre boyunca aracı arka planda epey iş yaptı.

Bu da onu normal bir API isteğinden ayıran şeydir. 

Sadece bir modelin metin üretmesini beklemiyorsunuz. Bir aracının bir işi gerçekten tamamlamasını bekliyorsunuz.

Benim testlerimde, bu örneğin üç çalıştırması, model ve barındırılan ortam kullanımı dahil olmak üzere toplamda yaklaşık $1.52 tuttu. 

Bu kadar küçük bir görev için ucuz sayılmaz; bu yüzden üretimde önce daha küçük veya daha uygun maliyetli modelleri kesinlikle denerdim.

Ancak kodlama, hata ayıklama, dosyalar, akıl yürütme ve birbiriyle ilişkili çoklu adımlar içeren daha karmaşık işler için, ek maliyet çok daha mantıklı olabilir.