Une session d’agent peut subsister après l’arrêt de son environnement. Votre application gère les ressources de calcul et les fichiers utilisés par 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 avec l’identifiant de l’environnement de la session et une clé d’environnement.
Consultez les exemples de bacs à sable gérés par l’application dans l’OpenAI Cookbook.
Utilisez un seul composant pour gérer l’environnement de chaque session. Enregistrez la correspondance entre la session et les ressources de calcul du fournisseur. Les requêtes répétées ou simultanées ne doivent pas créer d’environnements en double.
Démarrez les ressources de calcul à partir de webhooks
Vous pouvez aussi attendre que des données d’entrée nécessitent une connexion à l’environnement. L’API émet agent.session.action_required avec required_action.type: "environment_connection" avant d’attendre l’exécuteur. 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 instructions de configuration des webhooks pour enregistrer votre gestionnaire pour agent.session.action_required et agent.session.failed. Conservez son secret de signature et son identifiant d’authentification pour la lecture des sessions 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 et le worker ont des rôles distincts :
- Vérifiez et mettez en file d’attente. Vérifiez la signature du webhook. Ne mettez les demandes de connexion en file d’attente que lorsque
data.required_action.typevautenvironment_connection. Mettez également les échecs 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. - Vérifiez l’état actuel. Le worker récupère la session. Ignorez les sessions supprimées et les actions résolues. Pour une session auto-hébergée qui nécessite toujours une connexion, démarrez ou reconnectez son exécuteur à l’aide de
session.environment.idet desession.environment.remote_url. Pour une session toujours en échec, libérez ses ressources de calcul.
Le flux de la session signale la même demande par agent.session.requires_action. Une action requise de type function_call nécessite un résultat de fonction, et non 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 et respectez les éventuels filtres d’agents configurés dans votre gestionnaire. Le traitement de l’envoi initial se poursuit si l’exécuteur se connecte avant l’expiration du délai.
Gardez l’environnement disponible ou arrêtez-le
Laissez les ressources de calcul actives entre les tours pour les réutiliser, ou prévoyez un délai de grâce après la fin d’un tour avant de les arrêter. Coordonnez l’arrêt avec l’arrivée de nouvelles tâches. Annulez tout arrêt en attente lorsqu’une connexion est demandée ou qu’une exécution démarre. Vérifiez à nouveau l’état avant d’arrêter les ressources de calcul.
Un événement d’inactivité ne suffit pas à lui seul pour décider d’un arrêt sans risque. Il peut survenir lorsqu’une demande de connexion est résolue, avant que les données d’entrée en attente ne déclenchent leur tour. Si votre application ne peut pas coordonner l’arrêt avec l’arrivée de nouvelles tâches, laissez l’environnement en fonctionnement.
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. La phase de configuration 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 de fonctionnement du fournisseur.
Une déconnexion en cours de tour peut faire échouer un outil même si le tour se termine. Examinez les résultats des outils et la réponse finale de l’agent. La déconnexion ne demande pas automatiquement une reconnexion via un webhook et ne relance pas une commande interrompue. Un envoi ultérieur de données d’entrée peut demander une reconnexion.
L’API attend jusqu’à cinq minutes qu’une connexion s’établisse lors d’un envoi de données d’entrée. Configurez les délais d’expiration du client et du proxy en conséquence. Si ce délai expire, l’envoi échoue. Le traitement des données d’entrée initiales peut échouer de manière asynchrone et laisser la session dans l’état failed.
L’API ne garantit pas la récupération des données d’entrée en attente après le plantage d’un processus. Vérifiez le résultat de la requête ou de la session avant de réessayer. Ne renvoyez pas les données tant que la requête initiale est en attente. Une connexion tardive ne relance pas le traitement des données d’entrée dont le délai d’attente a expiré.
Réutiliser l’identifiant de l’environnement ne restaure pas les fichiers sur les ressources de calcul de remplacement. Utilisez le stockage du fournisseur ou des instantanés pour les conserver.
Nettoyez 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 actives.
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 n’émet pas de webhook de suppression.