Benutzerdefinierte Agents

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

Leitfaden für benutzerdefinierte Agents

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

Framework im Einsatz?

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

Python 3.10 oder neuer. Keine Laufzeitabhä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 stets im Basis-Wheel mitgeliefert.

Verbindung zum Failproof-Daemon herstellen

Dashboard
CLI

Gehen Sie zu Admin → Keys 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 die genaue ID unter Observe → Events.
Gehen Sie zu Observe → Sessions, wählen Sie dieselbe Umgebung und öffnen Sie den rekonstruierten Trace.

Lesen Sie den events:add-Schlüssel in die Shell ein. read -s nimmt ihn über eine Eingabeaufforderung entgegen, die nicht angezeigt wird – er erscheint daher weder in einem Befehl noch im Shell-Verlauf:

read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN

Richten Sie anschließend die Maschine ein und prüfen Sie die Verbindung:

failproofai config
failproofai config --status

Konfiguration

import failproofai_sdk

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

Argument	Funktion
`environment`	Die Bezeichnung für jeden Event – `production`, `staging`, `prod-eu`. Standardwert: `dev`.
`flush_interval`	Wie oft der Hintergrundthread auf die Festplatte schreibt, in Sekunden. Standardwert: `0.5`.
`base_dir`	Speicherort für Ausgaben. Standardmäßig wird der Daemon-Spool verwendet, was in der Regel das Richtige ist.

Alternativ per Umgebungsvariable setzen:

Variable	Funktion
`AGENTEYE_ENVIRONMENT`	Setzt `environment` ohne Codeänderung – sinnvoll, wenn die Bezeichnung zum Deployment und nicht 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 als Exception aufsteigen, anstatt sie zu protokollieren.
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` lässt Framework-Kompatibilitätsprobleme als Exception aufsteigen, anstatt zu warnen und fortzufahren.

Keine Kommas in environment. Die Verarbeitungspipeline teilt dieses Feld an Kommas auf, um Filter zu erstellen, und verwirft jeden Event, dessen Bezeichnung ein Komma enthält – ein ganzer Durchlauf verschwindet dabei lautlos. Schreiben Sie prod-eu, nicht prod,eu.configure(environment="prod,eu") löst eine Exception aus, damit Sie es sofort bemerken. AGENTEYE_ENVIRONMENT kann keine Exception auslösen – niemand ruft Sie auf – daher wird einmal gewarnt und auf dev zurückgefallen.

Events werden im Arbeitsspeicher gepuffert und im Hintergrund alle flush_interval Sekunden geschrieben, mit einem abschließenden Flush beim Beenden des Interpreters. Ein abrupt beendeter Prozess verliert alle noch nicht geschriebenen Events.

Identität

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

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

session_id oder agent_id explizit zu übergeben funktioniert weiterhin und hat Vorrang. Wenn weder ein Scope gebunden noch ein Wert übergeben wird, löst der Aufruf einen TypeError aus, anstatt einen Event zu senden, den Cloud stillschweigend verwerfen würde.

Die Identität wird über Kontextvariablen weitergegeben. Sie folgt asyncio-Tasks automatisch, jedoch nicht neuen Threads – umschließen Sie einen Worker mit 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 den Zeitraum 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 für sich allein: error, human_pause, human_interrupt.

Alle Felder pro Methode

Jede Methode akzeptiert außerdem session_id und agent_id, die die Scopes für Sie befüllen. Alles, was als None belassen wird, wird weggelassen und nicht als JSON null gesendet; jede Methode gibt None zurück.

Methode	Erforderlich	Optional
`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 einen Durchlauf 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. Damit werden sie verknüpft, und das SDK kann den Zeitraum dazwischen 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 den Wert, und eine eigene Übergabe löst einen ValueError aus. Die einzige Ausnahme ist model_response, wo nur Sie die tatsächliche Provider-Latenz kennen. Übergeben Sie eine ganze Anzahl von Millisekunden – ein Float löst eine Exception aus, da die Spalte eine 32-Bit-Ganzzahl ist und der Wert sonst leer gespeichert würde.

Sonderfälle

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

Eigene Felder

Jedes zusätzliche Schlüsselwort, das Sie übergeben, wird zusammen 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
)

Verwenden Sie nach Möglichkeit JSON-Typen, wenn Sie die Werte später abfragen möchten. Alles andere – eine UUID, ein Datetime-Objekt, ein Decimal, ein Set, Bytes, ein Modellobjekt – wird als Zeichenkette gespeichert.

Präfixieren Sie Ihre Feldnamen. Zusätzliche Felder werden zuletzt angewendet, sodass ein Feld mit dem Namen model, tool_name oder outcome den eigentlichen Wert stillschweigend überschreibt. Die Framework-Adapter verwenden fw_; tun Sie dasselbe, und es kann zu keinen Kollisionen kommen.Aus diesem Grund führt ein falsch geschriebenes optionales Feld auch nie zu einem Fehler – 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 direkt 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 stellen Sie sicher, dass Model-, Tool-, Human-, Hook- und Error-Events in der vorgesehenen Reihenfolge erscheinen. Verwenden Sie die Sitzungs-ID als primären Schlüssel zur Fehlersuche.

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 Emission durch das SDK; ein wachsender Spool deutet auf ein Daemon-Konfigurations- oder Zustellungsproblem hin, während ein leerer Spool auf ein Instrumentierungs- oder Prozesslebensdauerproblem hindeutet.

Prüfen Sie den Spool nur, wenn der Daemon gestoppt ist. Während er läuft, erfasst und löscht er jede Charge innerhalb von Millisekunden – eine Verzeichnisauflistung steht dann im Wettbewerb mit dem Collector und zeigt weit weniger Events als tatsächlich emittiert wurden.

Fehler in einer benutzerdefinierten Laufzeitumgebung verhindern

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

Connect your agents

Reference

Benutzerdefinierte Agents

Leitfaden für benutzerdefinierte Agents

Framework im Einsatz?

Installation

Verbindung zum Failproof-Daemon herstellen

Konfiguration

Identität

Event-Katalog

Paarung und Dauer

Eigene Felder

Zustellung und Überprüfung

Fehler in einer benutzerdefinierten Laufzeitumgebung verhindern

Leitfaden für benutzerdefinierte Agents

Framework im Einsatz?

​Installation

​Verbindung zum Failproof-Daemon herstellen

​Konfiguration

​Identität

​Event-Katalog

​Paarung und Dauer

​Eigene Felder

​Zustellung und Überprüfung

​Fehler in einer benutzerdefinierten Laufzeitumgebung 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 Laufzeitumgebung verhindern