Python sdk skill

​

title: “Failproof AI Observability Python SDK Agent Skill” description: “Da un agente senza strumentazione a eventi che puoi visualizzare, con il tuo agente di codifica che trova i punti di strumentazione, li scrive e verifica che siano stati implementati.”

​

La strumentazione è facile da scrivere e facile da sbagliare silenziosamente

​

Quello che fa, in ordine

1. Pianificazione. Legge il tuo loop di agente e pone le due domande a cui solo tu puoi rispondere: cosa conta come un’esecuzione (il tuo session_id) e chi sono gli attori distinguibili (il tuo agent_id). Raggiunge un accordo su queste questioni prima di scrivere codice, perché cambiarle in seguito dividerà la tua cronologia e romperà i trend.
2. Scrittura. Associa l’identità una volta per esecuzione piuttosto che trascinandola attraverso ogni sito di chiamata, e sceglie una forma thread-safe — un dettaglio importante, perché il collegamento ovvio silenziosamente mescola due esecuzioni 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 corretto e che un’esecuzione abbia prodotto una sessione.

​

Come si relaziona con le altre skill

​

Prerequisiti

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

​

Dove ottenerla

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 la lista /skills, o chiedile semplicemente qualcosa che corrisponda.
• Codex: Codex legge lo stesso SKILL.md. Il agents/openai.yaml incluso imposta allow_implicit_invocation: true, quindi è auto-selezionato quando un’attività corrisponde; altrimenti invocalo come $agenteye-python-sdk.

​

Che aspetto ha una sessione

you   ▸ Add Failproof AI Observability to this agent.

agent ▸ Read your loop — one tool dispatcher in tools.py, one Anthropic
        wrapper in llm.py. Two questions before I write anything.

        What counts as one run? You handle requests concurrently, so I'd
        use the request id you already have in ctx.request_id — then a
        session here and a request in your logs are the same string.

        And who are the actors? I see a planner path and a researcher
        path. Label them separately, or is that one agent to you?

you   ▸ Request id is right. They're one agent, call it "assistant".

agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and
        agent_end bracket handle_request, including the error path. Used
        a context-local for identity — your dispatcher runs tools in a
        thread pool, and the simpler approach would have mixed concurrent
        runs into one session without complaining.

        Verified against a real run: 11 events across 4 files —
        agent_start, model_request/response, tool_use/tool_result x3,
        agent_end (outcome=success). environment=production, one session
        per request, durations paired.

        One thing I did NOT do: your worker pool in batch.py submits
        straight to the executor, so events from there would be dropped.
        Want me to fix those too?

​

Quello che puoi chiederle

• “Perché il mio agente non appare nel dashboard?” → percorre la scala: gli eventi vengono scritti, c’è agent_start, l’ambiente è giusto, il collector legge lo stesso posto.
• “Tutto sta atterrando sotto dev.” → l’ambiente non è mai stato impostato, oppure è stato resettato da una chiamata successiva.
• “Aggiungi token tracking.” → 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, nidificate sotto il loro genitore.
• “Scrivi test per la strumentazione.” → punta l’SDK a una directory temporanea e asserisce sugli eventi che ha scritto.

​

Cosa guardare

​

Prossimi passi

• Python SDK: il riferimento completo degli eventi — ogni tipo di evento e campo — dietro ciò che questa skill automatizza.
• Sessions: quello che la tua strumentazione produce una volta che gli eventi arrivano.
• Evaluator Agent Skill: il passo successivo una volta che le esecuzioni arrivano — valutarle.
• CLI Agent Skill: leggere la tua telemetria indietro.