Özel ajanlar

Her ayarın, metodun ve alanın ne yaptığı. İlk kez enstrüman ediyorsanız, kılavuzla başlayın — bu sayfa şeyler aramak içindir.

Özel ajanlar kılavuzu

Kurun, enstrüman edin, olay metodları, işlenmiş bir örnek ve yaygın sorunlar.

Bir framework kullanıyor musunuz?

LangChain, CrewAI, LlamaIndex ve Pydantic AI kendilerini tek bir çağrıyla enstrüman ederler.

Python 3.10 veya daha yeni. Çalışma zamanı bağımlılığı yok.

Kurun

pip install failproofai-sdk

Paket failproofai-sdk olarak yüklenir ve Python’da failproofai_sdk olarak içe aktarılır. failproofai-sdk[langgraph] gibi framework ekstraları, framework’ün kendisini kurar; adaptörler her zaman temel wheel’de gönderilir.

Failproof daemon’ını bağlayın

Gösterge Paneli
CLI

Admin → Keys’e gidin ve events:add ile bir anahtar oluşturun.
Failproof daemon’ını Cloud’a bağlayın ajan makinesinde.
Bir enstrümantalı oturumu çalıştırın, ardından Observe → Events altında tam kimliğini bulun.
Observe → Sessions’a gidin, aynı ortamı seçin ve yeniden oluşturulmuş izlemeyi açın.

failproofai config \
  --connect https://app.befailproof.ai \
  --token <events-add-key>
failproofai config --status

Konfigürasyon

import failproofai_sdk

failproofai_sdk.configure(
    base_dir=None,
    flush_interval=0.5,
    environment="production",
)

Bağımsız Değişken	Ne yapar
`environment`	Her olay üzerindeki etiket — `production`, `staging`, `prod-eu`. Varsayılan olarak `dev`’dir.
`flush_interval`	Arka plan thread’inin diske yazma sıklığı, saniye cinsinden. Varsayılan olarak `0.5`’tir.
`base_dir`	Nereye yazılacağı. Varsayılan olarak daemon’ın spool’udur, aksi takdirde bilmediğiniz müddetçe istediğiniz şeydir.

Bunun yerine ortam değişkeni tarafından ayarlayın:

Değişken	Ne yapar
`AGENTEYE_ENVIRONMENT`	Kod değişikliği olmadan `environment`’ı ayarlar, etiketin uygulamaya değil dağıtıma ait olduğu durumlarda. Bir `configure()` bağımsız değişkeni bunu geçersiz kılar.
`FAILPROOFAI_HOME`	Spool’u tutan Failproof AI köküne taşır.
`FAILPROOFAI_SDK_STRICT`	`1`, enstrümantasyon hatalarının günlüğe kaydedilmesi yerine yükseltilmesine neden olur.
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1`, bir framework uyumluluk sorununun devam etmek ve uyarı vermek yerine yükseltilmesine neden olur.

environment’da virgül yok. İşlem bu alanı filtrelerini oluşturmak için virgülde böler ve bir tane içeren herhangi bir olayı atlar — tüm çalıştırma sessizce kaybolur. prod,eu değil prod-eu yazın.configure(environment="prod,eu") hemen öğrenmeniz için yükseltir. AGENTEYE_ENVIRONMENT yükseltemez — hiç kimse sizi aramıyor — bu nedenle bir kez uyarı verir ve dev’e geri döner.

Olaylar bellekte sıralanır ve arka planda her flush_interval saniyede yazılır; yorumlayıcı çıkışında son bir temizlik yapılır. Doğrudan öldürülen bir işlem henüz yazılmamış her şeyi kaybeder.

Kimlik

Her olay bir oturuma ve bir ajana aittir. Kapsamlar her ikisini de doldurur, bu nedenle nadiren bunları geçersiniz:

with failproofai_sdk.session():
    with failproofai_sdk.agent("planner"):
        failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1")

session_id veya agent_id’yi açıkça geçmek hala çalışır ve kazanır. Hiçbiri bağlı veya geçilmez ise, çağrı Cloud’un sessizce atması gereken bir olay yayacak yerine TypeError yükseltir.

Kimlik, bağlam değişkenlerinde bulunur. asyncio görevlerini otomatik olarak takip eder, ancak yeni thread’leri değil — bir işçiyi failproofai_sdk.propagate() içine sarın veya olayları eki olmadan başarısız alın.

Olay kataloğu

On beş metod. Çoğu çiftler halinde gelir — açıcıyı çağırırsınız, ardından kapatıcıyı ve SDK boşluğu zamanlar.

	Açar	Kapatır
Ajanlar	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
Modeller	`model_request`	`model_response`
Araçlar	`tool_use`	`tool_result`
Kancalar	`hook_triggered`	`hook_completed`
İnsanlar	`human_wait`	`human_input`

Üç başında durur: error, human_pause, human_interrupt.

Her alan, 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 herhangi bir şey JSON null olarak gönderilmek yerine bırakılır ve her metod None döndürür.

Metod	Gerekli	İsteğe Bağlı
`agent_start`	—	`goal`, `parent_id`
`agent_end`	—	`outcome`, `summary`
`agent_pause`	`pause_id`	`reason`, `user_id`
`agent_resume`	`pause_id`	`reason`, `user_id`
`model_request`	—	`model`, `messages`, `system`, `tools`, `request_id`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`, `request_id`, `duration_ms`
`tool_use`	`tool_name`, `tool_call_id`	`input`
`tool_result`	`tool_name`, `tool_call_id`	`output`, `error`
`hook_triggered`	`hook_name`, `hook_id`	`trigger_event`, `input`
`hook_completed`	`hook_name`, `hook_id`	`outcome`, `output`, `error`
`error`	`error_type`, `message`	`traceback`
`human_wait`	`input_id`	`prompt`, `options`, `reason`
`human_input`	`input_id`	`response`
`human_pause`	—	`reason`, `user_id`
`human_interrupt`	—	`reason`, `user_id`, `at_step`

Bir çalıştırmayı başarısız olarak işaretlemek için outcome, failed, error, timeout veya rejected olmalıdır. Başka herhangi bir şey — yakın kaçış "failure" da dahil olmak üzere — bir başarı olarak sayılır.

Eşleştirme ve süre

Bir kural: kapatma olayına açıcısıyla aynı kimliği verin. Bu onları eşleştirir ve SDK’ya boşluğu zamanlamasını sağlar.

Çift	Eşleştirilir
`tool_use` → `tool_result`	`tool_call_id`
`hook_triggered` → `hook_completed`	`hook_id`
`agent_pause` → `agent_resume`	`pause_id`
`human_wait` → `human_input`	`input_id`
`model_request` → `model_response`	`request_id`

duration_ms kendiniz geçmeyin. SDK bunu ölçer ve geçmek ValueError yükseltir. Tek istisna model_response’dir; burada sadece siz gerçek sağlayıcı gecikmesini bilirsiniz. Milisaniye cinsinden bir tam sayı geçin — bir float yükseltir, çünkü sütun 32 bit bir tamsayıdır ve aksi takdirde boş kalırdı.

Kenar durumları

Kimlikler yalnızca tür başına, oturum başına benzersiz olması gerekir. Bir araç çağrısı ve bir kanca aynısını paylaşabilir; aynı anda çalışan iki oturum aynı kimlikler çarpışmadan yeniden kullanabilir.
Bunlar bir ajana kapsamlı değildir. Bir çiftin bir ajan altında açılması ve başka bir ajan altında kapatılması hala eşleşir — bu, çok ajanlı kodda normal durumdur.
request_id isteğe bağlı ancak önerilir. Olmadan, model olayları varış sırasında eşleştirilir, bu nedenle aynı ajan içinde iki eşzamanlı çağrı yanlış eşleşebilir.
Süreçler arasında bölünmüş bir çift Cloud’da hala eşleşir, ancak SDK bunu zamanlamaz — hiçbir işlemin her iki yarısı da görmediği bir şey.
En fazla 10.000 açıcı aynı anda kapatıcı için bekler. Bunun ötesinde en eski bırakılır, bu nedenle bir sızıntı sınırsız olarak büyüyemez.

Kendi alanlarınız

Geçtiğiniz herhangi bir ekstra anahtar sözcük olay ile saklanır:

failproofai_sdk.event.tool_use(
    tool_name="search", tool_call_id="c1",
    fw_tenant="acme", fw_region="eu-west-1",     # sizin
)

Daha sonra sorgulamak istiyorsanız JSON türlerini tercih edin. Başka herhangi bir şey — bir UUID, bir datetime, bir Decimal, bir set, bytes, bir model nesnesi — dize olarak depolanır.

Alan adlarınızı önek olarak yazın. Ekstralar son olarak uygulanır, bu nedenle model, tool_name veya outcome adı verilen bir alan sessizce gerçek olanı geçersiz kılar. Framework adaptörleri fw_ kullanır; aynısını yapın ve hiçbir şey çarpışamaz.Bunun nedeni de yazım hatası yapılan isteğe bağlı bir alanın hiçbir zaman hata vermemesidir — sadece yeni bir özel alan olur. Cloud’da standart bir alan eksikse, önce yazımı kontrol edin.

Bu beş ad ayrılmıştır ve doğrudan reddedilir: timestamp, session_id, agent_id, type, environment.

Teslimat ve doğrulama

Gösterge Paneli
CLI

Observe → Events’te agent_start ilk olarak ve agent_end son olarak bulunduğunu doğrulayın. Ardından Observe → Sessions’ı açın ve model, araç, insan, kanca ve hata olaylarının amaçlanan sırada göründüğünü onaylayın. Oturum kimliğini birincil sorun giderme anahtarı olarak kullanın.

failproofai flush --wait --timeout 60
failproofai config --status
fp sessions --since 1h --env production --session-id <session-id>
fp events --since 1h --session-id <session-id> --full

Cloud boşsa, $FAILPROOFAI_HOME/custom-agents/events’i, aksi takdirde ~/.failproofai/custom-agents/events’i inceleyin. JSONL dosyaları SDK emisyonunu kanıtlar; büyüyen bir spool daemon konfigürasyonuna veya teslimata işaret ederken, boş bir spool enstrümantasyona veya işlem ömrüne işaret eder.

Spool’u yalnızca daemon durdurulduğunda inceleyin. Çalışırken, her toplu işi milisaniye içinde toplar ve siler, bu nedenle bir dizin listesi toplayıcıyla yarışır ve yayılan olaylardan çok daha azını gösterir.

Özel bir çalışma zamanında başarısızlıkları önleyin

Güvensiz eylemi, gerekli kanıtı ve amaçlanan yanıtı tanımlamak için denetim bulgularını ve bağlantılı izlemeleri kullanın. Özel bir uygulama entegrasyonu, eylemi yürütmeden önce ortaya koymak, yapılandırılmış girdisini ilke motoruna geçirmek ve ortaya çıkan allow, instruct veya deny kararını uygulamalıdır. Failproof AI ile iletişime geçin ve çalışma zamanınızın model, araç ve yaşam döngüsü sınırlarını ilke kancalarına harita taşımasına yardımcı olur, ardından entegrasyonu sizle doğrularız.

Connect your agents

Reference

Özel ajanlar kılavuzu

Bir framework kullanıyor musunuz?

Kurun

Failproof daemon’ını bağlayın

Konfigürasyon

Kimlik

Olay kataloğu

Eşleştirme ve süre

Kendi alanlarınız

Teslimat ve doğrulama

Özel bir çalışma zamanında başarısızlıkları önleyin

Özel ajanlar kılavuzu

Bir framework kullanıyor musunuz?

​Kurun

​Failproof daemon’ını bağlayın

​Konfigürasyon

​Kimlik

​Olay kataloğu

​Eşleştirme ve süre

​Kendi alanlarınız

​Teslimat ve doğrulama

​Özel bir çalışma zamanında başarısızlıkları önleyin

Kurun

Failproof daemon’ını bağlayın

Konfigürasyon

Kimlik

Olay kataloğu

Eşleştirme ve süre

Kendi alanlarınız

Teslimat ve doğrulama

Özel bir çalışma zamanında başarısızlıkları önleyin