Skip to main content
Cosa fanno ogni impostazione, metodo e campo. Se stai strumentando per la prima volta, inizia con la guida — questa pagina è per cercare le cose.

Guida agli agenti personalizzati

Installazione, strumentazione, i metodi degli eventi, un esempio pratico e problemi comuni.

Usi un framework?

LangChain, CrewAI, LlamaIndex e Pydantic AI si strumentano da soli con una sola chiamata.
Python 3.10 o più recente. Nessuna dipendenza di runtime.

​
Installazione

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

​
Connetti il daemon Failproof

  1. Vai a Admin → Keys e crea una chiave con events:add.
  2. Connetti il daemon Failproof al Cloud sulla macchina dell’agente.
  3. Esegui una sessione strumentata, quindi trova il suo ID esatto in Observe → Events.
  4. Vai a Observe → Sessions, seleziona lo stesso ambiente e apri la traccia ricostruita. Una sessione di agente Python personalizzato ricostruita come grafico di esecuzione e traccia di eventi ordinata.

​
Configurazione

Imposta tramite variabile d’ambiente invece:
Nessuna virgola in environment. L’ingest divide quel campo su virgole per costruire i suoi filtri e salta qualsiasi evento la cui etichetta ne contiene una — quindi un’intera esecuzione scompare silenziosamente. Scrivi prod-eu, non prod,eu.configure(environment="prod,eu") solleva un errore in modo da scoprirlo immediatamente. AGENTEYE_ENVIRONMENT non può sollevare — nessuno ti sta chiamando — quindi avverte una volta e ritorna a dev.
Gli eventi sono accodati in memoria e scritti in background ogni flush_interval secondi, con un flush finale all’uscita dell’interprete. Un processo ucciso bruscamente perde tutto ciò che non era stato ancora scritto.

​
Identità

Ogni evento appartiene a una sessione e un agente. Gli scope compilano entrambi, quindi raramente li passi:
Passare session_id o agent_id esplicitamente funziona ancora e prevale. Senza né binding né passaggio, la chiamata solleva TypeError anziché emettere un evento che Cloud scapterebbe silenziosamente.
L’identità si basa su variabili di contesto. Segue automaticamente i task asyncio, ma non i nuovi thread — avvolgi un worker in failproofai_sdk.propagate() o i suoi eventi finiscono scollati.

​
Catalogo degli eventi

Quindici metodi. La maggior parte vengono in coppie — chiami l’apertura, quindi la chiusura, e l’SDK misura l’intervallo. Tre sono indipendenti: error, human_pause, human_interrupt.
Ogni metodo accetta anche session_id e agent_id, che gli scope compilano per te. Qualsiasi cosa lasciata come None viene scartata anziché essere inviata come JSON null, e ogni metodo restituisce None.
Per contrassegnare un’esecuzione come non riuscita, outcome deve essere uno di failed, error, timeout o rejected. Qualsiasi altro valore — incluso il quasi-match "failure" — conta come un successo.

​
Associazione e durata

Una regola: dai all’evento di chiusura lo stesso id del suo apertura. È questo che li associa e che consente all’SDK di misurare l’intervallo. Non passare duration_ms tu stesso. L’SDK lo misura e passarlo solleva ValueError. L’unica eccezione è model_response, dove solo tu conosci la vera latenza del provider. Passa un numero intero di millisecondi — un float solleva un errore perché la colonna è un intero a 32 bit e altrimenti atterrerebbe vuota.
  • Gli id devono essere univoci solo per tipo, per sessione. Una chiamata di 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 sotto un agente e chiusa sotto un altro corrisponde ancora — che è il caso normale nel codice multi-agente.
  • request_id è opzionale ma consigliato. Senza di esso, gli eventi del modello si associano nell’ordine in cui arrivano, quindi due chiamate simultanee nello stesso agente possono associarsi male.
  • Una coppia divisa tra processi corrisponde ancora nel Cloud, ma l’SDK non può misurarla — nulla in entrambi i processi ha visto entrambe le metà.
  • Al massimo 10.000 aperture attendono una chiusura contemporaneamente. Oltre questo la più vecchia viene scartata, quindi una perdita non può crescere senza limiti.

​
I tuoi campi personalizzati

Qualsiasi extra keyword che passi viene archiviato con l’evento:
Preferisci i tipi JSON se vuoi interrogarli in seguito. Qualsiasi altra cosa — un UUID, un datetime, un Decimal, un set, bytes, un oggetto modello — viene archiviata come stringa.
Prefissa i nomi dei tuoi campi. Gli extra vengono applicati per ultimi, quindi un campo chiamato model, tool_name o outcome sovrascrive silenziosamente quello reale. Gli adattatori del framework usano fw_; fai lo stesso e nulla può collidere.Questo è anche il motivo per cui un campo opzionale con errori di ortografia non solleva mai — diventa solo un nuovo campo personalizzato. Se un campo standard manca nel Cloud, controlla prima l’ortografia.
Questi cinque nomi sono riservati e rifiutati completamente: timestamp, session_id, agent_id, type, environment.

​
Consegnare e verificare

In Observe → Events, verifica che agent_start esista prima e agent_end esista per ultimo. Quindi apri Observe → Sessions e conferma che gli eventi di modello, strumento, umano, hook e errore appaiano nell’ordine previsto. Usa l’ID sessione come chiave di risoluzione dei problemi principale.
Se Cloud è vuoto, ispeziona $FAILPROOFAI_HOME/custom-agents/events, altrimenti ~/.failproofai/custom-agents/events. I file JSONL provano l’emissione dell’SDK; uno spool crescente indica un daemon o una consegna configurazione, mentre uno spool vuoto indica un’instrumentazione o una durata del processo.
Ispeziona lo spool solo quando il daemon è arrestato. Mentre è in esecuzione, raccoglie ed elimina ogni batch entro millisecondi, quindi un elenco di directory corre con il collezionista e mostra molti meno eventi di quelli che sono stati emessi.

​
Prevenire errori in un runtime personalizzato

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