Aide-mémoire Agents API et Agents SDK

OpenAI propose trois façons de construire des agents, et savoir laquelle choisir est un jugement récurrent sur les pistes développeur. Cette page les compare, puis détaille l’Agents API en bêta — le harnais Codex géré d’OpenAI. Revérifiez auprès de developers.openai.com/api/docs ; l’Agents API est en bêta et sa surface peut changer.

Les trois runtimes

   more control / more ops burden ◄─────────────────────► less ops / OpenAI-managed
   Responses API + tools        Agents SDK                 Agents API
   ─ your loop, your infra      ─ your infra, framework    ─ OpenAI runs the session
   ─ no sessions/sandbox        ─ orchestration+guardrails ─ hosted sandbox, compaction,
                                  you host                    recovery, subagents

Cycle de vie d’une session Agents API

Les concepts centraux :

• Agent — modèle, instructions, outils, serveurs MCP.
• Environment — un bac à sable hébergé par OpenAI ou auto-hébergé, avec fichiers/artefacts, un cycle de vie et des contrôles de sécurité.
• Session — une instance durable : créer → lui donner une tâche → suivre la progression via streaming ou webhooks → continuer ou orienter.
• Events et items — le flux de ce que la session a fait.

Le harnais géré fournit l’exécution de commandes/code en bac à sable, les skills et instructions, l’accès aux données MCP/outils, l’orientation en cours d’exécution, la synthèse de contexte, la délégation à des subagents et la reprise de session — vous ne construisez rien de tout cela vous-même.

from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    extra_headers={"OpenAI-Beta": "agents=v1"},
    agent={
        "model": "gpt-6-astra",
        "instructions": "You are a build agent. Fix the failing tests, then stop.",
        "tools": [{"type": "shell"}, {"type": "apply_patch"}],
    },
    environment={"type": "hosted"},
    input="Clone the repo, run the test suite, and fix the first failing test.",
)
print(session.id, session.status)

import OpenAI from 'openai';

const client = new OpenAI();

const session = await client.beta.agents.sessions.create(
  {
    agent: {
      model: 'gpt-6-astra',
      instructions: 'You are a build agent. Fix the failing tests, then stop.',
      tools: [{ type: 'shell' }, { type: 'apply_patch' }],
    },
    environment: { type: 'hosted' },
    input: 'Clone the repo, run the test suite, and fix the first failing test.',
  },
  { headers: { 'OpenAI-Beta': 'agents=v1' } },
);
console.log(session.id, session.status);

L’endpoint est POST /v1/agents/sessions et chaque appel porte l’en-tête OpenAI-Beta: agents=v1. Après la création, vous suivez la session en streaming ou par webhooks, puis vous la continuez (ajout d’input) ou l’orientez (redirection en cours d’exécution) ; la session est durable, elle survit donc au-delà d’une seule requête et peut être reprise.

Environnements

Les deux exposent des fichiers et artefacts, un cycle de vie défini (créer → exécuter → terminer) et des contrôles de sécurité. Le choix porte sur l’endroit où le code s’exécute et ce qu’il peut atteindre, pas sur les garanties de traitement des données.

Outils

Les outils de l’agent incluent tout ce qui figure sur la liste intégrée (shell, exécution de code, file/web search, apply patch, génération d’images, computer use) plus :

• Connexions MCP — atteindre des systèmes externes via des serveurs MCP ; un secure MCP tunnel atteint des serveurs privés sans les exposer.
• Vaults — stockage géré de secrets que l’agent peut utiliser sans que le secret apparaisse dans les prompts ou les logs.
• Skills et instructions — paquets de capacités réutilisables et guidage permanent chargés dans la session.

Multi-agent

Déléguez à des subagents qui s’exécutent en parallèle :

{
  "multi_agent": { "enabled": true, "max_concurrent_subagents": 4 }
}

max_concurrent_subagents plafonne le parallélisme. Davantage de subagents terminent le travail de fan-out plus vite, mais multiplient la dépense en tokens et le coût de conteneur, alors dimensionnez-le à la tâche, pas au maximum.

Garde-fous et approbations

• Garde-fous (guardrails) — contrôles d’entrée/sortie qui bloquent ou transforment un contenu dangereux ou hors politique avant qu’il n’atteigne le modèle ou l’utilisateur.
• Approbations — points de contrôle avec supervision humaine sur les actions sensibles ; la session se met en pause pour approbation avant d’exécuter (par exemple, avant une commande shell qui modifie l’état).

Placez les approbations sur les outils à effet de bord ; placez les garde-fous sur les frontières. L’Agents SDK expose les deux par programmation ; l’Agents API les applique au sein du harnais géré.

Tracing et observabilité

Les sessions émettent une trace d’événements et d’items — appels de modèle, appels d’outils, spans de subagents, interventions d’orientation. Utilisez-la pour déboguer pourquoi un agent a fait ce qu’il a fait et pour construire des evals. L’Agents SDK fournit des intégrations et des hooks d’observabilité ; l’Agents API expose le flux d’événements/items que vous suivez pendant une session.

Composantes de facturation

Une session Agents API facture sur trois composantes :

Un bac à sable auto-hébergé supprime le tarif de conteneur mais vous payez votre propre compute à la place — et cela ne relâche toujours pas les contraintes ci-dessous.

Contraintes

Surface de l’Agents SDK

L’Agents SDK open-source (Python/TS) couvre, à peu près dans l’ordre :

1. Définitions d’agents — modèle, instructions, outils, handoffs.
2. Modèles et providers — quel modèle propulse l’agent, y compris des providers non-OpenAI.
3. Exécution d’agents — la boucle d’exécution et les résultats.
4. Exécution en bac à sable — exécuter outils/code dans un bac à sable que vous contrôlez.
5. Orchestration — handoffs multi-agents et flux de contrôle personnalisé.
6. Garde-fous — validation d’entrée/sortie.
7. Résultats et état — capturer les sorties et porter l’état d’une exécution à l’autre.
8. Intégrations et observabilité — tracing, logging, hooks tiers.
9. Evals d’agents — évaluer le comportement de l’agent systématiquement.

Choisir entre eux — raisonnement détaillé

Une équipe veut un agent de codage durable qui corrige les échecs de CI la nuit, conserve les artefacts et ne nécessite aucune ops d’astreinte.

1. Durable + longue durée + artefacts + pas d’ops → c’est le terrain de prédilection de l’Agents API ; le harnais géré prend en charge la compaction, la récupération et la reprise.
2. Vérifier résidence/ZDR → le code et les logs sont internes mais pas des données personnelles réglementées, et l’org accepte la résidence US et l’absence de ZDR. Si l’un ou l’autre était requis, l’Agents API serait écartée et la réponse serait l’Agents SDK sur une infra auto-hébergée.
3. Modèle → gpt-6-astra pour les corrections les plus difficiles, ou Terra/Luna pour les routinières ; réduisez l’effort là où c’est possible.
4. Sécurité → approbations sur tout outil qui pousse ou déploie ; garde-fous sur les entrées.
5. Parallélisme → activez le multi-agent avec un max_concurrent_subagents modeste et mesurez le coût avant de l’augmenter.

Faits clés à mémoriser

• Trois runtimes : Responses API + tools (votre boucle), Agents SDK (votre infra, framework), Agents API (harnais géré par OpenAI, bêta).
• Agents API : POST /v1/agents/sessions, en-tête OpenAI-Beta: agents=v1, concepts Agent · Environment · Session · Events/items.
• Les environnements sont des bacs à sable hébergés par OpenAI ou auto-hébergés ; l’auto-hébergement ne change pas la résidence ni le ZDR.
• Multi-agent via max_concurrent_subagents ; vaults pour les secrets ; secure MCP tunnel pour les serveurs privés.
• Facturation = tarifs du modèle + tarifs d’outils + tarifs de conteneur.
• Résidence US uniquement, pas de ZDR — la contrainte dure qui écarte l’Agents API pour des données réglementées.