Araştırma ajanı müşterinin hesabını buldu, planı onayladı ve son dört faturayı çekti. Tek satırlık bir özetle faturalandırma ajanına devretti: "Müşteri iade istiyor." Hesap, plan veya faturalar hakkında hiçbir şey bilmeyen faturalandırma ajanı, işe hesap kimliğini sorarak başlıyor.
İlk ajanın topladığı her bilgi, sınırda yok sayıldı. Bu, devir teslim sorunudur ve size iki katına mal olur: birincisi tekrarlanan API çağrılarında, ikincisi ise ikinci ajanın ilk ajandan daha az bilgiyle çalışmasından kaynaklanan hatalarda.
Bu kılavuz, bir devir tesliminde neyin hayatta kalması gerektiğini, ekiplerin durumu aktarma üç yolunu ve her birinin ne zaman işe yaradığını, özetlerin neden beklenenden daha fazlasını kaybettiğini ve bir devir tesliminin iddia ettiğini taşıdığını nasıl test edeceğinizi anlatıyor. Ajanların üretimde neden bozulduğuna dair yazımız, kayıp durumu temel bir hata modu olarak ele alıyor; bu onun çoklu ajan versiyonu.
Apidog burada ortaya çıkıyor çünkü en ucuz çözüm genellikle veri aktarmayı tamamen bırakıp tanımlayıcıları aktarmaktır, ki bu da yalnızca her ajanın aynı kaydı aynı şekilde getirebilmesi durumunda işe yarar.
Sınırı aslında neyin geçmesi gerekiyor?
Her şeyin değil. Tüm konuşmayı kopyalayan bir devir teslimi, hiçbir şeyi kopyalamayan kadar bozuktur, sadece diğer yönden: ikinci ajan tam bir bağlam penceresi devralır ve hangi kısımların önemli olduğunu anlamak zorundadır.
Dört kategori ayırmaya değerdir.
Tanımlayıcılar. Hesap kimlikleri, sipariş kimlikleri, iş kimlikleri, bilet numaraları. Bunlar küçük, kararlı ve alıcı ajanın ihtiyaç duyduğu her şeyi getirmesine olanak tanır. Geçirilecek en değerli şeylerdir ve en sık düşürülenlerdir.
Halihazırda alınmış kararlar. "Müşteri, 3. politika uyarınca iade almaya uygundur." Alıcı ajan bunu yeniden tartışmamalıdır. Eğer yaparsa, bir görev içinde anlaşmazlığa düşen iki ajan elde edersiniz.
Kısıtlamalar. Bütçe limitleri, verilmiş onaylar, halihazırda yapılmış eylemler. Bunu kaybetmek, bir görevin iki kez ücretlendirilmesine veya aynı onay için ikinci kez sorulmasına yol açar. Bu, yapay zeka ajanları için idempotinans konulu yazımızla doğrudan bağlantılıdır.
Açık sorular. İlk ajanın çözemediği şeyler. Bunları açıkça geçirmek, ikinci ajanın sessizce varsaymasını engeller.
Nelerin geçmesine gerek yok: ham API yanıtları, gerekçelendirme dökümü ve alıcı ajanın tek bir çağrıda kendi başına getirebileceği her şey.
Durumu aktarmanın üç yolu
Tüm konuşmayı aktar. Basit ve iki ajan için kısa bir görevde işe yarar. Döküm uzun olduğunda hemen başarısız olur, çünkü alıcı ajan bütçesinin çoğunu geçmişi okumaya harcar ve ilgili gerçekler ortada kaybolur. Araç yanıtlarını bağlam penceresi dışında tutma konulu yazımız, o ortanın tam olarak modellerin neleri kaybettiği yer olduğunu açıklar.
Özet aktar. İlk ajan bir devir teslim mesajı yazar; ikincisi oradan başlar. Bu, çoğu çerçevede varsayılandır ve belirli bir şekilde bilgi kaybına neden olur: modeller, anlatıma doğru özetleme yapar ve tanımlayıcılardan uzaklaşır. Bir özet istediğinizde, "müşteri iki yıldır abone ve sinirli" gibi bir şey alırsınız, "hesap 8812, plan pro, dört fatura, inv_44 faturası için iade onaylandı" yerine.
Yapılandırılmış bir devir teslim nesnesi aktar. İlk ajan bir şemayı doldurur. İkincisi, düzyazıyı değil, alanları okur. Bu, kurulumu daha fazla iş gerektirir ve ayakta kalan yöntem budur.
{
"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ında hala düzyazı bulunur, çünkü şemanın taşımadığı nüansları taşır. Önemli olan, yapılandırılmış alanların yerini almak yerine onların yanında durmasıdır.
Devir teslimi başlamadan önce nesneyi doğrulayın. Eğer customer_id eksikse, ikinci ajanın üç çağrı sonra keşfetmesine izin vermek yerine sınırda yüksek sesle hata verin.
Yükler değil, referanslar aktarın
Bir devir tesliminin en güçlü versiyonu neredeyse hiç veri aktarmaz. Kimlikleri aktarır ve alıcı ajan ihtiyacı olanı getirir.
Bu, üç nedenle işe yarar. Durum taze kalır, bu nedenle iki ajan arasında bir şey değiştiyse ikincisi eski bir kopyayı değil, mevcut değeri görür. Devir teslimi küçük kalır, on binlerce belirteç yerine birkaç yüz bayt. Ve denetim izi iyileşir, çünkü her okuma, istemler arasında kopyalanan metin olarak değil, bir API çağrısı olarak görünür.
Tek bir şey gerektirir: her ajan, doğru izinlerle aynı API'ye ulaşabilir. Bu ücretsiz değildir. Her ajan, yaptığı işe göre kendi kimlik bilgilerine ihtiyaç duyar, bu da ajanlar için en az ayrıcalıklı API anahtarları konulu yazımızdaki argümandır. Salt okunur bir araştırma belirtecine sahip bir faturalandırma ajanı iade yapamaz ve faturalandırma belirtecine sahip bir araştırma ajanı bir patlama yarıçapı sorunudur.
Yeniden getirme pahalı veya yavaş olacaksa, kaydı orkestratörünüzde önbelleğe alın ve önbellek girişine bir referans iletin. Alıcı ajan veriyi yine de açıkça ister, bu nedenle desen aynı kalır, ancak ikinci okuma ucuzdur.
Devir teslimlerinin gerçekten bozulduğu yerler
Dört hata çoğu olayı kapsar.
Düşürülen tanımlayıcı. Özet "müşteri" der ve hiçbir zaman bir kimlik vermez, bu nedenle ikinci ajan ada göre arama yapar, iki eşleşme bulur ve yanlış olanı seçer. Zorunlu varlık kimliklerinin devir tesliminin ilerlemesine izin verilmeden önce mevcut olduğunu doğrulayarak bunu önleyin.
Tekrarlanan eylem. İlk ajan e-postayı zaten gönderdi. Devir teslimi bunu kaydetmiyor. İkinci ajan onu tekrar gönderiyor. actions_taken'ı devir teslim nesnesine kaydedin ve herhangi bir yazmadan önce kontrol edin, bir tekrarı zararsız kılan idempotinans anahtarlarıyla desteklenir.
Kayıp onay. İlk ajan çalışırken bir insan iadeyi onayladı. İkinci ajan, bunu bilmeden tekrar sorar. Kullanıcılar ikinci istemi dinlemeyen bir sistem olarak okur. Onayları açık kısıtlamalar olarak taşıyın ve bunları ajana değil, göreve göre kapsamlı olarak ele alın.
Kendinden emin icat. Alıcı ajan, devir tesliminin taşımadığı bir değere ihtiyaç duyar ve sormak yerine, anlatıya uyan bir değer uydurur. Bu, tamamlanmış bir görev gibi göründüğü için en tehlikeli hatadır. Savunma, open_questions alanı ve alıcı ajanın isteminde katı bir kuraldır: gerekli bir tanımlayıcı eksikse, dur ve sor.
Döngüler dördünü de daha kötü hale getirir. A ajanı B'ye devrettiğinde ve B tekrar A'ya devrettiğinde, her geçişte durum bozulur, fotokopinin fotokopisi gibi. Atlama sayısını sınırlayın ve her birinde orijinal görev nesnesini yeniden oluşturmak yerine taşıyın.
Sadece ajanları değil, sınırı da test edin
Devir teslimleri entegrasyon noktalarıdır, bu nedenle onları entegrasyon noktaları olarak test edin.
Devir teslim nesnesini doğrulayın. İlk ajanı sabit bir senaryoya karşı çalıştırın ve ürettiği nesneyi kontrol edin: gerekli tanımlayıcılar mevcut mu, kararlar kaydedilmiş mi, eylemler listelenmiş mi? Bu, onu üreten ajanın deterministik olmamasına rağmen yapılandırılmış bir yük üzerinde deterministik bir doğrulamadır, bu da onu kullanılabilir bir test yapar. Genel yaklaşım, deterministik olmayan yapay zeka ajanlarını test etme kılavuzumuzda yer almaktadır.
Alıcıyı izole olarak test edin. Faturalandırma ajanına el yapımı bir devir teslim nesnesi verin ve ne yaptığını kontrol edin. Ardından kasıtlı olarak bozuk bir tane, müşteri kimliği kaldırılmış olarak verin ve tahmin etmek yerine sorduğunu onaylayın. Bu ikinci test, icatları yakalayan testtir.
Her ikisini de sahte nesnelere karşı çalıştırın. Gerçek iadeler yapan bir devir teslim testi, bir kez çalıştıracağınız bir testtir. ajanları üretim yerine sahte API'lere karşı çalıştırma konulu yazımızı takip ederek, paketin her değişikliğinde çalışabilmesi için her iki ajanı da sahte uç noktalara yönlendirin. Apidog'da sahte nesneler, her iki ajanın da çağırdığı aynı API tanımından gelir, bu nedenle ikisi asla birbirinden sapmaz.
Her devir teslimini günlüğe kaydedin. Her sınırda, görev kimliğiyle birlikte tam nesneyi kaydedin. Çoklu ajan çalışması yanlış gittiğinde, devir teslim günlüğü size hangi ajanın bilgiye sahip olduğunu ve hangisinin onu kaybettiğini söyler, ki bu genellikle tüm araştırmadır. Ajan araç çağrılarını izleme konulu yazımız, bu kayıtta başka nelerin yer alması gerektiğini kapsar.
Çerçevelerin size sundukları
Çoğu orkestrasyon çerçevesi bir devir teslim ilkelini gönderir ve ona güvenmeden önce her birinin sınır boyunca neyi gerçekten hareket ettirdiğini bilmek faydalıdır.
OpenAI Agents SDK devir teslim dokümantasyonu, bir devir teslimini ajanın çağırabileceği bir araç olarak modeller, bu da kontrolün ne zaman aktarılacağına modelin karar verdiği anlamına gelir. Bu uygundur ve kararı sisteminizin en az deterministik kısmına bırakır, bu yüzden çıkış yolunda doğrulama ile eşleştirin.
LangGraph'ın çoklu ajan rehberliği tam tersi bir yaklaşım benimser: durum, her düğümün okuyup yazdığı açık bir grafik nesnesidir. Bu, yukarıda açıklanan yapılandırılmış devir teslimine yakından eşleşir ve size kalan ana iş, hangi alanların gerekli olduğuna karar vermektir.
Anthropic'in çoklu ajan araştırma sistemi oluşturma üzerine yazdığı yazı, operasyonel ayrıntılar, özellikle bir alt ajanın kendi başına faydalı bir şekilde çalışabilmesi için ne kadar talimata ihtiyacı olduğu hakkında okunmaya değerdir.
Ortak nokta: her çerçeve bir şeyler taşıyacaktır. Hiçbiri, hangi gerçeklerin yük taşıyıcı olduğuna sizin için karar vermez. Bu liste sizin yazmanız gereken listedir ve bir çalışma yanlış gittiğinde gözden geçirmeye değer olan şey budur.
Görev nesnesini konuşmanın dışında tutun
Tek bir yapısal değişiklik, tüm bir hata ailesini önler. Görev durumunu, görev kimliğiyle anahtarlı olarak kalıcı bir yerde saklayın ve her ajanın mesajlar aracılığıyla aktarmak yerine onu okumasını ve yazmasını sağlayın.
Konuşma, durum için kötü bir kapsayıcıdır. Özetleme ile sıkıştırılır, kısaltılır ve yeniden yazılır ve bu işlemlerin hiçbiri kaybetmeyi göze alamayacağınız alanları bilmez. Bir veritabanındaki bir satırın böyle bir sorunu yoktur.
Desen küçüktür. Bir turun başlangıcında, ajan görev nesnesini yükler. Bir eylem gerçekleştirdiğinde, actions_taken'a ekler ve kaydeder. Devir tesliminde, görev kimliğini aktarır ve alıcı ajan aynı nesneyi yükler. Önemli hiçbir şey istemde hareket etmez, bu nedenle önemli hiçbir şey özetlenerek kaybolamaz.
Bu aynı zamanda size bir kaldığı yerden devam etme noktası da verir. Eğer bir çalışma dördüncü adımda ölürse, görev nesnesi ilk üç adımın oluşturduğu her şeyi hala tutar ve yeniden deneme sıfırdan değil, oradan başlar.
Platformun durumu tutabileceği yer
Ajanlarınız geliştirici makinelerinde CLI çalışma zamanları olarak çalışıyorsa, yukarıda açıklanan kalıcı görev nesnesi sizin inşa ettiğiniz bir şeydir. Bazı ajan iş yönetimi platformları bunu zaten modeller ve kendi çözümünüzü yazmadan önce neye benzediğini bilmek değerlidir.
Sharkly, insanlar ve ajanlar için tam da bu birim etrafında inşa edilmiş bir iş yönetimi sistemidir. Bir Görev, hedefi, durumu, sorumlu kişiyi, onu yürütecek Ajanı veya Ekibi, yorumları ve ajanın yürütme durumunu ve sonucunu taşır. Bir Ekip, bir lider Ajanı diğer Ajanlar ve insanlarla eşleştirir, böylece birkaç uzmana ihtiyaç duyan bir görev, istemler aracılığıyla elden ele geçirilmek yerine yeniden kullanılabilir bir gruba atanır. Durum, konuşmada değil Görevde yaşadığı için, iki ajan arasındaki bir devir teslimi, birinin iyi özetlemesine bağlı değildir.
Çalışma zamanları, halihazırda kullandığınız ne olursa olsun aynı kalır. Claude Code, Codex ve diğerleri işi kaydettiğiniz bir Bilgisayarda yürütür; platform görev kaydını, atamayı ve onlar etrafındaki inceleme döngüsünü sağlar. Kalıcı görev modelini kendiniz inşa ediyorsanız, Sharkly dokümantasyonu hangi alanların önemli olduğu konusunda yararlı bir referanstır.
Devir teslimleri için kontrol listesi
- Devir teslimi için tanımlanmış bir şema mevcuttur ve sınırda doğrulanır.
- Varlık tanımlayıcıları isteğe bağlı değil, gerekli alanlardır.
- Kararlar gerekçelerini taşır, böylece alıcı mantığı yeniden düşünmez.
- Halihazırda yapılmış eylemler kaydedilir ve herhangi bir yazmadan önce kontrol edilir.
- Onaylar ve bütçeler ajanla değil, görevle birlikte seyahat eder.
- Açık sorular açıktır ve alıcı varsaymak yerine sorar.
- Yeniden getirmenin ucuz olduğu durumlarda veriler referans yoluyla aktarılır.
- Atlama sayısı sınırlandırılmıştır ve orijinal görev nesnesi her atlamadan sağ çıkar.
- Her devir teslimi görev kimliği ile günlüğe kaydedilir.
- Sınır testleri, kasıtlı olarak eksik bir devir teslimi de dahil olmak üzere sahte nesnelere karşı CI'da çalışır.
Çoğu çoklu ajan hatası mantık hataları değildir. Bunlar, bir ajanda var olan ancak diğerinde olmayan bir gerçektir. Sınırı, bir şema ve testlerle bir arayüz olarak tasarlayın ve ikinci ajan, birincisinin zaten cevapladığı soruları sormayı bırakır. Her iki ajanın da bağlı olduğu API'nin yanında sahte nesneleri ve sınır testlerini tutmak için Apidog'u indirin.
Sıkça sorulan sorular
Yapılandırılmış bir devir teslimi iki ajan için değer mi? Kısa bir görevde iki ajan için, konuşmayı aktarmak genellikle yeterlidir. Yapılandırılmış nesne, üç veya daha fazla ajanda, uzun görevlerde veya bir devir tesliminin bir süreci veya çalışma sınırını geçtiği her yerde değerini kanıtlar.
Model mi devir teslim nesnesini yazmalı yoksa kod mu oluşturmalı? Mümkünse kod. Tanımlayıcılar, yapılan eylemler ve onaylar, modelin hatırladıklarından değil, gerçekten olanlardan orkestratörünüz tarafından doldurulmalıdır. Modelin yalnızca summary ve açık soruları yazmasına izin verin.
Bir döngüdeki bağlam bozulmasını nasıl durdururum? Her sınırda yeniden oluşturmak yerine, tüm çalışma boyunca tek bir görev nesnesini taşıyın ve güncelleyin. Sonra atlamaları sınırlayın. Eğer bir görev birkaçdan fazlasına ihtiyaç duyuyorsa, ayrıştırma muhtemelen yanlıştır.
Yerleşik devir teslim desteği olan çerçeveler ne olacak? Onları kullanın ve gerçekten ne aktardıklarını kontrol edin. Birçoğu mesaj geçmişini ve başka hiçbir şeyi aktarmaz, bu da tanımlayıcıların ancak metinde görünmesi durumunda hayatta kalacağı anlamına gelir. Çerçevenin taşıdığı her ne olursa olsun, yanına yapılandırılmış bir yük ekleyin.
Alt ajanların ayrı API kimlik bilgilerine ihtiyacı var mı? Evet, her birinin yaptığı işe göre kapsamlı. Ajanlar arasında tek bir güçlü anahtarı paylaşmak, hasarı sınırlama ve hangi ajanın çağrı yaptığını anlama yeteneğinizi ortadan kaldırır. Ajanlar için en az ayrıcalıklı API anahtarları konulu yazımız kurulumu kapsar.
Özet alanı ne kadar içermeli? Birkaç cümle, yapılandırılmış alanların tutamayacağı niyet ve nüansı kapsayacak şekilde. Eğer kimlikleri ve miktarları listelemeye başlarsa, bunlar doğrulanabilecekleri yapılandırılmış alanlara aittir.