Skip to main content
Kendiniz yazdığınız bir aracı veya Failproof AI’nin adaptörü olmayan bir çerçeve için. Enstrümante edilecek bir şey yoktur: olayları siz yayınlarsınız. Bu, dört çerçeve adaptörünün altında çağırdığı API’dir. Bunlar onun üzerinde çeviri tablolarıdır.

Yükleme

Ek paket yok, bağımlılık yok.

Enstrümantasyon

Baştan sona okuyun, söylediği şey budur: Ve her biri aslında neyi yayınlar: İçindeki her şey session_id ve agent_id atlamabilir. Kapsamlar kimliği bağlam değişkenlerine bağlar ve her olay çağrısı onu geri okur, bu yüzden kimlikler hiçbir zaman işlevler aracılığıyla iletilmez. Üçü de async with ve with altında çalışır. Aracıları iç içe yerleştirmek ağacı oluşturur. parent_id ve derinlik yığından hesaplanır:

Bir kapsam nasıl kapanır

agent() istisnaları sizin için işler: Hata agent_end öncesinde yayınlanır, çünkü gösterge paneli yayını agent_end konumunda kapatır ve bundan sonra gelen her şey hiçbir şeye atfedilir. İptal bir hata değildir, bu nedenle iptal edilen çalışmalar hata yüzeyini kirletmez. İstisna her zaman yeniden yükseltilir: bir kapsam asla yutmaz.

Olay yöntemleri

On beş yöntem altı ailededir. Çoğu çiftler halinde gelir — açan yayını yayınlarsınız, sonra kapatanı yayınlarsınız ve SDK aralarındaki yayını ölçer.
Kapsamları tercih edin — agent() ve tool_call() — uygun oldukları yerlerde. Gövde yükseltirse bile kapanan olayı garantilerler. İçerik akışınız iç içe olmadığında doğrudan bu yöntemlere ulaşın; örneğin yardımcı içinde bir model çağrısı.
İki insan ailesi zıt yönleri gösterir.Hiçbir çerçeve ikinci çifti sinyal vermez, bu yüzden her zaman siz yayınlarsınız.
Model çağrıları eşzamanlı olarak çalıştığında request_id geçirin. Olmadan, istekler ve yanıtlar ajan başına varış sırasına göre eşleşir — ve eşzamanlı çağrılar yanlış eşleşir, her yanıtı yanlış isteğe iliştirir.

Örnek

OpenAI API’sine karşı araç çağırma döngüsü, ajan çerçevesi olmadan:
Bu, bir adaptörün size vereceği altı olay türünü üretir. Tam çalıştırılabilir sürüm, araç tanımlarıyla birlikte, SDK deposunda docs/manual/examples/ altında bulunur.

İş parçacıkları ve async

Bağlam değişkenleri asyncio görevlerine otomatik olarak yayılır. Bir iş parçacığı boş bir bağlamla başladığı için yeni iş parçacıklarına yayılmaz.
propagate() olmadan, worker’ın olayları düzeltmeyi adlandıran bir TypeError yükseltir, bu da hiçbir oturuma gitmez. Bu kasıtlıdır: oturumu olmayan bir olay ingest tarafından atlanır ve 200 ile yanıtlanır, bu da kimlik katmanının önlemesi amaçladığı sessiz başarısızdır.

Adaptörü olmayan bir çerçeveyi enstrümante edin

Her ajan çerçevesi aynı üç bağlantı noktası sağlar. Onları harita yapın ve tam bir izlemeniz vardır — sevk edilen dört adaptör bundan fazla bir şey yapmaz.
1

Çalışmayı köşeli ayraç içine alın

2

Her aracı köşeli ayraç içine alın

Çerçevenin araç sarıcısı veya ara yazılım olarak adlandırdığı her şeyde.
3

Her model çağrısını eşleştirin

Görmeye değer bir düğüm, adım veya ara yazılım sınırı var mı? Bunu iç içe bir agent() değil, kancanın içine sarın — hook_triggered / hook_completed. agent_id düşük kardinalite yönüdür ve düğüm başına bir giriş onu boğar. Kancanın yayını aynı şekilde işlenir ve düğüm başına gecikme süresi sağlar.
Manuel ve otomatik oluşturma. El yazısı bir kapsam içinde çalışan bir adaptör bu oturuma katılır ve bu aracıya ebeveyn olur, bu nedenle iki tane yerine bir ağaç alırsınız — desteklenen bir tarafı kendiniz enstrümante ederken bir çerçeveyi yan yana kullanışlı olduğunda.
İki neden vardır ve yukarıdaki üç bağlantı noktası her ikisine de cevaptır:
  • autogen-core Eylül 2025’ten beri bakımsız olmuştur.
  • AG2, diğer çerçevelerin kancanlarına eşdeğer hiçbir işlem açısından kayıt noktası açığa çıkarmaz, bu nedenle enstrümantasyonu her inşaat alanında her aracıyı sararak anlamına gelir.
Bağlantı noktalarını elle harita yaparak, sevk edilen bir adaptörün yaptığı aynı fidelitede aynı olayları kaydeder.

Daha derine gitme

Kaydın aslında nasıl çalıştığı. Başlamak için buna ihtiyaç yoktur.
Her kaydın aynı şekli vardır: bir yay açılır, iş içinde iç içe geçer ve her açma olayı kapatma olayı alır.Çift birimdir. Her kapatma olayı SDK’nın açma olayından ölçtüğü bir süre taşır.Aşağıda SDK ile sevk edilen örneklerden yakalanan çerçeve başına bir gerçek çalışma vardır — model adı normalleştirilmiştir. Tek bir çağrıdan ne kadar döndüğüne dikkat edin.
14 olay
Düğümler kancanın çiftleri olur, bu nedenle onları kalabalık yapmadan düğüm başına gecikme süresi alırsınız.
Oturum sonu olayı yoktur. Oturum kapattığınız bir şey değil — session_id paylaşan bir olay grubudur.Durum izlemenin şeklinden türetilir:Yani bir oturum her çift kapatıldığında biter. Adaptörler sizin için agent_end yayınlar ve kapalı kaldığında açık kalan her şeyi kapatırlar ve eksik olarak işaretlerler — çökmüş bir çalışma asılı kalmak yerine görünür bir boşlukla done olarak yerleşir.
Bu yüzden bir oturum iki çağrıya yayılabilir. Bir LangGraph interrupt() çalışmayı duraklatır, kök yayı kasıtlı olarak açık kalır ve devam eden çağrı onu kapatır. Her iki çağrı bir oturuma aittir.
session_id ve agent_id her olay yönteminde isteğe bağlıdır. Atlanırsa, çevreleyen kapsamdan çözülürler:
Bunları açıkça iletmek yine de işe yarar ve önceliği alır. Hiçbir şey bağlı değil ve hiçbir şey iletilmezse, çağrı düzeltmeyi adlandıran bir TypeError yükseltir, ingest atlamış olacağı oturumu olmayan bir olayı yayınlamak yerine, 200 ile yanıtlar.Kapsamlar kimliği bağlam değişkenlerine bağlar. Bunlar asyncio görevlerine otomatik olarak yayılır ancak yeni iş parçacıklarına yayılmaz — bir worker’ı failproofai_sdk.propagate() içine sarın.

Hangi kimlik kim tarafından basım yapılır

Adaptörler session_id nasıl çözer

İlk eşleşme kazanır:
  1. Açık bir session_id seçeneği
  2. Çağrı başına meta veri
  3. Çevreleyen session() kapsamı
  4. Çerçeve meta verileri
  5. Çerçevenin kendi çalışma kimliği
Bunlardan biri vardığı sürece asla icat edilmez — sentezlenmiş bir kimlik bir çalışmayı birkaç oturuma böler.

agent_id düşük kardinaliteyi koruyun

Bu her gösterge paneli yüzeyinde birincil yönüdür ve LowCardinality(String) sütunu. Çalışma başına bir değer sütunu düşürür ve filtre açılır menüsünü çalışma başına bir giriş ile doldurur.Adaptörler bu sütunu sizin için savunur:Gerçek kimlik fw_agent_id / fw_run_id üzerinde tutulur, burada yönü olmuş bir yüzey olmadan sorgulanabilir kalır.
Bu koruma yalnızca çerçevenin seçtiği etiketlere dokunur. Kendiniz ilettiğiniz bir agent_idevent.* veya failproofai_sdk.agent(...) için — tam olarak verilen şekilde kaydedilir. Açık bir bağımsız değişkeni sessizce yeniden yazmak, kardinalieti önledikten daha kötü olur, bu yüzden kendi yaylarınızı buna göre adlandırın.
Hangi çerçeve neyi kaydeder, yukarıdaki çalışmalardan ölçülen:Tire, çerçevenin böyle bir kavramı olmadığı anlamına gelir. human_pause ve human_interrupt, aracıya etkide bulunan bir kişiyi tanımlar, hiçbir çerçeve sinyal vermez — bunları kendiniz yayınlayın.
Bir olay asla yalnız gelmez. Biri bir yayı açar, biri onu kapatır ve kapatma olayı SDK’nın açma olayından ölçtüğü bir süre taşır.
Kapatma olayı olmayan açma olayı hiçbir zaman bitmez bir yaydır. Oturum sonsuza dek çalışıyor olarak işlenir ve etkin süresi büyümeye devam eder. Bu, el ile enstrümante ederken izlenecek hata modudur.

Korelasyon kuralları

  • Eşleşen tamamlama olayı için aynı tool_call_id, hook_id, pause_id veya input_id yeniden kullanın.
  • SDK tool_result, hook_completed, agent_resume ve human_input için duration_ms hesaplar. Bunları iletmek ValueError yükseltir.
  • duration_ms kabul edilir model_response üzerinde, çünkü yalnızca arayan gerçek sağlayıcı gecikmesini bilir. Bir tamsayı olmalı — bir kayan sayı çağrı sitesinde ValueError yükseltir, sunucu sütunu işaretsiz 32 bitlik bir tamsayı olarak okur ve başka bir şey için NULL depolar.
  • Korelasyon anahtarları tür ve oturum kapsamındadır, böylece bir araç çağrısı ve kancanın kimliği güvenle paylaşabilir ve iki eşzamanlı oturum kimlikler yeniden kullanabilir çarpışma olmadan. Agent kapsamında değil: bir ajan altında açılan ve diğeri altında kapatılan bir çift yine de ilişkilendirilir, bu multi-ajan çerçevelerdeki sıradan durumdur.
  • request_id model_request model_response ile eşleştirir. Olmadan, model olayları ajan başına sırada eşleşir, bu nedenle eşzamanlı çağrılar yanlış eşleşir.
  • İşlemler arasında bölünmüş bir çift yine de aşağı doğru ilişkilendirilir, ancak SDK işlem içi süresini hesaplayamaz.
  • Bekleyen harita en fazla 10.000 başlangıç tutar ve dolu olduğunda en eski giriş tahliye eder.
failproofai-sdk kurmak her şeyi, dört adaptör dahil olmak üzere yükler. Ekstralar adaptörü değil, çerçeveyi çeker.
import failproofai_sdk sözleşmeli olarak sıfır bağımlılıktır, yerleşik tekerleği --no-deps ile kuran ve hiçbir çerçevenin sys.modules erişmemesini kanıtlayan başka bir test tarafından uygulanır.
failproofai_sdk.crewai niteliği yoktur. Adaptörler kasıtlı olarak en üst düzey pakette açığa çıkarılmaz: birini değmek, öznitelik erişiminin yan etkisi olarak çerçeveyi içe aktarır, sıfır bağımlılık vaadini kırarak. instrument() kullanın.
Otomatik algılama sys.modules okur, yüklü paket listesi değil, bu nedenle kurmuş ancak asla içe aktarmadığınız bir çerçeve enstrümente edilmez ve asla sizin adınıza içe aktarılmaz. Neyin bağlı olduğunu görmek için:
CrewAI olmayan bir makinede instrument("crewai") yükseltmez. Bir uyarı kaydeder ve () döndürür, bu nedenle bir eksik çerçeve diğerlerini de enstrümante eden bir işlemi asla alır.Uyarı temel ImportError taşır ve bu ileti tam kurulum komutu adlandırır — düzeltme günlüklerde gizli değildir.
Bunun yerine yükseltmesini sağlamak için FAILPROOFAI_SDK_STRICT=1 ayarlayın. Bu bayrak bir kez okunur ve önbelleğe alınır, bu yüzden işleminiz başlamadan önce bunu dışa aktarın, çalışma sırasında ayarlamak yerine.
instrument() çerçeve ithalinizin sonra gelmeli. Otomatik algılama sys.modules okur, bu yüzden içeri aktarmanın üstünde açık bir çağrı hiçbir şey bulmaz, hiçbir şey yüklemez ve () döndürür.
Bunu yanlış yapın ve işlem SDK’yı içe aktarılmış, adaptör görünüşte yüklenmiş ve tek bir olayı yayınla olmayan ile çalışır. Bu tam olarak söyleyen bir uyarı kaydeder — çalışma hiçbir şey kaydedildiğinde loglarınızı ilk kontrol edin.
Makara bunu güvenli yapar: ajanız hiçbir zaman ağda bloke olmaz ve Bulut kesintisi, kayıp olaylar yerine büyüyen bir dizin anlamına gelir.Her temizleme bir toplu dosya yazar, .tmp ilk, sonra fsync, sonra atomik yeniden adlandır:
Daemon yalnızca .jsonl alır, bu nedenle asla yarı yazılı dosya okuyamaz. Gövde zaman damgası, işlem kimliği ve sıra numarası taşır, bu nedenle iki işlem aynı milisaniyede temizlenirse çarpışamaz. Kuyruk 10.000 olayda sınırlıdır; bunun ötesinde en eskisini bırakır ve kaydeder.
collector.redact SDK olaylarınıza uygulanmaz. Asla onları görmez.
Daemon gönderir topluları. Açmaz veya yeniden yazmaları yapmaz.Redaksiyon daemon’un kendi olaylarını yazdığı yerde çalışır — topluların sevk edildiği yerde değil. Bu yüzden bir istemi veya bir API anahtarı tutan araç bağımsız değişkeni varışta tutmaya devam eder.Bu kasıtlıdır. Bunlar kendi enstrümantasyon çağrılarınızdır ve bunları aktarım sırasında yeniden yazmak, aldığınız olayların yayınladığınız olaylar olmadığı anlamına gelir.
Yüklemeleri kaynakta kontrol edersiniz, iki yerde:
  • Adaptörde içerik yakalamayı kapatın. Seçenek adı farklıdır ve bir adaptörün hiçbiri yoktur — bu tek evrensel anahtar değildir:
    • LangChain / LangGraph, Pydantic AI — capture_content=False
    • LlamaIndex — capture_messages=False
    • CrewAI — içerik anahtarı hiç yoktur; session_id okuduğu tek seçenektir, bu yüzden istekler ve tamamlamalar her zaman kaydedilir.
    instrument() bir adaptörün okumuyor olduğu seçenekleri bırakır, bu nedenle yanlış adı iletmek hiçbir şey yükseltmez ve hiçbir şey değiştirmez.
  • Sırrı ilk yerde input= tutmayın.
collector.redact ikisi için bir yedek değil.
Boş bir makara dizini sağlıklı durumdur. Teslimi kontrol etmek için kullanmayın.
Daemon her topluyu gönderdikten sonra milisaniyeler içinde siler, bu yüzden ls toplayıcıyı yarışır ve yayınladığınız kesirini gösterir — hiçbir şey kaydeden bir SDK’dan ayırt edilemez.Olayların gerçekten iniş yaptığını doğrulamak için gösterge panelini kontrol edin. Makarayı dolmaya karşı izlemek için daemon’u ilk durdurun.
Her geri çağrı, tek işi yeniden yükseltmek olan bir sarıcı içinde çalışır, bu nedenle çağrınız tam olarak bir try içinde oturur ve SDK’nın yaptığı her şey bunun dışında olur.Varsayılan, üretimde doğru ve hata ayıklarken yanlıştır, çünkü yalnızca hiçbir zaman çökmediğini kanıtlayabilir. Yutkunmuş bir başarısızlığı yüksek sesle yapmak için FAILPROOFAI_SDK_STRICT=1 ayarlayın.

Yaygın sorunlar

Açma olayı kapatma olayı olmaz: model_response olmayan model_request veya tool_result olmayan tool_use. Kapsamları kullanın, gövde yükseltirse bile çifti garanti ederler. Olay yöntemlerini doğrudan çağrırsanız, try ve finally kullanın.
Eşleşen açma olayından ölçüldüğü için tool_result, hook_completed, agent_resume ve human_input üzerinde reddedilir. model_response üzerinde kabul edilir, çünkü yalnızca siz gerçek sağlayıcı gecikmesini bilirsiniz ve bir tamsayı olmalı.
İş parçacığı asla bağlamı devralması olmadı. Çağrıyı failproofai_sdk.propagate() içine sarın. Bkz. İş parçacıkları ve async.
Ekstra alanlar son olarak birleşir, bu nedenle model veya outcome gibi gerçek alana benzer bir ad, onu yeniden yazar ve depolanmış sütunu değiştirir. Sizinkini ad alanı yapın; adaptörler bir fw_ ön eki kullanır.
agent_id düşük kardinalite yönüdür ve bir çalışma kimliğini içine koydunuz. Rol veya düğüm adı kullanın ve gerçek kimliği yayın alanına koyun.

Sonraki

Nasıl çalışır

Çiftler, kimlikler, oturum yaşam döngüsü ve teslim.

İzmeyi oku

Az önce yakaladığınız oturum aracılığıyla nedenselliği takip edin.

Çerçeve adaptörleri

LangGraph, CrewAI, LlamaIndex ve Pydantic AI.