L'API Agents d'OpenAI exécute le harnais Codex open-source d'OpenAI pour vous. Vous envoyez une requête POST https://api.openai.com/v1/agents/sessions avec l'en-tête OpenAI-Beta: agents=v1, une définition d'agent et une tâche ; OpenAI exécute le modèle et la boucle d'outils, maintient la session et peut provisionner un bac à sable. Il n'y a pas de frais pour l'API Agents : vous payez pour les jetons, les outils et le temps d'exécution du conteneur hébergé (0,03 $ à 0,48 $ par session de 20 minutes pour les tailles de bac à sable de 1 Go à 16 Go). Elle est entrée en bêta publique le 10 septembre 2026, et OpenAI a ajouté la fonctionnalité d'utilisation de l'ordinateur lors du DevDay le 29 septembre.
Ci-dessous : une première session REST, les événements de progression, les outils MCP, les sous-agents et le flux d'approbation d'utilisation de l'ordinateur. Pour savoir comment elle se compare aux autres interfaces d'agents d'OpenAI, lisez API Agents vs API Responses vs SDK Agents ; pour le reste de l'événement, consultez le récapitulatif du DevDay 2026. Chaque appel est du HTTP pur, vous pouvez donc l'envoyer depuis Apidog avant d'écrire du code d'application.
L'API Agents d'OpenAI en un coup d'œil
| Élément | Valeur |
|---|---|
| Statut | Bêta publique depuis le 10 sept. 2026 ; utilisation de l'ordinateur ajoutée le 29 sept. |
| Créer une session | POST /v1/agents/sessions |
| En-tête bêta | OpenAI-Beta: agents=v1 (les SDK d'OpenAI l'ajoutent) |
| Permissions de clé | api.agents.read, api.agents.write, api.responses.write |
| Tarification | Pas de frais pour l'API Agents ; jetons du modèle aux tarifs de l'API, outils aux tarifs standard (recherche web 10 $ pour 1K appels) |
| Conteneurs hébergés | 0,03 $ (small, 1 Go), 0,12 $ (medium, 4 Go), 0,48 $ (large, 16 Go) par session de 20 minutes |
| Environnements | none, openai_hosted, self_hosted |
| Modèle dans les exemples de la documentation | gpt-6-astra |
| Contrôles de données | Résidence des données aux États-Unis uniquement ; pas de Rétention Zéro des Données (ZDR) |
| Taille maximale de la requête | 4 MiB |
Sources : Présentation de l'API Agents, l'aperçu de l'API Agents et la page de tarification.
Les quatre concepts
La documentation articule l'API autour de quatre éléments :
- Agent : le modèle, les instructions, les outils et les serveurs MCP. Passez-le en ligne ou enregistrez-le et réutilisez son
agent_id. - Environnement : un bac à sable ou un ordinateur optionnel où l'agent lit les fichiers et exécute les commandes.
- Session : une instance durable de l'agent qui conserve la configuration, la conversation et le travail enregistré.
- Événements et éléments : les événements rapportent la progression en temps réel ; les éléments sont les messages et les appels d'outils enregistrés.
Un message envoyé à une session inactive démarre un nouveau tour ; un message envoyé en cours de tour le dirige. Le harnais (selon la page d'architecture, l'instance Codex hébergée exécutant le modèle et la boucle d'outils) gère également la compaction du contexte, vous n'avez donc pas à le configurer.
Choisir un environnement
environment.type décide où les commandes sont exécutées :
none: pas de calcul. Les serveurs MCP distants et vos outils de fonction fonctionnent toujours ; Bash intégré, apply-patch, fichiers de l'espace de travail et MCP d'exécution ne fonctionnent pas.openai_hosted: OpenAI gère un bac à sable Linux avec Python et Node.js dans/workspace. Définissezcontainer_sizesursmall(1 Go),medium(par défaut, 4 Go) oularge(16 Go), etnetwork.accesssurenabled,disabledourestrictedavecallowed_domains. Les fichiers dans/workspace/outputsdeviennent des artefacts lorsqu'un tour est terminé. Un bac à sable inactif sans maintien en vie peut être supprimé après une heure.self_hosted: votre infrastructure. Vous exécutezcodex exec-serversur un ordinateur portable, un conteneur ou un bac à sable distant, et il se connecte en externe avec une clé d'environnement distincte.
L'article de lancement liste les partenaires de bac à sable Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop et Vercel ; le guide d'auto-hébergement ajoute les MicroVMs AWS Lambda.
Votre première session via REST
Exportez une clé avec les permissions ci-dessus en tant que OPENAI_API_KEY, puis envoyez la tâche de démarrage rapide avec un petit conteneur :
curl --no-buffer https://api.openai.com/v1/agents/sessions \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Écris du code propre, exécute-le et rapporte la sortie réelle."
},
"environment": { "type": "openai_hosted", "container_size": "small" },
"input": "Crée tree.py, un script qui affiche une arborescence des fichiers du répertoire courant. Exécute-le et montre la sortie.",
"stream": true
}'
Avec stream: true, la réponse est le flux d'événements du premier tour. Enregistrez l'ID de session à partir de celui-ci ; le reste du cycle de vie utilise la même ressource :
| Action | Requête |
|---|---|
| Faire un suivi ou diriger | POST /v1/agents/sessions/{id}/events avec un événement agent.session.input.message |
| Annuler le tour actif | Même point de terminaison, type d'événement agent.session.input.cancel |
| Lire le travail enregistré | GET /v1/agents/sessions/{id}/items?order=asc&limit=100 |
| Nettoyer | DELETE /v1/agents/sessions/{id} |
Le SDK JavaScript prend la même forme. Cette version, adaptée de l'article de lancement, ajoute un outil, des sous-agents et un coffre-fort :
import OpenAI from "openai";
const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
tools: [{ type: "web_search" }],
multi_agent: { enabled: true, max_concurrent_subagents: 3 },
},
vault_ids: [process.env.VAULT_ID],
environment: { type: "openai_hosted" },
input: "Résume les changements disruptifs dans les dernières notes de version.",
});
console.log(session.id);
Suivre la progression : flux en continu ou webhooks
Diffusion en continu. Ouvrez GET /v1/agents/sessions/{id}/events?stream=true avec Accept: text/event-stream avant d'envoyer l'entrée, afin de ne pas manquer les premiers événements. Surveillez :
agent.session.turn.output_text.deltaetagent.session.turn.output_text.donepour le texteagent.session.turn.completed,agent.session.turn.failed, ouagent.session.turn.cancelledpour le résultatagent.session.requires_actionlorsque l'agent a besoin d'un résultat de fonction, d'une connexion d'environnement ou d'une approbation d'utilisation de l'ordinateur
Trois pièges : agent.session.idle ne signifie pas que le tour a réussi, un tour terminé peut contenir des appels d'outils échoués, et fermer le flux ne met pas fin à la tâche. Les flux ne rejouent pas les événements manqués, donc après une déconnexion, ouvrez un nouveau flux et récupérez la session et ses éléments.
Webhooks. Abonnez-vous à agent.session.created, agent.session.action_required, agent.session.in_progress, agent.session.idle et agent.session.failed. Notez la nomenclature : le flux indique requires_action, le webhook indique action_required. Les charges utiles omettent les détails d'appel, votre gestionnaire récupère donc la session et lit required_actions. Vérifiez chaque signature (vérification de signature de webhook) ; les opérations API de longue durée expliquent pourquoi les webhooks conviennent aux tâches de plusieurs minutes.
Outils MCP, recherche d'outils, appel d'outils programmatique et sous-agents
MCP. Ajoutez un serveur à agent.tools :
{
"type": "mcp",
"server_label": "openai_docs",
"transport": { "type": "http", "server_url": "https://developers.openai.com/mcp" },
"required": true
}
Par défaut, OpenAI établit la connexion (connection_origin: "service"), de sorte que le serveur doit être accessible depuis OpenAI. Utilisez connection_origin: "environment" pour un serveur en réseau privé, ou stdio pour en démarrer un dans le bac à sable. Pour les identifiants, passez transport.authorization pour une session, ou attachez un identifiant de coffre-fort (static_bearer ou mcp_oauth) avec vault_ids.
Recherche d'outils. Les outils MCP sont découverts automatiquement lorsque le modèle prend en charge la recherche d'outils. Pour de nombreux outils de fonction, ajoutez {"type": "tool_search"} et marquez les fonctions avec defer_loading: true.
Appel d'outils programmatique. Activé par défaut : l'agent reçoit un outil exec qui exécute du JavaScript dans un environnement d'exécution V8 isolé, ce qui lui permet de boucler sur les appels d'outils et de réduire les résultats volumineux avant qu'ils n'atteignent le contexte. Désactivez-le avec {"type": "programmatic_tool_calling", "enabled": false}.
Sous-agents. Définissez multi_agent: {"enabled": true, "max_concurrent_subagents": 3} (la limite par défaut est 6). Les sous-agents partagent le système de fichiers de l'environnement et héritent des outils MCP et de la recherche web, mais ne peuvent pas utiliser d'outils de fonction. L'subagent_id d'un tour est null pour l'agent principal.
Utilisation de l'ordinateur : l'ajout du DevDay
L'utilisation de l'ordinateur donne à l'agent un navigateur hébergé. Ajoutez l'outil et un bureau à un environnement hébergé :
{
"agent": {
"model": "gpt-6-astra",
"tools": [{ "type": "computer_use", "include_screenshots": true }]
},
"environment": {
"type": "openai_hosted",
"desktop": { "enabled": true },
"network": { "access": "enabled" }
}
}
Le navigateur a besoin de l'approbation de l'utilisateur avant de visiter chaque nouvelle origine de site web, y compris les sites publics. Lors de agent.session.requires_action, récupérez la session et recherchez les entrées computer_use_approval_request. Le request.type imbriqué est de deux types :
browser_origin_access: affichezoriginetreason, puis soumettezapprove,denyoucancel.browser_authentication: un formulaire de connexion avecfields, desoptionsde connexion facultatives et unecredential_origin. Soumettezaction: "submit"avec les valeurs de l'utilisateur, ouaction: "cancel".
Les deux réponses sont renvoyées via le point de terminaison des événements :
curl "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"events": [{
"type": "agent.session.input.computer_use_approval_request_result",
"request_id": "REQUEST_ID",
"response": { "type": "browser_origin_access", "decision": "approve" }
}]}'
Le travail du navigateur apparaît sous forme d'éléments computer_use_call avec id, turn_id, title, status et output, qui contient une capture d'écran JPEG en base64 lorsque include_screenshots est activé et qu'une est disponible. Gardez les captures d'écran hors des journaux ; elles peuvent contenir des données de compte.
Le guide d'utilisation de l'ordinateur signale ces mises en garde :
- L'approbation de l'origine n'est pas une confirmation d'action. Approuver un site ne signifie pas que l'agent demandera avant chaque achat ou suppression. Si vous en avez besoin, restreignez le navigateur aux ressources qui ne peuvent pas effectuer ces actions, ou utilisez un environnement d'exécution de navigateur que vous contrôlez.
- La connexion couvre les e-mails, les mots de passe et les codes de vérification. Les Passkeys et la connexion par code QR ne sont pas pris en charge.
- Seul l'agent principal peut demander l'authentification. Les sous-agents ne le peuvent pas.
- Désactivez les tentatives automatiques lors des soumissions d'identifiants (
maxRetries: 0dans le SDK,--retry 0dans curl). - Un code
202signifie accepté, et non que la navigation ou la connexion a réussi. Les requêtes d'authentification expirent après cinq minutes. - L'approbation d'origine ne remplace pas la politique réseau. Autorisez également le site et ses domaines de redirection dans
network.
Le récapitulatif indique que l'utilisation de l'ordinateur est disponible "via l'API et dans Codex et ChatGPT Work sur Pro 500 et Enterprise". Pour les tests basés sur l'interface utilisateur avec le même modèle, consultez GPT-6 Astra et l'utilisation de l'ordinateur pour les tests d'API.
Donnez à l'agent votre API, pas votre interface utilisateur
Un navigateur est la solution de repli pour les logiciels sans API. Si le système est le vôtre, enveloppez-le dans un serveur MCP : outils typés, pas d'invites d'origine, résultats vérifiables. Utilisation de l'ordinateur vs API structurées couvre le compromis, et le Serveur MCP Apidog fournit votre spécification API à l'assistant de codage qui écrit l'enveloppe.
Testez l'API Agents dans Apidog avant d'écrire du code
L'API est en version bêta, alors confirmez d'abord la forme de chaque appel manuellement dans Apidog :
- Créez un environnement Apidog avec
OPENAI_API_KEY,VAULT_IDetSESSION_ID. EnvoyezBearer {{OPENAI_API_KEY}}etOpenAI-Beta: agents=v1à chaque requête. - Envoyez la requête de création de session sans
stream, affirmez un statut 2xx et unidnon vide, et extrayeziddansSESSION_ID. - Ouvrez le flux d'événements comme une requête SSE, envoyez l'entrée depuis une deuxième requête, et observez les événements arriver.
- Enregistrez les charges utiles d'approbation et d'annulation comme des requêtes pour rejouer chaque cas de
required_actions. - Enchaînez-les dans un scénario de test et exécutez-le en CI avec l'Apidog CLI.
Le guide de test de l'API d'agents IA propose des modèles d'assertion pour les sorties non déterministes. Téléchargez Apidog pour suivre.
FAQ
L'API Agents d'OpenAI est-elle gratuite ? Il n'y a pas de frais de plateforme, mais vous payez pour les jetons du modèle, les appels d'outils et le temps d'exécution du conteneur hébergé.
Quels modèles fonctionnent avec l'API Agents ? Les exemples de la documentation, y compris tous les exemples d'utilisation de l'ordinateur, utilisent gpt-6-astra. Les pages ne listent pas d'autres modèles pris en charge, alors testez le vôtre en premier.
L'API Agents prend-elle en charge la Rétention Zéro des Données ? Non. Elle ne prend en charge que la résidence des données aux États-Unis et n'est pas éligible à la Rétention Zéro des Données (ZDR), même avec un bac à sable auto-hébergé.
En quoi est-elle différente du SDK Agents ou de l'API Responses ? Le SDK exécute la boucle dans votre application ; l'API Responses est l'appel de modèle autour duquel vous construisez une boucle. Voir la comparaison complète.
Commencez par une session en lecture seule
Commencez par une session qui ne fait que lire, ajoutez un serveur MCP, puis ajoutez l'utilisation de l'ordinateur derrière un gestionnaire d'approbation qui refuse par défaut. Si ChatGPT doit réagir aux événements de votre propre serveur à la place, les Événements MCP sont la pièce correspondante.