Intervention humaine pour Vercel AI SDK

Votre agent Vercel AI SDK peut interroger une personne sur son téléphone.

Votre agent AI SDK demande avant de rembourser ou de supprimer. Votre utilisateur touche Approuver ou Refuser sur son téléphone.

Try it on your phone

Ce que propose Vercel AI SDK

toolApproval, avec une politique qui décide en premier

AI SDK 7 vérifie chaque appel d’outil avec toolApproval sur generateText, streamText et ToolLoopAgent avant de l’exécuter. needsApproval sur l’outil est désormais obsolète. @ai-sdk/policy-opa peut répondre selon des règles Open Policy Agent : autoriser, refuser, exiger une approbation ou non applicable.

natif

import { opaPolicy } from "@ai-sdk/policy-opa"

await generateText({
  model,
  tools,
  toolApproval: opaPolicy({ client, path: "agent/call/decision" }),
})

Le point de blocage

Un appel qui exige une approbation revient à votre code. Personne n’est prévenu : à vous de gérer l’attente et la reprise.
La politique repose sur du Rego que vous déployez. Passer le plafond de remboursement de $500 à $750 nécessite une pull request.
Le système ne sait pas à quel utilisateur appartient l’action ni comment le joindre.
Son exploitation exige de maintenir du Rego : un bundle compilé dans votre application, ou un serveur OPA que vous gérez.

La solution

Pushary recueille la réponse de votre utilisateur.

AI SDK peut arrêter un appel d’outil avant son exécution, mais ne prévient personne. pusharyApproval envoie la question sur le téléphone de votre utilisateur et transmet sa réponse au SDK.

Pushary ajoute l’approbation humaine à AI SDK 7 via toolApproval. L’exemple soumet issueRefund à une approbation et laisse lookupOrder fonctionner librement. policy: false exige une réponse humaine, sans laisser une règle Pushary enregistrée décider. Une approbation lance le remboursement ; un refus ou l’absence de réponse le bloque. Gardez la clé API et l’identifiant de l’utilisateur connecté sur votre serveur.

bash

npm i @pushary/ai-sdk ai zod

approbation de l’outil sensible

import { generateText, stepCountIs } from "ai"
import { enroll, pusharyApproval } from "@pushary/ai-sdk"

// Once per user: show this link as a button or QR code.
const { universalLink } = await enroll({ apiKey: process.env.PUSHARY_API_KEY! }, user.id)

const { text } = await generateText({
  model: "openai/gpt-4o",
  tools: { issueRefund, lookupOrder },
  // Only issueRefund asks your user. lookupOrder runs untouched.
  toolApproval: pusharyApproval({ externalId: user.id, tools: ["issueRefund"], policy: false }),
  stopWhen: stepCountIs(5),
  prompt: "Refund order 1234.",
})

Ou laissez le modèle poser une question

createPusharyTools ajoute un outil askHuman pour un oui ou un non, un choix comme la livraison Standard ou Express, ou une réponse écrite. Le modèle choisit quand l’appeler : son utilisation reste facultative. Une consigne « demander d’abord » ne bloque pas un remboursement. Pour cela, placez pusharyApproval sur l’outil de remboursement.

question facultative

import { generateText, stepCountIs } from "ai"
import { createPusharyTools } from "@pushary/ai-sdk"

const { text } = await generateText({
  model: "openai/gpt-4o",
  tools: createPusharyTools({ apiKey: process.env.PUSHARY_API_KEY!, externalId: user.id }),
  stopWhen: stepCountIs(10),
  prompt: "Ask the customer to choose Standard or Express shipping.",
})

Fonctionnement

De l’installation à la première réponse

Connectez votre utilisateur une seule fois. Exigez son approbation à l’étape sensible. Pushary envoie la question, attend la réponse et l’enregistre.

01
Installez le package
Exécutez npm i @pushary/ai-sdk ai zod. Conservez votre clé API dans PUSHARY_API_KEY sur votre serveur, jamais dans le navigateur.
02
Connectez votre utilisateur une seule fois
Un appel renvoie un lien. Affichez-le sous forme de bouton ou de QR code. Votre utilisateur l’ouvre sur son téléphone avec l’application Pushary gratuite. Sans compte ni paiement.
03
Exigez l’approbation sur l’outil sensible
Passez pusharyApproval à toolApproval avec l’identifiant de votre utilisateur authentifié et les outils qui exigent un oui. Utilisez policy: false lorsqu’une personne doit toujours décider. Les autres outils fonctionnent comme avant.
04
Agissez selon la réponse
Une approbation exécute l’outil. Un refus, une expiration ou l’absence de réponse renvoie un refus, et l’outil ne s’exécute pas. Une nouvelle tentative réutilise la même demande sans poser la question deux fois.

Une question peut demander un oui ou un non, un choix dans une liste ou une réponse écrite. Chaque réponse est enregistrée.

Avant la mise en production

Les pièges à éviter avec Vercel AI SDK

toolApproval exige AI SDK 7: Le contrôle utilise toolApproval, absent d’AI SDK 5 et 6. L’outil askHuman fonctionne à partir d’AI SDK 5. Mettez le SDK à jour avant de compter sur ce contrôle, sinon rien ne protège votre outil de remboursement.
Accordez au modèle une étape pour utiliser la réponse: Avec une seule étape, la réponse d’askHuman revient comme résultat d’outil et l’exécution se termine. Autorisez une autre étape avec stopWhen si le modèle doit exploiter cette réponse. Aucun de ces réglages ne l’autorise à exécuter un outil sensible.
Le streaming masque la pause: Avec streamText, l’interface continue de s’afficher pendant que l’outil attend. L’agent semble encore réfléchir alors qu’il attend une personne. Affichez l’approbation en attente dans votre interface pour éviter que les utilisateurs relancent leur demande.

L’offre Partner

Votre agent interroge vos utilisateurs, pas seulement vous

Proposez votre agent à vos utilisateurs. Chacun approuve ses actions sensibles depuis son téléphone, sous votre marque.

$99/ mois, tous les frameworks inclus

Start free

Vos utilisateurs ne créent jamais de compte Pushary et ne nous paient rien.

Vos utilisateurs répondent sur leur propre téléphone

Connectez chaque utilisateur une seule fois avec un lien. Il installe l’application Pushary gratuite et répond depuis l’écran verrouillé, sans créer de compte.

Sans réponse, c’est non

Exécutez l’action uniquement après une approbation explicite. Une demande en attente, expirée ou annulée ne vaut jamais un oui. Pushary conserve chaque demande : votre code peut la reprendre après un redémarrage.

Joignez-les sur leur téléphone

L’application passe en premier, car elle seule affiche Approuver et Refuser sur l’écran verrouillé. Les notifications du navigateur viennent ensuite. Vous n’avez aucun système d’envoi à construire.

Chaque réponse est enregistrée

Chaque réponse est enregistrée avec son auteur et sa date. Vous pouvez effectuer des recherches et exporter les réponses. Avec une URL de rappel, chaque réponse est aussi envoyée à votre serveur par webhook signé.

FAQ

Les réponses à vos questions

Existe-t-il un package Pushary pour Vercel AI SDK ?

Oui. @pushary/ai-sdk est disponible sur npm. pusharyApproval et pusharyToolApproval s’intègrent à toolApproval d’AI SDK et bloquent un outil jusqu’à l’approbation de votre utilisateur. createPusharyTools ajoute un outil askHuman que le modèle peut appeler pour poser des questions. Vos utilisateurs se connectent une fois avec un lien et l’application Pushary gratuite.

Comment l’outil askHuman met-il l’agent en pause ?

Il maintient l’appel d’outil ouvert jusqu’à la réponse de votre utilisateur ou la fin de l’attente, 55 secondes par défaut. Cela ne maintient pas votre processus en vie. L’adaptateur renvoie uniquement la réponse reçue pendant ce délai. Pour attendre plus longtemps, créez la décision avec @pushary/server et une URL de rappel, enregistrez l’approbation en attente et les messages d’AI SDK, puis reprenez l’exécution à l’arrivée du webhook signé.

Que se passe-t-il si la personne ne répond jamais ?

L’action ne s’exécute pas. Une demande sans réponse vaut un non : pusharyApproval renvoie donc un refus. Pushary conserve la demande et enregistre aussi une réponse tardive. Il ne relance pas un appel d’outil déjà terminé : votre code décide s’il faut demander à nouveau.

Mes utilisateurs finaux ont-ils besoin d’un compte Pushary ou d’une clé API ?

Non. Vous identifiez chaque utilisateur avec votre propre identifiant. Il installe l’application Pushary gratuite et ouvre votre lien de connexion une fois. Il ne s’inscrit jamais chez Pushary, ne nous paie rien et ne détient aucune clé. Votre clé API reste sur votre serveur.

Où la notification est-elle envoyée ?

Sur le téléphone de votre utilisateur, via l’application Pushary gratuite. La notification affiche « <Votre produit> demande votre approbation ». Approuver et Refuser apparaissent sur l’écran verrouillé pour les questions oui/non ; un choix ou une réponse écrite ouvre l’application. Votre utilisateur peut aussi répondre dans un navigateur.

Laissez votre agent Vercel AI SDK demander avant d’agir.

Connectez un utilisateur une seule fois, posez une question en un appel et exécutez l’action uniquement après un oui. Chaque réponse est enregistrée.

Start free

Offre Partner, $99 par mois. Vos utilisateurs ne créent jamais de compte Pushary et ne nous paient rien.

Intervention humaine avec d’autres frameworks

Tous les frameworks Voir l’offre Partner Documentation sur l’intervention humaine Comprendre l’intervention humaine Intégrer à votre produit LangGraph CrewAI OpenAI Agents SDK Eve Mastra LangChain MCP Claude Agent SDK Hermes OpenClaw n8n