Agenti personalizzati

Cosa fa ogni impostazione, metodo e campo. Se stai strumentando per la prima volta, inizia con la guida — questa pagina serve per cercare le cose.

Guida agenti personalizzati

Installa, strumenta, i metodi degli eventi, un esempio completo e problemi comuni.

Stai usando un framework?

LangChain, CrewAI, LlamaIndex e Pydantic AI si strumentano automaticamente con una sola chiamata.

Python 3.10 o più recente. Nessuna dipendenza runtime.

Installa

pip install failproofai-sdk

Il pacchetto è installato come failproofai-sdk e importato in Python come failproofai_sdk. Gli extra dei framework come failproofai-sdk[langgraph] installano il framework stesso; gli adattatori vengono sempre forniti nella wheel di base.

Connetti il daemon Failproof

Dashboard
CLI

Vai su Admin → Keys e crea una chiave con events:add.
Connetti il daemon Failproof al Cloud sulla macchina dell’agente.
Esegui una sessione strumentata, quindi trova il suo ID esatto in Observe → Events.
Vai su Observe → Sessions, seleziona lo stesso ambiente e apri la traccia ricostruita.

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

Configurazione

import failproofai_sdk

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

Argomento	Cosa fa
`environment`	L’etichetta su ogni evento — `production`, `staging`, `prod-eu`. Il valore predefinito è `dev`.
`flush_interval`	Ogni quanto il thread in background scrive su disco, in secondi. Il valore predefinito è `0.5`.
`base_dir`	Dove scrivere. Il valore predefinito è lo spool del daemon, che è quello che vuoi a meno che tu non sappia diversamente.

Impostare tramite variabile di ambiente:

Variabile	Cosa fa
`AGENTEYE_ENVIRONMENT`	Imposta `environment` senza modificare il codice, per quando l’etichetta appartiene al deployment piuttosto che all’app. Un argomento `configure()` ha la precedenza.
`FAILPROOFAI_HOME`	Sposta la root di Failproof AI che contiene lo spool.
`FAILPROOFAI_SDK_STRICT`	`1` fa sollevare gli errori di strumentazione invece di registrarli.
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` fa sollevare un problema di compatibilità del framework invece di avvertire e continuare.

Niente virgole in environment. L’ingest divide quel campo su virgole per creare i suoi filtri e salta tutti gli eventi la cui etichetta ne contiene una — quindi un’intera esecuzione scompare silenziosamente. Scrivi prod-eu, non prod,eu.configure(environment="prod,eu") genera un’eccezione per farti scoprirlo immediatamente. AGENTEYE_ENVIRONMENT non può generare un’eccezione — nessuno ti sta chiamando — quindi avverte una volta e ricade a dev.

Gli eventi sono accodati in memoria e scritti in background ogni flush_interval secondi, con uno scarico finale all’uscita dell’interprete. Un processo ucciso immediatamente perde qualunque cosa non fosse stata ancora scritta.

Identità

Ogni evento appartiene a una sessione e un agente. Gli scope riempiono entrambi, quindi raramente li passi:

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

Passare session_id o agent_id esplicitamente funziona ancora e ha la precedenza. Senza né un vincolo né un passaggio, la chiamata genera TypeError piuttosto che emettere un evento che il Cloud scarterebbero silenziosamente.

L’identità si basa su variabili di contesto. Segue automaticamente i compiti asyncio, ma non i nuovi thread — avvolgi un worker in failproofai_sdk.propagate() o i suoi eventi rimangono scollati.

Catalogo degli eventi

Quindici metodi. La maggior parte arriva in coppie — chiami l’opener, poi il closer, e l’SDK misura il divario.

	Apre	Chiude
Agenti	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
Modelli	`model_request`	`model_response`
Strumenti	`tool_use`	`tool_result`
Hook	`hook_triggered`	`hook_completed`
Umani	`human_wait`	`human_input`

Tre sono indipendenti: error, human_pause, human_interrupt.

Ogni campo, per metodo

Ogni metodo accetta anche session_id e agent_id, che gli scope riempiono per te. Qualunque cosa rimanga come None viene scartata piuttosto che inviata come JSON null, e ogni metodo restituisce None.

Metodo	Richiesto	Opzionale
`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`

Per contrassegnare un’esecuzione come non riuscita, outcome deve essere uno di failed, error, timeout o rejected. Qualunque altro valore — incluso il quasi-colpo "failure" — conta come un successo.

Accoppiamento e durata

Una regola: dai all’evento di chiusura lo stesso id del suo opener. Questo è ciò che li accoppia e che permette all’SDK di misurare il divario.

Coppia	Abbinato su
`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`

Non passare duration_ms tu stesso. L’SDK lo misura e passarlo genera ValueError. L’unica eccezione è model_response, dove solo tu conosci la vera latenza del provider. Passa un numero intero di millisecondi — un float genera un’eccezione, perché la colonna è un intero a 32 bit e altrimenti sarebbe vuota.

Casi limite

Gli Id devono essere univoci solo per tipo, per sessione. Una chiamata a uno strumento e un hook possono condividerne uno; due sessioni in esecuzione contemporaneamente possono riutilizzare gli stessi id senza collisioni.
Non sono scoped a un agente. Una coppia aperta in un agente e chiusa in un altro corrisponde comunque — che è il caso normale nel codice multi-agente.
request_id è opzionale ma consigliato. Senza di esso, gli eventi del modello si accoppiano nell’ordine di arrivo, quindi due chiamate concorrenti nello stesso agente possono accoppiarsi male.
Una coppia divisa tra processi corrisponde comunque nel Cloud, ma l’SDK non può misurarla — nessuno in nessuno dei due processi ha visto entrambe le metà.
Al massimo 10.000 opener attendono un closer contemporaneamente. Oltre questo il più vecchio viene scartato, quindi una perdita non può crescere senza limiti.

I tuoi campi propri

Qualunque extra keyword che passi viene memorizzato con l’evento:

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

Preferisci tipi JSON se vuoi interrogarli in seguito. Qualunque altro — un UUID, un datetime, un Decimal, un set, bytes, un oggetto modello — viene memorizzato come stringa.

Prefissa i tuoi nomi di campo. Gli extra vengono applicati per ultimi, quindi un campo chiamato model, tool_name o outcome sovrascrive silenziosamente quello vero. Gli adattatori del framework usano fw_; fai lo stesso e niente può collidere.È anche per questo che un campo opzionale con errore di ortografia non genera mai un errore — diventa semplicemente un nuovo campo personalizzato. Se un campo standard manca nel Cloud, controlla prima l’ortografia.

Questi cinque nomi sono riservati e rifiutati immediatamente: timestamp, session_id, agent_id, type, environment.

Consegna e verifica

Dashboard
CLI

In Observe → Events, verifica che agent_start esista per primo e agent_end esista per ultimo. Quindi apri Observe → Sessions e conferma che gli eventi modello, strumento, umano, hook ed errore appaiano nell’ordine previsto. Usa l’ID della sessione come chiave di risoluzione dei problemi primaria.

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

Se il Cloud è vuoto, ispeziona $FAILPROOFAI_HOME/custom-agents/events, altrimenti ~/.failproofai/custom-agents/events. I file JSONL provano l’emissione dell’SDK; uno spool in crescita punta a configurazione del daemon o consegna, mentre uno spool vuoto punta a strumentazione o durata del processo.

Ispeziona lo spool solo quando il daemon è arrestato. Mentre è in esecuzione, raccoglie e cancella ogni batch in millisecondi, quindi un elenco di directory gara il collettore e mostra molti meno eventi di quelli emessi.

Prevenire errori in un runtime personalizzato

Usa i risultati dell’audit e le tracce collegate per definire l’azione non sicura, la prova richiesta e la risposta prevista. Un’integrazione di enforcement personalizzata deve esporre l’azione prima dell’esecuzione, passare il suo input strutturato al motore delle policy e applicare la decisione allow, instruct o deny risultante. Contatta Failproof AI e ti aiuteremo a mappare i confini di modello, strumento e ciclo di vita del tuo runtime agli hook delle policy, quindi convalidare l’integrazione con te.

Connect your agents

Reference

Guida agenti personalizzati

Stai usando un framework?

Installa

Connetti il daemon Failproof

Configurazione

Identità

Catalogo degli eventi

Accoppiamento e durata

I tuoi campi propri

Consegna e verifica

Prevenire errori in un runtime personalizzato

Guida agenti personalizzati

Stai usando un framework?

​Installa

​Connetti il daemon Failproof

​Configurazione

​Identità

​Catalogo degli eventi

​Accoppiamento e durata

​I tuoi campi propri

​Consegna e verifica

​Prevenire errori in un runtime personalizzato

Installa

Connetti il daemon Failproof

Configurazione

Identità

Catalogo degli eventi

Accoppiamento e durata

I tuoi campi propri

Consegna e verifica

Prevenire errori in un runtime personalizzato