Python SDK

Observez exactement ce que vos agents IA ont fait en production : chaque exécution d’agent, appel d’outil, requête de modèle, hook et intervention humaine. Le SDK Python d’observabilité Failproof AI enregistre cette trace depuis l’intérieur de votre code d’agent afin que vous puissiez déboguer, auditer et évaluer ce qui s’est passé. Utilisez-le chaque fois que vous souhaitez que Failproof AI Observability observe vos agents. En coulisses, le SDK écrit des événements structurés dans des fichiers JSONL locaux, et le daemon collecteur les récupère et les envoie automatiquement vers la plateforme. Vous n’avez pas à gérer ces fichiers vous-même.

Conseil : Vous découvrez Failproof AI Observability ? Cette page est la référence complète des événements du SDK.

Installation

Le SDK est distribué aux clients sous forme de wheel privé plutôt que depuis un index de paquets public. Votre processus d’intégration explique comment l’obtenir, l’installer et le figer — contactez votre interlocuteur Failproof AI si vous avez besoin d’un accès. Une fois installé, vérifiez qu’il est bien présent :

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

Vous préférez laisser un agent de codage gérer toute l’intégration ? Le Python SDK Agent Skill connaît le chemin d’installation, planifie les points d’instrumentation, les implémente et vérifie que les événements arrivent bien.

Démarrage rapide

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")

Instrumenter un appel réel

En pratique, vous enveloppez votre code d’agent existant. Encadrez un appel de modèle avec model_request avant et model_response après, afin que les deux événements couvrent la requête réelle et que Failproof AI Observability puisse les associer :

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],
)

Enveloppez les appels d’outils de la même manière avec tool_use et tool_result, en réutilisant le même tool_call_id pour les deux. Voici à quoi ressemblent ces événements une fois qu’ils arrivent dans le tableau de bord, codés par couleur selon leur type et filtrables par environnement, agent et session :

Le flux d'événements en direct, codé par couleur selon le type d'événement et filtrable par environnement, agent et session

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
)

Appelez cette fonction une seule fois avant tout appel event.*. Vous pouvez l’omettre en toute sécurité ; les valeurs par défaut fonctionnent directement. Tous les arguments sont uniquement nommés ; passez-les par nom comme indiqué ci-dessus. Lorsque base_dir vaut None (valeur par défaut), le SDK lit $AGENTEYE_HOME s’il est défini, sinon il utilise ~/.agenteye. Ce comportement correspond à la résolution propre du collecteur, ainsi une seule variable d’environnement AGENTEYE_HOME configure le spool d’événements partagé pour le SDK et le collecteur.

Environnement

Associez chaque événement à un environnement de déploiement (production, staging, qa, canary, etc.). Définissez-le une seule fois ; le SDK l’attache automatiquement à chaque événement. Option 1 : via configure() :

agenteye.configure(environment="production")

Option 2 : via une variable d’environnement :

export AGENTEYE_ENVIRONMENT=production

Priorité : configure(environment=...) prend le dessus sur la variable d’environnement. Si aucun des deux n’est défini, la valeur par défaut est "dev". La valeur d’environnement apparaît comme filtre de premier niveau dans le tableau de bord et est stockée sur le serveur pour des requêtes rapides.

Avertissement : Les valeurs d’environnement ne doivent pas contenir de virgule , littérale. Les filtres du tableau de bord utilisent une sélection multiple séparée par des virgules sur le réseau (?environment=prod,staging), donc un environnement nommé prod,blue serait divisé en deux valeurs. Les événements dont l’environnement contient une virgule sont rejetés lors de l’ingestion.

Données et confidentialité

Le SDK n’enregistre que les champs que vous passez explicitement. Les prompts, messages, entrées et sorties d’outils ainsi que le contenu des modèles sont capturés uniquement parce que vous les transmettez à un appel event.*. Rien n’est lu depuis votre processus ni capturé implicitement. Tout champ que vous ne définissez pas est omis de l’événement ; il n’est pas écrit sur le disque. La suppression des données sensibles est donc votre choix et votre responsabilité. Si un prompt ou une charge utile d’outil contient des données personnelles ou des secrets que vous préférez ne pas stocker, masquez-les ou supprimez-les avant de les passer à la méthode d’événement.

Référence des événements

La plupart des événements viennent par paires début/fin partageant un identifiant de corrélation : tool_use et tool_result partagent un tool_call_id, hook_triggered et hook_completed partagent un hook_id, et human_wait et human_input partagent un input_id. Émettez l’événement de début, effectuez le travail, puis émettez l’événement de fin avec le même identifiant. Failproof AI Observability associe la paire et calcule duration_ms pour vous, vous n’avez donc jamais à passer duration_ms vous-même.

Le graphe d'exécution de style git d'une session à côté de sa chronologie d'événements, reconstruit à partir des événements associés, avec le panneau de répartition outil/modèle/hook

Toutes les méthodes d’événement requièrent ces deux champs :

Champ	Type	Description
`session_id`	`str`	Identifie l’exécution de l’agent de niveau supérieur
`agent_id`	`str`	Identifie quel agent dans la session a émis l’événement

Toutes les méthodes acceptent également des **kwargs arbitraires pour des métadonnées personnalisées (voir Champs personnalisés).

`event.agent_start()`

Émis lorsqu’un agent commence à travailler.

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()`

Émis lorsqu’un agent termine son travail.

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

`event.tool_use()`

Émis lorsqu’un agent invoque un outil. À associer avec tool_result ; le SDK calcule automatiquement duration_ms.

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()`

Émis lorsqu’un outil retourne un résultat. Corrélé avec tool_use via 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()`

Émis juste avant l’envoi d’un prompt à un LLM.

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"}},
    ],
)

Les entrées de messages acceptent soit une content sous forme de chaîne simple, soit une content sous forme de liste de blocs de style Anthropic. Les paramètres d’échantillonnage (temperature, max_tokens, etc.) peuvent être passés en tant que kwargs supplémentaires.

`event.model_response()`

Émis lorsque le LLM retourne une réponse.

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 accepte soit une chaîne simple (fournisseurs génériques) soit une liste de blocs de contenu de style Anthropic. Les appels d’outils se trouvent dans content sous forme de blocs {"type": "tool_use", ...}, sans champ tool_calls séparé.

`event.hook_triggered()`

Émis lorsqu’un hook se déclenche. À associer avec hook_completed ; le SDK calcule automatiquement duration_ms.

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()`

Émis lorsqu’un hook se termine. Corrélé avec hook_triggered via 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()`

Émis lorsqu’une erreur non gérée survient.

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

Événements Human-in-the-Loop

Les événements human-in-the-loop vous donnent une visibilité sur les moments où une personne intervient dans l’exécution de l’agent (attente d’approbation, saisie d’informations, mise en pause ou arrêt de l’agent). Ils vous permettent de mesurer le temps que prennent les humains pour répondre (le SDK calcule automatiquement duration_ms sur les événements associés), d’auditer qui a mis en pause ou interrompu un agent, et de construire des workflows d’approbation et de supervision qui apparaissent dans le tableau de bord.

`event.human_wait()`

Émis lorsque l’agent suspend son exécution pour attendre qu’un humain fournisse une entrée. À associer avec human_input ; le SDK calcule automatiquement duration_ms (le temps que l’humain a mis pour répondre).

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()`

Émis lorsqu’un humain fournit une entrée et que l’agent reprend. Corrélé avec human_wait via input_id. duration_ms est calculé automatiquement et ne doit pas être passé par l’appelant.

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()`

Émis lorsqu’un humain met activement l’agent en pause (par exemple via un contrôle du tableau de bord). L’agent est suspendu mais pas terminé.

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()`

Émis lorsqu’un humain arrête activement l’agent en cours d’exécution. Contrairement à human_pause, le travail de l’agent est terminé plutôt que suspendu.

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
)

Champs personnalisés

Tout argument nommé supplémentaire est ajouté à l’événement après les champs standard :

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 et environment sont réservés et lèvent une ValueError (Reserved field names cannot be used as custom fields: [...]) s’ils sont passés comme champs personnalisés. session_id et agent_id sont des paramètres obligatoires sur chaque méthode d’événement et ne peuvent pas être fournis une seconde fois ; Python lève une TypeError si vous le faites. Définissez l’environnement avec configure(environment=...) (ou la variable AGENTEYE_ENVIRONMENT) à la place. Conservez les charges utiles en JSON structuré lorsque vous souhaitez interroger leurs champs. Les valeurs que JSON ne prend pas nativement en charge — telles que les datetimes, UUIDs, décimales, ensembles, bytes ou objets de modèle — sont converties en chaînes afin que l’enregistrement se poursuive en toute sécurité.

Comment les événements sont écrits

Les événements sont mis en mémoire tampon dans le processus et vidés sur le disque toutes les flush_interval secondes (par défaut 500 ms). Chaque vidage écrit un fichier JSONL :

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

Le collecteur surveille ce répertoire et télécharge les fichiers automatiquement. Vous n’avez pas besoin de gérer ces fichiers directement. Chaque fichier est écrit de manière atomique : le SDK écrit dans un fichier temporaire puis le renomme à sa place définitive, ainsi le collecteur ne voit jamais un fichier partiellement écrit. Un vidage final est également effectué à la fermeture de votre processus, afin que les événements mis en mémoire tampon lors du dernier intervalle ne soient pas perdus. Si le collecteur est hors ligne, les événements s’accumulent simplement sous forme de fichiers sur le disque et sont envoyés dès qu’il revient en ligne.

Étapes suivantes

Flux d’événements : regardez ces événements arriver en direct, codés par couleur et filtrables par environnement, agent et session.
Sessions : découvrez comment les événements associés reconstituent chaque exécution d’agent sous forme de graphe d’exécution et de chronologie.

Overview

Features

SDK and CLI

Administration

Installation

Démarrage rapide

Instrumenter un appel réel

configure()

Environnement

Données et confidentialité

Référence des événements

`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()`

Événements Human-in-the-Loop

`event.human_wait()`

`event.human_input()`

`event.human_pause()`

`event.human_interrupt()`

Champs personnalisés

Comment les événements sont écrits

Étapes suivantes

​Installation

​Démarrage rapide

​Instrumenter un appel réel

​configure()

​Environnement

​Données et confidentialité

​Référence des événements

​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()

​Événements Human-in-the-Loop

​event.human_wait()

​event.human_input()

​event.human_pause()

​event.human_interrupt()

​Champs personnalisés

​Comment les événements sont écrits

​Étapes suivantes

Installation

Démarrage rapide

Instrumenter un appel réel

configure()

Environnement

Données et confidentialité

Référence des événements

`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()`

Événements Human-in-the-Loop

`event.human_wait()`

`event.human_input()`

`event.human_pause()`

`event.human_interrupt()`

Champs personnalisés

Comment les événements sont écrits

Étapes suivantes