Skip to main content
Qué hace cada ajuste, método y campo. Si estás instrumentando por primera vez, comienza con la guía — esta página es para consultas de referencia.

Guía de agentes personalizados

Instalación, instrumentación, los métodos de eventos, un ejemplo práctico y problemas comunes.

¿Usas un framework?

LangChain, CrewAI, LlamaIndex y Pydantic AI se instrumentan solos con una sola llamada.
Python 3.10 o superior. Sin dependencias en tiempo de ejecución.

​
Instalación

El paquete se instala como failproofai-sdk y se importa en Python como failproofai_sdk. Los extras de framework como failproofai-sdk[langgraph] instalan el framework en sí; los adaptadores siempre se incluyen en el wheel base.

​
Conectar el daemon de Failproof

  1. Ve a Admin → Keys y crea una clave con events:add.
  2. Conecta el daemon de Failproof a Cloud en la máquina del agente.
  3. Ejecuta una sesión instrumentada y luego encuentra su ID exacto en Observe → Events.
  4. Ve a Observe → Sessions, selecciona el mismo entorno y abre la traza reconstruida. Una sesión de agente Python personalizado reconstruida como grafo de ejecución y traza de eventos ordenada.

​
Configuración

También se puede configurar mediante variables de entorno:
Sin comas en environment. La ingesta divide ese campo por comas para construir sus filtros, y omite cualquier evento cuya etiqueta contenga una — así una ejecución entera desaparece silenciosamente. Escribe prod-eu, no prod,eu.configure(environment="prod,eu") lanza una excepción para que lo detectes de inmediato. AGENTEYE_ENVIRONMENT no puede lanzar excepciones — nadie te está llamando — por lo que advierte una vez y recurre a dev.
Los eventos se encolan en memoria y se escriben en segundo plano cada flush_interval segundos, con un flush final al salir del intérprete. Un proceso que se mata bruscamente pierde lo que aún no se había escrito.

​
Identidad

Cada evento pertenece a una sesión y a un agente. Los scopes rellenan ambos, por lo que rara vez necesitas pasarlos:
Pasar session_id o agent_id explícitamente sigue funcionando y tiene prioridad. Si no hay ninguno vinculado ni pasado, la llamada lanza TypeError en lugar de emitir un evento que Cloud descartaría silenciosamente.
La identidad viaja en variables de contexto. Sigue las tareas de asyncio automáticamente, pero no los nuevos hilos — envuelve un worker con failproofai_sdk.propagate() o sus eventos quedarán sin adjuntar.

​
Catálogo de eventos

Quince métodos. La mayoría vienen en pares — llamas al abridor y luego al cierre, y el SDK mide el tiempo entre ambos. Tres son independientes: error, human_pause, human_interrupt.
Cada método también acepta session_id y agent_id, que los scopes rellenan por ti. Cualquier campo que quede como None se descarta en lugar de enviarse como JSON null, y cada método devuelve None.
Para marcar una ejecución como fallida, outcome debe ser uno de failed, error, timeout o rejected. Cualquier otro valor — incluido el parecido "failure" — se cuenta como éxito.

​
Emparejamiento y duración

Una regla: dale al evento de cierre el mismo id que al de apertura. Eso es lo que los empareja y lo que permite al SDK medir el tiempo transcurrido. No pases duration_ms tú mismo. El SDK lo mide, y pasarlo lanza un ValueError. La única excepción es model_response, donde solo tú conoces la latencia real del proveedor. Pasa un número entero de milisegundos — un float lanza una excepción, porque la columna es un entero de 32 bits y de lo contrario quedaría vacía.
  • Los ids solo necesitan ser únicos por tipo y por sesión. Una llamada a herramienta y un hook pueden compartir el mismo id; dos sesiones que se ejecuten a la vez pueden reutilizar los mismos ids sin colisionar.
  • No están limitados al ámbito de un agente. Un par abierto bajo un agente y cerrado bajo otro sigue emparejándose — que es el caso habitual en código multiagente.
  • request_id es opcional pero recomendado. Sin él, los eventos de modelo se emparejan en el orden en que llegan, por lo que dos llamadas concurrentes en el mismo agente pueden emparejarse incorrectamente.
  • Un par dividido entre procesos sigue emparejándose en Cloud, pero el SDK no puede cronometrarlo — ninguno de los dos procesos vio ambas mitades.
  • Como máximo 10.000 aperturas pueden esperar un cierre a la vez. Pasado ese límite se descarta la más antigua, de modo que una fuga no puede crecer sin límite.

​
Tus propios campos

Cualquier palabra clave adicional que pases se almacena junto al evento:
Prefiere tipos JSON si quieres consultarlos más adelante. Cualquier otra cosa — un UUID, un datetime, un Decimal, un set, bytes, un objeto de modelo — se almacena como cadena de texto.
Usa un prefijo en los nombres de tus campos. Los extras se aplican al final, por lo que un campo llamado model, tool_name o outcome sobreescribirá silenciosamente el valor real. Los adaptadores de framework usan fw_; haz lo mismo y nada podrá colisionar.Esta es también la razón por la que un campo opcional mal escrito nunca genera un error — simplemente se convierte en un nuevo campo personalizado. Si falta un campo estándar en Cloud, revisa primero la ortografía.
Estos cinco nombres están reservados y se rechazan directamente: timestamp, session_id, agent_id, type, environment.

​
Entrega y verificación

En Observe → Events, verifica que agent_start existe primero y agent_end existe al final. Luego abre Observe → Sessions y confirma que los eventos de modelo, herramienta, humanos, hooks y errores aparecen en el orden previsto. Usa el ID de sesión como clave principal para la resolución de problemas.
Si Cloud está vacío, inspecciona $FAILPROOFAI_HOME/custom-agents/events, o en su defecto ~/.failproofai/custom-agents/events. Los archivos JSONL prueban la emisión del SDK; un spool en crecimiento apunta a la configuración del daemon o a la entrega, mientras que un spool vacío apunta a la instrumentación o al ciclo de vida del proceso.
Inspecciona el spool solo cuando el daemon esté detenido. Mientras está en ejecución, recopila y elimina cada lote en milisegundos, por lo que un listado del directorio compite con el colector y mostrará muchos menos eventos de los que se emitieron.

​
Prevenir fallos en un runtime personalizado

Usa los hallazgos de auditoría y las trazas vinculadas para definir la acción no segura, la evidencia requerida y la respuesta prevista. Una integración de aplicación de políticas personalizada debe exponer la acción antes de su ejecución, pasar su entrada estructurada al motor de políticas y aplicar la decisión resultante de allow, instruct o deny. Contacta con Failproof AI y te ayudaremos a mapear los límites de modelo, herramienta y ciclo de vida de tu runtime a los hooks de política, y luego validaremos la integración contigo.