Benutzerdefinierte Agents

Was jede Einstellung, Methode und jedes Feld bewirkt. Wenn Sie zum ersten Mal instrumentieren, beginnen Sie mit dem Leitfaden — diese Seite dient zum Nachschlagen.

Leitfaden für benutzerdefinierte Agents

Installation, Instrumentierung, die Event-Methoden, ein durchgearbeitetes Beispiel und häufige Probleme.

Verwenden Sie ein Framework?

LangChain, CrewAI, LlamaIndex und Pydantic AI instrumentieren sich selbst mit einem einzigen Aufruf.

Python 3.10 oder neuer. Keine Laufzeit-Abhängigkeiten.

Installation

pip install failproofai-sdk

Das Paket wird als failproofai-sdk installiert und in Python als failproofai_sdk importiert. Framework-Extras wie failproofai-sdk[langgraph] installieren das Framework selbst; die Adapter werden immer im Basis-Wheel mitgeliefert.

Verbindung zum Failproof-Daemon herstellen

Dashboard
CLI

Gehen Sie zu Admin → Schlüssel und erstellen Sie einen Schlüssel mit events:add.
Verbinden Sie den Failproof-Daemon mit Cloud auf der Agent-Maschine.
Führen Sie eine instrumentierte Sitzung aus und suchen Sie deren genaue ID unter Observe → Events.
Gehen Sie zu Observe → Sessions, wählen Sie dieselbe Umgebung und öffnen Sie den rekonstruierten Trace.

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

Konfiguration

import failproofai_sdk

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

Argument	Funktion
`environment`	Das Label für jeden Event — `production`, `staging`, `prod-eu`. Standardmäßig `dev`.
`flush_interval`	Wie oft der Hintergrund-Thread auf die Festplatte schreibt, in Sekunden. Standard: `0.5`.
`base_dir`	Wohin geschrieben wird. Standardmäßig der Daemon-Spool — das ist in der Regel das Richtige, sofern Sie es nicht bewusst ändern möchten.

Alternativ per Umgebungsvariable setzen:

Variable	Funktion
`AGENTEYE_ENVIRONMENT`	Setzt `environment` ohne Code-Änderung — geeignet, wenn das Label zur Deployment-Umgebung statt zur App gehört. Ein `configure()`-Argument hat Vorrang.
`FAILPROOFAI_HOME`	Verschiebt das Failproof AI-Stammverzeichnis, das den Spool enthält.
`FAILPROOFAI_SDK_STRICT`	`1` lässt Instrumentierungsfehler eine Ausnahme auslösen, statt sie nur zu protokollieren.
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` lässt ein Framework-Kompatibilitätsproblem eine Ausnahme auslösen, statt nur zu warnen und fortzufahren.

Keine Kommas in environment. Die Ingest-Schicht teilt dieses Feld an Kommas auf, um Filter zu erstellen, und überspringt jeden Event, dessen Label ein Komma enthält — eine ganze Ausführung verschwindet damit lautlos. Schreiben Sie prod-eu, nicht prod,eu.configure(environment="prod,eu") löst sofort eine Ausnahme aus, damit Sie es sofort bemerken. AGENTEYE_ENVIRONMENT kann keine Ausnahme auslösen — niemand ruft Sie zurück — daher wird einmal gewarnt und auf dev zurückgefallen.

Events werden im Speicher in eine Warteschlange gestellt und alle flush_interval Sekunden im Hintergrund geschrieben, mit einem abschließenden Flush beim Beenden des Interpreters. Ein abrupt beendeter Prozess verliert alles, was noch nicht geschrieben wurde.

Identität

Jeder Event gehört zu einer Sitzung und einem Agent. Die Scopes füllen beides aus, sodass Sie sie selten manuell übergeben müssen:

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

Die explizite Übergabe von session_id oder agent_id funktioniert weiterhin und hat Vorrang. Wenn weder gebunden noch übergeben, löst der Aufruf TypeError aus, statt einen Event zu senden, den Cloud still verwerfen würde.

Die Identität wird über Context-Variablen weitergegeben. Sie folgt asyncio-Tasks automatisch, aber nicht neuen Threads — kapseln Sie einen Worker in failproofai_sdk.propagate(), sonst landen seine Events ohne Zuordnung.

Event-Katalog

Fünfzehn Methoden. Die meisten kommen in Paaren — Sie rufen den Öffner auf, dann den Schließer, und das SDK misst die Zeitspanne dazwischen.

	Öffnet	Schließt
Agents	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
Modelle	`model_request`	`model_response`
Tools	`tool_use`	`tool_result`
Hooks	`hook_triggered`	`hook_completed`
Menschen	`human_wait`	`human_input`

Drei stehen allein: error, human_pause, human_interrupt.

Alle Felder, je Methode

Jede Methode akzeptiert außerdem session_id und agent_id, die von den Scopes automatisch befüllt werden. Alles, was None bleibt, wird weggelassen statt als JSON null gesendet, und jede Methode gibt None zurück.

Methode	Pflichtfelder	Optionale Felder
`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`

Um eine Ausführung als fehlgeschlagen zu markieren, muss outcome einen der folgenden Werte haben: failed, error, timeout oder rejected. Alles andere — einschließlich des ähnlichen "failure" — wird als Erfolg gewertet.

Paarung und Dauer

Eine Regel: Geben Sie dem schließenden Event dieselbe ID wie dem öffnenden. Das ist es, was sie verknüpft und was dem SDK ermöglicht, die Zeitspanne zu messen.

Paar	Abgeglichen über
`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`

Übergeben Sie duration_ms nicht selbst. Das SDK misst es, und die Übergabe löst ValueError aus. Die einzige Ausnahme ist model_response, wo nur Sie die tatsächliche Provider-Latenz kennen. Übergeben Sie eine ganzzahlige Anzahl von Millisekunden — ein Float löst eine Ausnahme aus, da die Spalte ein 32-Bit-Integer ist und sonst leer bleibt.

Sonderfälle

IDs müssen nur pro Art und pro Sitzung eindeutig sein. Ein Tool-Aufruf und ein Hook können dieselbe ID teilen; zwei gleichzeitig laufende Sitzungen können dieselben IDs wiederverwenden, ohne zu kollidieren.
Sie sind nicht auf einen Agent beschränkt. Ein Paar, das unter einem Agent geöffnet und unter einem anderen geschlossen wird, wird trotzdem korrekt zugeordnet — was in Multi-Agent-Code der Normalfall ist.
request_id ist optional, wird aber empfohlen. Ohne sie werden Model-Events in der Reihenfolge ihres Eingangs gepaart, sodass zwei gleichzeitige Aufrufe im selben Agent falsch zugeordnet werden können.
Ein Paar, das sich über Prozesse erstreckt, wird in Cloud trotzdem abgeglichen, aber das SDK kann es nicht zeitlich messen — kein Prozess hat beide Hälften gesehen.
Maximal 10.000 Öffner warten gleichzeitig auf einen Schließer. Darüber hinaus wird der älteste verworfen, damit ein Leck nicht unbegrenzt wachsen kann.

Eigene Felder

Jedes zusätzliche Schlüsselwortargument, das Sie übergeben, wird mit dem Event gespeichert:

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

Bevorzugen Sie JSON-Typen, wenn Sie sie später abfragen möchten. Alles andere — eine UUID, ein Datetime-Objekt, ein Decimal, ein Set, Bytes, ein Modell-Objekt — wird als Zeichenkette gespeichert.

Präfigieren Sie Ihre Feldnamen. Extras werden zuletzt angewendet, sodass ein Feld namens model, tool_name oder outcome das echte Feld stillschweigend überschreibt. Die Framework-Adapter verwenden fw_; tun Sie dasselbe, und es kann keine Kollision auftreten.Das ist auch der Grund, warum ein falsch geschriebenes optionales Feld keinen Fehler erzeugt — es wird einfach zu einem neuen benutzerdefinierten Feld. Wenn ein Standardfeld in Cloud fehlt, prüfen Sie zuerst die Schreibweise.

Diese fünf Namen sind reserviert und werden grundsätzlich abgelehnt: timestamp, session_id, agent_id, type, environment.

Zustellung und Überprüfung

Dashboard
CLI

Überprüfen Sie unter Observe → Events, ob agent_start als erster und agent_end als letzter Event vorhanden ist. Öffnen Sie dann Observe → Sessions und bestätigen Sie, dass Model-, Tool-, Human-, Hook- und Error-Events in der vorgesehenen Reihenfolge erscheinen. Verwenden Sie die Sitzungs-ID als primären Troubleshooting-Schlüssel.

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

Wenn Cloud leer ist, prüfen Sie $FAILPROOFAI_HOME/custom-agents/events, andernfalls ~/.failproofai/custom-agents/events. JSONL-Dateien belegen die SDK-Emission; ein wachsender Spool deutet auf ein Problem bei der Daemon-Konfiguration oder Zustellung hin, während ein leerer Spool auf ein Instrumentierungs- oder Prozesslebenszyklusproblem hindeutet.

Prüfen Sie den Spool nur, wenn der Daemon gestoppt ist. Während er läuft, sammelt und löscht er jeden Batch innerhalb von Millisekunden — eine Verzeichnisauflistung konkurriert mit dem Collector und zeigt weit weniger Events als tatsächlich emittiert wurden.

Fehler in einer benutzerdefinierten Laufzeit verhindern

Nutzen Sie Audit-Ergebnisse und verknüpfte Traces, um die unsichere Aktion, den erforderlichen Nachweis und die vorgesehene Reaktion zu definieren. Eine benutzerdefinierte Enforcement-Integration muss die Aktion vor der Ausführung offenlegen, ihre strukturierte Eingabe an die Policy-Engine übergeben und die resultierende allow-, instruct- oder deny-Entscheidung anwenden. Kontaktieren Sie Failproof AI und wir helfen Ihnen, die Modell-, Tool- und Lebenszyklus-Grenzen Ihrer Laufzeit auf Policy-Hooks abzubilden und die Integration gemeinsam mit Ihnen zu validieren.

Connect your agents

Reference

Benutzerdefinierte Agents

Leitfaden für benutzerdefinierte Agents

Verwenden Sie ein Framework?

Installation

Verbindung zum Failproof-Daemon herstellen

Konfiguration

Identität

Event-Katalog

Paarung und Dauer

Eigene Felder

Zustellung und Überprüfung

Fehler in einer benutzerdefinierten Laufzeit verhindern

Leitfaden für benutzerdefinierte Agents

Verwenden Sie ein Framework?

​Installation

​Verbindung zum Failproof-Daemon herstellen

​Konfiguration

​Identität

​Event-Katalog

​Paarung und Dauer

​Eigene Felder

​Zustellung und Überprüfung

​Fehler in einer benutzerdefinierten Laufzeit verhindern

Installation

Verbindung zum Failproof-Daemon herstellen

Konfiguration

Identität

Event-Katalog

Paarung und Dauer

Eigene Felder

Zustellung und Überprüfung

Fehler in einer benutzerdefinierten Laufzeit verhindern