Python sdk

title: “Python SDK” description: “Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione dell’agente, chiamata di strumento, richiesta del modello, hook e intervento umano.”

Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione dell’agente, chiamata di strumento, richiesta del modello, hook e intervento umano. L’SDK Python per l’Observability di Failproof AI registra questa traccia dall’interno del codice del tuo agente, così puoi eseguire il debug, audit e valutazione di ciò che è accaduto. Usalo ogni volta che vuoi che Failproof AI Observability osservi i tuoi agenti. Sotto il cofano, l’SDK scrive eventi strutturati in file JSONL locali e il daemon collector li preleva e li invia automaticamente alla piattaforma. Non devi gestire tu stesso questi file.

Consiglio: Nuovo a Failproof AI Observability? Questa pagina è il riferimento completo degli eventi SDK.

Installazione

L’SDK viene distribuito ai clienti come wheel privato piuttosto che da un indice di pacchetti pubblico. L’onboarding copre come ottenerlo, installarlo e pinarlo — parla con il tuo contatto Failproof AI se hai bisogno di accesso. Una volta installato, confermalo:

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

Preferisci lasciare che un agente di codifica gestisca l’intera integrazione? L’Agent Skill Python SDK conosce il percorso di installazione, pianifica i punti di strumentazione, li scrive e verifica che gli eventi arrivino.

Quick Start

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

Strumentazione di una chiamata reale

In pratica racchiudi il tuo codice agente esistente. Circonda una chiamata al modello con model_request prima e model_response dopo, in modo che i due eventi abbracciamo la richiesta reale e Failproof AI Observability possa abbinarli:

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

Racchiudi le chiamate ai strumenti allo stesso modo con tool_use e tool_result, riutilizzando uno stesso tool_call_id per la coppia. Ecco come appaiono questi eventi una volta raggiunto il dashboard, codificati per colore per tipo e filtrabili per ambiente, agente e sessione:

Lo stream live degli Events, codificato per colore per tipo di evento e filtrabile per ambiente, agente e sessione

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
)

Chiamalo una volta prima di qualsiasi chiamata event.*. Sicuro da omettere; i valori predefiniti funzionano subito. Tutti gli argomenti sono solo keyword; passali per nome come mostrato sopra. Quando base_dir è None (il valore predefinito), l’SDK legge $AGENTEYE_HOME se impostato, altrimenti ricade a ~/.agenteye. Questo corrisponde alla risoluzione del collector stesso, quindi una singola variabile env AGENTEYE_HOME configura lo spool di eventi condiviso per entrambi l’SDK e il collector.

Ambiente

Etichetta ogni evento con un ambiente di deployment (production, staging, qa, canary, ecc.). Impostalo una volta; l’SDK lo allega a ogni evento automaticamente. Opzione 1: via configure():

agenteye.configure(environment="production")

Opzione 2: via variabile d’ambiente:

export AGENTEYE_ENVIRONMENT=production

Priorità: configure(environment=...) prevale sulla variabile d’ambiente. Se nessuno è impostato, il valore predefinito è "dev". Il valore dell’ambiente appare come filtro di prima classe nel dashboard ed è memorizzato sul server per query veloci.

Avvertenza: I valori dell’ambiente non devono contenere una virgola letterale ,. I filtri del dashboard utilizzano multi-select separato da virgole sul filo (?environment=prod,staging), quindi un ambiente denominato prod,blue verrebbe diviso in due valori. Gli eventi con ambienti contenenti virgole vengono rifiutati al momento dell’ingestione.

Dati e privacy

L’SDK registra solo i campi che tu esplicitamente passi. Prompt, messaggi, input e output dei strumenti e il contenuto del modello vengono catturati solo perché li consegni a una chiamata event.*. Nulla viene letto dal tuo processo o catturato implicitamente. Qualsiasi campo che lasci non impostato viene omesso dall’evento interamente; non viene scritto su disco. Questo rende la redazione tua scelta e tua responsabilità. Se un prompt o payload dello strumento contiene PII o segreti che preferisci non memorizzare, rimuovili o mascherali prima di passarli al metodo dell’evento.

Riferimento degli eventi

La maggior parte degli eventi viene in coppie start/end che condividono un ID di correlazione: tool_use e tool_result condividono un tool_call_id, hook_triggered e hook_completed condividono un hook_id, e human_wait e human_input condividono un input_id. Emetti l’evento di inizio, fai il lavoro, poi emetti l’evento di fine con lo stesso ID. Failproof AI Observability abbina la coppia e calcola duration_ms per te, così non passi mai duration_ms da solo.

Un grafo di esecuzione in stile git di una sessione accanto alla sua timeline degli eventi, ricostruito da eventi appaiati, con il pannello di breakdown strumento/modello/hook

Tutti i metodi degli eventi richiedono questi due campi:

Campo	Tipo	Descrizione
`session_id`	`str`	Identifica l’esecuzione dell’agente di livello superiore
`agent_id`	`str`	Identifica quale agente all’interno della sessione ha emesso l’evento

Tutti i metodi accettano anche **kwargs arbitrari per metadati personalizzati (vedi Custom Fields).

`event.agent_start()`

Emesso quando un agente inizia il lavoro.

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

Emesso quando un agente termina il lavoro.

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

`event.tool_use()`

Emesso quando un agente invoca uno strumento. Accoppia con tool_result; l’SDK calcola automaticamente 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()`

Emesso quando uno strumento ritorna. Si correla con 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()`

Emesso appena prima di inviare un prompt a 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"}},
    ],
)

Le voci messages accettano sia un content di stringa semplice che Anthropic-style list-of-blocks content. I parametri di campionamento (temperature, max_tokens, ecc.) possono essere passati come kwargs extra.

`event.model_response()`

Emesso quando l’LLM ritorna una risposta.

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 accetta sia una stringa semplice (provider generici) che una lista di content blocks in stile Anthropic. Le chiamate ai strumenti vivono dentro content come blocchi {"type": "tool_use", ...}, senza un campo tool_calls separato.

`event.hook_triggered()`

Emesso quando un hook si attiva. Accoppia con hook_completed; l’SDK calcola automaticamente 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()`

Emesso quando un hook termina. Si correla con 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()`

Emesso quando si verifica un errore non gestito.

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

Eventi Human-in-the-Loop

Gli eventi human-in-the-loop ti danno visibilità sui momenti in cui una persona entra nell’esecuzione dell’agente (in attesa di approvazione, fornitura di input, pausa o arresto dell’agente). Ti permettono di misurare quanto tempo gli umani impiegano a rispondere (l’SDK calcola automaticamente duration_ms sugli eventi appaiati), audit chi ha messo in pausa o interrotto un agente, e di costruire flussi di lavoro di approvazione e supervisione che emergono nel dashboard.

`event.human_wait()`

Emesso quando l’agente mette in pausa l’esecuzione per attendere che un umano fornisca input. Accoppia con human_input; l’SDK calcola automaticamente duration_ms (quanto tempo l’umano ha impiegato a rispondere).

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

Emesso quando un umano fornisce input e l’agente riprende. Si correla con human_wait via input_id. duration_ms viene calcolato automaticamente e non deve essere passato dal chiamante.

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

Emesso quando un umano mette attivamente in pausa l’agente (ad es. tramite un controllo del dashboard). L’agente è sospeso ma non terminato.

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

Emesso quando un umano arresta attivamente l’agente a metà dell’esecuzione. A differenza di human_pause, il lavoro dell’agente viene terminato piuttosto che sospeso.

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
)

Custom Fields

Qualsiasi argomento di parola chiave extra viene aggiunto all’evento dopo i campi 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, e environment sono riservati e sollevano ValueError (Reserved field names cannot be used as custom fields: [...]) se passati come custom fields. session_id e agent_id sono parametri richiesti su ogni metodo dell’evento e non possono essere forniti una seconda volta; Python solleva TypeError se lo fai. Imposta l’ambiente con configure(environment=...) (o la variabile AGENTEYE_ENVIRONMENT) invece. Mantieni i payload come JSON strutturato quando vuoi interrogare i loro campi. I valori che JSON non supporta nativamente — come datetime, UUID, decimali, set, byte o oggetti modello — vengono convertiti in stringhe in modo che la registrazione continui in sicurezza.

Come vengono scritti gli eventi

Gli eventi vengono memorizzati nel buffer in-process e svuotati su disco ogni flush_interval secondi (default 500 ms). Ogni flush scrive un file JSONL:

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

Il collector guarda questa directory e carica i file automaticamente. Non hai bisogno di gestire questi file direttamente. Ogni file viene scritto atomicamente: l’SDK scrive in un file temporaneo e poi lo rinomina in posizione, quindi il collector non vede mai un file a metà della scrittura. Un flush finale è anche eseguito quando il tuo processo esce, quindi gli eventi memorizzati nell’intervallo finale non vengono persi. Se il collector è offline, gli eventi semplicemente si accumulano come file su disco e vengono inviati una volta che torna online.

Prossimi step

Event stream: guarda questi eventi arrivare in tempo reale, codificati per colore e filtrabili per ambiente, agente e sessione.
Sessions: vedi come gli eventi appaiati ricostruiscono ogni esecuzione dell’agente come un grafo di esecuzione e timeline.

Overview

Features

SDK and CLI

Administration

title: “Python SDK” description: “Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione dell’agente, chiamata di strumento, richiesta del modello, hook e intervento umano.”

Installazione

Quick Start

Strumentazione di una chiamata reale

configure()

Ambiente

Dati e privacy

Riferimento degli eventi

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

Eventi Human-in-the-Loop

`event.human_wait()`

`event.human_input()`

`event.human_pause()`

`event.human_interrupt()`

Custom Fields

Come vengono scritti gli eventi

Prossimi step

​title: “Python SDK” description: “Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione dell’agente, chiamata di strumento, richiesta del modello, hook e intervento umano.”

​Installazione

​Quick Start

​Strumentazione di una chiamata reale

​configure()

​Ambiente

​Dati e privacy

​Riferimento degli eventi

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

​Eventi Human-in-the-Loop

​event.human_wait()

​event.human_input()

​event.human_pause()

​event.human_interrupt()

​Custom Fields

​Come vengono scritti gli eventi

​Prossimi step

title: “Python SDK” description: “Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione dell’agente, chiamata di strumento, richiesta del modello, hook e intervento umano.”

Installazione

Quick Start

Strumentazione di una chiamata reale

configure()

Ambiente

Dati e privacy

Riferimento degli eventi

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

Eventi Human-in-the-Loop

`event.human_wait()`

`event.human_input()`

`event.human_pause()`

`event.human_interrupt()`

Custom Fields

Come vengono scritti gli eventi

Prossimi step