Özel aracılar rehberi
Kurulum, enstrümantasyon, olay metodları, pratik örnek ve yaygın sorunlar.
Framework kullanıyor musunuz?
LangChain, CrewAI, LlamaIndex ve Pydantic AI kendilerini tek çağrı ile enstrümante ederler.
Kurulum
failproofai-sdk olarak yüklenir ve Python’da failproofai_sdk olarak içe aktarılır. failproofai-sdk[langgraph] gibi framework ek paketleri framework’ü kendisini yükler; adaptörler her zaman temel wheel’de bulunur.
Failproof daemon’ını bağlayın
- Gösterge Paneli
- CLI
-
Admin → Keys bölümüne gidin ve
events:addile bir anahtar oluşturun. - Failproof daemon’ını Cloud’a bağlayın ajan makinesinde.
- Bir enstrümante edilmiş oturum çalıştırın, sonra Observe → Events altında tam ID’sini bulun.
-
Observe → Sessions bölümüne gidin, aynı ortamı seçin ve yeniden oluşturulan iz’i açın.
Konfigürasyon
Bunun yerine ortam değişkeni tarafından ayarlayın:
Olaylar bellekte sıraya alınır ve arka planda her
flush_interval saniyede diske yazılır; yorumlayıcı çıkışında son bir flush yapılır. Doğrudan öldürülen bir işlem henüz yazılmış olmayan her şeyi kaybeder.
Kimlik
Her olay bir oturum ve bir ajanına aittir. Kapsamlar her ikisini de doldurur, bu nedenle nadiren bunları geçersiniz:session_id veya agent_id’yi açıkça geçmek hala çalışır ve kazanır. Bağlı ne de geçilmiş olmadan, çağrı Cloud’un sessizce atılacağı bir olayı yayınlamak yerine TypeError yükseltir.
Kimlik bağlam değişkenlerinde durur.
asyncio görevlerini otomatik olarak takip eder, ancak yeni iş parçacıklarını değil — bir işçiyi failproofai_sdk.propagate() içine sarın veya olayları bağlantısız kalırlar.Olay kataloğu
On beş metod. Çoğu çiftler halinde gelir — açanı çağırırısınız, sonra kapatıcısını, ve SDK açıklığı ölçer.
Üçü bağımsız:
error, human_pause, human_interrupt.
Her alan, her metod başına
Her alan, her metod başına
Her metod ayrıca
session_id ve agent_id alır, kapsamlar bunları sizin için doldurur. None olarak bırakılan her şey JSON null olarak gönderilmek yerine atılır ve her metod None döndürür.Eşleştirme ve süre
Bir kural: kapatıcı olayına açıcısı ile aynı id’yi verin. Bunun ne eşleştirdikleri ne de SDK’nın boşluğu zamanlamasını sağlayan şeydir.
Kendiniz
duration_ms geçmeyin. SDK onu ölçer ve geçmesi ValueError yükseltir.
Tek istisna model_response’tir, burada yalnızca siz gerçek sağlayıcı gecikmesini bilirsiniz. Tam bir milisaniye sayısı geçin — kayan sayı yükseltir, çünkü sütun 32-bit bir tamsayıdır ve aksi takdirde boş kalırdı.
Kenar durumları
Kenar durumları
- ID’ler yalnızca tür başına, oturum başına benzersiz olması gerekir. Bir araç çağrısı ve bir kanca bir taneyi paylaşabilir; aynı anda çalışan iki oturum çarpışma olmadan aynı ID’leri yeniden kullanabilir.
- Onlar bir ajanın kapsamında değildir. Bir çift bir ajan altında açılıp başka bir ajan altında kapatılırsa yine eşleşir — bu, çok ajanın kodunda normal durumdur.
request_idisteğe bağlıdır ancak önerilir. Olmadan, model olayları gelişte sıraya alınırlar, bu nedenle aynı ajan içindeki iki eşzamanlı çağrı hatalı eşleşebilir.- İşlemler arasında bölünmüş bir çift Cloud’da yine eşleşir, ancak SDK onu zamanlamaz — hiçbir işlem her iki yarıyı da görmedi.
- En fazla 10.000 açıcı aynı anda kapatıcıyı bekler. Bunun ötesinde en eski atılır, böylece bir sızıntı sınırsızca büyüyemez.
Kendi alanlarınız
Geçtiğiniz herhangi bir ekstra anahtar sözcük olayda depolanır:Decimal, küme, bayt, bir model nesnesi — bir dizi olarak depolanır.
Bu beş ad ayrılmıştır ve tamamen reddedilir: timestamp, session_id, agent_id, type, environment.
Teslimat ve doğrulama
- Gösterge Paneli
- CLI
Observe → Events bölümünde önce
agent_start var mı kontrol edin ve agent_end sonunda var mı. Sonra Observe → Sessions bölümünü açın ve model, araç, insan, kanca ve hata olaylarının amaçlanan sırada göründüğünü doğrulayın. Oturum ID’sini birincil sorun giderme anahtarı olarak kullanın.$FAILPROOFAI_HOME/custom-agents/events bölümünü inceleyin, aksi takdirde ~/.failproofai/custom-agents/events bölümünü inceleyin. JSONL dosyaları SDK yayınını kanıtlar; büyüyen bir spool daemon konfigürasyonunu veya teslimatı gösterirken boş bir spool enstrümantasyonu veya süreç ömrünü gösterir.
Spool’u yalnızca daemon durdurulmuş durumdayken inceleyin. Çalışırken, her topluyu milisaniye cinsinden toplar ve siler, bu nedenle bir dizin listesi toplayıcıyla yarışır ve yayınlanan etkinliklerden çok daha azını gösterir.