> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Özel ajanlar

> Özel ajanlardan alınan izlemeleri işaretle; böylece Failproof AI çalıştırmaları yeniden oluşturabilir ve hataları bulabilir.

`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.

<Info>
  Özel bir ajan kurulumunda ilkeleri uygulamak için [Failproof AI ile iletişime geçin](mailto:support@befailproof.ai). Ç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.
</Info>

<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?rel=0&playsinline=1" title="Agent tracing with the Failproof AI Python SDK" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }} />
</div>

## `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.

```bash theme={null}
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

<Tabs>
  <Tab title="Pano">
    1. **Admin → Anahtarlar** bölümüne gidin ve `events:add` ile bir anahtar oluşturun.
    2. [Failproof daemon'ını Cloud'a bağlayın](/tr/start/setup#connect-a-machine-to-cloud) (ajan makinesinde).
    3. İşaretlenmiş bir oturumu çalıştırın, sonra **Gözlemle → Olaylar** bölümünde tam kimliğini bulun.
    4. **Gözlemle → Oturumlar** bölümüne gidin, aynı ortamı seçin ve yeniden oluşturulan izlemeyi açın.

           <img src="https://mintcdn.com/exosphere/WgPwQzedeDNwJBTy/images/dashboard/session-detail.png?fit=max&auto=format&n=WgPwQzedeDNwJBTy&q=85&s=7b5f022dd5c485565a8cd92b2e936235" alt="Yürütme grafiği ve sıralanmış olay izlemesi olarak yeniden oluşturulan özel bir Python ajan oturumu." width="3200" height="2000" data-path="images/dashboard/session-detail.png" />
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    failproofai config \
      --connect https://app.befailproof.ai \
      --token <events-add-key>
    failproofai config --status
    ```
  </Tab>
</Tabs>

## 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.

```python theme={null}
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

```python theme={null}
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

<Tabs>
  <Tab title="Pano">
    **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.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    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
    ```
  </Tab>
</Tabs>

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](mailto:support@befailproof.ai) adresine e-posta gönderin.