API de validation humaine pour agents IA
Décidez de ce que votre agent IA peut faire.
Votre agent doit traiter les remboursements sans faire vérifier chaque demande à une personne. Vous fixez les règles : un remboursement de 42 $ est automatique ; pour 4 200 $, la personne concernée décide d’abord sur son téléphone.
@pushary/server · @pushary/ai-sdk · @pushary/eve · pip install pushary
Qu’est-ce qu’une API Human-in-the-Loop ?
Un agent IA a parfois besoin d’un accord humain avant d’agir. Une API Human-in-the-Loop demande cet accord et renvoie la réponse. Pushary est cette API ; vos règles peuvent aussi autoriser ou refuser seules. L’agent appelle authorize() avant une action importante. Les règles autorisent, refusent ou sollicitent une personne désignée. Les remboursements sous 100 $ passent directement. À partir de 1 000 $, la personne dont l’argent est concerné décide. Toute action sans règle passe aussi par un humain : une politique vide n’autorise rien par défaut. Sans réponse à temps, votre code reçoit approved: false et l’action ne s’exécute pas. Chaque décision est enregistrée avec la règle ou la personne qui l’a prise.
Réservez les demandes aux cas qui ont besoin d’un avis
Fixez le montant à partir duquel un remboursement nécessite un accord. La personne intervient pour les exceptions, sans devoir vérifier chaque petit remboursement.
refund.create amount < 100 allow
refund.create amount >= 1000 require_approval
refund.create amount >= 10000 deny42 $ passent directement. À 4 200 $, votre utilisateur décide. 40 000 $ sont bloqués. Sans règle, une personne est sollicitée. Une absence de règle n’est jamais un oui.
- allow
- Une règle autorise l’action. L’agent continue sans déranger personne, et le journal indique la règle qui l’a autorisée.
- deny
- Une règle bloque l’action. L’agent s’arrête et reçoit une raison claire pour ne pas recommencer la même tentative.
- requires_human
- Une règle exige une personne, ou aucune règle ne couvre l’action. La personne désignée par votre code reçoit alors la question sur son téléphone. Une règle manquante déclenche une demande, jamais une autorisation.
La règle la plus stricte l’emporte, quel que soit l’ordre. La règle décide s’il faut demander. Vous décidez à qui.
L’appel
Demandez l’accord avant de rembourser, publier ou supprimer.
Appelez l’API avant l’action. Vos règles vérifient d’abord si elle est autorisée. Si une personne doit décider, elle reçoit la question sur son téléphone.
import { createPusharyServer } from "@pushary/server"
// Rules need a server key from Settings > API keys.
// The key from onboarding can ask a person, but it cannot read your rules.
const px = createPusharyServer({ apiKey: process.env.PUSHARY_API_KEY! })
// Once per person: show them this link to connect. No account needed.
const { universalLink } = await px.enroll(user.id)
// Rules answer first. This one is over your $1,000 threshold.
const decision = await px.authorize({
toolName: "refund.create",
toolTarget: "order_4471",
externalId: user.id,
parameters: { amount: 4200 },
question: "Approve a $4,200 refund for order #4471?",
})
if (!decision.approved) throw new Error(decision.reason)
await issueRefund()Chaque appel renvoie la même structure
Trois résultats, une structure. Vérifiez approved pour poursuivre. Conservez l’identifiant de décision si vous devez reprendre l’exécution plus tard.
// $42. A rule allowed it. Nobody was asked.
{ approved: true, resolvedBy: "policy", reason: "Allowed by policy rule refund.create." }
// $4,200. Your >= 1000 rule sent it to a person. They tapped Approve.
{ approved: true, resolvedBy: "human", reason: "A person approved it." }
// $4,200, and nobody answered inside the window.
{ approved: false, resolvedBy: "human", reason: "Nobody answered, so this was not approved." }Sans réponse à temps, c’est non. L’agent reçoit une raison claire à enregistrer, et le remboursement n’a pas lieu. Une action sans règle renvoie la même structure, mais la décision vient d’une personne.
Après la pause
L’agent attend. Il reste à joindre la personne qui décide.
LangGraph, Vercel AI SDK et OpenAI Agents SDK savent suspendre une action pour obtenir un accord. Il reste à choisir le destinataire, lui transmettre la question et renvoyer sa réponse à l’agent.
- Prendre la décision
- Il faut lire l’action, par exemple le montant du remboursement, et appliquer la bonne règle. Si le montant est illisible, il faut demander plutôt que laisser passer.
- Ajuster les limites
- Vous voulez passer le seuil de 500 $ à 750 $ ? Modifiez la règle sans changer le code ni redéployer votre application.
Fonctionnement
Faites parvenir la question à la bonne personne
Installez le SDK, connectez la personne qui décide et définissez vos règles. Ajoutez un appel avant l’action pour vérifier les règles, demander si nécessaire, attendre la réponse et la conserver.
- 01
Installer le SDK
npm i @pushary/server en TypeScript, ou pip install pushary en Python. Des adaptateurs sont publiés pour Vercel AI SDK, LangGraph, Mastra, OpenAI Agents SDK, CrewAI et Eve.
- 02
Connecter la personne qui répond
Appelez enroll() avec votre propre identifiant utilisateur. La personne ouvre une fois le lien dans l’application Pushary. Les demandes arrivent sur son écran verrouillé. Aucun compte ni clé API à créer de son côté.
- 03
Définir les règles
Une règle comprend une action, une condition sur ses paramètres et un effet. Sous 100 $, autoriser. À partir de 1 000 $, demander une approbation. À partir de 10 000 $, refuser. La règle la plus restrictive l’emporte, quel que soit l’ordre.
- 04
Appeler authorize() avant l’action
Les règles répondent d’abord. Une personne n’est sollicitée que si elles ne tranchent pas. Sans réponse dans le délai prévu, l’appel renvoie un refus : l’expiration du délai n’autorise jamais l’action.
La question peut demander oui ou non, un choix dans une liste ou une réponse écrite. Chaque réponse est enregistrée.
Questions et réponses
Comment ajouter une validation humaine à un agent IA existant ?
Qui choisit la personne à solliciter ?
Cela crée-t-il plus d’interruptions ?
Que se passe-t-il si personne ne répond ?
Mes utilisateurs ont-ils besoin d’un compte ou d’une application ?
Quels frameworks Pushary prend-il en charge ?
Combien cela coûte-t-il ?
Vos utilisateurs décident avant les actions importantes.
Définissez ce qui peut se faire automatiquement et ce qui doit être approuvé. La personne concernée décide sur son téléphone avant l’exécution. Vous pouvez ensuite retrouver la règle ou la personne à l’origine de chaque décision.
Start freeValidation humaine par framework
Par type de produit
Pour aller plus loin
Les quatre niveaux de supervision
Superviser un agent IA revient à répondre à quatre questions : que s’est-il passé, faut-il autoriser cette action, quels cas peuvent passer automatiquement et qui a décidé ? Les notifications informent après l’action. Les approbations suspendent l’action jusqu’à la réponse. Les règles traitent les cas courants. Le journal d’audit conserve ce qui a été exécuté et qui l’a autorisé. Ces quatre niveaux se complètent et s’appuient les uns sur les autres.
| Niveau | Question traitée | Moment d’intervention |
|---|---|---|
| 1. Notifier | Que fait l’agent ? | Après l’action, sans décision |
| 2. Approuver | Faut-il exécuter cette action ? | Sur le moment, avec blocage |
| 3. Règles | Quels cas ont réellement besoin de moi ? | Avant l’action, automatiquement |
| 4. Audit | Que s’est-il passé et qui a décidé ? | Après, dans un journal durable |
- Notifier
- Notifier, c’est informer sans décision : l’agent agit puis vous raconte ce qui s’est passé. Claude Code, Codex et Cursor proposent déjà leurs notifications natives. La différence tient désormais à la capacité du message à vous atteindre. Notifications pour tous vos agents
- Approuver
- L’approbation bloque l’agent avant l’action jusqu’à un oui ou un non humain. Elle ne compte que si elle arrête réellement l’exécution, grâce à un hook placé avant l’appel. Une simple demande sans pouvoir de blocage reste une notification sous un autre nom.
- Règles
- Les règles tranchent les cas courants sans vous : autoriser, demander ou refuser avant toute intervention humaine. Elles doivent lire les paramètres, pas seulement le nom de l’appel. Une vérification d’état passe seule, tandis qu’un push vers un dépôt partagé attend votre accord. Règles d’autorisation
- Audit
- L’audit conserve chaque décision, son auteur humain ou automatique et ses conséquences. Il inclut aussi les appels autorisés sans intervention, avec la règle appliquée. Ne garder que les interruptions humaines ferait disparaître presque tout ce que l’agent a pu faire seul. Le journal d’audit
Pour comprendre pourquoi ces niveaux s’additionnent et pourquoi la notification seule ne suffit plus, consultez Les quatre niveaux de supervision des agents IA : notification, approbation, règles, audit.
Contrôler les agents que vous utilisez
Les deux mêmes appels fonctionnent avec tout framework, cité ici ou non, partout où @pushary/server ou pip install pushary peut s’exécuter.
Vous utilisez vous-même des agents IA ? Recevez leurs questions sur votre téléphone ou votre Mac et répondez depuis l'un ou l'autre. Consultez les offres Agent.