Instalación
Instrumentación
session_id y agent_id. Los ámbitos vinculan la identidad en variables de contexto y cada llamada a evento la lee de vuelta, por lo que nunca necesitas pasar ids a través de tus funciones.
Los tres funcionan tanto con async with como con with.
Anidar agentes construye el árbol. parent_id y la profundidad se calculan desde la pila:
Cómo se cierra un ámbito
agent() gestiona las excepciones por ti:
agent_end, porque el panel cierra el span en agent_end y cualquier cosa posterior no se atribuye a nada. Una cancelación no es un fallo, por lo que las ejecuciones canceladas no contaminan la superficie de errores. La excepción siempre se relanza: un ámbito nunca la suprime.
Los métodos de evento
Quince métodos en seis familias. La mayoría vienen en pares: emites el abridor, luego el cierre, y el SDK mide el span entre ellos.Ejemplo
Un bucle de llamada a herramientas contra la API de OpenAI, sin ningún framework de agentes:docs/manual/examples/.
Hilos y async
Las variables de contexto se propagan automáticamente a las tareas de asyncio. No se propagan a nuevos hilos, porque un hilo comienza con un contexto vacío.propagate(), los eventos del worker lanzan un TypeError que indica la corrección en lugar de terminar sin sesión. Esto es deliberado: un evento sin sesión es omitido por el ingest y respondido con 200, que es el fallo silencioso que la capa de identidad existe para prevenir.
Instrumentar un framework sin adaptador
Cada framework de agentes te ofrece los mismos tres puntos de enganche. Mapéalos y tendrás una traza completa — los cuatro adaptadores incluidos no hacen nada más que esto.Delimita la ejecución
Delimita cada herramienta
Empareja cada llamada al modelo
Por qué no hay adaptador para AutoGen
Por qué no hay adaptador para AutoGen
autogen-coreno tiene mantenimiento desde septiembre de 2025.- AG2 no expone ningún punto de registro a nivel de proceso equivalente a los hooks de los otros frameworks, por lo que instrumentarlo significa envolver cada agente en cada punto de construcción.
Profundizando
Cómo funciona la grabación realmente. Nada de esto es necesario para empezar.Cómo se ve una grabación, por framework
Cómo se ve una grabación, por framework
- LangGraph
- CrewAI
- LlamaIndex
- Pydantic AI
- Custom agents
Cómo empieza y termina una sesión
Cómo empieza y termina una sesión
session_id.El estado se deriva de la forma de la traza:agent_end por ti, y al finalizar cierran todo lo que siga abierto y lo marcan como incompleto — una ejecución que se interrumpió se resuelve como done con un hueco visible en lugar de quedar colgada.interrupt() de LangGraph pausa la ejecución, el span raíz permanece deliberadamente abierto, y la llamada de reanudación lo cierra. Ambas llamadas son una sola sesión.Identidad: session_id, agent_id, y quién los genera
Identidad: session_id, agent_id, y quién los genera
session_id y agent_id son opcionales en todos los métodos de evento. Si se omiten, se resuelven desde el ámbito que los contiene:TypeError que indica la corrección en lugar de emitir un evento sin sesión, que el ingest omitiría respondiendo con 200.Los ámbitos vinculan la identidad en variables de contexto. Estas se propagan automáticamente a las tareas de asyncio pero no a los nuevos hilos — envuelve un worker en failproofai_sdk.propagate().Quién genera cada id
Cómo los adaptadores resuelven session_id
Gana la primera coincidencia:- Una opción
session_idexplícita - Metadatos por llamada
- El ámbito
session()que lo contiene - Metadatos del framework
- El id de ejecución propio del framework
Mantén agent_id con baja cardinalidad
Es la faceta principal en todas las superficies del panel, y una columna LowCardinality(String). Un valor por ejecución degrada la columna y llena el desplegable de filtros con una entrada por ejecución.Los adaptadores protegen esa columna por ti:fw_agent_id / fw_run_id, donde sigue siendo consultable sin ser una faceta.Tipos de eventos agrupados — y qué registra cada framework
Tipos de eventos agrupados — y qué registra cada framework
human_pause y human_interrupt describen a una persona actuando sobre el agente, algo que ningún framework señaliza — emítelos tú mismo.Pares, correlación y duración
Pares, correlación y duración
Reglas de correlación
- Reutiliza el mismo
tool_call_id,hook_id,pause_idoinput_idpara el evento de completado correspondiente. - El SDK calcula
duration_msparatool_result,hook_completed,agent_resumeyhuman_input. Pasarlo a esos métodos lanzaValueError. duration_mssí se acepta enmodel_response, porque solo el llamador conoce la latencia real del proveedor. Debe ser un entero — un float lanzaValueErroren el punto de llamada, porque el servidor lee la columna como un entero de 32 bits sin signo y almacenaría NULL para cualquier otro valor.- Las claves de correlación tienen ámbito por tipo y sesión, por lo que una llamada a herramienta y un hook pueden compartir un id sin problemas, y dos sesiones concurrentes pueden reutilizar los mismos ids sin colisionar. No tienen ámbito por agente: un par abierto bajo un agente y cerrado bajo otro sigue correlacionando, que es el caso habitual en frameworks multi-agente.
request_idemparejamodel_requestconmodel_response. Sin él, los eventos de modelo se emparejan en orden por agente, por lo que las llamadas concurrentes se emparejan incorrectamente.- Un par dividido entre procesos sigue correlacionando en destino, pero el SDK no puede calcular su duración en proceso.
- El mapa de pendientes almacena como máximo 10.000 inicios y desaloja la entrada más antigua cuando se llena.
Qué hay en el paquete, y cómo instrument() encuentra tu framework
Qué hay en el paquete, y cómo instrument() encuentra tu framework
failproofai-sdk instala todo, los cuatro adaptadores incluidos. Los extras incorporan el framework, no el adaptador.import failproofai_sdk es contractualmente sin dependencias, verificado por un test que instala la wheel compilada con --no-deps y otro que demuestra que ningún framework llega a sys.modules.sys.modules, no la lista de paquetes instalados, por lo que un framework que tienes instalado pero nunca has importado no se instrumenta y nunca se importa en tu nombre. Para ver qué está conectado:instrument("crewai") en una máquina sin CrewAI no lanza una excepción. Registra una advertencia y devuelve (), por lo que un framework faltante nunca derrumba un proceso que también instrumenta otros.La advertencia incluye el ImportError subyacente, y ese mensaje indica el comando de instalación exacto — así que la corrección está en tus logs, no oculta.FAILPROOFAI_SDK_STRICT=1 para que lance una excepción en su lugar. Ese flag se lee una vez y se cachea, así que expórtalo antes de que inicie tu proceso, no lo establezcas a mitad de ejecución.Cómo llegan los eventos a Cloud
Cómo llegan los eventos a Cloud
.tmp, luego fsync, luego un renombrado atómico:.jsonl, por lo que nunca puede leer un archivo a medio escribir. El nombre lleva un timestamp, id de proceso y número de secuencia, por lo que dos procesos que hagan flush en el mismo milisegundo no colisionan. La cola tiene un límite de 10.000 eventos; a partir de ahí descarta los más antiguos y lo registra en el log.El daemon envía tus lotes. No los abre ni los reescribe.ls compite con el collector y muestra una fracción de lo que emitiste — indistinguible de un SDK que no registró nada.Para confirmar que los eventos realmente llegaron, comprueba el panel. Para ver cómo se llena el spool, detén el daemon primero.Cuando falla la instrumentación
Cuando falla la instrumentación
try y todo lo que hace el SDK ocurre fuera de él.FAILPROOFAI_SDK_STRICT=1 para hacer visible un fallo suprimido.Problemas comunes
Un span nunca termina
Un span nunca termina
model_request sin model_response, o un tool_use sin tool_result. Usa los ámbitos, que garantizan el par incluso cuando el cuerpo lanza una excepción. Si llamas a los métodos de evento directamente, usa try y finally.Pasar duration_ms lanza un ValueError
Pasar duration_ms lanza un ValueError
tool_result, hook_completed, agent_resume y human_input. Se acepta en model_response, porque solo tú conoces la latencia real del proveedor, y debe ser un entero.Los eventos de un hilo worker lanzan un TypeError
Los eventos de un hilo worker lanzan un TypeError
failproofai_sdk.propagate(). Consulta Hilos y async.Un campo extra desapareció o sobreescribió algo
Un campo extra desapareció o sobreescribió algo
model o outcome lo sobreescribiría y cambiaría una columna almacenada. Usa un espacio de nombres propio; los adaptadores utilizan el prefijo fw_.El filtro de agentes tiene miles de entradas
El filtro de agentes tiene miles de entradas
agent_id es una faceta de baja cardinalidad y pusiste un id de ejecución en ella. Usa un rol o nombre de nodo y guarda el id real en un campo del payload.
