Python SDK

Beobachten Sie genau, was Ihre KI-Agenten in der Produktion getan haben: jeden Agentenlauf, Tool-Aufruf, Modellanfrage, Hook und menschlichen Eingriff. Das Failproof AI Observability Python SDK zeichnet diesen Verlauf direkt aus Ihrem Agenten-Code auf, damit Sie debuggen, prüfen und nachvollziehen können, was passiert ist. Verwenden Sie es immer dann, wenn Failproof AI Observability Ihre Agenten beobachten soll. Im Hintergrund schreibt das SDK strukturierte Events in lokale JSONL-Dateien; der Collector-Daemon liest diese ein und übermittelt sie automatisch an die Plattform. Sie müssen diese Dateien nicht selbst verwalten.

Tipp: Neu bei Failproof AI Observability? Diese Seite ist die vollständige SDK-Event-Referenz.

Installation

Das SDK wird Kunden als privates Wheel und nicht über einen öffentlichen Paketindex bereitgestellt. Ihr Onboarding erklärt, wie Sie es beziehen, installieren und versionieren — sprechen Sie Ihren Failproof AI-Ansprechpartner an, wenn Sie Zugang benötigen. Sobald es installiert ist, überprüfen Sie die Installation:

python -c "import agenteye; print(agenteye.__version__)"

Möchten Sie die gesamte Integration lieber von einem Coding-Agenten erledigen lassen? Der Python SDK Agent Skill kennt den Installationspfad, plant die Instrumentierungspunkte, schreibt sie und verifiziert, dass die Events ankommen.

Schnellstart

import agenteye

agenteye.configure(environment="production")

agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    input={"query": "latest AI research"},
)

agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    output={"results": ["..."]},
)

agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")

Einen echten Aufruf instrumentieren

In der Praxis wrappen Sie Ihren bestehenden Agenten-Code. Umschließen Sie einen Modellaufruf mit model_request davor und model_response danach, sodass die beiden Events die eigentliche Anfrage umspannen und Failproof AI Observability sie einander zuordnen kann:

import anthropic
import agenteye

agenteye.configure(environment="production")
client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Summarise today's incidents."}]

agenteye.event.model_request(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6",
    messages=messages,
)

reply = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=messages,
)

agenteye.event.model_response(
    session_id="run-001",
    agent_id="planner",
    model=reply.model,
    stop_reason=reply.stop_reason,
    input_tokens=reply.usage.input_tokens,
    output_tokens=reply.usage.output_tokens,
    content=[block.model_dump() for block in reply.content],
)

Wrappen Sie Tool-Aufrufe auf dieselbe Weise mit tool_use und tool_result, wobei Sie eine tool_call_id für das jeweilige Paar wiederverwenden. So sehen diese Events aus, sobald sie das Dashboard erreichen — farblich nach Typ kodiert und nach Umgebung, Agent und Session filterbar:

Der Live-Events-Stream, farblich nach Event-Typ kodiert und nach Umgebung, Agent und Session filterbar

configure()

agenteye.configure(
    base_dir=None,           # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye
    flush_interval=0.5,      # float, seconds between flush cycles
    environment=None,        # str | None. Deployment environment label
)

Einmal vor dem ersten event.*-Aufruf aufrufen. Kann weggelassen werden; die Standardwerte funktionieren sofort. Alle Argumente sind Keyword-only; übergeben Sie sie wie oben gezeigt mit Namen. Wenn base_dir None ist (Standard), liest das SDK $AGENTEYE_HOME, falls gesetzt, und fällt andernfalls auf ~/.agenteye zurück. Dies entspricht der eigenen Auflösungslogik des Collectors, sodass eine einzelne AGENTEYE_HOME-Umgebungsvariable den gemeinsamen Event-Spool für das SDK und den Collector konfiguriert.

Umgebung

Versehen Sie jedes Event mit einem Deployment-Environment-Label (production, staging, qa, canary usw.). Einmal setzen; das SDK hängt es automatisch an jedes Event an. Option 1: über configure():

agenteye.configure(environment="production")

Option 2: über Umgebungsvariable:

export AGENTEYE_ENVIRONMENT=production

Priorität: configure(environment=...) hat Vorrang vor der Umgebungsvariable. Wenn keines von beidem gesetzt ist, wird standardmäßig "dev" verwendet. Der Environment-Wert erscheint als erstklassiger Filter im Dashboard und wird für schnelle Abfragen auf dem Server gespeichert.

Warnung: Environment-Werte dürfen kein wörtliches ,-Komma enthalten. Die Dashboard-Filter verwenden kommagetrennte Mehrfachauswahl in der URL (?environment=prod,staging), sodass ein Environment namens prod,blue in zwei Werte aufgeteilt würde. Events mit Komma-enthaltenden Environments werden beim Ingest abgelehnt.

Daten und Datenschutz

Das SDK zeichnet nur die Felder auf, die Sie explizit übergeben. Prompts, Nachrichten, Tool-Eingaben und -Ausgaben sowie Modellinhalt werden ausschließlich erfasst, weil Sie sie einem event.*-Aufruf übergeben. Es wird nichts aus Ihrem Prozess gelesen oder implizit erfasst. Jedes Feld, das Sie weglassen, wird vollständig aus dem Event ausgelassen; es wird nicht auf die Festplatte geschrieben. Das macht die Schwärzung zu Ihrer Wahl und Verantwortung. Wenn ein Prompt oder ein Tool-Payload personenbezogene Daten oder Geheimnisse enthält, die Sie lieber nicht speichern möchten, entfernen oder maskieren Sie diese, bevor Sie sie an die Event-Methode übergeben.

Event-Referenz

Die meisten Events kommen in Start/End-Paaren, die eine Korrelations-ID teilen: tool_use und tool_result teilen eine tool_call_id, hook_triggered und hook_completed teilen eine hook_id, und human_wait und human_input teilen eine input_id. Senden Sie das Start-Event, führen Sie die Arbeit aus und senden Sie dann das End-Event mit derselben ID. Failproof AI Observability ordnet das Paar zu und berechnet duration_ms für Sie — Sie übergeben duration_ms daher nie selbst.

Ein git-ähnlicher Ausführungsgraph einer Session neben ihrer Event-Zeitleiste, rekonstruiert aus den gepaarten Events, mit dem Tool/Model/Hook-Aufschlüsselungspanel

Alle Event-Methoden erfordern diese beiden Felder:

Feld	Typ	Beschreibung
`session_id`	`str`	Identifiziert den übergeordneten Agentenlauf
`agent_id`	`str`	Identifiziert, welcher Agent innerhalb der Session das Event ausgelöst hat

Alle Methoden akzeptieren auch beliebige **kwargs für benutzerdefinierte Metadaten (siehe Benutzerdefinierte Felder).

`event.agent_start()`

Wird ausgelöst, wenn ein Agent mit der Arbeit beginnt.

agenteye.event.agent_start(
    session_id="run-001",
    agent_id="planner",
    goal="answer user query",   # str | None
    parent_id=None,             # str | None - parent agent_id for nested agents
)

`event.agent_end()`

Wird ausgelöst, wenn ein Agent die Arbeit beendet.

agenteye.event.agent_end(
    session_id="run-001",
    agent_id="planner",
    outcome="success",          # str | None
    summary="Answered query",   # str | None
)

`event.tool_use()`

Wird ausgelöst, wenn ein Agent ein Tool aufruft. In Kombination mit tool_result verwendet; das SDK berechnet duration_ms automatisch.

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",     # str, required
    tool_call_id="toolu_01",    # str, required - correlation key for the matching tool_result
    input={"query": "..."},     # dict | None
)

`event.tool_result()`

Wird ausgelöst, wenn ein Tool eine Antwort zurückgibt. Korreliert mit tool_use über tool_call_id.

agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",        # must match the prior tool_use
    output={"results": ["..."]},    # Any | None
    error=None,                     # str | None - set if the tool raised
    # duration_ms is computed automatically - do not pass it
)

`event.model_request()`

Wird unmittelbar vor dem Senden eines Prompts an ein LLM ausgelöst.

agenteye.event.model_request(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
    messages=[                   # list[dict] | None - conversation turns
        {"role": "user", "content": "..."},
    ],
    system="You are helpful.",   # Any | None - str or list of content blocks
    tools=[                      # list[dict] | None - tool schemas offered to the model
        {"name": "search", "input_schema": {"type": "object"}},
    ],
)

messages-Einträge akzeptieren entweder einen einfachen String als content oder Anthropic-Stil Listen von Content-Blöcken als content. Sampling-Parameter (temperature, max_tokens usw.) können als zusätzliche kwargs übergeben werden.

`event.model_response()`

Wird ausgelöst, wenn das LLM eine Antwort zurückgibt.

agenteye.event.model_response(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
    stop_reason="end_turn",     # str | None
    input_tokens=1024,          # int | None
    output_tokens=256,          # int | None
    content=[                    # Any | None - str, or list of content blocks
        {"type": "text", "text": "..."},
    ],
    role="assistant",            # str | None
)

content akzeptiert entweder einen einfachen String (generische Provider) oder eine Liste von Anthropic-Stil Content-Blöcken. Tool-Aufrufe befinden sich innerhalb von content als {"type": "tool_use", ...}-Blöcke, ohne ein separates tool_calls-Feld.

`event.hook_triggered()`

Wird ausgelöst, wenn ein Hook feuert. In Kombination mit hook_completed verwendet; das SDK berechnet duration_ms automatisch.

agenteye.event.hook_triggered(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",   # str, required
    hook_id="hook-abc",         # str, required - correlation key
    trigger_event="tool_use",   # str | None
    input={"tool": "search"},   # Any | None
)

`event.hook_completed()`

Wird ausgelöst, wenn ein Hook abgeschlossen ist. Korreliert mit hook_triggered über hook_id.

agenteye.event.hook_completed(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",
    hook_id="hook-abc",         # must match the prior hook_triggered
    outcome="allow",            # str | None
    output=None,                # Any | None
    error=None,                 # str | None
    # duration_ms is computed automatically - do not pass it
)

`event.error()`

Wird ausgelöst, wenn ein unbehandelter Fehler auftritt.

agenteye.event.error(
    session_id="run-001",
    agent_id="planner",
    error_type="TimeoutError",  # str, required
    message="timed out",        # str, required
    traceback="Traceback...",   # str | None
)

Human-in-the-Loop-Events

Human-in-the-Loop-Events geben Ihnen Einblick in die Momente, in denen eine Person in die Ausführung des Agenten eingreift (warten auf Genehmigung, Eingaben bereitstellen, pausieren oder den Agenten stoppen). Sie ermöglichen es Ihnen zu messen, wie lange Menschen für eine Antwort benötigen (das SDK berechnet duration_ms bei gepaarten Events automatisch), zu prüfen, wer einen Agenten pausiert oder unterbrochen hat, und Genehmigungs- und Überwachungs-Workflows zu erstellen, die im Dashboard angezeigt werden.

`event.human_wait()`

Wird ausgelöst, wenn der Agent die Ausführung unterbricht, um auf eine menschliche Eingabe zu warten. In Kombination mit human_input verwendet; das SDK berechnet duration_ms (wie lange der Mensch für eine Antwort benötigte) automatisch.

agenteye.event.human_wait(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",                          # str, required - correlation key for the matching human_input
    prompt="Do you approve this action?",        # str | None - the question shown to the human
    options=["approve", "reject", "defer"],      # list[str] | None - choices presented to the human
    reason="approval_required",                  # str | None - why the agent is waiting
)

`event.human_input()`

Wird ausgelöst, wenn ein Mensch eine Eingabe bereitstellt und der Agent die Ausführung fortsetzt. Korreliert mit human_wait über input_id. duration_ms wird automatisch berechnet und darf nicht vom Aufrufer übergeben werden.

agenteye.event.human_input(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",    # str, required - must match the prior human_wait
    response="approve",    # str | None - the human's answer (free text or selected option)
    # duration_ms is computed automatically - do not pass it
)

`event.human_pause()`

Wird ausgelöst, wenn ein Mensch den Agenten aktiv pausiert (z. B. über eine Dashboard-Steuerung). Der Agent wird angehalten, aber nicht beendet.

agenteye.event.human_pause(
    session_id="run-001",
    agent_id="planner",
    reason="user_requested",  # str | None
    user_id="usr_42",         # str | None - who paused the agent
)

`event.human_interrupt()`

Wird ausgelöst, wenn ein Mensch den Agenten mitten in der Ausführung aktiv stoppt. Im Gegensatz zu human_pause wird die Arbeit des Agenten beendet und nicht nur ausgesetzt.

agenteye.event.human_interrupt(
    session_id="run-001",
    agent_id="planner",
    reason="output_incorrect",       # str | None
    user_id="usr_42",                # str | None - who interrupted the agent
    at_step="tool_use:web_search",   # str | None - what the agent was doing when stopped
)

Benutzerdefinierte Felder

Alle zusätzlichen Keyword-Argumente werden nach den Standardfeldern an das Event angehängt:

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="db_query",
    tool_call_id="toolu_02",
    tenant_id="acme",           # custom field
    region="us-east-1",         # custom field
)

timestamp, type und environment sind reserviert und lösen einen ValueError aus (Reserved field names cannot be used as custom fields: [...]), wenn sie als benutzerdefinierte Felder übergeben werden. session_id und agent_id sind Pflichtparameter bei jeder Event-Methode und können nicht ein zweites Mal übergeben werden; Python löst in diesem Fall einen TypeError aus. Setzen Sie die Umgebung stattdessen mit configure(environment=...) (oder der AGENTEYE_ENVIRONMENT-Variable). Halten Sie Payloads als strukturiertes JSON, wenn Sie deren Felder abfragen möchten. Werte, die JSON nicht nativ unterstützt — wie Datetimes, UUIDs, Decimals, Sets, Bytes oder Modell-Objekte — werden in Strings konvertiert, damit die Aufzeichnung sicher fortgesetzt werden kann.

Wie Events geschrieben werden

Events werden prozessintern gepuffert und alle flush_interval Sekunden (Standard: 500 ms) auf die Festplatte geschrieben. Jeder Flush schreibt eine JSONL-Datei:

~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl

Der Collector überwacht dieses Verzeichnis und lädt Dateien automatisch hoch. Sie müssen diese Dateien nicht direkt verwalten. Jede Datei wird atomar geschrieben: Das SDK schreibt in eine temporäre Datei und benennt sie dann an den endgültigen Ort um, sodass der Collector nie eine halbfertige Datei sieht. Ein abschließender Flush wird auch beim Beenden Ihres Prozesses ausgeführt, sodass im letzten Intervall gepufferte Events nicht verloren gehen. Wenn der Collector offline ist, sammeln sich Events einfach als Dateien auf der Festplatte an und werden übermittelt, sobald er wieder verfügbar ist.

Nächste Schritte

Event-Stream: Beobachten Sie, wie diese Events live ankommen, farblich kodiert und nach Umgebung, Agent und Session filterbar.
Sessions: Sehen Sie, wie die gepaarten Events jeden Agentenlauf als Ausführungsgraph und Zeitleiste rekonstruieren.

Overview

Features

SDK and CLI

Administration

Installation

Schnellstart

Einen echten Aufruf instrumentieren

configure()

Umgebung

Daten und Datenschutz

Event-Referenz

`event.agent_start()`

`event.agent_end()`

`event.tool_use()`

`event.tool_result()`

`event.model_request()`

`event.model_response()`

`event.hook_triggered()`

`event.hook_completed()`

`event.error()`

Human-in-the-Loop-Events

`event.human_wait()`

`event.human_input()`

`event.human_pause()`

`event.human_interrupt()`

Benutzerdefinierte Felder

Wie Events geschrieben werden

Nächste Schritte

​Installation

​Schnellstart

​Einen echten Aufruf instrumentieren

​configure()

​Umgebung

​Daten und Datenschutz

​Event-Referenz

​event.agent_start()

​event.agent_end()

​event.tool_use()

​event.tool_result()

​event.model_request()

​event.model_response()

​event.hook_triggered()

​event.hook_completed()

​event.error()

​Human-in-the-Loop-Events

​event.human_wait()

​event.human_input()

​event.human_pause()

​event.human_interrupt()

​Benutzerdefinierte Felder

​Wie Events geschrieben werden

​Nächste Schritte

Installation

Schnellstart

Einen echten Aufruf instrumentieren

configure()

Umgebung

Daten und Datenschutz

Event-Referenz

`event.agent_start()`

`event.agent_end()`

`event.tool_use()`

`event.tool_result()`

`event.model_request()`

`event.model_response()`

`event.hook_triggered()`

`event.hook_completed()`

`event.error()`

Human-in-the-Loop-Events

`event.human_wait()`

`event.human_input()`

`event.human_pause()`

`event.human_interrupt()`

Benutzerdefinierte Felder

Wie Events geschrieben werden

Nächste Schritte