Özel ajanlar

failproofai-sdk ile özel bir ajanın izlemelerini işaretleyin; böylece Failproof AI her çalıştırmayı yeniden oluşturabilir, davranışını denetleyebilir ve kanıtla desteklenen hataları bulabilir. SDK, Failproof daemon’ının buluta göndermesi için yapılandırılmış olayları yazar. Python 3.10 veya daha yeni bir sürüm gerekir. İzleme, özel ajanları gözlemlenebilir ve denetlenebilir hale getirir. Güvensiz bir eylemi yürütülmeden önce engellemek, çalışma zamanında bir zorlama kancası gerektirir.

Özel bir ajan kurulumunda ilkeleri uygulamak için Failproof AI ile iletişime geçin. Çalışma zamanının model, araç ve yaşam döngüsü sınırlarını ilke kancalarıyla eşleştirmenize yardımcı olacağız.

`failproofai-sdk` yükleyin

SDK şu anda özel bir wheel olarak dağıtılmaktadır. Mevcut sürüm ve indirme erişimi için Failproof AI temsilcinize başvurun.

VERSION=<sdk-version>
pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl"
python -c "import failproofai; print(failproofai.__version__)"

uv ile, wheel’i indirin ve uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl komutunu çalıştırın. Wheel’i özel bir artifact deposunda sabitleyin veya bağımlılık kilidinde tutun. Paket failproofai-sdk olarak yüklenir ve Python’da failproofai olarak içe aktarılır.

Failproof daemon’ını bağlayın

Pano
CLI

Admin → Anahtarlar bölümüne gidin ve events:add ile bir anahtar oluşturun.
Failproof daemon’ını Cloud’a bağlayın (ajan makinesinde).
İşaretlenmiş bir oturumu çalıştırın, sonra Gözlemle → Olaylar bölümünde tam kimliğini bulun.
Gözlemle → Oturumlar bölümüne gidin, aynı ortamı seçin ve yeniden oluşturulan izlemeyi açın.

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

Tam bir çalıştırmayı işaretleyin

İşlem başlangıcında configure() öğesini bir kez çağırın. Her olay çağrısı yalnızca anahtar sözcüktür ve kararlı bir session_id ve agent_id gerektirir.

import traceback
import uuid

import failproofai

failproofai.configure(environment="production")

session_id = uuid.uuid4().hex
agent_id = "checkout-agent"

failproofai.event.agent_start(
    session_id=session_id,
    agent_id=agent_id,
    goal="Resolve a failed checkout",
)

try:
    tool_call_id = uuid.uuid4().hex
    failproofai.event.tool_use(
        session_id=session_id,
        agent_id=agent_id,
        tool_name="lookup_order",
        tool_call_id=tool_call_id,
        input={"order_id": "ord_8421"},
    )
    result = {"status": "payment_failed"}
    failproofai.event.tool_result(
        session_id=session_id,
        agent_id=agent_id,
        tool_name="lookup_order",
        tool_call_id=tool_call_id,
        output=result,
    )
except Exception as exc:
    failproofai.event.error(
        session_id=session_id,
        agent_id=agent_id,
        error_type=type(exc).__name__,
        message=str(exc),
        traceback=traceback.format_exc(),
    )
    failproofai.event.agent_end(
        session_id=session_id,
        agent_id=agent_id,
        outcome="failed",
    )
    raise
else:
    failproofai.event.agent_end(
        session_id=session_id,
        agent_id=agent_id,
        outcome="success",
        summary="Escalated the failed payment",
    )

Aktör başına bir kez agent_start gönderin. Alt ajanlar için ebeveynin session_id öğesini yeniden kullanın, her aktöre farklı bir agent_id verin ve parent_id öğesini üst öğenin agent ID öğesine ayarlayın (oturum kimliğine değil).

Yapılandırma başvurusu

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

Ayar	Davranış
`base_dir`	Açık spool kökü. Tüm ortam değişkenlerine göre önceliklidir.
`flush_interval`	Bellekten JSONL’ye arka plan yazmaları arasındaki saniye sayısı. Varsayılan: `0.5`.
`environment`	Her olaydaki dağıtım etiketi. `dev` olarak varsayılan değer.
`FAILPROOFAI_HOME`	`custom-agents` spool’unu içeren Failproof AI kökünü değiştirir.

SDK, ayarlandığında açık base_dir öğesine yazar. Aksi takdirde, FAILPROOFAI_HOME veya ~/.failproofai altında Failproof daemon’ının custom-agents spool’unu kullanır. SDK çağrıları bellekte sıraya alır ve arka plan iş parçacığında toplu işler yazar. Ayrıca Python’ın atexit işlemesi aracılığıyla son bir temizleme girişiminde bulunur. Kısa ömürlü işçiler için normal yorumlayıcı kapatmasına izin verin; sabit işlem sonlandırması bellekte kalan olayları kaybedebilir.

Olay kataloğu

Tüm yöntemler None döndürür. None olarak bırakılan alanlar JSON null olarak yazılmak yerine çıkarılır.

Yöntem	Kimlik ötesinde gerekli alanlar	İsteğe bağlı alanlar
`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`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`
`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 tamamlama hata olarak sayılması gereken durumlarda outcome="failed", "error", "timeout" veya "rejected" kullanın. "failure" dahil diğer değerler geçerli arka uç tarafından hata olarak sınıflandırılmaz.

Korelasyon ve süre kuralları

Eşleştirme tamamlama olayı için aynı tool_call_id, hook_id, pause_id veya input_id öğesini yeniden kullanın.
SDK, tool_result, hook_completed, agent_resume ve human_input için duration_ms öğesini hesaplar. Bunu kendiniz bu yöntemlere aktarmak ValueError yükseltir.
Araç ve kanca kimlikleri bir işlem genelinde bekleyen harita paylaşır. Bunları eşzamanlı oturumlar ve her iki ad alanı genelinde genel olarak benzersiz yapın; sağlayıcı kimlikleri veya UUID’ler en güvenlidir.
Süreçler arasında bölünmüş bir çift yine de aşağı akış olarak ilişkilendirir, ancak SDK işlem içi süresini hesaplayamaz.
Bekleyen harita en fazla 10.000 başlama barındırır ve dolu olduğunda en eski girişi çıkarır.

Özel alanlar ve yükler

Her olay ekstra anahtar sözcük alanlarını kabul eder. Aşağı akış sorgularında yapı gerektiğinde JSON uyumlu değerleri kullanın. UUID’ler, tarihler, ondalıklar, kümeler, baytlar ve model nesneleri gibi desteklenmeyen yapraklar yazar tarafından dizeleştirilir. Ayrılmış özel adlar timestamp, session_id, agent_id, type ve environment öğeleridir. İsteğe bağlı alan yazım hataları yeni özel alanlar olarak kabul edilir, bu nedenle standart bir alan Cloud’da görünmediğinde yayılan JSON’u gözden geçirin.

Teslimat ve doğrulama

Pano
CLI

Gözlemle → Olaylar bölümünde, önce agent_start öğesinin var olduğunu, sonra agent_end öğesinin son olduğunu doğrulayın. Sonra Gözlemle → Oturumlar 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 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 öğesini inceleyin; aksi takdirde ~/.failproofai/custom-agents/events öğesini inceleyin. JSONL dosyaları SDK emisyonunu kanıtlar; büyüyen bir spool daemon yapılandırması veya teslimata işaret ederken, boş bir spool araçlar veya işlem ömrüne işaret eder.

Özel bir çalışma zamanında hataları önleyin

Güvensiz eylemi, gerekli kanıtı ve amaçlanan yanıtı tanımlamak için denetim bulgularını ve bağlı izlemeleri kullanın. Özel bir zorlama entegrasyonu, eylemi yürütülmeden önce ortaya koymak, yapılandırılmış girdisini ilke motoruna geçirmek ve sonuç allow, instruct veya deny kararını uygulamalıdır. Çalışma zamanınız için bu entegrasyonu tasarlamak ve doğrulamak amacıyla support@befailproof.ai adresine e-posta gönderin.

Connect your agents

Reference

HTTP API

`failproofai-sdk` yükleyin

Failproof daemon’ını bağlayın

Tam bir çalıştırmayı işaretleyin

Yapılandırma başvurusu

Olay kataloğu

Korelasyon ve süre kuralları

Özel alanlar ve yükler

Teslimat ve doğrulama

Özel bir çalışma zamanında hataları önleyin

​failproofai-sdk yükleyin

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

​Tam bir çalıştırmayı işaretleyin

​Yapılandırma başvurusu

​Olay kataloğu

​Korelasyon ve süre kuralları

​Özel alanlar ve yükler

​Teslimat ve doğrulama

​Özel bir çalışma zamanında hataları önleyin

`failproofai-sdk` yükleyin

Failproof daemon’ını bağlayın

Tam bir çalıştırmayı işaretleyin

Yapılandırma başvurusu

Olay kataloğu

Korelasyon ve süre kuralları

Özel alanlar ve yükler

Teslimat ve doğrulama

Özel bir çalışma zamanında hataları önleyin