Skill de Agente del SDK de Python para Observabilidad de Failproof AI

​

La instrumentación es fácil de escribir y fácil de equivocarse silenciosamente

​

Lo que hace, en orden

1. Planificar. Lee tu bucle de agente y hace las dos preguntas que solo tú puedes responder: qué cuenta como una ejecución (tu session_id) y quiénes son los actores distinguibles (tu agent_id). Llega a un acuerdo sobre eso antes de escribir código, porque cambiarlos después divide tu historial y rompe las tendencias.
2. Escribir. Vincula la identidad una sola vez por ejecución en lugar de propagarla por cada punto de llamada, y elige una forma segura para la concurrencia — un detalle que importa, porque el atajo obvio mezcla silenciosamente dos ejecuciones solapadas en una sola sesión.
3. Verificar. Ejecuta tu agente y lee los archivos de eventos resultantes, comprobando que agent_start está presente, que el entorno es correcto y que una ejecución produjo una sesión.

​

Cómo se relaciona con los otros skills

​

Prerequisitos

1. Python 3.10+ y la base de código del agente que quieres instrumentar.
2. El SDK. Se distribuye a los clientes como un wheel privado en lugar de un índice público — tu proceso de incorporación explica cómo obtenerlo e instalarlo. El skill conoce la ruta de instalación y te preguntará en lugar de adivinar si no puede encontrarla.
3. Nada más. Sin inicio de sesión en el dashboard, sin clave de API, sin red. El skill verifica contra los archivos de eventos que escribe el SDK, así que puede terminar y demostrar su trabajo sin conexión.

​

Dónde encontrarlo

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

​

Instalación manual

• Claude Code: copia la carpeta agenteye-python-sdk/ en ~/.claude/skills/ (todos los proyectos) o <tu-repo>/.claude/skills/ (solo ese repositorio). Claude Code la descubre automáticamente — revisa la lista /skills, o simplemente pregunta algo que coincida con él.
• Codex: Codex lee el mismo SKILL.md. El agents/openai.yaml incluido establece allow_implicit_invocation: true, por lo que se selecciona automáticamente cuando una tarea coincide; de lo contrario, invócalo como $agenteye-python-sdk.

​

Cómo luce una sesión

tú    ▸ Añade Observabilidad de Failproof AI a este agente.

agente▸ Leí tu bucle — un dispatcher de herramientas en tools.py, un
        wrapper de Anthropic en llm.py. Dos preguntas antes de escribir
        algo.

        ¿Qué cuenta como una ejecución? Manejas solicitudes de forma
        concurrente, así que usaría el id de solicitud que ya tienes en
        ctx.request_id — entonces una sesión aquí y una solicitud en tus
        logs serían el mismo string.

        ¿Y quiénes son los actores? Veo un camino de planificador y un
        camino de investigador. ¿Los etiqueto por separado, o para ti es
        un solo agente?

tú    ▸ El id de solicitud está bien. Es un solo agente, llámalo
        "assistant".

agente▸ Listo. Envolví el dispatcher y el cliente LLM; agent_start y
        agent_end delimitan handle_request, incluyendo el camino de
        error. Usé un contexto local para la identidad — tu dispatcher
        ejecuta herramientas en un pool de hilos, y el enfoque más simple
        habría mezclado ejecuciones concurrentes en una sola sesión sin
        quejarse.

        Verificado contra una ejecución real: 11 eventos en 4 archivos —
        agent_start, model_request/response, tool_use/tool_result x3,
        agent_end (outcome=success). environment=production, una sesión
        por solicitud, duraciones emparejadas.

        Una cosa que NO hice: tu pool de workers en batch.py envía
        directamente al executor, así que los eventos de ahí se
        descartarían. ¿Quieres que también los corrija?

​

Qué puedes pedirle

• “¿Por qué no aparece mi agente en el dashboard?” → recorre la escalera: ¿se están escribiendo los eventos?, ¿está agent_start?, ¿es correcto el entorno?, ¿está leyendo el colector desde el mismo lugar?
• “Todo está llegando bajo dev.” → el entorno nunca se configuró, o fue restablecido por una llamada posterior.
• “Añade seguimiento de tokens.” → encuentra tu wrapper de LLM y registra el modelo, el motivo de parada y el uso.
• “Instrumenta también los sub-agentes.” → una sesión, etiquetas de agente distintas, anidadas bajo su padre.
• “Escribe tests para la instrumentación.” → apunta el SDK a un directorio temporal y hace aserciones sobre los eventos escritos.

​

Qué tener en cuenta

​

Próximos pasos

• SDK de Python: la referencia completa de eventos — cada tipo de evento y campo — detrás de lo que automatiza este skill.
• Sesiones: lo que produce tu instrumentación una vez que los eventos llegan.
• Skill de Agente Evaluador: el siguiente paso una vez que las ejecuciones están llegando — puntuarlas.
• Skill de Agente CLI: leer tu telemetría de vuelta.