Agents personnalisés

Instrumentez les traces d’un agent personnalisé avec failproofai-sdk afin que Failproof AI puisse reconstruire chaque exécution, auditer son comportement et détecter les défaillances avec preuves à l’appui. Le SDK écrit des événements structurés que le daemon Failproof transmet au Cloud. Il requiert Python 3.10 ou une version ultérieure. Le traçage rend les agents personnalisés observables et auditables. Pour bloquer une action non sécurisée avant son exécution, il faut également un hook d’application dans votre runtime.

Pour appliquer des politiques dans une configuration d’agent personnalisé, contactez Failproof AI. Nous vous aiderons à mapper les frontières de modèle, d’outil et de cycle de vie de votre runtime sur des hooks de politique.

Installer `failproofai-sdk`

Le SDK est actuellement distribué sous forme de wheel privé. Contactez votre interlocuteur Failproof AI pour obtenir la version actuelle et l’accès au téléchargement.

VERSION=<sdk-version>
pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl"
python -c "import failproofai; print(failproofai.__version__)"

Avec uv, téléchargez d’abord le wheel puis exécutez uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl. Épinglez le wheel dans un dépôt d’artefacts privé ou un fichier de verrouillage des dépendances. Le package est installé sous le nom failproofai-sdk et importé en Python sous le nom failproofai.

Connecter le daemon Failproof

Tableau de bord
CLI

Accédez à Admin → Clés et créez une clé avec events:add.
Connectez le daemon Failproof au Cloud sur la machine de l’agent.
Exécutez une session instrumentée, puis retrouvez son identifiant exact dans Observer → Événements.
Accédez à 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

Instrumenter une exécution complète

Appelez configure() une seule fois au démarrage du processus. Chaque appel d’événement est exclusivement par mot-clé et requiert un session_id et un agent_id stables.

import traceback
import uuid

import failproofai

failproofai.configure(environment="production")

session_id = uuid.uuid4().hex
agent_id = "checkout-agent"

failproofai.event.agent_start(
    session_id=session_id,
    agent_id=agent_id,
    goal="Resolve a failed checkout",
)

try:
    tool_call_id = uuid.uuid4().hex
    failproofai.event.tool_use(
        session_id=session_id,
        agent_id=agent_id,
        tool_name="lookup_order",
        tool_call_id=tool_call_id,
        input={"order_id": "ord_8421"},
    )
    result = {"status": "payment_failed"}
    failproofai.event.tool_result(
        session_id=session_id,
        agent_id=agent_id,
        tool_name="lookup_order",
        tool_call_id=tool_call_id,
        output=result,
    )
except Exception as exc:
    failproofai.event.error(
        session_id=session_id,
        agent_id=agent_id,
        error_type=type(exc).__name__,
        message=str(exc),
        traceback=traceback.format_exc(),
    )
    failproofai.event.agent_end(
        session_id=session_id,
        agent_id=agent_id,
        outcome="failed",
    )
    raise
else:
    failproofai.event.agent_end(
        session_id=session_id,
        agent_id=agent_id,
        outcome="success",
        summary="Escalated the failed payment",
    )

Émettez agent_start une seule fois par acteur. Pour les sous-agents, réutilisez le session_id du parent, attribuez un agent_id distinct à chaque acteur et définissez parent_id sur l’identifiant d’agent du parent, et non sur l’identifiant de session.

Référence de configuration

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

Paramètre	Comportement
`base_dir`	Racine de spool explicite. Prioritaire sur toutes les variables d’environnement.
`flush_interval`	Secondes entre les écritures en arrière-plan de la mémoire vers le JSONL. Par défaut : `0.5`.
`environment`	Libellé de déploiement sur chaque événement. Par défaut : `dev`.
`FAILPROOFAI_HOME`	Modifie la racine Failproof AI qui contient le spool `custom-agents`.

Le SDK écrit dans le base_dir explicite lorsqu’il est défini. Sinon, il utilise le spool custom-agents du daemon Failproof sous FAILPROOFAI_HOME ou ~/.failproofai. Le SDK met les appels en file d’attente en mémoire et écrit des lots sur un thread en arrière-plan. Il tente également un vidage final via le mécanisme atexit de Python. Pour les workers à courte durée de vie, autorisez l’arrêt normal de l’interpréteur ; une terminaison brutale du processus peut entraîner la perte des événements encore en mémoire.

Catalogue d’événements

Toutes les méthodes retournent None. Les champs laissés à None sont omis plutôt qu’écrits comme JSON null.

Méthode	Champs requis au-delà de l’identité	Champs optionnels
`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`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`
`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`

Utilisez outcome="failed", "error", "timeout" ou "rejected" lorsqu’une complétion doit être comptabilisée comme un échec. Les autres valeurs, y compris "failure", ne sont pas classifiées comme des échecs par le backend actuel.

Règles de corrélation et de durée

Réutilisez le même tool_call_id, hook_id, pause_id ou input_id pour l’événement de complétion correspondant.
Le SDK calcule duration_ms pour tool_result, hook_completed, agent_resume et human_input. Le passer manuellement à ces méthodes lève une ValueError.
Les identifiants d’outils et de hooks partagent une même table de correspondance des starts en attente au niveau du processus. Rendez-les globalement uniques entre les sessions concurrentes et entre les deux espaces de noms ; les identifiants de fournisseur ou les UUID sont les plus sûrs.
Une paire répartie sur plusieurs processus reste corrélée en aval, mais le SDK ne peut pas calculer sa durée interne au processus.
La table de correspondance conserve au maximum 10 000 démarrages et évince l’entrée la plus ancienne lorsqu’elle est pleine.

Champs personnalisés et payloads

Chaque événement accepte des champs de mot-clé supplémentaires. Utilisez des valeurs compatibles JSON lorsque les requêtes en aval nécessitent une structure. Les types non pris en charge tels que les UUID, les datetime, les decimals, les ensembles, les bytes et les objets de modèle sont convertis en chaîne par le writer. Les noms personnalisés réservés sont timestamp, session_id, agent_id, type et environment. Les fautes de frappe sur les champs optionnels sont acceptées comme de nouveaux champs personnalisés ; vérifiez donc le JSON émis lorsqu’un champ standard n’apparaît pas dans le Cloud.

Livrer et vérifier

Tableau de bord
CLI

Dans Observer → Événements, vérifiez que agent_start apparaît en premier et agent_end en dernier. Ouvrez ensuite 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é de dépannage principale.

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

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

Utilisez les résultats d’audit et les traces associées pour définir l’action non sécurisée, les preuves requises et la réponse prévue. Une intégration d’application 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. Envoyez un email à support@befailproof.ai pour concevoir et valider cette intégration pour votre runtime.

Connect your agents

Reference

HTTP API

Installer `failproofai-sdk`

Connecter le daemon Failproof

Instrumenter une exécution complète

Référence de configuration

Catalogue d’événements

Règles de corrélation et de durée

Champs personnalisés et payloads

Livrer et vérifier

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

​Installer failproofai-sdk

​Connecter le daemon Failproof

​Instrumenter une exécution complète

​Référence de configuration

​Catalogue d’événements

​Règles de corrélation et de durée

​Champs personnalisés et payloads

​Livrer et vérifier

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

Installer `failproofai-sdk`

Connecter le daemon Failproof

Instrumenter une exécution complète

Référence de configuration

Catalogue d’événements

Règles de corrélation et de durée

Champs personnalisés et payloads

Livrer et vérifier

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