Utilisation de Lambda MicroVMS comme sandbox pour l'API OpenAI Agents

Vous pouvez utiliser AWS Lambda MicroVMS comme environnement auto-hébergé pour les agents créés avec l'API OpenAI Agents, en conservant les fichiers de l'espace de travail, l'exécution des outils et l'accès au réseau dans l'infrastructure que vous contrôlez. OpenAI exécute le harnais d'agents ; la microVM Lambda exécute vos tâches. Dans cet exemple, il s'exécutecodex exec-server, qui exécute les appels d'outils de l'agent et contient les fichiers d'espace de travail de la session. Vous décidez du contenu de l'image, des chemins réseau que l'exécuteur peut emprunter et des AWS ressources auxquelles son rôle d'exécution est limité.

Chaque microVM s'exécute comme un Firecracker-isolated environnement qui démarre à partir d'un instantané de votre image. La durée de vie totale d'une microVM est de 8 heures maximum, temps de fonctionnement et de suspension compris. Terminez-le après le dernier tour ou suspendez-le entre les tours. Vous créez une image réutilisable, puis vous lancez une microVM à partir de votre application ou d'un lanceur de webhook. Les deux approches utilisent la même image et les mêmes informations d'identification. Pour plus de détails, consultez l'exemple de référence pour le sandbox auto-hébergé de l'API OpenAI Agents sur Lambda MicroVMS.

Comment ça marche

Dans le chemin géré par Webhook, une fonction Lambda du lanceur démarre une microVM lorsque la session a besoin d'un exécuteur pour la première fois. Il réutilise la microVM existante et la reprend d'abord en cas de suspension. Votre candidature y met fin après le dernier tour. La figure 1 montre le flux :

1. Votre application crée une session auto-hébergée et envoie des données à l'API Agents.

2. Lorsque la session nécessite un exécuteur, OpenAI envoie un agent.session.action_required webhook contenant une environment_connection action à un point de terminaison Amazon API Gateway de votre compte.

3. Une fonction Lambda du lanceur vérifie la signature du webhook, récupère la session en cours et confirme que le gestionnaire en est le propriétaire.

4. Le lanceur appelle RunMicrovm avec l'image, le rôle d'exécution, les connecteurs réseau et un élément runHookPayload qui contient les valeurs de connexion de la session.

5. Le /run hook de la microVM utilise son rôle d'exécution IAM pour récupérer la clé d'exécuteur depuis AWS Secrets Manager et démarrer Codex.

6. L'exécuteur s'enregistre auprès d'OpenAI à l'adresse. https://api.openai.com Il ouvre ensuite une WebSocket connexion sécurisée pour wss://codex-cloud-environments.chatgpt.com recevoir les commandes de l'outil et renvoyer les résultats.

7. Votre application peut charger des fichiers d'entrée et télécharger des fichiers de sortie via le point de terminaison HTTPS authentifié de la microVM. Il suit le flux d'événements de session et peut suspendre la microVM entre les tours.

8. Après le dernier tour, votre application met fin à la microVM.

Figure 1. Webhook-managed provisionnement d'un sandbox d'API Agents sur AWS Lambda MicroVMS.

Conservez le secret de signature de la clé d'application et du webhook en dehors de la microVM. Le lanceur transmet uniquement l'ARN secret de la clé d'exécution ; la machine virtuelle récupère la clé en utilisant son rôle d'exécution.

Principales propriétés

Propriété	Avantage
Isolation des pétards	Hardware-virtualized limite pour la microVM de chaque session
Snapshot-based démarrage	Chaque microVM est lancée à partir d'un instantané de l'image que vous avez préparée
IAM via le rôle d'exécution	Le /run hook lit la clé de l'exécuteur avec le rôle d'exécution de la microVM ; la clé n'est pas stockée dans l'image
Durée précise	Chaque microVM peut fonctionner jusqu'à 8 heures, y compris le temps de suspension
Suspendre et reprendre entre les tours	L'état de la mémoire et du disque est préservé afin que les rotations suivantes se poursuivent dans le même environnement
Usage-based calculer	L'exécution de machines virtuelles entraîne des frais de calcul. La suspension met fin aux frais de calcul, au stockage des reads/writes instantanés et à la facturation séparée.

Conditions préalables

• Un AWS compte avec accès à Lambda MicroVMS, une version AWS CLI qui inclut lambda-microvms et des autorisations pour créer des images et exécuter des MicroVMS. Pour créer le compartiment d'artefacts Amazon Simple Storage Service (Amazon S3) et le rôle de création d'images Gestion des identités et des accès AWS (IAM), consultez. Créez votre première microVM Lambda

• Une clé d'application OpenAI (OPENAI_API_KEY) pour créer des sessions et soumettre des informations.

• Une clé d'exécution OpenAI distincte (OPENAI_EXECUTOR_API_KEY) avec la même organisation, le même projet et le même compte utilisateur ou de service que la session. Stockez-le dans Secrets Manager, par exemple sous forme de fichiercodex/agents-api/executor. Le /run crochet le transmet au Codex en tant queCODEX_API_KEY.

• Un rôle d'exécution de microVM qui ne peut lire que le secret de la clé d'exécution. Si le secret utilise une clé du service de gestion des AWS clés (AWS AWS KMS) gérée par le client, ajoutez une autorisation de déchiffrement. Consultez Sécurité et autorisations.

Préparation de l'image MicroVM

Créez une image qui inclut la CLI Codex, les dépendances de vos outils, un répertoire de travail tel que/workspace, et un serveur HTTP pour les hooks du cycle de vie.

Crochet	Comportement
/aws/lambda-microvms/runtime/v1/ready	Renvoie le protocole HTTP 200 lorsque le serveur est prêt à permettre à Lambda de prendre le snapshot. L'exécuteur testamentaire reste déconnecté.
/aws/lambda-microvms/runtime/v1/run	Lit les valeurs de connexion de session et l'ARN secret, récupère la clé de l'exécuteur et démarre l'exécuteur.
/aws/lambda-microvms/runtime/v1/validate	Facultatif. Vérifie que Codex s'exécute et que l'espace de travail est accessible en écriture.
/aws/lambda-microvms/runtime/v1/suspend	Obligatoire pour suspend/resume. Arrête l'exécuteur et vide les écritures avant de créer un AWS instantané de la machine virtuelle.
/aws/lambda-microvms/runtime/v1/resume	Obligatoire pour suspend/resume. Récupère à nouveau la clé et redémarre l'exécuteur pour le même environnement.
/aws/lambda-microvms/runtime/v1/terminate	Facultatif. Arrête l'exécuteur testamentaire et efface les écritures avant la résiliation.

Emballez le serveur Dockerfile and hook dans un artefact Amazon S3, puis créez l'codex-executorimage avec 8 Go de mémoire de base (4 processeurs virtuels de base). Activez les crochets sélectionnés dans la configuration de l'image et définissez le port du hook en fonction de votre serveur. Veillez à ce que les ID de session, les informations d'identification et les connexions à l'exécuteur en direct ne figurent pas dans la capture d'image. Pour la configuration de build et de hook, consultezImages de microVM.

Au lancement, votre application ou votre lanceur sérialise les valeurs suivantes au format JSON dans runHookPayload :

Value	Objectif
session.environment.id	Identifie l'environnement auquel l'exécuteur se connecte
session.environment.remote_url	Fournit l'URL de connexion OpenAI de l'exécuteur
Executor-key ARN secret	Permet au hook de récupérer la clé en utilisant le rôle d'exécution de la microVM

Revenez du /run hook une fois que le processus d'exécution a démarré, sans attendre la fin du tour, pour éviter un délai d'expiration du hook.

Lancement de MicroVMS

Vous pouvez lancer MicroVMS depuis votre application ou depuis un lanceur de webhook. Dans les deux cas, maintenez le flux d'événements de session ouvert jusqu'à la fin du tour.

Application-managed approvisionnement

1. Créez une session auto-hébergée dont le répertoire de travail correspond à l'image, puis ouvrez son flux d'événements.

2. Appelez RunMicrovm avec l'ARN et la version de l'image, le rôle d'exécution, les connecteurs réseau etrunHookPayload. Enregistrez les informations renvoyées microvmId à côté de l'ID de session.

3. Attendezagent.session.environment.connected, puis envoyez une saisie et suivez le résultat du tour.

4. Récupérez les fichiers de sortie et terminez le tour comme décrit dansFin d'un tour.

Webhook-managed approvisionnement

Votre application crée la session, ouvre son flux et soumet des données. Le lanceur gère le reste lorsque le webhook arrive.

1. Déployez une POST /webhook route dans Amazon API Gateway qui appelle le lanceur. Accordez au lanceur l'autorisation de lire ses informations d'identification, d'inspecter, de lancer, de reprendre et d'arrêter les microVM à partir de l'image sélectionnée, de transmettre le rôle d'exécution de microVM et d'utiliser les connecteurs réseau configurés.

2. Enregistrez le point de terminaison pour agent.session.action_required etagent.session.failed. Stockez le secret de signature du terminal dans Secrets Manager à l'aide de la clé d'application du lanceur.

3. Vérifiez la signature du webhook par rapport au corps brut de la requête avant d'accéder aux sessions ou de lancer le calcul. Récupérez ensuite la session en cours et confirmez que le gestionnaire en est propriétaire, par exemple en faisant correspondre un agent enregistré dédié.

4. Si environment_connection c'est toujours en attente, inspectez la microVM enregistrée avecGetMicrovm. Reprenez-le en ResumeMicrovm cas de suspension. Appelez RunMicrovm uniquement si aucune machine virtuelle n'est enregistrée, puis enregistrez son identifiant. Si l'enregistrement échoue, arrêtez la machine virtuelle que vous avez lancée. Si l'exécuteur se connecte avant l'expiration du délai de connexion, l'entrée en attente se poursuit sans nouvelle soumission.

5. Pour un agent.session.failed événement, récupérez la session en cours et mettez fin à sa microVM enregistrée uniquement si son état est toujours défaillant. Ignorez les sessions supprimées, les actions résolues et les sessions appartenant à un autre gestionnaire.

L'exemple de référence enregistre l'ID de la microVM dans les métadonnées de session. Les livraisons simultanées de webhooks peuvent lancer des machines virtuelles supplémentaires avant que cet identifiant ne soit enregistré. Avant toute utilisation en production, empêchez les lancements simultanés pour la même session et dédupliquez les événements du webhook.

Fin d'un tour

La figure 2 montre le cycle de vie de la microVM pour un seul tour, ainsi que le chemin de suspension et de reprise facultatif pour les tours suivants.

Figure 2. Cycle de vie de la microVM pour un seul tour d'API des agents. RunMicrovmlance la microVM, le /run hook démarre l'exécuteur, l'environnement se connecte, le tour s'exécute et le tour se termine. Dans le chemin en un tour de main, vous récupérez des fichiers et vous appelezTerminateMicrovm. Dans le chemin multitour, la microVM s'arrête après le tour et reprend à la demande de connexion suivante.

Dans le flux de session, attendez agent.session.turn.completedagent.session.turn.failed, ou agent.session.turn.cancelled l'agent principal, où se event.turn.subagent_id trouvenull. Les sous-agents partagent la microVM, de sorte que les événements de leur terminal ne déclenchent pas le nettoyage. Récupérez les fichiers dont vous avez besoin. Après le dernier tour, appelez TerminateMicrovm et confirmez que la machine virtuelle est arrivéeTERMINATED. Pour les tours de suivi, maintenez-le en marche ou suspendez-le. Exécutez le nettoyage si votre application rencontre une erreur.

Les résultats au tour par tour arrivent sous forme d'événements de streaming, et non d'abonnements à des webhooks. Le agent.session.failed webhook couvre les échecs de session, mais pas tous les tours échoués. Pour cette raison, ne vous arrêtez pas agent.session.idle seul, car il peut arriver avant le début de la saisie en attente.

Pour limiter la durée de vie de la microVM si le nettoyage ne s'exécute pas, configurez les paramètres suivants au lancement :

Paramètre	Conseils
maximumDurationInSeconds	Fixez un plafond pour la charge de travail, par exemple 900 pour un test de 15 minutes. Cette limite s'applique même lorsque les travaux sont en cours.
maxIdleDurationSeconds	Couvrez la charge de travail attendue. Lambda mesure le trafic entrant, de sorte que la connexion sortante de l'exécuteur ne réinitialise pas ce temporisateur.
suspendedDurationSeconds / autoResumeEnabled	Utilisez 0/false pour le modèle à tour unique, qui ne reprend pas les microVM suspendues.

Pour les commandes de durée de vie et de ralenti, voirExécution et utilisation de microVMS.

Supprimez la session séparément. La suppression d'une session n'arrête pas la microVM et n'envoie pas de webhook de suppression. Conservez l'image et la clé d'exécution secrètes pour les réutiliser. Pour la gestion des rotations de suivi, consultez la section Cycle de vie du https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws bac à sable.

Suspendre et reprendre entre les tours

Pour préserver la mémoire et l'état du disque entre les tours, suspendez la microVM une fois le tour de l'agent principal terminé et tous les outils et sous-agents terminés. Reprenez la même microVM la prochaine fois que la session aura besoin d'un exécuteur.

• Définissez une valeur non nulle. suspendedDurationSeconds Des frais de stockage des snapshots s'appliquent lorsque la microVM est suspendue.

• Activez le /suspend hook pour vider les écritures et fermer les connexions, et le /resume hook pour actualiser les informations d'identification et reconnecter l'exécuteur.

• Le chemin géré par l'application reprend la machine virtuelle avant d'envoyer l'entrée suivante. Dans le chemin géré par Webhook, l'envoi d'une entrée déclenche la demande de connexion qui relance la machine virtuelle. Le tour se poursuit une fois que l'exécuteur se reconnecte.

Note

maximumDurationInSecondslimite la durée totale de fonctionnement et de suspension à 8 heures. Pour reprendre sur demande, appelezResumeMicrovm. La reprise automatique nécessite le trafic entrant vers la microVM ; la saisie de l'API Agents à elle seule ne permet pas de le reprendre.

Mise en réseau

Autorisez les connexions sortantes requises de l'exécuteur à OpenAI et à accéder à Secrets Manager. Pour accéder à des ressources privées ou appliquer vos propres restrictions réseau, connectez un connecteur de sortie VPC au moment du lancement. Consultez Utilisation de connecteurs réseau de sortie.

L'exemple prend en charge le chargement et le téléchargement de fichiers via le point de terminaison HTTPS de la microVM, à l'aide d'un jeton d'authentification limité au port du serveur.

Contrôle

Exécutez l'un ou l'autre des exemples, puis confirmez que les hello.txt téléchargements atteignent TERMINATED la microVM et que la session supprimée renvoie HTTP 404.

Journaux du lanceur. Consultez les journaux de la fonction Lambda du lanceur dans CloudWatch Logs :

aws logs tail /aws/lambda/codex-agents-api-webhook --since 10m

Exécution de MicroVMS. Définissez MICROVM_IMAGE_ARN l'ARN de votre image, utilisez AWS la région de votre déploiement et répertoriez les micromachines virtuelles pour l'image :

aws lambda-microvms list-microvms \
  --image-identifier "$MICROVM_IMAGE_ARN" \
  --query 'items[].{id:microvmId,state:state}' --output table

Enregistrez les identifiants de session et de microVM ensemble afin de pouvoir suivre une exécution de bout en bout. Évitez les informations d'identification et les corps bruts des webhooks dans les journaux.

Résolution des problèmes

Symptôme	Ce qu'il faut vérifier
La signature du Webhook est rejetée	Utilisez le secret de signature du terminal et vérifiez que le corps de la demande n'a pas été modifié.
Aucun lancement de microVM	Vérifiez l'abonnement au webhook, le filtre de propriété de session, l'environment_connectionaction en attente et les autorisations IAM du lanceur.
La création de l'image échoue	Vérifiez l'artefact Amazon S3, le rôle de création de l'image et la réponse du /ready hook.
/runéchoue ou expire	Vérifiez l'accès secret et le démarrage de l'exécuteur. Revenez après avoir démarré le processus, pas après le tour.
L'exécuteur ne peut pas se connecter	Vérifiez l'ID d'environnement, l'URL distante, la propriété de la clé et l'accès réseau sortant.
MicroVM s'arrête pendant un tour	Vérifiez la durée de vie maximale et la politique d'inactivité. Le trafic sortant de l'exécuteur n'est pas considéré comme une activité entrante.

En cas d'échec de connexion, inspectez les agent.session.environment.failed événements et les journaux de l'exécuteur. Pour le contrat d'exécuteur testamentaire partagé, voir Self-hosted sandboxes.

Ressources connexes

• AWS Lambda MicroVM

• Exécution et utilisation de microVMS

• Sécurité et autorisations

• Référence d’API RunMicrovm

• Sandbox auto-hébergés par l'API OpenAI Agents

• Guide de l'API OpenAI Agents AWS