Intervention humaine pour Mastra
L’intervention humaine pour les agents et workflows Mastra.
Votre agent Mastra s’arrête avant l’exécution d’un outil sensible, et votre utilisateur l’approuve sur son téléphone.
Ce que propose Mastra
suspend() et run.resume()
Une étape de workflow peut se suspendre, puis votre code appelle run.resume() plus tard. Un outil d’agent peut définir requireApproval pour suspendre l’exécution avant son appel. Une attente qui doit survivre au processus exige un stockage Mastra persistant et l’identifiant d’exécution enregistré. Vérifiez resumeData avant d’autoriser toute exécution.
const approval = createStep({
id: "approval",
inputSchema: z.object({}),
outputSchema: z.object({ approved: z.boolean() }),
resumeSchema: z.object({ approved: z.boolean() }),
execute: async ({ suspend, resumeData }) => {
if (!resumeData) return await suspend({})
return { approved: resumeData.approved }
},
})Le point de blocage
- Une étape suspendue reste silencieuse. Le stockage sait que l’exécution attend ; aucune personne ne le sait.
- Un composant doit appeler run.resume(). Vous construisez la route qui reçoit la réponse et retrouve le bon runId.
- L’instantané conserve l’état du workflow. Il n’enregistre ni qui a approuvé ni ce que cette personne a vu.
La solution
Pushary recueille la réponse de votre utilisateur.
Mastra peut suspendre une exécution avant d’appeler un outil, mais ne prévient personne. Pushary envoie chaque appel suspendu sur le téléphone de votre utilisateur et l’approuve ou le refuse dans Mastra.
issueRefund définit requireApproval de Mastra : l’exécution se suspend avant de l’appeler. resolvePusharyApprovals interroge votre utilisateur, puis approuve ou refuse l’appel dans Mastra. En cas de refus ou sans réponse à temps, le remboursement ne s’exécute jamais. Si une de vos règles Pushary couvre le remboursement, elle répond en premier.
npm install @pushary/mastra @mastra/core zodimport { createTool } from "@mastra/core/tools"
import { resolvePusharyApprovals } from "@pushary/mastra"
import { z } from "zod"
export const issueRefund = createTool({
id: "issue-refund",
description: "Refund an order",
inputSchema: z.object({ orderId: z.string(), amount: z.number().positive() }),
requireApproval: true,
execute: async (input) => refundOrder(input),
})
const output = await agent.generate("Refund order 1234", {
memory: { thread: conversation.id, resource: user.id },
})
if (output.finishReason === "suspended") {
// Your user taps Approve or Deny. No answer means declined.
const outcome = await resolvePusharyApprovals({ externalId: user.id }, { agent, resourceId: user.id })
await handlePendingRuns(outcome.pending)
}Dans un workflow, utilisez l’étape d’approbation
pusharyApprovalStep crée la demande, suspend le workflow et rend la main immédiatement. Pushary envoie la réponse à votre URL de rappel par webhook signé. Votre route la vérifie et appelle run.resume(). Une étape ultérieure vérifie approved avant l’exécution de l’action sensible.
import { createWorkflow } from "@mastra/core/workflows"
import { pusharyApprovalStep, pusharyApprovalStepInputSchema, pusharyAnswerSchema } from "@pushary/mastra"
const config = { apiKey: process.env.PUSHARY_API_KEY! }
const review = pusharyApprovalStep(config, { callbackUrl, externalId: user.id })
const workflow = createWorkflow({
id: "customer-review",
inputSchema: pusharyApprovalStepInputSchema,
outputSchema: pusharyAnswerSchema,
}).then(review).commit()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 l’adaptateur
Exécutez npm install @pushary/mastra @mastra/core zod et placez votre clé API dans PUSHARY_API_KEY. Configurez un stockage Mastra persistant pour les réponses ultérieures.
- 02
Connectez votre utilisateur une seule fois
connect() renvoie un lien. Affichez-le dans votre produit. 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
Définissez requireApproval: true sur l’outil. Dans un workflow, ajoutez pusharyApprovalStep. Pour une simple question que le modèle peut choisir de poser, ajoutez createPusharyAskTool.
- 04
Agissez selon la réponse
resolvePusharyApprovals approuve ou refuse l’appel suspendu, puis reprend l’exécution. Dans un workflow, votre route de rappel appelle run.resume(). Un non, une expiration ou l’absence de réponse n’exécute jamais l’action.
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 Mastra
- Un outil de question ne force pas l’approbation
- createPusharyAskTool est un outil que le modèle choisit d’appeler. Il ne peut pas imposer une approbation avant un autre outil, pas plus qu’une consigne « demander d’abord ». Placez requireApproval sur l’outil sensible lui-même.
- Il faut associer correlationId à runId
- La réponse arrive à votre webhook avec la référence de la demande, pas celle du workflow. Enregistrez cette correspondance à la suspension, sinon vous recevrez une réponse sans savoir à quelle exécution suspendue elle appartient.
- resumeData vaut undefined au premier passage
- La fonction execute de l’étape s’exécute une fois pour suspendre, puis de nouveau pour reprendre. Sans branche pour undefined au premier passage, elle lève une erreur avant même la suspension.
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.
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 Mastra ?
Faut-il utiliser l’outil ou l’étape de workflow ?
Que se passe-t-il si personne ne répond ?
Chacun de mes utilisateurs finaux peut-il approuver sur son téléphone ?
L’attente survit-elle à un redémarrage ou un déploiement ?
Quand utiliser suspend() plutôt qu’un outil de question bloquante ?
Laissez votre agent Mastra 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 freeOffre Partner, $99 par mois. Vos utilisateurs ne créent jamais de compte Pushary et ne nous paient rien.