Agentes personalizados

Qué hace cada configuración, método y campo. Si es la primera vez que instrumentas, empieza por la guía — esta página es solo de referencia.

Guía de agentes personalizados

Instalación, instrumentación, métodos de evento, un ejemplo completo y problemas frecuentes.

¿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.

Instalar

pip install failproofai-sdk

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 propio framework; los adaptadores siempre vienen incluidos en el wheel base.

Conectar el daemon de Failproof

Dashboard
CLI

Ve a Admin → Keys y crea una clave con events:add.
Conecta el daemon de Failproof a Cloud en la máquina del agente.
Ejecuta una sesión instrumentada y luego busca su ID exacto en Observe → Events.
Ve a Observe → Sessions, selecciona el mismo entorno y abre el trace reconstruido.

Lee la clave events:add en el shell. read -s la solicita en un prompt que no la muestra en pantalla, por lo que nunca aparece en un comando ni en el historial del shell:

read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN

Luego configura la máquina y verifica que se haya conectado:

failproofai config
failproofai config --status

Configuración

import failproofai_sdk

failproofai_sdk.configure(
    base_dir=None,
    flush_interval=0.5,
    environment="production",
)

Argumento	Qué hace
`environment`	La etiqueta en cada evento: `production`, `staging`, `prod-eu`. Por defecto es `dev`.
`flush_interval`	Con qué frecuencia el hilo en segundo plano escribe en disco, en segundos. Por defecto es `0.5`.
`base_dir`	Dónde escribir. Por defecto usa el spool del daemon, que es lo que necesitas salvo que sepas exactamente lo que haces.

Configurable también mediante variables de entorno:

Variable	Qué hace
`AGENTEYE_ENVIRONMENT`	Establece `environment` sin modificar el código, para cuando la etiqueta pertenece al despliegue y no a la aplicación. Un argumento de `configure()` tiene prioridad sobre ella.
`FAILPROOFAI_HOME`	Mueve la raíz de Failproof AI que contiene el spool.
`FAILPROOFAI_SDK_STRICT`	`1` hace que los errores de instrumentación lancen una excepción en lugar de registrarse.
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` hace que un problema de compatibilidad con el framework lance una excepción en lugar de advertir y continuar.

Sin comas en environment. La ingesta divide ese campo por comas para construir sus filtros y descarta cualquier evento cuya etiqueta contenga una, por lo que una ejecución entera desaparece silenciosamente. Escribe prod-eu, no prod,eu.configure(environment="prod,eu") lanza una excepción para que te enteres de inmediato. AGENTEYE_ENVIRONMENT no puede lanzar excepciones — nadie te está llamando — así que advierte una vez y vuelve 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 cierra abruptamente pierde todo lo que no se había escrito todavía.

Identidad

Cada evento pertenece a una sesión y a un agente. Los scopes rellenan ambos automáticamente, así que raramente necesitas pasarlos:

with failproofai_sdk.session():
    with failproofai_sdk.agent("planner"):
        failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1")

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 hilos nuevos — envuelve un worker con failproofai_sdk.propagate() o sus eventos quedarán sin asociar.

Catálogo de eventos

Quince métodos. La mayoría vienen en pares — llamas al de apertura, luego al de cierre, y el SDK mide el tiempo entre ambos.

	Abre	Cierra
Agentes	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
Modelos	`model_request`	`model_response`
Herramientas	`tool_use`	`tool_result`
Hooks	`hook_triggered`	`hook_completed`
Humanos	`human_wait`	`human_input`

Tres son independientes: error, human_pause, human_interrupt.

Todos los campos, por método

Cada método también acepta session_id y agent_id, que los scopes rellenan por ti. Todo lo que quede como None se omite en lugar de enviarse como JSON null, y todos los métodos devuelven None.

Método	Obligatorio	Opcional
`agent_start`	—	`goal`, `parent_id`
`agent_end`	—	`outcome`, `summary`
`agent_pause`	`pause_id`	`reason`, `user_id`
`agent_resume`	`pause_id`	`reason`, `user_id`
`model_request`	—	`model`, `messages`, `system`, `tools`, `request_id`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`, `request_id`, `duration_ms`
`tool_use`	`tool_name`, `tool_call_id`	`input`
`tool_result`	`tool_name`, `tool_call_id`	`output`, `error`
`hook_triggered`	`hook_name`, `hook_id`	`trigger_event`, `input`
`hook_completed`	`hook_name`, `hook_id`	`outcome`, `output`, `error`
`error`	`error_type`, `message`	`traceback`
`human_wait`	`input_id`	`prompt`, `options`, `reason`
`human_input`	`input_id`	`response`
`human_pause`	—	`reason`, `user_id`
`human_interrupt`	—	`reason`, `user_id`, `at_step`

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 sola 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.

Par	Se empareja por
`tool_use` → `tool_result`	`tool_call_id`
`hook_triggered` → `hook_completed`	`hook_id`
`agent_pause` → `agent_resume`	`pause_id`
`human_wait` → `human_input`	`input_id`
`model_request` → `model_response`	`request_id`

No pases duration_ms tú mismo. El SDK lo mide, y pasarlo lanza 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 otro modo quedaría vacía.

Casos límite

Los IDs solo necesitan ser únicos por tipo y por sesión. Una llamada a una 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 vinculados a un agente. Un par abierto bajo un agente y cerrado bajo otro sigue emparejándose, que es el caso habitual en código multi-agente.
request_id es opcional pero recomendable. 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 medirlo — ningún proceso vio ambas mitades.
Como máximo 10 000 aperturas pueden esperar un cierre a la vez. A partir de ahí, se descarta la más antigua, de modo que una fuga no puede crecer sin límite.

Tus propios campos

Cualquier argumento adicional que pases se almacena junto al evento:

failproofai_sdk.event.tool_use(
    tool_name="search", tool_call_id="c1",
    fw_tenant="acme", fw_region="eu-west-1",     # los tuyos propios
)

Usa tipos JSON si quieres consultarlos después. Cualquier otro tipo — 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 real. Los adaptadores de framework usan fw_; haz lo mismo y nada podrá colisionar.También es por eso que un campo opcional mal escrito nunca produce un error — simplemente se convierte en un nuevo campo personalizado. Si falta un campo estándar en Cloud, comprueba 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

Dashboard
CLI

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, humano, hook y error aparecen en el orden esperado. Usa el ID de sesión como clave principal para depurar.

failproofai flush --wait --timeout 60
failproofai config --status
fp sessions --since 1h --env production --session-id <session-id>
fp events --since 1h --session-id <session-id> --full

Si Cloud está vacío, inspecciona $FAILPROOFAI_HOME/custom-agents/events; de lo contrario, ~/.failproofai/custom-agents/events. Los archivos JSONL confirman la emisión por parte del SDK; un spool que crece apunta a un problema de configuración o entrega del daemon, 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, recoge 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 realmente se emitieron.

Prevenir fallos en un runtime personalizado

Usa los hallazgos de auditoría y las trazas enlazadas para definir la acción insegura, la evidencia requerida y la respuesta prevista. Una integración de aplicación de políticas personalizada debe exponer la acción antes de ejecutarla, pasar su entrada estructurada al motor de políticas y aplicar la decisión resultante: 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 hooks de política, y luego validaremos la integración contigo.

Connect your agents

Reference

Guía de agentes personalizados

¿Usas un framework?

Instalar

Conectar el daemon de Failproof

Configuración

Identidad

Catálogo de eventos

Emparejamiento y duración

Tus propios campos

Entrega y verificación

Prevenir fallos en un runtime personalizado

Guía de agentes personalizados

¿Usas un framework?

​Instalar

​Conectar el daemon de Failproof

​Configuración

​Identidad

​Catálogo de eventos

​Emparejamiento y duración

​Tus propios campos

​Entrega y verificación

​Prevenir fallos en un runtime personalizado

Instalar

Conectar el daemon de Failproof

Configuración

Identidad

Catálogo de eventos

Emparejamiento y duración

Tus propios campos

Entrega y verificación

Prevenir fallos en un runtime personalizado