Failproof AI Observability Python SDK Agent Skill

​

La strumentazione è facile da scrivere e facile da sbagliare senza accorgersene

​

Quello che fa, in ordine

1. Piano. Legge il tuo loop dell’agente e pone le due domande a cui solo tu puoi rispondere: cosa conta come una corsa (il tuo session_id) e chi sono gli attori distinguibili (il tuo agent_id). Ottiene un accordo su questi prima di scrivere il codice, perché cambiarli in seguito divide la tua cronologia e rompe le tendenze.
2. Scrivi. Associa l’identità una volta per corsa piuttosto che trascinandola in ogni sito di chiamata, e sceglie una forma thread-safe — un dettaglio che importa, perché la scorciatoia ovvia mescola silenziosamente due corse sovrapposte in una sessione.
3. Verifica. Esegue il tuo agente e legge i file di evento risultanti, verificando che agent_start sia presente, l’ambiente sia giusto e una corsa abbia prodotto una sessione.

​

Come si rapporta alle altre skill

​

Prerequisiti

1. Python 3.10+ e la codebase dell’agente che vuoi strumentare.
2. L’SDK. È distribuito ai clienti come wheel privata piuttosto che da un indice pubblico — il tuo onboarding copre come ottenerlo e installarlo. La skill conosce il percorso di installazione e ti chiederà piuttosto che indovinare se non riesce a trovarlo.
3. Nient’altro. Nessun accesso alla dashboard, nessuna chiave API, nessuna rete. La skill verifica sui file di evento che l’SDK scrive, quindi può terminare e provare il suo lavoro offline.

​

Dove trovarlo

npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code

​

Installarla manualmente

• Claude Code: copia la cartella agenteye-python-sdk/ in ~/.claude/skills/ (ogni progetto) o <your-repo>/.claude/skills/ (solo quel repo). Claude Code la scopre automaticamente — controlla l’elenco /skills o chiedi semplicemente qualcosa che corrisponda.
• Codex: Codex legge lo stesso SKILL.md. Il bundled agents/openai.yaml imposta allow_implicit_invocation: true, quindi è auto-selezionato quando un compito corrisponde; altrimenti invocalo come $agenteye-python-sdk.

​

L’aspetto di una sessione

tu    ▸ Aggiungi Failproof AI Observability a questo agente.

agente ▸ Leggo il tuo loop — un dispatcher di strumenti in tools.py, un wrapper
        Anthropic in llm.py. Due domande prima che scriva qualunque cosa.

        Cosa conta come una corsa? Gestisci richieste concorrentemente, quindi
        userei l'id della richiesta che hai già in ctx.request_id — allora una
        sessione qui e una richiesta nei tuoi log sono la stessa stringa.

        E chi sono gli attori? Vedo un percorso planner e un percorso
        researcher. Li etichetto separatamente, o è un agente per te?

tu    ▸ L'id della richiesta è corretto. Sono un agente, chiamalo "assistant".

agente ▸ Fatto. Ho avvolto il dispatcher e il client LLM; agent_start e
        agent_end racchiudono handle_request, incluso il percorso di errore.
        Ho usato un context-local per l'identità — il tuo dispatcher esegue
        gli strumenti in un thread pool, e l'approccio più semplice avrebbe
        mescolato le corse concorrenti in una sessione senza protestare.

        Verificato rispetto a una corsa reale: 11 eventi su 4 file —
        agent_start, model_request/response, tool_use/tool_result x3,
        agent_end (outcome=success). environment=production, una sessione
        per richiesta, durate accoppiate.

        Una cosa che NON ho fatto: il tuo worker pool in batch.py invia
        direttamente all'executor, quindi gli eventi da lì sarebbero eliminati.
        Vuoi che corregga anche quelli?

​

Quello che puoi chiedergli

• “Perché il mio agente non compare sulla dashboard?” → percorre la scala: gli eventi vengono scritti, c’è agent_start, l’ambiente è giusto, il collector legge lo stesso posto.
• “Tutto arriva sotto dev.” → l’ambiente non è mai stato impostato, o è stato reimpostato da una chiamata successiva.
• “Aggiungi il tracciamento dei token.” → trova il tuo wrapper LLM e registra il modello, la ragione di stop e l’utilizzo.
• “Strumenta anche i sub-agenti.” → una sessione, etichette di agente distinte, annidate sotto il loro genitore.
• “Scrivi test per la strumentazione.” → punta l’SDK a una directory temporanea e asserisce sugli eventi che ha scritto.

​

Quello che devi guardare

​

Prossimi passi

• Python SDK: il riferimento completo degli eventi — ogni tipo di evento e campo — dietro quello che questa skill automatizza.
• Sessions: quello che la tua strumentazione produce una volta che gli eventi arrivano.
• Evaluator Agent Skill: il prossimo passo una volta che le corse arrivano — assegna loro un punteggio.
• CLI Agent Skill: leggere la tua telemetria indietro.