OpenAI Agents API Nasıl Kullanılır?

OpenAI Agents API, OpenAI'ın açık kaynaklı Codex donanımını sizin için çalıştırır. `POST https://api.openai.com/v1/agents/sessions` adresine `OpenAI-Beta: agents=v1` başlığı, bir aracı tanımı ve bir görev ile istek gönderirsiniz; OpenAI modeli ve araç döngüsünü çalıştırır, oturumu sürdürür ve bir sanal alan sağlayabilir. Agents API ücreti yoktur: jetonlar, araçlar ve barındırılan kapsayıcı süresi için ödeme yaparsınız (1 GB ila 16 GB sanal alan boyutları için 20 dakikalık oturum başına 0,03 ila 0,48 ABD doları). 10 Eylül 2026'da genel betaya girdi ve OpenAI, 29 Eylül'deki DevDay'de bilgisayar kullanımını ekledi.

Düğme

Aşağıda: ilk REST oturumu, ilerleme olayları, MCP araçları, alt aracılar ve bilgisayar kullanım onayı akışı bulunmaktadır. OpenAI'ın diğer aracı yüzeyleriyle nasıl karşılaştırıldığını öğrenmek için Agents API vs Responses API vs Agents SDK makalesini okuyun; etkinliğin geri kalanı için DevDay 2026 özetine bakın. Her çağrı basit bir HTTP isteğidir, bu yüzden uygulama kodu yazmadan önce Apidog'dan gönderebilirsiniz.

OpenAI Agents API'ye bir bakış

Kaynaklar: Agents API'ye Giriş, Agents API genel bakışı ve fiyatlandırma sayfası.

Dört temel kavram

Belgeler API'yi dört temel unsur üzerine kurar:

• Aracı: model, talimatlar, araçlar ve MCP sunucuları. Doğrudan geçirin veya kaydedip agent_id'sini yeniden kullanın.
• Ortam: aracının dosyaları okuduğu ve komutları çalıştırdığı isteğe bağlı bir sanal alan veya bilgisayar.
• Oturum: yapılandırmayı, konuşmayı ve kaydedilen işleri tutan aracının kalıcı bir örneği.
• Olaylar ve öğeler: olaylar ilerlemeyi canlı olarak bildirir; öğeler kaydedilen mesajlar ve araç çağrılarıdır.

Boşta duran bir oturuma gönderilen bir mesaj yeni bir tur başlatır; bir turun ortasında gönderilen bir mesaj turu yönlendirir. Donanım ( mimari sayfasına göre, modeli ve araç döngüsünü çalıştıran barındırılan Codex örneği) ayrıca bağlam sıkıştırmayı da yönetir, bu nedenle bunu yapılandırmanıza gerek yoktur.

Bir ortam seçin

environment.type komutların nerede çalışacağını belirler:

• none: hesaplama yok. Uzak MCP sunucuları ve işlev araçlarınız hala çalışır; yerleşik Bash, yama uygulama, çalışma alanı dosyaları ve yürütücü MCP'ler çalışmaz.
• openai_hosted: OpenAI, /workspace içinde Python ve Node.js ile bir Linux sanal alanı yönetir. container_size'ı small (1 GB), medium (varsayılan, 4 GB) veya large (16 GB) olarak ayarlayın ve network.access'i enabled, disabled veya allowed_domains ile restricted olarak ayarlayın. Bir tur tamamlandığında /workspace/outputs içindeki dosyalar yapıt haline gelir. Bağlantı kesilmeden boşta duran bir sanal alan bir saat sonra silinebilir.
• self_hosted: sizin altyapınız. codex exec-server'ı bir dizüstü bilgisayarda, kapsayıcıda veya uzak sanal alanda çalıştırırsınız ve ayrı bir ortam anahtarı ile dışarıya doğru bağlanır.

Lansman yazısı sanal alan ortakları olarak Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop ve Vercel'i listeler; kendi kendine barındırma kılavuzu AWS Lambda MicroVM'leri ekler.

REST üzerinden ilk oturumunuz

Yukarıdaki izinlere sahip bir anahtarı OPENAI_API_KEY olarak dışa aktarın, ardından hızlı başlangıç görevini küçük bir kapsayıcı ile gönderin:

curl --no-buffer https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Write clean code, run it, and report the actual output."
    },
    "environment": { "type": "openai_hosted", "container_size": "small" },
    "input": "Create tree.py, a script that prints a tree of the files in the current directory. Run it and show the output.",
    "stream": true
  }'

stream: true ile yanıt, ilk turun olay akışıdır. Oturum kimliğini kaydedin; yaşam döngüsünün geri kalanı aynı kaynağı kullanır:

JavaScript SDK'sı aynı şekle sahiptir. Lansman yazısından uyarlanan bu sürüm, bir araç, alt aracılar ve bir kasa ekler:

import OpenAI from "openai";

const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [{ type: "web_search" }],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: [process.env.VAULT_ID],
  environment: { type: "openai_hosted" },
  input: "Summarize breaking changes in the latest release notes.",
});
console.log(session.id);

İlerlemeyi takip et: akış veya web kancaları

Akış. Girdi göndermeden önce GET /v1/agents/sessions/{id}/events?stream=true adresini `Accept: text/event-stream` ile açın, böylece erken olayları kaçırmazsınız. Şunları izleyin:

• Metin için agent.session.turn.output_text.delta ve agent.session.turn.output_text.done
• Sonuç için agent.session.turn.completed, agent.session.turn.failed veya agent.session.turn.cancelled
• Aracı bir işlev sonucuna, bir ortam bağlantısına veya bilgisayar kullanımı onayına ihtiyaç duyduğunda agent.session.requires_action

Üç tuzak: agent.session.idle turun başarılı olduğu anlamına gelmez, tamamlanmış bir tur başarısız araç çağrıları içerebilir ve akışı kapatmak görevi durdurmaz. Akışlar kaçırılan olayları tekrar oynatmaz, bu nedenle bir bağlantı kesintisinden sonra yeni bir akış açın ve oturumu ve öğelerini alın.

Web Kancaları. agent.session.created, agent.session.action_required, agent.session.in_progress, agent.session.idle ve agent.session.failed olaylarına abone olun. Adlandırmaya dikkat edin: akış `requires_action` derken, web kancası `action_required` der. Yükler çağrı ayrıntılarını içermez, bu nedenle işleyiciniz oturumu alır ve `required_actions` okur. Her imzayı doğrulayın (webhook imza doğrulama); uzun süreli API işlemleri, web kancalarının neden çok dakikalık görevler için uygun olduğunu açıklar.

MCP araçları, araç arama, programatik araç çağırma ve alt aracılar

MCP. `agent.tools`'a bir sunucu ekleyin:

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": { "type": "http", "server_url": "https://developers.openai.com/mcp" },
  "required": true
}

Varsayılan olarak OpenAI bağlantıyı kurar (connection_origin: "service"), bu nedenle sunucunun OpenAI'dan erişilebilir olması gerekir. Özel ağ sunucusu için connection_origin: "environment" kullanın veya sanal alanda bir tane başlatmak için stdio kullanın. Kimlik bilgileri için, bir oturum için transport.authorization geçirin veya vault_ids ile bir kasa kimlik bilgisi (static_bearer veya mcp_oauth) ekleyin.

Araç arama. Model araç aramayı desteklediğinde MCP araçları otomatik olarak keşfedilir. Birçok işlev aracı için {"type": "tool_search"} ekleyin ve işlevleri defer_loading: true olarak işaretleyin.

Programatik araç çağırma. Varsayılan olarak etkin: aracı, JavaScript'i izole bir V8 çalışma zamanında çalıştıran bir `exec` aracı alır, böylece araç çağrıları üzerinde döngü yapabilir ve büyük sonuçları bağlama ulaşmadan önce kırpabilir. {"type": "programmatic_tool_calling", "enabled": false} ile devre dışı bırakın.

Alt aracılar. multi_agent: {"enabled": true, "max_concurrent_subagents": 3} olarak ayarlayın (varsayılan sınır 6'dır). Alt aracılar ortamın dosya sistemini paylaşır ve MCP araçlarını ve web aramasını miras alır, ancak işlev araçlarını kullanamaz. Bir turun subagent_id'si ana aracı için null'dır.

Bilgisayar kullanımı: DevDay eklentisi

Bilgisayar kullanımı aracıya barındırılan bir tarayıcı sağlar. Aracı ve bir masaüstünü barındırılan bir ortama ekleyin:

{
  "agent": {
    "model": "gpt-6-astra",
    "tools": [{ "type": "computer_use", "include_screenshots": true }]
  },
  "environment": {
    "type": "openai_hosted",
    "desktop": { "enabled": true },
    "network": { "access": "enabled" }
  }
}

Tarayıcı, her yeni web sitesi kaynağını ziyaret etmeden önce (genel siteler dahil) kullanıcının onayına ihtiyaç duyar. agent.session.requires_action üzerinde oturumu alın ve computer_use_approval_request girişlerini bulun. İç içe yerleştirilmiş request.type iki türden biridir:

• browser_origin_access: origin ve reason'ı gösterin, ardından approve, deny veya cancel gönderin.
• browser_authentication: fields, isteğe bağlı oturum açma options ve bir credential_origin içeren bir oturum açma formu. Kullanıcının değerleriyle birlikte action: "submit" veya action: "cancel" gönderin.

Her iki yanıt da olaylar uç noktası üzerinden geri döner:

curl "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [{
    "type": "agent.session.input.computer_use_approval_request_result",
    "request_id": "REQUEST_ID",
    "response": { "type": "browser_origin_access", "decision": "approve" }
  }]}'

Tarayıcı çalışması, id, turn_id, title, status ve output ile computer_use_call öğeleri olarak görünür; bu output, include_screenshots açık ve mevcut olduğunda base64 JPEG ekran görüntüsü taşır. Ekran görüntülerini günlüklerden uzak tutun; hesap verilerini gösterebilirler.

Bilgisayar kullanımı kılavuzu şu uyarılara dikkat çeker:

• Origin onayı eylem onayı değildir. Bir siteyi onaylamak, aracının her satın alma veya silme işleminden önce sormasını sağlamaz. Buna ihtiyacınız varsa, tarayıcıyı bu eylemleri gerçekleştiremeyen kaynaklarla sınırlayın veya kontrol ettiğiniz bir tarayıcı çalışma zamanı kullanın.
• Oturum açma e-posta, parolalar ve doğrulama kodlarını kapsar. Parola anahtarları ve QR kodlu oturum açma desteklenmez.
• Yalnızca ana aracı kimlik doğrulaması isteyebilir. Alt aracılar isteyemez.
• Kimlik bilgisi gönderimlerinde otomatik yeniden denemeleri devre dışı bırakın (SDK'da maxRetries: 0, curl'de --retry 0).
• Bir 202 kabul edildi anlamına gelir, navigasyon veya oturum açma başarılı oldu anlamına gelmez. Kimlik doğrulama istekleri beş dakika sonra sona erer.
• Origin onayı ağ politikasını geçersiz kılmaz. Siteyi ve yönlendirme alanlarını network içinde de izin verin.

Özet, bilgisayar kullanımının “API aracılığıyla ve Codex ile ChatGPT İşlerinde Pro 500 ve Enterprise sürümlerinde” sunulduğunu belirtiyor. Aynı modelle UI odaklı testler için API testi için GPT-6 Astra bilgisayar kullanımına bakın.

Aracıya kullanıcı arayüzünüzü değil, API'nizi verin

Tarayıcı, API'si olmayan yazılımlar için bir yedektir. Sistem sizinse, onu bir MCP sunucusuna sarın: tip tanımlı araçlar, origin istemleri yok, kontrol edilebilir sonuçlar. Bilgisayar kullanımı ve yapılandırılmış API'ler takası ele alır ve Apidog MCP Sunucusu, API belirtiminizi sarmalayıcıyı yazan kodlama asistanına besler.

Kod yazmadan önce Agents API'yi Apidog'da test edin

API beta aşamasındadır, bu nedenle her çağrının yapısını önce Apidog'da elle onaylayın:

1. OPENAI_API_KEY, VAULT_ID ve SESSION_ID ile bir Apidog ortamı oluşturun. Her istekte Bearer {{OPENAI_API_KEY}} ve OpenAI-Beta: agents=v1 gönderin.
2. stream olmadan oturum oluşturma isteğini gönderin, 2xx durum kodu ve boş olmayan bir id olduğunu doğrulayın ve id'yi SESSION_ID'ye çıkarın.
3. Olay akışını bir SSE isteği olarak açın, ikinci bir istekten girdi gönderin ve olayların gelmesini izleyin.
4. Onay ve iptal yüklerini, her required_actions durumunu tekrar oynatmak için istekler olarak kaydedin.
5. Bunları bir test senaryosunda zincirleyin ve Apidog CLI ile CI'da çalıştırın.

Yapay zeka aracı API test kılavuzu, deterministik olmayan çıktılar için doğrulama kalıplarına sahiptir. Takip etmek için Apidog'u indirin.

Sıkça Sorulan Sorular

OpenAI Agents API ücretsiz mi? Platform ücreti yoktur, ancak model jetonları, araç çağrıları ve barındırılan kapsayıcı süresi için ödeme yaparsınız.

Hangi modeller Agents API ile çalışır? Belgelerdeki örnekler, her bilgisayar kullanımı örneği dahil, gpt-6-astra kullanır. Sayfalarda desteklenen diğer modeller listelenmemiştir, bu nedenle önce kendi modelinizi test edin.

Agents API Sıfır Veri Saklamayı destekliyor mu? Hayır. Yalnızca ABD veri ikametgahını destekler ve kendi kendine barındırılan bir sanal alanla bile ZDR uygun değildir.

Agents SDK veya Responses API'den farkı nedir? SDK, döngüyü uygulamanızın içinde çalıştırır; Responses API, etrafında bir döngü oluşturduğunuz model çağrısıdır. Tam karşılaştırmaya bakın.

Tek bir salt okunur oturumla başlayın

Yalnızca okuyan bir oturumla başlayın, bir MCP sunucusu ekleyin, ardından varsayılan olarak reddeden bir onay işleyicisinin arkasına bilgisayar kullanımını ekleyin. ChatGPT kendi sunucunuzdan gelen olaylara tepki vermesi gerektiğinde, MCP Olayları eşleşen parçadır.