Intervention humaine pour OpenAI Agents SDK

Mettez l’outil en pause. Obtenez l’approbation du client sur téléphone.

Votre agent OpenAI s’arrête avant un remboursement. Votre utilisateur l’approuve sur son téléphone, puis l’exécution reprend.

Try it on your phone

Ce que propose OpenAI Agents SDK

needsApproval et interruptions d’exécution

Marquez un outil de fonction avec needsApproval : le SDK s’arrête avant de l’exécuter. L’exécution renvoie result.interruptions et un RunState que vous pouvez enregistrer. Votre code approuve ou rejette chaque interruption, puis relance l’agent à partir de cet état.

Le point de blocage

needsApproval détermine qu’une personne est nécessaire. Personne n’est interrogé : résoudre l’interruption vous revient.
Une longue attente exige d’enregistrer RunState et de le restaurer avec le même agent et la même version du SDK.
Le système ne sait pas lequel de vos utilisateurs doit répondre ni comment le joindre.

La solution

Pushary recueille la réponse de votre utilisateur.

Agents SDK peut suspendre un appel d’outil, mais ne prévient personne. Pushary envoie chaque appel suspendu sur le téléphone de votre utilisateur et réintègre sa réponse à l’exécution.

issue_refund exige une approbation : l’exécution s’arrête avant de l’appeler. resolvePusharyInterruptions interroge votre utilisateur sur chaque appel suspendu, un à la fois. Une approbation lance le remboursement. Un refus, une expiration ou l’absence de réponse le rejette, et le modèle reçoit le motif. Si une de vos règles Pushary couvre issue_refund, elle répond en premier.

bash

npm i @pushary/openai-agents @openai/agents zod

approbation de l’outil sensible

import { Agent, run, tool } from "@openai/agents"
import { z } from "zod"
import { pusharyNeedsApproval, resolvePusharyInterruptions } from "@pushary/openai-agents"

const issueRefund = tool({
  name: "issue_refund",
  description: "Refund an order",
  parameters: z.object({ amount: z.number() }),
  needsApproval: pusharyNeedsApproval(),
  execute: async ({ amount }) => chargeBack(amount),
})

const agent = new Agent({ name: "Refunds", instructions: "Refund orders when asked.", tools: [issueRefund] })

let result = await run(agent, "Refund order 1234")
while (result.interruptions?.length) {
  const outcome = await resolvePusharyInterruptions(
    { externalId: user.id },
    { interruptions: result.interruptions, state: result.state },
  )
  result = await run(agent, result.state)
  if (!outcome.allApproved) break
}

Le streaming et Responses API enregistrent des éléments différents

Pour une exécution en streaming, lisez les événements et attendez result.completed avant de vérifier les interruptions et d’enregistrer l’état. L’exemple Responses API distinct conserve l’identifiant de réponse et la demande d’approbation MCP exacte, puis envoie mcp_approval_response avec previous_response_id. Le tutoriel couvre les deux avec de vrais services.

attendre la fin du flux avant l’enregistrement

const result = await runner.run(agent, input, { stream: true });
for await (const event of result) {
  // Display appropriate events; output is not permission to act.
}
await result.completed;
// Now inspect result.interruptions and persist result.state.
// The complete recipe binds this state to customer + action.

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 i @pushary/openai-agents @openai/agents zod et placez votre clé API dans PUSHARY_API_KEY. Pour Python, pip install pushary-openai-agents.
02
Connectez votre utilisateur une seule fois
connect() renvoie un lien. Votre utilisateur l’ouvre sur son téléphone avec l’application Pushary gratuite. Gardez votre clé API et son identifiant utilisateur sur votre serveur.
03
Exigez l’approbation sur l’outil sensible
Définissez needsApproval: pusharyNeedsApproval() sur l’outil. L’exécution s’arrête avant de l’appeler, et resolvePusharyInterruptions envoie chaque appel suspendu à votre utilisateur.
04
Agissez selon la réponse
Après une approbation, relancez l’agent à partir de result.state. En cas de refus ou sans réponse, l’appel est rejeté. Pour les longues attentes, enregistrez l’état et reprenez à l’arrivée de la réponse.

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 OpenAI Agents SDK

Un outil de question que le modèle peut ignorer ne bloque rien: pusharyTool est un outil que le modèle choisit d’appeler. Il convient pour « allez poser cette question ». Pour « ceci ne doit pas arriver sans un oui », placez needsApproval sur l’outil sensible lui-même. Une consigne « demander d’abord » ne bloque rien.
Une réponse enregistrée ne sauvegarde pas l’agent: Enregistrez l’état d’exécution, l’appel exact, l’utilisateur et la version de l’action avant de poser la question. Pushary conserve la réponse, mais ne reconstruit pas votre processus et ne programme pas la reprise. Votre propre système de tâches s’en charge.
L’approbation couvre l’appel vu par votre utilisateur: Relisez la réponse depuis Pushary et vérifiez qu’elle correspond à l’appel enregistré. Seul un oui à une question oui/non permet l’exécution. Si le brouillon change, demandez à nouveau. Les demandes en attente, expirées, annulées ou refusées ne comptent jamais.
Une nouvelle tentative peut encore exécuter l’action deux fois: L’exemple n’exécute chaque reprise qu’une fois, mais votre API de remboursement doit aussi avoir sa propre clé d’opération pour ignorer une répétition. Si le résultat réseau est incertain, vérifiez ce qui s’est passé avant de réessayer. L’exemple gère un appel suspendu par opération enregistrée.

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

Quels packages OpenAI sont disponibles ?

@pushary/openai-agents pour TypeScript et pushary-openai-agents pour Python. Les deux proposent connect(), un outil de question et un contrôle d’approbation pour needsApproval (pusharyNeedsApproval et resolvePusharyInterruptions, ou leurs noms en snake_case en Python). Les exemples d’état enregistré, de streaming et de Responses API sont en TypeScript.

L’exemple de streaming utilise-t-il un vrai modèle ou téléphone ?

Non. Il exécute le véritable Agents SDK avec des événements de modèle, réponses HTTP et remboursements simulés, en utilisant SQLite et de nouveaux workers. Aucun compte ni clé API n’est nécessaire. Le tutoriel montre comment connecter de vrais services ; ces vérifications ne prouvent pas qu’un téléphone a reçu une notification.

Comment l’exemple MCP avec Responses API reprend-il ?

Il enregistre l’identifiant d’une réponse terminée et le mcp_approval_request exact, vérifie la réponse de votre utilisateur, puis envoie mcp_approval_response avec previous_response_id. Il conserve require_approval à always. Ce mécanisme est distinct du RunState d’Agents SDK et nécessite des réponses stockées.

Que se passe-t-il si le client ne répond jamais ?

L’appel ne s’exécute pas. Une demande encore en attente n’est pas un oui, et le worker rejette les demandes expirées, annulées ou refusées. Votre application interroge le service ou attend un webhook signé et sauvegarde elle-même l’état d’exécution du SDK : Pushary conserve la demande, pas votre processus.

Pushary remplace-t-il l’autorisation ou Codex Auto-review ?

Non. La réponse de votre utilisateur s’ajoute à vos propres autorisations, contrôles d’entrée et limites des outils. Les applications construites sur Responses API ou Agents SDK ne bénéficient pas automatiquement de Codex Auto-review.

Laissez votre agent OpenAI Agents 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 Vercel AI SDK LangGraph CrewAI Eve Mastra LangChain MCP Claude Agent SDK Hermes OpenClaw n8n