Çoklu Ajan Devri: Alt Ajanlar Arasında Bağlam Aktarımı

Araştırma ajanı müşterinin hesabını, planını ve son dört faturayı buldu; ardından faturalandırma ajanına yalnızca “Müşteri iade istiyor” diye devretti. İkinci ajan hesap kimliğini yeniden sorarsa, ilk ajanın yaptığı araştırma sınırda kaybolmuş demektir.

Apidog'u bugün deneyin

Bu hata iki maliyet yaratır: tekrarlanan API çağrıları ve eksik bağlamla alınan yanlış kararlar. Üretimde AI ajan güvenilirliği açısından kayıp durum, özellikle çoklu ajan sistemlerinde temel bir hata modudur.

En ucuz çözüm çoğu zaman veriyi aktarmak değil, tanımlayıcıları aktarmaktır. Bunun çalışması için her ajanın aynı kaydı doğru izinlerle yeniden getirebilmesi gerekir. Apidog, ortak API sözleşmeleri ve sahte uç noktalarla bu modeli destekler.

Devir tesliminde ne taşınmalı?

Tüm konuşmayı iletmeyin. Alıcı ajan bağlam penceresini geçmişi okumaya harcar ve önemli gerçekleri ayıklamak zorunda kalır.

Bunun yerine şu dört alanı aktarın:

1. Tanımlayıcılar: customer_id, invoice_id, order_id, ticket_id.
2. Alınmış kararlar: Örneğin müşterinin hangi politika kapsamında iadeye uygun olduğu.
3. Kısıtlamalar: Bütçe, onaylar ve daha önce yapılmış eylemler.
4. Açık sorular: İlk ajanın çözemediği veya kullanıcıdan yanıt bekleyen konular.

Ham API yanıtlarını, uzun muhakeme dökümlerini ve alıcı ajanın tek çağrıyla yeniden getirebileceği verileri aktarmayın.

Üç durum aktarım modeli

1. Tüm konuşmayı aktarın

Kısa görevlerde iki ajan için işe yarayabilir. Ancak konuşma uzadığında alıcı ajanın token bütçesi tükenir ve ilgili bilgiler kaybolur. Bu özellikle araç yanıtları bağlama dahil edildiğinde büyür; araç yanıtlarını bağlam penceresi dışında tutma yaklaşımı bu nedenle önemlidir.

2. Özet aktarın

Çoğu çerçevenin varsayılanı budur. Sorun şudur: modeller özetlerken anlatıyı korur, tanımlayıcıları düşürür.

Şu özet zayıftır:

Müşteri iki yıldır abone ve sinirli.

Şu bilgi ise uygulanabilirdir:

Hesap cus_8812, plan Pro, dört fatura var; inv_44 için iade onaylandı.

3. Yapılandırılmış devir teslim nesnesi aktarın

En dayanıklı yaklaşım budur. İlk ajan şemayı doldurur; ikinci ajan düzyazıdan çıkarım yapmak yerine alanları doğrudan okur.

{
  "task_id": "task_2026_08_26_0031",
  "from_agent": "research",
  "to_agent": "billing",
  "entities": {
    "customer_id": "cus_8812",
    "invoice_ids": ["inv_41", "inv_42", "inv_43", "inv_44"],
    "subscription_id": "sub_119"
  },
  "decisions": [
    {
      "decision": "refund_eligible",
      "value": true,
      "basis": "policy 3.2, charged twice in one cycle"
    }
  ],
  "constraints": {
    "max_refund_cents": 4900,
    "human_approval_granted": false,
    "actions_taken": ["read_invoices"]
  },
  "open_questions": [
    "Customer has not confirmed which invoice to refund"
  ],
  "summary": "Customer cus_8812 was double-charged in August. Refund of one invoice is approved under policy 3.2, up to 4900 cents. Awaiting the customer's choice of invoice."
}

summary alanını koruyun, ancak yapılandırılmış alanların yerine kullanmayın. Sınırda doğrulama yapın: customer_id eksikse, ikinci ajanın bunu üç API çağrısı sonra keşfetmesine izin vermeyin.

Veri yerine referans aktarın

En iyi devir teslimi çoğu zaman yalnızca kimlikleri taşır. Alıcı ajan, ihtiyacı olan güncel veriyi API'den getirir.

Bu yaklaşım:

• Durumu güncel tutar.
• Devir teslimini yüzlerce bayta indirir.
• Her okumayı API çağrısı olarak görünür kıldığı için denetim izini iyileştirir.

Bunun için ajanların aynı API'ye, ancak kendi işleriyle sınırlı izinlerle erişmesi gerekir. Araştırma ajanı salt okunur erişime; faturalandırma ajanı ise yalnızca gerekli iade yetkilerine sahip olmalıdır. Ajanlar için en az ayrıcalıklı API anahtarları tek ve güçlü bir anahtarı paylaşmaktan daha güvenlidir.

Yeniden getirme maliyetliyse, veriyi orkestratörde önbelleğe alın ve ajanlar arasında önbellek anahtarını aktarın. Alıcı ajan veriyi yine açıkça ister; yalnızca ikinci okuma ucuzlar.

En yaygın devir teslim hataları

Düşürülen tanımlayıcı

Özet “müşteri” der ama customer_id taşımaz. İkinci ajan ada göre arar, birden fazla sonuç bulur ve yanlış hesabı seçer.

Önlem: Kritik varlık kimliklerini zorunlu şema alanları yapın.

Tekrarlanan eylem

İlk ajan e-postayı gönderir, ancak actions_taken alanına yazmaz. İkinci ajan aynı e-postayı tekrar yollar.

Önlem: Yapılan eylemleri kaydedin ve yazma işlemlerinden önce kontrol edin. Bunu idempotency key kullanımıyla destekleyin.

Kayıp insan onayı

İlk ajan çalışırken bir insan iadeyi onaylar. İkinci ajan bu bilgiyi görmez ve kullanıcıdan tekrar onay ister.

Önlem: Onayları ve bütçeleri ajana değil, göreve ait kalıcı durum olarak saklayın.

Kendinden emin uydurma

Alıcı ajan eksik bir değeri sormak yerine tahmin eder. Bu hata tehlikelidir çünkü görev tamamlanmış gibi görünür.

Önlem: open_questions alanını zorunlu tutun ve isteme şu kuralı ekleyin:

Gerekli bir tanımlayıcı veya onay eksikse dur, tahmin etme ve soru sor.

Devir teslim sınırını test edin

Devir teslimi bir entegrasyon noktasıdır; onu da API entegrasyonu gibi test edin.

1. Üreten ajanı test edin. Sabit bir senaryoda üretilen nesnede zorunlu kimliklerin, kararların ve eylemlerin bulunduğunu doğrulayın.
2. Alıcı ajanı izole test edin. El yapımı geçerli bir nesne verin ve beklenen eylemi doğrulayın.
3. Eksik nesneyle negatif test yapın. customer_id alanını kaldırın; ajanın tahmin etmek yerine soru sorduğunu doğrulayın.
4. Sahte API kullanın. Gerçek iade yapan testler güvenli ve tekrarlanabilir değildir. Ajanları üretim yerine sahte API'lere karşı çalıştırın.
5. Her devri günlüğe kaydedin. task_id ile birlikte tam devir teslim nesnesini saklayın. Ajan araç çağrısı izleme kayda hangi çağrı ve sonuçların eklenmesi gerektiğini gösterir.

Yapılandırılmış yük üzerinde yapılan doğrulama deterministiktir; ajanın kendisi deterministik olmasa bile test güvenilir kalır. Daha geniş test stratejileri için deterministik olmayan AI ajanlarını test etme rehberine bakın.

Çerçeveler ne sağlar?

• OpenAI Agents SDK handoff dokümantasyonu, devir teslimini modelin çağırdığı bir araç olarak ele alır. Kullanışlıdır, ancak karar en az deterministik katmana bırakılır; çıkış doğrulaması ekleyin.
• LangGraph çoklu ajan rehberliği, düğümlerin ortak bir durum grafiğini okuması ve yazması yaklaşımını kullanır. Bu, yapılandırılmış görev nesnesi modeline yakındır.
• Anthropic'in çoklu ajan araştırma sistemi, alt ajanların bağımsız çalışabilmesi için gereken operasyonel bağlamı açıklar.

Çerçeve ne taşırsa taşısın, kritik gerçeklerin listesini siz tanımlamalısınız.

Görev nesnesini konuşmadan ayırın

Kalıcı bir task_id ile anahtarlanmış görev nesnesi kullanın. Ajanlar bu nesneyi okuyup güncellesin; konuşma üzerinden durum aktarmasın.

Önerilen akış:

1. Ajan göreve başlarken görev nesnesini yükler.
2. Bir eylem yaptığında actions_taken alanını günceller.
3. Devir tesliminde yalnızca task_id aktarılır.
4. Alıcı ajan aynı görev nesnesini yükler.
5. Çalışma yarıda kesilirse yeniden deneme kaldığı yerden devam eder.

Bu yaklaşım, özetleme sırasında kritik alanların kaybolmasını engeller ve güvenilir bir devam noktası sağlar.

Bazı iş yönetimi platformları bu modeli hazır sunar. Sharkly, hedef, durum, sorumlu, ajan/ekip, yorumlar ve yürütme sonucunu Görev üzerinde tutar. Sharkly dokümantasyonu, kalıcı görev modelinde hangi alanların önemli olduğuna dair yararlı bir referanstır.

Kontrol listesi

• [ ] Devir teslim şeması tanımlı ve sınırda doğrulanıyor.
• [ ] Varlık kimlikleri zorunlu alanlar.
• [ ] Kararlar gerekçeleriyle kaydediliyor.
• [ ] Yapılmış eylemler yazmadan önce kontrol ediliyor.
• [ ] Onaylar ve bütçeler göreve bağlı tutuluyor.
• [ ] Açık sorular açıkça listeleniyor.
• [ ] Uygun olduğunda veri yerine referans aktarılıyor.
• [ ] Atlama sayısı sınırlanıyor.
• [ ] Orijinal görev nesnesi her devirden sağ çıkıyor.
• [ ] Her devir teslimi task_id ile günlüğe kaydediliyor.
• [ ] CI testleri kasıtlı olarak eksik bir devir teslimi içeriyor.

Çoklu ajan hatalarının çoğu mantık hatası değildir; bir ajanın bildiği gerçeğin diğerine ulaşmamasıdır. Sınırı şeması, doğrulaması ve testleri olan bir arayüz olarak tasarlayın. Ortak API tanımından sahte uç noktalar üretmek ve sınır testlerini API sözleşmenizle birlikte yönetmek için Apidog'u indirin.

Sıkça sorulan sorular

Yapılandırılmış devir teslimi iki ajan için gerekli mi?

Kısa görevlerde konuşma aktarımı yeterli olabilir. Üç veya daha fazla ajan, uzun görevler ya da süreç/çalışma zamanı sınırları varsa yapılandırılmış nesne kullanın.

Devir teslim nesnesini model mi, kod mu üretmeli?

Mümkün olduğunda kod üretmelidir. Kimlikler, eylemler ve onaylar modelin hatırladıklarından değil, orkestratörün kaydettiği gerçek olaylardan doldurulmalıdır. Modeli summary ve open_questions alanlarıyla sınırlayın.

Döngülerde bağlam bozulmasını nasıl önlerim?

Her geçişte yeni özet üretmek yerine aynı görev nesnesini güncelleyin. Ardından maksimum atlama sayısı belirleyin. Bir görev sürekli yeni devirlere ihtiyaç duyuyorsa, görev ayrıştırması yanlıştır.

Yerleşik handoff desteği olan çerçeveler yeterli mi?

Kullanın, ancak gerçekten ne taşıdıklarını doğrulayın. Birçok çerçeve yalnızca mesaj geçmişini aktarır. Kritik kimlikleri, kararları ve kısıtlamaları ayrıca yapılandırılmış yükte taşıyın.

Alt ajanların ayrı API kimlik bilgilerine ihtiyacı var mı?

Evet. Her ajan yalnızca yaptığı iş için gerekli en az yetkiye sahip olmalıdır. Tek, güçlü bir anahtarı paylaşmak hem hasar alanını hem de denetim belirsizliğini artırır.

summary alanı ne kadar uzun olmalı?

Birkaç cümle yeterlidir. Yapılandırılmış alanların taşıyamadığı niyet ve nüansı açıklamalıdır; kimlikler, tutarlar ve durumlar ise doğrulanabilir alanlarda kalmalıdır.