Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# 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écute`codex 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 ](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/sandboxes/aws) 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.
1. 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.
1. 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.
1. 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.
1. 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.
1. 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.
1. 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.
1. 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](microvms-getting-started.md)
+ 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 fichier`codex/agents-api/executor`. Le `/run` crochet le transmet au Codex en tant que`CODEX_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](microvms-security.md).
## 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-executor`image 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, consultez[Images de microVM](microvms-images.md).
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.
1. Appelez `RunMicrovm` avec l'ARN et la version de l'image, le rôle d'exécution, les connecteurs réseau et`runHookPayload`. Enregistrez les informations renvoyées `microvmId` à côté de l'ID de session.
1. Attendez`agent.session.environment.connected`, puis envoyez une saisie et suivez le résultat du tour.
1. Récupérez les fichiers de sortie et terminez le tour comme décrit dans[Fin d'un tour](#microvms-integrations-openai-agents-api-ending-turn).
### 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.
1. Enregistrez le point de terminaison pour `agent.session.action_required` et`agent.session.failed`. Stockez le secret de signature du terminal dans Secrets Manager à l'aide de la clé d'application du lanceur.
1. 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é.
1. Si `environment_connection` c'est toujours en attente, inspectez la microVM enregistrée avec`GetMicrovm`. 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.
1. 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 ](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/sandboxes/aws) 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. `RunMicrovm`lance 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 appelez`TerminateMicrovm`. 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.completed``agent.session.turn.failed`, ou `agent.session.turn.cancelled` l'agent principal, où se `event.turn.subagent_id` trouve`null`. 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ée`TERMINATED`. 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, voir[Exécution et utilisation de microVMS](microvms-launching.md).
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](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**
`maximumDurationInSeconds`limite la durée totale de fonctionnement et de suspension à 8 heures. Pour reprendre sur demande, appelez`ResumeMicrovm`. 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](microvms-networking.md#microvms-networking-connectors).
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 ](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws) sandboxes.
## Ressources connexes
+ [AWS Lambda MicroVM](lambda-microvms-guide.md)
+ [Exécution et utilisation de microVMS](microvms-launching.md)
+ [Sécurité et autorisations](microvms-security.md)
+ [Référence d’API RunMicrovm](https://docs.aws.amazon.com/cli/latest/reference/lambda-microvms/run-microvm.html)
+ [Sandbox auto-hébergés par l'API OpenAI Agents ](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)
+ [Guide de l'API OpenAI Agents AWS](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)