Agents personnalisés

Ce que font chaque paramètre, méthode et champ. Si vous instrumentez pour la première fois, commencez par le guide — cette page sert de référence.

Guide des agents personnalisés

Installation, instrumentation, les méthodes d’événements, un exemple concret et les problèmes courants.

Vous utilisez un framework ?

LangChain, CrewAI, LlamaIndex et Pydantic AI s’instrumentent eux-mêmes en un seul appel.

Python 3.10 ou supérieur. Aucune dépendance d’exécution.

Installation

pip install failproofai-sdk

Le paquet est installé sous le nom failproofai-sdk et importé en Python sous failproofai_sdk. Les extras de framework tels que failproofai-sdk[langgraph] installent le framework lui-même ; les adaptateurs sont toujours inclus dans le wheel de base.

Connexion au daemon Failproof

Dashboard
CLI

Accédez à Admin → Keys et créez une clé avec events:add.
Connectez le daemon Failproof au Cloud sur la machine de l’agent.
Lancez une session instrumentée, puis retrouvez son ID exact sous Observe → Events.
Allez dans Observe → Sessions, sélectionnez le même environnement et ouvrez la trace reconstruite.

Lisez la clé events:add dans le shell. read -s la saisit via une invite qui n’affiche pas la saisie, de sorte qu’elle n’apparaît jamais dans une commande ni dans l’historique du shell :

read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN

Configurez ensuite la machine et vérifiez qu’elle est bien connectée :

failproofai config
failproofai config --status

Configuration

import failproofai_sdk

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

Argument	Ce qu’il fait
`environment`	Le label apposé sur chaque événement — `production`, `staging`, `prod-eu`. Par défaut `dev`.
`flush_interval`	Fréquence à laquelle le thread en arrière-plan écrit sur le disque, en secondes. Par défaut `0.5`.
`base_dir`	Où écrire. Par défaut dans le spool du daemon, ce qui convient sauf si vous savez ce que vous faites.

Configurable via variable d’environnement :

Variable	Ce qu’elle fait
`AGENTEYE_ENVIRONMENT`	Définit `environment` sans modification du code, pour que le label appartienne au déploiement plutôt qu’à l’application. Un argument `configure()` a la priorité sur elle.
`FAILPROOFAI_HOME`	Déplace la racine de Failproof AI qui contient le spool.
`FAILPROOFAI_SDK_STRICT`	`1` fait lever une exception sur les erreurs d’instrumentation au lieu de les journaliser.
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` fait lever une exception sur un problème de compatibilité de framework au lieu d’avertir et de continuer.

Pas de virgules dans environment. L’ingestion divise ce champ sur les virgules pour construire ses filtres, et ignore tout événement dont le label en contient une — une exécution entière disparaît silencieusement. Écrivez prod-eu, pas prod,eu.configure(environment="prod,eu") lève une exception pour que vous le sachiez immédiatement. AGENTEYE_ENVIRONMENT ne peut pas lever d’exception — rien ne vous appelle — donc il émet un avertissement une seule fois et revient à dev.

Les événements sont mis en file d’attente en mémoire et écrits en arrière-plan toutes les flush_interval secondes, avec un flush final à la sortie de l’interpréteur. Un processus tué brutalement perd tout ce qui n’avait pas encore été écrit.

Identité

Chaque événement appartient à une session et à un agent. Les scopes remplissent les deux, vous n’avez donc rarement besoin de les passer :

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

Passer session_id ou agent_id explicitement fonctionne toujours et a la priorité. Si ni l’un ni l’autre n’est lié ou passé, l’appel lève une TypeError plutôt que d’émettre un événement que Cloud ignorerait silencieusement.

L’identité est portée par des variables de contexte. Elle suit automatiquement les tâches asyncio, mais pas les nouveaux threads — enveloppez un worker dans failproofai_sdk.propagate() sinon ses événements se retrouvent sans rattachement.

Catalogue d’événements

Quinze méthodes. La plupart se présentent en paires — vous appelez l’ouvreur, puis le fermeur, et le SDK mesure l’intervalle.

	Ouvre	Ferme
Agents	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
Modèles	`model_request`	`model_response`
Outils	`tool_use`	`tool_result`
Hooks	`hook_triggered`	`hook_completed`
Humains	`human_wait`	`human_input`

Trois sont autonomes : error, human_pause, human_interrupt.

Tous les champs, par méthode

Chaque méthode accepte également session_id et agent_id, que les scopes remplissent pour vous. Tout ce qui est laissé à None est omis plutôt qu’envoyé en JSON null, et chaque méthode retourne None.

Méthode	Requis	Optionnel
`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`

Pour marquer une exécution comme échouée, outcome doit être l’une des valeurs suivantes : failed, error, timeout ou rejected. Toute autre valeur — y compris la quasi-correspondance "failure" — est considérée comme un succès.

Appariement et durée

Une seule règle : donnez à l’événement fermant le même id que son ouvreur. C’est ce qui les apparie et ce qui permet au SDK de mesurer l’intervalle.

Paire	Mise en correspondance sur
`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`

Ne passez pas duration_ms vous-même. Le SDK le mesure, et le passer lève une ValueError. La seule exception est model_response, où seul vous connaissez la latence réelle du fournisseur. Passez un nombre entier de millisecondes — un float lève une exception, car la colonne est un entier 32 bits et serait sinon vide.

Cas limites

Les ids n’ont besoin d’être uniques que par type et par session. Un appel d’outil et un hook peuvent partager le même ; deux sessions s’exécutant simultanément peuvent réutiliser les mêmes ids sans collision.
Ils ne sont pas limités à un agent. Une paire ouverte sous un agent et fermée sous un autre est quand même mise en correspondance — ce qui est le cas normal dans du code multi-agents.
request_id est optionnel mais recommandé. Sans lui, les événements de modèle sont appariés dans l’ordre d’arrivée, donc deux appels concurrents dans le même agent peuvent être mal appariés.
Une paire répartie sur plusieurs processus est toujours mise en correspondance dans Cloud, mais le SDK ne peut pas la chronométrer — aucun processus n’a vu les deux moitiés.
Au maximum 10 000 ouvreurs attendent un fermeur à la fois. Au-delà, le plus ancien est abandonné, de sorte qu’une fuite ne peut pas croître indéfiniment.

Vos propres champs

Tout mot-clé supplémentaire que vous passez est stocké avec l’événement :

failproofai_sdk.event.tool_use(
    tool_name="search", tool_call_id="c1",
    fw_tenant="acme", fw_region="eu-west-1",     # vos propres champs
)

Préférez les types JSON si vous souhaitez les interroger ultérieurement. Tout le reste — un UUID, un datetime, un Decimal, un set, des bytes, un objet modèle — est stocké sous forme de chaîne.

Préfixez vos noms de champs. Les extras sont appliqués en dernier, donc un champ nommé model, tool_name ou outcome écrase silencieusement le vrai. Les adaptateurs de framework utilisent fw_ ; faites de même et rien ne peut entrer en collision.C’est aussi pourquoi un champ optionnel mal orthographié ne génère jamais d’erreur — il devient simplement un nouveau champ personnalisé. Si un champ standard est manquant dans Cloud, vérifiez l’orthographe en premier.

Ces cinq noms sont réservés et rejetés d’emblée : timestamp, session_id, agent_id, type, environment.

Livraison et vérification

Dashboard
CLI

Dans Observe → Events, vérifiez que agent_start existe en premier et agent_end en dernier. Ouvrez ensuite Observe → Sessions et confirmez que les événements de modèle, d’outil, humains, de hook et d’erreur apparaissent dans l’ordre prévu. Utilisez l’ID de session comme clé principale de dépannage.

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 vide, inspectez $FAILPROOFAI_HOME/custom-agents/events, sinon ~/.failproofai/custom-agents/events. Les fichiers JSONL prouvent l’émission par le SDK ; un spool en croissance indique un problème de configuration du daemon ou de livraison, tandis qu’un spool vide indique un problème d’instrumentation ou de durée de vie du processus.

N’inspectez le spool que lorsque le daemon est arrêté. Pendant son fonctionnement, il collecte et supprime chaque lot en quelques millisecondes, donc un listage de répertoire est en concurrence avec le collecteur et affiche bien moins d’événements que ce qui a été émis.

Prévenir les défaillances dans un runtime personnalisé

Utilisez les résultats d’audit et les traces liées pour définir l’action non sécurisée, les preuves requises et la réponse attendue. Une intégration d’application des politiques personnalisée doit exposer l’action avant son exécution, transmettre son entrée structurée au moteur de politiques et appliquer la décision allow, instruct ou deny qui en résulte. Contactez Failproof AI et nous vous aiderons à mapper les frontières de modèle, d’outil et de cycle de vie de votre runtime aux hooks de politique, puis à valider l’intégration avec vous.

Connect your agents

Reference

Guide des agents personnalisés

Vous utilisez un framework ?

Installation

Connexion au daemon Failproof

Configuration

Identité

Catalogue d’événements

Appariement et durée

Vos propres champs

Livraison et vérification

Prévenir les défaillances dans un runtime personnalisé

Guide des agents personnalisés

Vous utilisez un framework ?

​Installation

​Connexion au daemon Failproof

​Configuration

​Identité

​Catalogue d’événements

​Appariement et durée

​Vos propres champs

​Livraison et vérification

​Prévenir les défaillances dans un runtime personnalisé

Installation

Connexion au daemon Failproof

Configuration

Identité

Catalogue d’événements

Appariement et durée

Vos propres champs

Livraison et vérification

Prévenir les défaillances dans un runtime personnalisé