Ajanlar için Responses API ve Chat Completions Karşılaştırması: Bir Sözleşme Seçimi

Ajan iş yükleri için Responses API daha iyi bir varsayılan seçenektir: previous_response_id aracılığıyla sunucu tarafında konuşma durumu, tek bir mesaj bloğu yerine türü belirlenmiş çıktı öğeleri ve anlamsal streaming etkinlikleri sunar. Bu özellikler, aksi takdirde orkestrasyon katmanınızın üstlenmesi gereken defter tutma yükünü azaltır. Chat Completions, mesaj geçmişi üzerinde tam kontrol istediğinizde veya OpenAI sohbet mesajı formatı etrafında oluşturulmuş araçlarla entegrasyon sağladığınızda geçerli bir seçenek olmaya devam eder, ancak çok turlu araç çağıran (tool-calling) ajanlar için Responses daha doğrudan bir uyum sağlar.

Her iki uç nokta da GPT-5.6 ve GPT-5.5 için güncel model referans sayfalarında belgelenmiştir ve Responses için paylaşılan istek/yanıt sözleşmesi Responses create referansında belirtilmiştir.

Önemli Çıkarımlar

• Chat Completions çağrı yapan tarafından yönetilir: Her istekte tam messages dizisini gönderir ve geçmişi kendiniz yeniden oluşturursunuz.
• Responses sunucu desteklidir: input ve isteğe bağlı instructions gönderirsiniz ve geçmişi yeniden göndermek yerine previous_response_id ile turları birbirine bağlayabilirsiniz.
• Araç çağırma yapısal olarak farklıdır: Chat Completions çağrıları choices[0].message.tool_calls altında iç içe yerleştirir; Responses bunları düz bir output dizisinde türü belirlenmiş öğeler olarak yayar.
• Araç sonuçları, tool_call_id (Chat) ile function_call_output öğesindeki call_id (Responses) üzerinden eşleştirilir.
• Streaming, Chat Completions'da parça tabanlı deltalardan oluşurken, Responses'da adlandırılmış anlamsal etkinliklerden oluşur.
• Barındırılan araç desteği (web araması, kod yorumlayıcı, dosya araması vb.) her iki API'de de modele bağlıdır; kullanılabilirliği varsaymadan önce modelin sayfasını kontrol edin.

Alan Düzeyinde Karşılaştırma

Konu	Chat Completions	Responses
Uç Nokta	POST /v1/chat/completions	POST /v1/responses
Birincil girdi	messages: [] (her çağrıda tam dizi)	input (dize veya öğe dizisi)
Sistem tarzı rehberlik	messages[0].role = "system"	Üst düzey instructions alanı
Çok turlu devamlılık	Çağrı yapan tüm messages geçmişini yeniden gönderir	previous_response_id sunucu tarafında önceki turu referans alır
Çıktı şekli	choices[0].message (tek mesaj nesnesi)	output: [], türü belirlenmiş öğeler dizisi (mesaj, function_call vb.)
Araç çağrısı konumu	choices[0].message.tool_calls[]	output içinde type: "function_call" olan öğeler
Araç sonucu gönderimi	role: "tool", tool_call_id içeren yeni mesaj	type: "function_call_output", call_id içeren öğe
Streaming	chunk.choices[0].delta parçaları	Adlandırılmış etkinlikler (response.output_text.delta, response.completed vb.)

previous_response_id: Gerçekte Ne Yapar?

Chat Completions'da konuşma belleği tamamen sizin sorumluluğunuzdadır. Her istek tam mesaj geçmişini içermelidir ve sunucunun önceki tura dair hiçbir bilgisi yoktur. Responses API ise her yanıt nesnesinde bir id döndürür. Uygulamanız bu id'yi kalıcı hale getirir ve bir sonraki çağrıda previous_response_id olarak geri gönderirse, sunucu önceki konuşma durumunu kendi tarafında yeniden oluşturur. Mevcut tur için yalnızca yeni input ve (isteğe bağlı olarak) taze instructions göndermeniz yeterlidir. Bu, durum yönetimini uygulama katmanınızdan OpenAI'ın altyapısına kaydırır; bu, sıralı araç çağırma turları yapan ajanlar için önemlidir çünkü her adımda büyüyen bir geçmişi yeniden serileştirmekten ve yeniden iletmekten kaçınırsınız.

Bunun karşılığındaki ödünleşim, uygulamanızın id'yi turlar arasında kalıcı bir yerde (bir oturum deposu, veritabanı satırı) saklaması gerektiğidir; API size geçmiş yanıtlar üzerinde sonsuz saklama veya arama imkanı vermez, sadece hemen önceki yanıtı bir devam noktası olarak referans almanızı sağlar.

Güncel İstek Örnekleri (gpt-5.6)

Chat Completions: tüm geçmişin sorumluluğu sizde:

{
  "model": "gpt-5.6",
  "messages": [
    { "role": "system", "content": "You are a support agent." },
    { "role": "user", "content": "Check order #4471 status." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } }
      }
    }
  ]
}

Responses: instructions ve input ile ilk tur:

{
  "model": "gpt-5.6",
  "instructions": "You are a support agent.",
  "input": "Check order #4471 status.",
  "tools": [
    {
      "type": "function",
      "name": "get_order_status",
      "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } }
    }
  ]
}

Responses: takip eden tur, geçmiş yeniden gönderilmiyor:

{
  "model": "gpt-5.6",
  "previous_response_id": "resp_abc123",
  "input": "What about order #4472?"
}

Fonksiyon Çağırma Yaşam Döngüsü

Chat Completions:

1. Model, her biri bir id ve fonksiyon adı/argümanları içeren choices[0].message.tool_calls döndürür.
2. Fonksiyonu yerel olarak çalıştırırsınız.
3. Asistan mesajını (tool_calls ile) messages dizinize eklersiniz, ardından yeni bir mesaj eklersiniz: { "role": "tool", "tool_call_id": "<id>", "content": "<result>" }.
4. Devam etmek için güncellenmiş messages dizisinin tamamını yeniden gönderirsiniz.

Responses:

1. output dizisi, call_id, name ve arguments içeren type: "function_call" türünde bir öğe içerir.
2. Fonksiyonu yerel olarak çalıştırırsınız.
3. previous_response_id değerini önceki yanıtın id'sine ayarlanmış ve input kısmında call_id ile eşleşen type: "function_call_output" türünde bir öğe içeren yeni bir istek gönderirsiniz.
4. Sunucu fonksiyon çağrısı bağlamını zaten koruduğu için önceki turları yeniden göndermezsiniz.

Düz türü belirlenmiş çıktı öğeleri ile iç içe diziye sahip tek bir mesaj arasındaki yapısal fark, Responses'da ayrıştırma mantığını basitleştirme eğilimindedir; çünkü bir mesajın isteğe bağlı alanlarını deşmek yerine output üzerinde yineleme yapabilir ve type üzerinden seçim yapabilirsiniz.

Karar Kontrol Listesi

• Araç çağrıları içeren çok turlu bir ajan mı inşa ediyorsunuz? Responses'ı varsayılan yapın; previous_response_id geçmiş defter tutma yükünü ortadan kaldırır.
• Geçmişte ne olduğu üzerinde tam kontrole mi ihtiyacınız var (redaksiyon, özel özetleme, standart dışı mesaj enjeksiyonu)? Chat Completions, messages'ı kendiniz oluşturduğunuz için size bu kontrolü açıkça verir.
• Mevcut bir Chat Completions entegrasyonunu mu taşıyorsunuz? Yeniden düzenleme maliyetini durum yönetimi tasarrufuyla tartın; kısa ömürlü, tek turlu çağrılar için fayda daha azdır.
• Barındırılan araçlara mı bağımlısınız (arama, kod yorumlayıcı, dosya araçları)? Taahhütte bulunmadan önce belirli modelin sayfasında desteği doğrulayın, çünkü kullanılabilirlik model ve uç noktaya göre değişir.
• İnce ayarlı etkinlik semantiği ile streaming'e mi ihtiyacınız var (örneğin, delta şeklini incelemeden metin deltalarını araç çağrısı deltalarından ayırmak)? Responses'ın adlandırılmış etkinlikleri, Chat Completions'ın genel delta parçalarından daha açıktır.
• Sohbet mesajları etrafında oluşturulmuş mevcut bir framework veya SDK içinde mi çalışıyorsunuz? Proje ortasında sözleşme değiştirmeden önce Responses desteğinin olgunluğunu doğrulayın.

Çoklu sağlayıcı ajanları ve sözleşme çevirisi

Ajanlar nadiren uzun süre tek bir sağlayıcıda kalır. Bir kodlama ajanı, uygulama işleri için Claude Sonnet 5 veya Kimi K2.7 Code'a yönlendirebilir, ucuz taslak geçişleri için DeepSeek V4 Flash veya Gemini 3.5 Flash'a geri dönebilir ve bazen açık ağırlıklı maliyet kontrolü için GLM-5.2 veya Qwen3.7 Plus'ı çağırabilir. Bu sağlayıcıların hiçbiri OpenAI'ın Chat Completions veya Responses sözleşmesini yerel olarak sunmak zorunda değildir.

İşte bir yönlendirme katmanının değeri burada ortaya çıkar. TokenLab'in docs.tokenlab.sh adresindeki belgeleri, birden fazla model sağlayıcısına ulaşmak için kullanılan tek bir API yüzeyini ve anahtarını açıklar; bu da her sağlayıcı sözleşmesi için ayrı bir istemci entegrasyonu yazma ihtiyacını ortadan kaldırır. Sözleşme uyumluluğu için başlık takma adları hakkındaki ilgili makalemiz, bir sözleşme şekline göre yazılmış kodun, onu yerel olarak konuşmayan modellere nasıl ulaşabileceğini kapsar. Birden fazla model ailesini çağırması gereken bir sohbet botu veya ajan oluşturuyorsanız, tek bir API anahtarıyla yapay zeka sohbet botu oluşturma rehberimiz kurulumu daha somut terimlerle anlatır.

TokenLab aracılığıyla ulaşılabilen, yukarıda referans verilen öncü, kodlama ve düşük maliyetli yönlendirme seçenekleri dahil olmak üzere güncel tam liste için modeller sayfamıza bakın. Mimarinizi kesinleştirmeden önce güncel kullanılabilirliği ve sözleşmeye özel notları orada doğrulayın, çünkü model dizilimleri API sözleşmelerinden daha sık değişir.

Sınırlamalar

Bu makale, her iki sözleşme için de OpenAI'ın tam alan düzeyindeki API referansını yeniden ifade etmez, çünkü bu detaylar sürümlüdür ve değişebilir. Yukarıdaki istek şekli örneğini üretime hazır kod olarak değerlendirmeyin. Ayrıca her sağlayıcının yerel sözleşmesini burada derinlemesine ele almadık; Claude, Gemini, DeepSeek ve GLM'nin her biri kendi API referanslarını yayınlar ve hiçbiri OpenAI'ın Chat Completions veya Responses şekilleriyle eşleşmek zorunda değildir. Ajanınızın araç çağırma sıralaması, streaming etkinlik formatları veya toplu işleme davranışı hakkında garantilere ihtiyacı varsa, bu detayları bu makaleye göre değil, ilgili sağlayıcının güncel belgelerine göre doğrulayın.

SSS

Responses API, Chat Completions'ın yerini mi alıyor? OpenAI'ın hızlı başlangıç belgeleri, Responses API'yi ajan kullanımı durumları da dahil olmak üzere yeni geliştirmeler için mevcut yol olarak konumlandırırken, Chat Completions belgelenmiş API yüzeylerinin bir parçası olmaya devam etmektedir. Chat Completions'ın herhangi bir zamanda kullanımdan kaldırılıp kaldırılmadığı, sonlandırılıp sonlandırılmadığı veya sadece eski bir teknoloji olup olmadığı, destek durumu değişebileceği için OpenAI'ın güncel belgelerinden doğrudan doğrulamanız gereken bir konudur.

Claude, Gemini veya DeepSeek gibi diğer sağlayıcılar aynı sözleşmeleri mi kullanıyor? Yerel olarak hayır. Her sağlayıcı kendi istek ve yanıt şeklini tanımlar. Bir ajanı OpenAI modelleri ve Claude Sonnet 5 veya DeepSeek V4 Pro gibi sağlayıcılar arasında çalıştırmanız gerekiyorsa, paylaşılan bir sözleşme varsaymak yerine bir çeviri katmanı planlayın.

Sözleşmeleri değiştirmek model çıktı kalitesini etkiler mi? Hayır. Sözleşme, isteğin ve yanıtın taşınması ve yapısıdır, modelin kendisi değildir. Çıktı kalitesi, Chat Completions veya Responses API'sini kullanıp kullanmadığınızla değil, hangi modeli çağırdığınızla (örneğin GPT-5.5 ile Claude Sonnet 5 karşılaştırması) yönetilir.

Ajanınız için hangi sözleşmenin ve hangi modellerin uygun olduğunu değerlendiriyorsanız, TokenLab'in belgelenmiş uç noktalarına karşı küçük bir test yapısı ile başlayın ve orkestrasyon yükünü doğrudan karşılaştırın. Kendi iş yükünüze karşı bu karşılaştırmayı çalıştırmak için docs.tokenlab.sh adresinden Başlayın.