Agents personnalisés

Tout 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, méthodes d’événements, exemple complet et problèmes courants.

Vous utilisez un framework ?

LangChain, CrewAI, LlamaIndex et Pydantic AI s’instrumentent automatiquement en un seul appel.

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

Installation

pip install failproofai-sdk

Le package s’installe sous le nom failproofai-sdk et s’importe 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 la roue de base.

Connecter le démon Failproof

Tableau de bord
CLI

Allez dans Admin → Clés et créez une clé avec events:add.
Connectez le démon Failproof au Cloud sur la machine de l’agent.
Lancez une session instrumentée, puis trouvez son identifiant exact dans Observer → Événements.
Allez dans Observer → Sessions, sélectionnez le même environnement et ouvrez la trace reconstruite.

failproofai config \
  --connect https://app.befailproof.ai \
  --token <events-add-key>
failproofai config --status

Configuration

import failproofai_sdk

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

Argument	Rôle
`environment`	Le libellé 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`	Répertoire d’écriture. Par défaut le spool du démon, ce qui convient sauf si vous savez ce que vous faites.

Définition par variable d’environnement :

Variable	Rôle
`AGENTEYE_ENVIRONMENT`	Définit `environment` sans modifier le code, pour les cas où le libellé appartient au déploiement plutôt qu’à l’application. Un argument `configure()` a la priorité.
`FAILPROOFAI_HOME`	Déplace la racine Failproof AI qui contient le spool.
`FAILPROOFAI_SDK_STRICT`	`1` fait lever une exception en cas d’erreur d’instrumentation au lieu de la journaliser.
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` fait lever une exception en cas de problème de compatibilité avec un framework, au lieu d’un avertissement.

Pas de virgules dans environment. L’ingest découpe ce champ sur les virgules pour construire ses filtres, et ignore tout événement dont le libellé en contient une — toute une exécution disparaît silencieusement. Écrivez prod-eu, et non prod,eu.configure(environment="prod,eu") lève une exception immédiatement. AGENTEYE_ENVIRONMENT ne peut pas lever d’exception — personne ne vous appelle — il émet donc 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 vidage final à la sortie de l’interpréteur. Un processus tué brutalement perd ce qui n’avait pas encore été écrit.

Identité

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

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 TypeError plutôt que d’émettre un événement que Cloud ignorerait silencieusement.

L’identité repose sur des variables de contexte. Elle suit les tâches asyncio automatiquement, mais pas les nouveaux threads — encapsulez un worker dans failproofai_sdk.propagate() ou ses événements seront non rattachés.

Catalogue d’événements

Quinze méthodes. La plupart viennent par paires — vous appelez l’ouvrante, puis la fermante, et le SDK mesure l’écart.

	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 contextes renseignent pour vous. Tout ce qui est laissé à None est abandonné plutôt qu’envoyé comme null JSON, et chaque méthode retourne None.

Méthode	Obligatoire	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 proche variante "failure" — est comptée comme un succès.

Appariement et durée

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

Paire	Appariée 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 vraie latence du fournisseur. Passez un nombre entier de millisecondes — un float lève une exception, car la colonne est un entier 32 bits et resterait sinon vide.

Cas limites

Les identifiants doivent seulement être uniques par type et par session. Un appel d’outil et un hook peuvent partager le même ; deux sessions simultanées peuvent réutiliser les mêmes identifiants 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 appariée — ce qui est le cas normal dans le 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, ce qui peut mener à des erreurs d’appariement entre deux appels simultanés dans le même agent.
Une paire répartie sur plusieurs processus est quand même appariée dans Cloud, mais le SDK ne peut pas la chronométrer — aucun des processus n’a vu les deux moitiés.
Au maximum 10 000 ouvreurs peuvent attendre un fermant simultanément. Au-delà, le plus ancien est supprimé, ce qui empêche une fuite de 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 écrasera silencieusement le vrai champ. Les adaptateurs de framework utilisent fw_ ; faites de même et aucune collision ne sera possible.C’est également 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 absent dans Cloud, vérifiez d’abord l’orthographe.

Ces cinq noms sont réservés et systématiquement rejetés : timestamp, session_id, agent_id, type, environment.

Livraison et vérification

Tableau de bord
CLI

Dans Observer → Événements, vérifiez que agent_start existe en premier et agent_end en dernier. Ensuite, ouvrez Observer → 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’identifiant 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 qui grossit indique un problème de configuration du démon ou de livraison, tandis qu’un spool vide pointe vers l’instrumentation ou la durée de vie du processus.

N’inspectez le spool que lorsque le démon est arrêté. Pendant son fonctionnement, il collecte et supprime chaque lot en quelques millisecondes, de sorte qu’un listage du répertoire sera en compétition avec le collecteur et affichera bien moins d’événements que ceux é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 politique, 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

Connecter le démon 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

​Connecter le démon 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

Connecter le démon 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é