Cycle de vie du bac à sable

Une session d’agent peut durer plus longtemps que son environnement. Votre application gère les ressources de calcul et les fichiers qu’utilise un environnement self_hosted.

Démarrez un environnement

Votre application peut démarrer les ressources de calcul après avoir créé une session. Utilisez le SDK ou l’API de votre fournisseur, puis connectez l’exécuteur à l’aide de l’identifiant de l’environnement de la session et d’une clé d’environnement.

Consultez les exemples de bacs à sable gérés par l’application dans l’OpenAI Cookbook.

Confiez la gestion de l’environnement de chaque session à un seul composant. Enregistrez la correspondance entre la session et les ressources de calcul du fournisseur. Des requêtes répétées ou simultanées ne doivent pas créer plusieurs environnements pour la même session.

Démarrez les ressources de calcul à la réception d’un webhook

Vous pouvez aussi attendre que le traitement de données d’entrée nécessite une connexion à l’environnement. L’API émet agent.session.action_required avec required_action.type: "environment_connection", puis attend que l’exécuteur se connecte. Votre gestionnaire de webhooks démarre ou reconnecte l’environnement.

Consultez les exemples de bacs à sable gérés par webhooks dans l’OpenAI Cookbook.

Suivez les étapes de configuration d’un webhook pour enregistrer votre gestionnaire afin qu’il reçoive les événements agent.session.action_required et agent.session.failed. Conservez son secret de signature et ses identifiants de lecture de session séparément de la clé d’environnement de l’exécuteur. Si plusieurs gestionnaires de fournisseurs partagent un projet, acheminez les événements vers le gestionnaire responsable de la session.

Le gestionnaire de webhooks et le processus de traitement ont chacun un rôle distinct.

1. Vérifiez les événements et placez-les en file d’attente. Vérifiez la signature du webhook. Ne placez les demandes de connexion en file d’attente que si data.required_action.type vaut environment_connection. Placez également les événements d’échec de session en file d’attente. Ne renvoyez une réponse HTTP de succès qu’une fois la mise en file d’attente réussie.
2. Vérifiez l’état actuel de la session. Le processus de traitement récupère la session. Ignorez les sessions supprimées et les actions déjà résolues. Si une session auto-hébergée a toujours besoin d’une connexion, démarrez ou reconnectez son exécuteur à l’aide de session.environment.id et de session.environment.remote_url. Si la session est toujours en échec, libérez ses ressources de calcul.

Le flux d’événements de la session signale la même demande sous la forme de agent.session.requires_action. Une action requise de type function_call attend le résultat d’une fonction et ne nécessite pas le démarrage de l’environnement. La création d’un tour et les événements agent.session.in_progress surviennent trop tard pour démarrer un exécuteur hors ligne.

Après avoir déployé le gestionnaire, créez une session auto-hébergée et envoyez des données d’entrée. Utilisez le répertoire de travail configuré dans votre gestionnaire et respectez tout filtre d’agent qui y est défini. Le traitement de la requête initiale se poursuit si l’exécuteur se connecte avant l’expiration du délai.

Maintenez l’environnement disponible ou arrêtez-le

Laissez les ressources de calcul fonctionner entre les tours pour pouvoir les réutiliser, ou prévoyez un délai après la fin d’un tour avant de les arrêter. Coordonnez leur arrêt avec l’arrivée de nouvelles tâches. Annulez tout arrêt programmé dès qu’une connexion est demandée ou qu’une exécution commence. Vérifiez à nouveau l’état de la session avant d’arrêter les ressources de calcul.

Un événement d’inactivité ne suffit pas à garantir que vous pouvez arrêter l’environnement. Il peut survenir lorsqu’une demande de connexion n’est plus en attente, avant même le début du tour correspondant aux données d’entrée en attente. Si votre application ne peut pas coordonner l’arrêt avec l’arrivée de nouvelles tâches, laissez l’environnement fonctionner.

Rétablissez la connexion après une déconnexion

Les événements de connexion indiquent l’état de la connexion. Utilisez agent.session.environment.connected et agent.session.environment.disconnected pour suivre les connexions. Lors de la configuration, l’API peut aussi émettre agent.session.environment.pending ou agent.session.environment.failed. Ces événements ne demandent pas de ressources de calcul. Utilisez l’action requise environment_connection pour déclencher le démarrage et vérifiez séparément l’état du service du fournisseur.

Une déconnexion en cours de tour peut faire échouer un appel d’outil même si le tour se termine. Examinez les résultats des outils et la réponse finale de l’agent. Une déconnexion ne déclenche pas automatiquement de demande de reconnexion par webhook et ne relance pas une commande interrompue. L’envoi ultérieur de données d’entrée peut déclencher une demande de reconnexion.

Lorsqu’une connexion est nécessaire pour traiter des données d’entrée, l’API attend jusqu’à cinq minutes. Configurez les délais d’expiration du client et du proxy en conséquence. Si le délai expire, la requête échoue. Le traitement des données d’entrée initiales peut échouer de manière asynchrone et laisser la session dans l’état failed.

Après un plantage du processus, l’API ne garantit pas la récupération des données d’entrée en attente. Vérifiez le résultat de la requête ou l’état de la session avant de réessayer. Ne renvoyez pas les données tant que la requête initiale est en attente. Une connexion établie après l’expiration du délai ne relance pas le traitement des données d’entrée concernées.

Réutiliser l’identifiant de l’environnement ne restaure pas les fichiers sur les ressources de calcul de remplacement. Pour conserver ces fichiers, utilisez le stockage du fournisseur ou des instantanés.

Libérez les ressources

Cessez d’accepter de nouvelles données d’entrée. Coordonnez le nettoyage avec les opérations de démarrage déjà en cours pour éviter de laisser des ressources de calcul en fonctionnement.

Supprimez la session et arrêtez séparément les ressources de calcul du fournisseur. La suppression d’une session n’arrête pas son environnement et ne déclenche pas de webhook de suppression.