- Agents API, Agents SDK et Responses API
- Qu'est-ce qu'un Harness d'Agent ?
- Pourquoi un agent a toujours besoin d'un Sandbox
- Novita Sandbox dans cette architecture
- Cycle de vie, persistance et travaux de longue durée
- Connecter Novita au chemin auto-hébergé
- Sécurité et identifiants
- Coûts et limites
- Où cette architecture s'applique
- FAQ
- Articles recommandés
L’API OpenAI Agents vous permet de lancer un agent cloud durable en un seul appel de création de session, tandis qu’OpenAI exécute le harness de l’agent dans le cloud. Novita Sandbox ne remplace pas l’API Agents ni son harness géré par OpenAI. Il vous offre un runtime isolé avec état pour le chemin d’exécution auto-hébergé documenté par OpenAI : votre application connecte le sandbox à la session, l’agent exécute des commandes et modifie des fichiers dans ce runtime, et votre application possède le cycle de vie du sandbox. Cette distinction compte lorsque vous souhaitez un workflow agent hébergé par OpenAI, mais avez besoin d’un environnement séparé et réutilisable pour le code, les fichiers, les navigateurs, l’utilisation de l’ordinateur et les tâches de longue durée.
Ce guide explique les principaux concepts de l’API, comment le harness et l’environnement répartissent les responsabilités, comment connecter un Novita Sandbox au chemin auto-hébergé, et ce qu’il faut vérifier avant de passer d’un prototype à la production. Si vous avez seulement besoin de la page produit, Novita Sandbox est le meilleur point de départ.
Agents API, Agents SDK et Responses API
La comparaison des runtimes agents d’OpenAI sépare trois modèles d’intégration :
| Vous voulez | Utilisez | Ce qui gère l’état |
|---|---|---|
| Exécuter une tâche longue via un harness Codex géré par OpenAI | Agents API | Configuration de session sauvegardée, tours et éléments |
| Garder la boucle agent dans votre application | Agents SDK | État de votre application, sessions SDK ou conversations Responses |
| Appeler les modèles directement et tout orchestrer vous-même | Responses API | Historique de votre application ou conversations Responses |
L’API Agents est l’option de plus haut niveau. OpenAI la décrit comme un accès au harness Codex via une API gérée par OpenAI. Elle gère les sessions, l’orchestration, la compaction du contexte et la reprise. L’Agents SDK s’exécute dans votre application et vous donne plus de contrôle sur le déploiement, le stockage, les approbations et l’intégration runtime. L’API Responses est la plus proche de la couche modèle. Cette division est utile car « Agent » peut désigner soit une configuration modèle/outil réutilisable, soit un agent durable en cours d’exécution ; la documentation de l’API utilise ces termes différemment dans chaque runtime.
Qu’est-ce qu’un Harness d’Agent ?
Un harness d’agent est le service cloud qui entoure un tour d’agent. Il envoie les instructions et le contexte au modèle, invoque les outils, suit la progression, gère l’interruption et la reprise, et organise le travail en un flux inspectable. Dans l’API Agents, ce harness est le harness Codex géré.
Le harness géré prend en charge :
- L’exécution de commandes et de code lorsqu’un environnement est attaché.
- L’application des compétences et instructions pertinentes.
- La connexion à des données externes via des outils ou MCP.
- Le pilotage de l’agent pendant son travail.
- La synthèse du travail précédent pour gérer la fenêtre de contexte.
- La décomposition du travail en sous-tâches et la délégation à des sous-agents.
- La reprise d’une session là où elle s’était arrêtée.
Cela ne signifie pas que votre application disparaît. Votre application crée toujours la session, soumet les entrées, reçoit les événements, gère les approbations ou les appels de fonction, et décide comment stocker les identifiants et artefacts. Le harness réduit le travail d’orchestration ; il ne supprime pas la politique produit.
Pourquoi un agent a toujours besoin d’un Sandbox
Certains agents répondent à des questions ou appellent des API distantes sans toucher à un système de fichiers. D’autres ont besoin de créer des fichiers, installer des dépendances, exécuter des scripts, inspecter un navigateur, contrôler un bureau ou maintenir une tâche en plusieurs étapes active pendant l’absence de l’utilisateur. Un sandbox offre à ces actions un environnement d’exécution remplaçable au lieu de les laisser toucher à votre serveur produit ou à votre machine locale.
L’API Agents considère l’environnement comme optionnel. La documentation d’architecture d’OpenAI prend en charge trois choix d’exécution :
none— le harness n’a ni shell ni système de fichiers. Les outils de fonction renvoient les résultats au harness.openai_hosted— OpenAI provisionne et gère le sandbox.self_hosted— votre application démarre et connecte l’environnement, vous permettant ainsi d’utiliser votre propre calcul, réseau privé ou logiciel personnalisé.
C’est là que la frontière entre les deux systèmes est la plus claire. L’API Agents et OpenAI peuvent héberger le harness, mais un environnement auto-hébergé permet à votre équipe de sélectionner la plateforme d’exécution. Ce choix affecte l’isolation, la forme du système de fichiers, la mise en réseau, les SDK, le comportement pause/reprise, la facturation et la quantité d’infrastructure que vous maintenez.
Novita Sandbox dans cette architecture
Novita Sandbox est un environnement d’exécution géré pour les agents IA. La vue d’ensemble officielle décrit des runtimes isolés avec état pour exécuter du code, installer des dépendances, accéder aux fichiers, utiliser des navigateurs et préserver l’état entre les sessions, sans gestion d’infrastructure. Dans une pile directe uniquement Novita, votre application crée le sandbox, le modèle ou le framework agent choisit les appels d’outils, le sandbox les exécute, et votre application conserve la politique, les approbations et le stockage en dehors du runtime.
Avec l’API Agents, la formulation précise recommandée est complémentaire plutôt que native : les guides actuels d’OpenAI pour les sandbox auto-hébergés listent Cloudflare, Daytona, DigitalOcean, E2B, Blaxel, Modal, Runloop, OCI et Vercel comme fournisseurs documentés. Novita Sandbox n’est actuellement pas dans cette liste de fournisseurs. La voie pratique consiste donc à utiliser Novita comme environnement d’exécution géré par votre application et à le connecter à une session API Agents via le contrat d’environnement auto-hébergé d’OpenAI. Cela préserve la séparation utile — OpenAI exécute le harness durable, Novita Sandbox fournit le runtime — sans revendiquer une intégration officielle de fournisseur que la documentation actuelle ne prend pas en charge.
Novita Sandbox est construit autour de cinq concepts :
| Concept | Ce qu’il apporte à l’agent |
|---|---|
| Sandbox | Un runtime isolé avec son propre système de fichiers et espace de processus |
| Template | Une image de départ reproductible, dépendances, configuration et installation |
| Snapshot | Un état de sandbox sauvegardé pouvant être réutilisé pour éviter une configuration répétée |
| Secret | Des valeurs chiffrées à l’échelle de l’équipe qui évitent le codage en dur des identifiants |
| Region | L’emplacement des points de terminaison US v1/v2 actuels |
Le runtime prend en charge les charges de travail d’agent de codage, d’agent navigateur, d’analyse de données, de recherche et de RL. La vue d’ensemble de Novita Sandbox est la source pour les régions actuelles et le comportement du cycle de vie.
Cycle de vie, persistance et travaux de longue durée
Novita Sandbox a trois états de cycle de vie : en cours d’exécution, en pause et tué. Un sandbox en cours d’exécution peut exécuter des commandes et servir des connexions. Un sandbox en pause préserve le système de fichiers et l’état en mémoire, y compris les processus en cours d’exécution et les variables, tandis que la facturation du CPU et de la RAM s’arrête. Les connexions réseau sont interrompues jusqu’à la reprise. Un sandbox tué est terminé et ne peut pas être restauré.
Deux contrôles de délai d’attente déclenchent les transitions : un délai d’attente de sandbox compte à rebours à partir de la création, et un délai d’attente d’inactivité se déclenche lorsqu’aucun client n’a été connecté pendant la durée configurée. Dans les deux cas, vous pouvez choisir de mettre en pause plutôt que de tuer, et éventuellement d’activer la reprise automatique. Ceci est utile pour une tâche d’édition de code qui attend une révision, une session de navigateur qui marque une pause entre les étapes, ou un carnet d’analyse de données qui reprend plus tard avec les dépendances et les variables intactes.
Les snapshots sont différents de la pause. La mise en pause conserve l’état actuel du sandbox pour cette instance. Un snapshot capture l’état en tant qu’environnement réutilisable, de sorte qu’un nouveau sandbox peut démarrer avec les dépendances, la configuration et les fichiers déjà présents. En production, utilisez des templates pour les images de base reproductibles, des snapshots pour les états de travail réutilisables, et des secrets pour les identifiants plutôt que de les intégrer dans un template ou un snapshot.
Connecter Novita au chemin auto-hébergé
Le guide d’OpenAI pour les sandbox auto-hébergés définit la forme de la connexion. Votre application crée une session avec environment.type: "self_hosted", reçoit l’ID d’environnement et l’URL distante, démarre un exécuteur dans votre runtime, puis signale la session comme connectée. La commande officielle de l’exécuteur est :
codex exec-server \
--remote "<session.environment.remote_url>" \
--environment-id "<session.environment.id>"
Le flux d’événements de la session rapporte agent.session.environment.pending, connected ou failed. Vous devez laisser l’exécuteur fonctionner pendant que l’agent travaille et coordonner l’arrêt avant d’arrêter le calcul.
L’esquisse suivante montre le côté Novita de ce flux en utilisant le SDK officiel Novita. Elle crée un sandbox, prépare l’authentification sans placer de secret dans le code source, et vous donne l’emplacement pour démarrer l’exécuteur OpenAI. La manière exacte d’injecter la clé de l’exécuteur et d’attendre le flux d’événements dépend de votre application et de la version du SDK OpenAI.
import os
from novita_sandbox import Novita
def create_agent_runtime() -> str:
novita = Novita(api_key=os.environ["NOVITA_API_KEY"])
sandbox = novita.sandbox.create(
"codex",
timeout=3600,
envs={"CODEX_API_KEY": os.environ["CODEX_EXECUTOR_KEY"]},
)
try:
sandbox.git.clone(
"https://github.com/your-org/your-repo.git",
path="/home/user/repo",
username="x-access-token",
password=os.environ["GITHUB_TOKEN"],
depth=1,
)
print(
"Créez la session API Agents avec environment.type=self_hosted, "
"puis démarrez codex exec-server ici."
)
except Exception:
sandbox.kill()
raise
return sandbox.sandbox_id
Avant d’utiliser ce chemin en production, vérifiez les objets actuels du SDK OpenAI, le nom de la clé d’environnement, le comportement de l’URL distante et les exigences du cycle de vie par rapport au guide d’OpenAI sur les sandbox auto-hébergés. Ne supposez pas que l’API de session gérera le sandbox pour vous ; avec self_hosted, cette responsabilité est explicitement la vôtre.
Pour le workflow plus simple sans API Agents, le guide de l’agent Codex de Novita montre comment exécuter le CLI Codex directement sur le template codex, diffuser sa sortie et tuer le sandbox une fois terminé.
Sécurité et identifiants
Considérez le harness, le sandbox et le serveur d’application comme des domaines de confiance distincts.
- Conservez les clés API OpenAI, les clés API Novita, les jetons Git et les identifiants de base de données en dehors des prompts et des fichiers source.
- Utilisez Novita Sandbox Secrets pour les valeurs sensibles à l’échelle de l’équipe utilisées à l’intérieur du sandbox.
- Utilisez les coffres OpenAI pour les identifiants que les directives d’OpenAI placent en dehors du sandbox.
- Préférez l’accès sécurisé au sandbox. La documentation Novita indique que l’accès sécurisé est activé automatiquement pour les sandbox créés avec la version 2.0.0 ou ultérieure du SDK ; les templates personnalisés plus anciens peuvent nécessiter une reconstruction.
- Définissez une politique réseau explicite et ne l’élargissez que lorsqu’une tâche l’exige.
- Examinez le code et les artefacts générés avant qu’ils ne reçoivent des autorisations plus larges ou n’atteignent les systèmes de production.
Ces contrôles fonctionnent ensemble. Un sandbox réduit le rayon d’explosion du code généré, mais il n’autorise pas l’agent, ne valide pas l’intention et ne décide pas quels artefacts peuvent quitter le runtime.
Coûts et limites
OpenAI facture l’utilisation du modèle de l’API Agents aux tarifs API du modèle sélectionné et les outils OpenAI à leurs tarifs standard. Pour un environnement hébergé par OpenAI, le tarif du conteneur s’applique. Pour un chemin auto-hébergé, les ressources d’exécution sont au coût de votre fournisseur.
La facturation de Novita Sandbox est à la seconde pour le CPU et la RAM lorsqu’un sandbox est en cours d’exécution. La mise en pause arrête la facturation du CPU et de la RAM. Les données en pause sont conservées en tant que stockage persistant ; chaque compte comprend 60 Go de stockage persistant gratuit, le stockage supplémentaire étant facturé à l’heure. Chaque sandbox en cours d’exécution comprend 20 Go de stockage éphémère. Les crédits et les prix officiels du sandbox changent, alors confirmez les valeurs actuelles sur la page de tarification Novita Sandbox.
Les limites de quota de Novita comptent également pour les charges de travail parallèles. Au moment de la rédaction, les comptes gratuits sont limités par défaut à 5 sandbox simultanés et les comptes payants à 100 ; le vCPU et la mémoire maximum d’un seul sandbox diffèrent selon le niveau. Les limites Entreprise peuvent être ajustées. Consultez le guide des limites de quota et Sandbox.get_quota() plutôt que de vous fier aux exemples sur les pages marketing.
Où cette architecture s’applique
Un runtime Novita auto-hébergé est un bon choix lorsque :
- L’agent doit exécuter du code, modifier des fichiers, installer des dépendances, exécuter des tests, naviguer sur le web ou interagir avec un bureau.
- L’application a besoin de sessions avec état pour gérer les délais humains, les tentatives ou les révisions en plusieurs étapes.
- Vous souhaitez une exécution isolée séparée de votre serveur produit.
- Votre charge de travail bénéficie de templates, de snapshots, de pause/reprise ou d’environnements reproductibles.
Ce n’est pas le bon choix lorsque :
- La tâche ne nécessite que des appels de fonction distants et aucun système de fichiers ou shell.
- Vous avez besoin d’un environnement géré par OpenAI et ne voulez pas posséder le cycle de vie de l’environnement.
- Vous avez besoin d’un fournisseur listé dans les guides directs actuels de fournisseurs de sandbox d’OpenAI.
- Votre modèle de conformité exige des contrôles d’isolation gérés par le fournisseur que Novita n’a pas documentés pour votre déploiement.
L’évaluation la plus sûre est une petite preuve de concept avec votre véritable dépôt, commandes, politique réseau, gestion des secrets et chemins d’échec. Mesurez ensuite le démarrage, la pause/reprise, l’achèvement des tâches et le coût total d’une exécution représentative.
FAQ
Novita Sandbox s’intègre-t-il nativement avec l’API OpenAI Agents ?
Non, selon les guides actuels des fournisseurs d’environnement d’OpenAI. L’architecture correcte consiste à utiliser le chemin d’environnement auto-hébergé de l’API Agents, à démarrer Novita Sandbox comme runtime géré par votre application, et à exécuter l’exécuteur documenté à l’intérieur. Vérifiez les guides actuels avant la publication car les intégrations de fournisseurs peuvent changer.
Ai-je encore besoin de Novita si OpenAI propose un sandbox hébergé ?
Cela dépend de vos besoins. Le sandbox hébergé d’OpenAI est le chemin à faible opération. Novita Sandbox est utile lorsque vous souhaitez un choix de runtime séparé pour des images personnalisées, des templates, des snapshots, des workflows de navigateur ou d’utilisation d’ordinateur, une pause/reprise avec état, ou un contrôle au niveau du fournisseur sur les ressources.
L’agent peut-il conserver des processus et des fichiers lors d’une pause ?
Oui. La documentation de pause/reprise de Novita indique que le système de fichiers et l’état en mémoire, y compris les processus en cours d’exécution et les variables, sont préservés. Les connexions réseau sont interrompues jusqu’à la reprise du sandbox.
Est-ce la même chose que l’OpenAI Agents SDK ?
Non. L’Agents SDK s’exécute dans votre application et vous donne plus de contrôle sur la boucle de l’agent. L’API Agents utilise le harness Codex géré par OpenAI. Novita Sandbox peut héberger l’exécution pour l’un ou l’autre modèle, mais le comportement de la session et de l’orchestration diffère.
Par où commencer ?
Essayez le guide de démarrage rapide de l’API OpenAI Agents pour comprendre les sessions et les événements du harness. Créez ensuite un Novita Sandbox et décidez si son runtime, son cycle de vie, sa sécurité et son modèle de coûts correspondent à vos besoins de production.
