Migration du SDK OpenAI Agents vers l'API Agents : qu'est-ce qui change réellement sur le plan architectural ?

Migrer du SDK OpenAI Agents vers l'API Agents n'est pas un simple renommage d'import. La frontière architecturale fondamentale change : le SDK exécute la boucle de l'agent à l'intérieur de votre application, tandis que l'API Agents exécute un harnais Codex géré et une session durable du côté d'OpenAI. La question de la migration n'est donc pas « Quelles classes correspondent à quels points de terminaison ? » mais « Quelles responsabilités d'exécution traversent la frontière, lesquelles restent dans notre application, et lesquelles doivent être repensées ? »

La migration va d'une boucle détenue par l'application vers un harnais géré

Dans le SDK Agents, une exécution est un tour au niveau de l'application. L'exécuteur du SDK appelle le modèle, inspecte la sortie, exécute les outils, suit les transferts et continue jusqu'à atteindre un point d'arrêt. Votre processus héberge cette boucle et en possède donc le cycle de vie.

Dans l'API Agents, OpenAI exécute le harnais. Une session est une instance durable d'une configuration d'agent qui accepte des tâches, produit des événements, peut se mettre en pause pour des actions requises et peut continuer dans le temps. OpenAI gère les sessions, l'orchestration, la compaction du contexte et la récupération ; votre application envoie le travail, gère les outils de fonction, reçoit les événements et gère éventuellement un environnement d'exécution auto-hébergé.

Ce transfert de propriété constitue la migration. Tout le reste — la syntaxe de l'API, les schémas d'outils, la gestion des événements, les identifiants de session — en découle.

La Carte de migration des frontières d'exécution

Ce qui peut migrer conceptuellement sans changer de propriété

Plusieurs concepts applicatifs survivent proprement à la migration même si leur représentation change. Les modèles, les instructions, les définitions de fonctions au format JSON-schema, l'accès MCP, les descriptions d'outils et les exigences de sortie structurée restent des préoccupations de configuration d'agent.

Le modèle de configuration de l'API Agents d'OpenAI définit explicitement un agent par le modèle, les instructions, les outils, le raisonnement et le comportement de sortie. Les outils de fonction restent du code applicatif : le harnais demande un appel de fonction, et votre gestionnaire renvoie le résultat. OpenAI note également que les implémentations de fonctions utilisées avec l'API Responses peuvent être réutilisées avec le flux de session de l'API Agents.

Ce qui ne doit pas être migré de manière univoque

Le schéma de migration dangereux consiste à recréer chaque abstraction d'exécution du SDK à l'intérieur de l'API Agents. Cela peut vous amener à payer pour un harnais géré tout en exploitant encore un harnais fantôme dans votre application.

Étape 1 — Séparer l'état du domaine de l'état de session de l'agent

Avant de toucher aux appels API, classez l'état que votre application SDK transporte actuellement. Certains états existent uniquement pour maintenir la conversation de l'agent en mouvement. D'autres états constituent la vérité métier : permissions utilisateur, statut de projet, données de commande, approbation de workflow, dossiers clients, versions de documents, état de politique ou configuration d'application.

La seconde catégorie ne doit pas devenir dépendante d'une session de l'API Agents. Une session durable est une continuité utile pour l'agent ; elle ne remplace pas la source de vérité de votre produit. Si la session disparaît, expire, est reconstruite ou change d'implémentation, votre application doit toujours savoir ce qui est vrai.

Étape 2 — Convertir l'état d'esprit du runner en un état d'esprit de session et d'événements

Les applications SDK pensent souvent en termes d'appel de run et de réception d'un résultat. L'API Agents pense en termes de session durable dont les tours peuvent s'exécuter de manière asynchrone. Un message à une session inactive démarre le travail ; un message pendant un tour actif peut l'orienter. La progression arrive via le streaming ou les webhooks.

Cela affecte l'architecture de l'application. Le travail de production de longue durée ne doit pas dépendre du maintien en vie d'une seule requête HTTP. Votre produit a besoin d'identifiants de session stables, d'une persistance du cycle de vie, d'une vérification des webhooks, de gestionnaires idempotents et d'un moyen de réconcilier l'état actuel de la session après le redémarrage des processus.

Étape 3 — Reconcevoir les outils de fonction autour des actions requises

Les outils de fonction restent une frontière importante de l'application. Vous définissez la fonction et son schéma JSON dans la configuration de l'agent. Lorsque le harness a besoin de la fonction, la session peut entrer dans un état d'action requise. Votre application récupère l'action requise, exécute la logique métier et renvoie le résultat.

Cela signifie que l'implémentation de la fonction doit pouvoir être reprise en toute sécurité. Un webhook peut être livré pendant qu'un autre worker traite. Une défaillance réseau peut survenir après l'effet de bord externe mais avant le renvoi du résultat. La migration est donc un bon moment pour ajouter des identifiants d'appel, des clés d'idempotence, une autorisation explicite, des politiques de timeout et des enregistrements d'audit aux outils conséquents.

Étape 4 — Décider où l'exécution doit avoir lieu

L'API Agents sépare le harness géré de l'environnement d'exécution. Un agent peut fonctionner sans environnement dédié, dans un sandbox hébergé par OpenAI, ou via un environnement auto-hébergé connecté à la session.

Cela crée une décision de migration que les applications SDK n'ont peut-être jamais prise explicitement : quel code doit s'exécuter comme fonction d'application, quel code appartient à un sandbox, et quelles charges de travail nécessitent une infrastructure que vous contrôlez ?

Étape 5 — Remplacer la récupération implicite par une gestion explicite du cycle de vie

Le harness géré fournit une récupération au niveau de la session, mais votre application reste propriétaire de chaque dépendance externe qui l'entoure. Les environnements auto-hébergés nécessitent un provisionnement, une reconnexion et un arrêt. Les gestionnaires de fonction peuvent échouer. Les webhooks peuvent être réessayés. L'état côté produit peut changer pendant qu'un agent est inactif.

La migration nécessite donc deux modèles de récupération : la récupération du runtime de l'agent et la récupération des opérations métier. La première est de plus en plus gérée par l'API Agents. La seconde reste votre responsabilité.

Étape 6 — Reconstruire l'observabilité autour de la nouvelle frontière de trace

Les sessions de l'API Agents exposent les événements, l'historique enregistré, les tours, les appels d'outils, les sous-agents et l'utilisation des jetons. OpenAI fournit également des journaux de session dans la plateforme et l'export de trace.

Ne rejetez pas l'observabilité de votre application parce que les traces de la plateforme se sont améliorées. Les journaux produit doivent toujours relier la session de l'agent à l'identité de l'utilisateur, la décision d'autorisation, l'objet métier, l'effet de bord de l'outil, l'enregistrement d'approbation et le résultat final accepté. La trace de production utile est la jonction entre les preuves du runtime de l'agent et les preuves du runtime métier.

Étape 7 — Préserver les évaluations avant de modifier le runtime

Une migration peut sembler réussie parce que le nouveau système produit toujours des réponses plausibles tout en modifiant silencieusement le choix des outils, la continuité de session, le comportement de transfert, la latence ou la reprise après échec. Établissez la référence comportementale avant de changer de runtime.

La référence doit inclure des tâches représentatives, les appels d'outils attendus, les actions interdites, les points d'approbation, la continuité d'état, les scénarios de reprise et les critères d'acceptation du résultat final. Exécutez les anciennes et nouvelles architectures sur les mêmes cas dans la mesure du possible.

Le test de preuve de migration

Ce qu'il faut mesurer pendant la migration

Quand ne pas encore migrer

Une application existante utilisant le SDK Agents ne devient pas une mauvaise architecture simplement parce que l'orientation de la plateforme a changé. OpenAI poursuit la maintenance, les correctifs de sécurité, les corrections de bugs critiques et le travail de compatibilité. Si l'application est stable, bien évaluée et n'a aucune exigence de feuille de route bloquée, une migration immédiate du runtime peut ne pas être justifiée.

• Une capacité requise du SDK n'est pas encore disponible dans l'API Agents.
• La migration perturberait une période de production critique sans apporter de valeur à court terme.
• L'application dépend de sémantiques d'orchestration personnalisées qui n'ont pas été validées sur le harnais géré.
• La portabilité entre fournisseurs est une exigence stricte et l'abstraction actuelle du SDK a une valeur matérielle.
• Votre équipe n'a pas encore séparé l'état métier de l'état du runtime de l'agent, ce qui rend le basculement risqué.
• Le comportement de la nouvelle API Agents n'a pas été testé sur des charges de travail de production représentatives.

Quand la migration devient stratégiquement importante

La migration devient plus convaincante lorsque les exigences produit s'alignent sur le harnais géré : travail durable de longue durée, compactage et reprise du contexte gérés par la plateforme, capacités plus récentes du runtime d'agent, exécution en bac à sable, gestion de cycle de vie hébergée plus riche, ou volonté de réduire la quantité de code d'orchestration que votre application exploite.

Le signal le plus fort n'est pas « l'ancien SDK est complet en fonctionnalités ». C'est « notre feuille de route dépend désormais de capacités dont le foyer naturel est le runtime géré de l'API Agents ».

Qu'est-ce qui changerait cette réponse ?

La stratégie de migration changerait si OpenAI publie des outils de migration automatisés, introduit des couches de compatibilité explicites, modifie la sémantique des sessions de l'API Agents, élargit ou restreint la prise en charge des environnements auto-hébergés, ou modifie la politique de support du SDK Agents.

Elle changerait également si les exigences de votre produit changent. Un assistant simple requête-réponse peut ne pas avoir besoin du tout d'un harnais géré durable. Un agent de codage, de recherche ou d'opérations de longue durée peut bénéficier beaucoup plus du modèle de propriété de l'API Agents.

Limites

Il n'existe pas de correspondance universelle univoque entre le SDK et l'API, car les applications utilisent le SDK Agents différemment. Certaines s'appuient fortement sur les sessions et les transferts ; d'autres l'utilisent comme un simple exécuteur autour d'outils fonctionnels. La migration correcte dépend des responsabilités que votre application assume réellement aujourd'hui.

L'API Agents est également en version bêta publique, les détails d'implémentation peuvent donc évoluer. Considérez les principes de propriété présentés dans cet article comme plus durables que toute forme de point de terminaison individuelle.

Conclusion

Migrer du SDK Agents vers l'API Agents se comprend mieux comme un déplacement de la frontière d'exécution de l'agent. Le harnais géré prend en charge une plus grande partie de la boucle, de la continuité de session, de la compaction et de la récupération. Votre application doit devenir plus explicite quant aux responsabilités qui vous incombent encore : vérité métier, autorisation, effets de bord des fonctions, artefacts, auditabilité et cycle de vie du produit.

Si une migration laisse en place toute l'ancienne machinerie d'orchestration et se contente de remplacer les appels au SDK par des appels à l'API Agents, elle a probablement manqué l'opportunité architecturale. L'objectif n'est pas de reproduire l'ancien environnement d'exécution au-dessus du nouveau. L'objectif est de décider quelles responsabilités d'exécution ne doivent plus incomber à votre application.

FAQ

Glossaire

Sources primaires et lectures complémentaires

Migrer du SDK OpenAI Agents vers l'API Agents n'est pas un simple renommage d'import. La frontière architecturale fondamentale change : le SDK exécute la boucle de l'agent au sein de votre application, tandis que l'API Agents exécute un harnais Codex géré et une session durable du côté d'OpenAI. La question de la migration n'est donc pas « Quelles classes correspondent à quels points de terminaison ? » mais « Quelles responsabilités d'exécution traversent la frontière, lesquelles restent dans notre application, et lesquelles doivent être repensées ? »

La migration va d'une boucle gérée par l'application à un harnais géré

Dans le SDK Agents, une exécution est un tour au niveau de l'application. Le runner du SDK appelle le modèle, inspecte la sortie, exécute les outils, suit les transferts et continue jusqu'à atteindre un point d'arrêt. Votre processus héberge cette boucle et en possède donc le cycle de vie.

Dans l'API Agents, OpenAI exécute le harnais. Une session est une instance durable d'une configuration d'agent qui accepte des tâches, produit des événements, peut se mettre en pause pour des actions requises et peut se poursuivre dans le temps. OpenAI gère les sessions, l'orchestration, la compaction du contexte et la récupération ; votre application envoie le travail, gère les outils de fonction, reçoit les événements et gère éventuellement un environnement d'exécution auto-hébergé.

Ce transfert de propriété constitue la migration. Tout le reste — syntaxe de l'API, schémas d'outils, gestion des événements, identifiants de session — en découle.

La Carte de migration des frontières d'exécution

Ce qui peut migrer conceptuellement sans changer de propriété

Plusieurs concepts applicatifs survivent proprement à la migration même si leur représentation change. Les modèles, les instructions, les définitions de fonctions au format JSON-schema, l'accès MCP, les descriptions d'outils et les exigences de sortie structurée restent des préoccupations de configuration d'agent.

Le modèle de configuration de l'API Agents d'OpenAI définit explicitement un agent par le modèle, les instructions, les outils, le raisonnement et le comportement de sortie. Les outils de fonction restent du code applicatif : le harnais demande un appel de fonction, et votre gestionnaire renvoie le résultat. OpenAI note également que les implémentations de fonctions utilisées avec l'API Responses peuvent être réutilisées avec le flux de session de l'API Agents.

Ce qui ne doit pas être migré un à un

Le schéma de migration dangereux consiste à recréer chaque abstraction d'exécution du SDK au sein de l'API Agents. Cela peut vous amener à payer pour un harnais managé tout en exploitant un harnais fantôme dans votre application.

Étape 1 — Séparer l'état du domaine de l'état de la session de l'agent

Avant de toucher aux appels d'API, classez l'état que votre application SDK transporte actuellement. Certains états n'existent que pour maintenir la conversation de l'agent en mouvement. D'autres états constituent la vérité métier : permissions utilisateur, statut du projet, données de commande, approbation de workflow, dossiers clients, versions de documents, état des politiques ou configuration applicative.

La seconde catégorie ne doit pas devenir dépendante d'une session de l'API Agents. Une session durable est une continuité utile pour l'agent ; elle ne remplace pas la source de vérité de votre produit. Si la session disparaît, expire, est reconstruite ou change d'implémentation, votre application doit toujours savoir ce qui est vrai.

Étape 2 — Convertir l'état d'esprit du runner en état d'esprit session et événements

Les applications SDK pensent souvent en termes d'appel à run et de réception d'un résultat. L'API Agents pense en termes de session durable dont les tours peuvent s'exécuter de manière asynchrone. Un message à une session inactive démarre un travail ; un message pendant un tour actif peut l'orienter. La progression arrive via le streaming ou les webhooks.

Cela affecte l'architecture applicative. Un travail de production de longue durée ne doit pas dépendre du maintien en vie d'une seule requête HTTP. Votre produit a besoin d'identifiants de session stables, de persistance du cycle de vie, de vérification des webhooks, de gestionnaires idempotents et d'un moyen de réconcilier l'état actuel de la session après un redémarrage de processus.

Étape 3 — Reconcevoir les outils de fonction autour des actions requises

Les outils de fonction restent une frontière applicative importante. Vous définissez la fonction et son schéma JSON dans la configuration de l'agent. Lorsque le harnais a besoin de la fonction, la session peut entrer dans un état d'action requise. Votre application récupère l'action requise, exécute la logique métier et renvoie le résultat.

Cela signifie que l'implémentation de la fonction doit pouvoir être reprise en toute sécurité. Un webhook peut être livré pendant qu'un autre worker traite. Une défaillance réseau peut survenir après l'effet de bord externe mais avant le renvoi du résultat. La migration est donc un bon moment pour ajouter des identifiants d'appel, des clés d'idempotence, une autorisation explicite, des politiques de délai d'attente et des enregistrements d'audit aux outils à conséquences.

Étape 4 — Décider où l'exécution doit avoir lieu

L'API Agents sépare le harnais managé de l'environnement d'exécution. Un agent peut fonctionner sans environnement dédié, dans un bac à sable hébergé par OpenAI, ou via un environnement auto-hébergé connecté à la session.

Cela crée une décision de migration que les applications SDK n'ont peut-être jamais prise explicitement : quel code doit s'exécuter comme fonction applicative, quel code appartient à un bac à sable, et quelles charges de travail nécessitent une infrastructure que vous contrôlez ?

Étape 5 — Remplacer la récupération implicite par une gestion explicite du cycle de vie

Le harnais géré assure une récupération au niveau de la session, mais votre application reste propriétaire de chaque dépendance externe qui l'entoure. Les environnements auto-hébergés nécessitent un provisionnement, une reconnexion et un arrêt. Les gestionnaires de fonctions peuvent échouer. Les webhooks peuvent être réessayés. L'état côté produit peut changer pendant qu'un agent est inactif.

La migration nécessite donc deux modèles de récupération : la récupération du runtime de l'agent et la récupération des opérations métier. La première est de plus en plus gérée par l'API Agents. La seconde reste de votre responsabilité.

Étape 6 — Reconstruire l'observabilité autour de la nouvelle frontière de trace

Les sessions de l'API Agents exposent les événements, l'historique sauvegardé, les tours, les appels d'outils, les sous-agents et l'utilisation des tokens. OpenAI fournit également des journaux de session dans la plateforme et l'export de traces.

Ne renoncez pas à l'observabilité de votre application sous prétexte que les traces de la plateforme se sont améliorées. Les journaux produit doivent toujours relier la session de l'agent à l'identité de l'utilisateur, à la décision d'autorisation, à l'objet métier, à l'effet de bord de l'outil, à l'enregistrement d'approbation et au résultat final accepté. La trace de production utile est la jonction entre les preuves du runtime de l'agent et celles du runtime métier.

Étape 7 — Préserver les évaluations avant de changer le runtime

Une migration peut sembler réussie parce que le nouveau système produit toujours des réponses plausibles tout en modifiant silencieusement le choix des outils, la continuité de session, le comportement de transfert, la latence ou la récupération après échec. Établissez la référence comportementale avant de changer de runtime.

La référence doit inclure des tâches représentatives, les appels d'outils attendus, les actions interdites, les points d'approbation, la continuité d'état, les scénarios de récupération et les critères d'acceptation du résultat final. Exécutez les anciennes et nouvelles architectures sur les mêmes cas chaque fois que possible.

Le test de preuve de migration

Ce qu'il faut mesurer pendant la migration

Quand ne pas encore migrer

Une application existante basée sur le SDK Agents ne devient pas une mauvaise architecture simplement parce que l'orientation de la plateforme a changé. OpenAI poursuit la maintenance, les correctifs de sécurité, les corrections de bugs critiques et le travail de compatibilité. Si l'application est stable, bien évaluée et n'a aucune exigence de feuille de route bloquée, une migration immédiate du runtime peut ne pas être justifiée.

• Une capacité requise du SDK n'est pas encore disponible dans l'API Agents.
• La migration perturberait une période de production critique sans apporter de valeur à court terme.
• L'application dépend de sémantiques d'orchestration personnalisées qui n'ont pas été validées sur le harnais géré.
• La portabilité entre fournisseurs est une exigence stricte et l'abstraction actuelle du SDK a une valeur matérielle.
• Votre équipe n'a pas encore séparé l'état métier de l'état du runtime de l'agent, ce qui rend le basculement dangereux.
• Le comportement de la nouvelle API Agents n'a pas été testé sur des charges de travail de production représentatives.

Quand la migration devient stratégiquement importante

La migration devient plus convaincante lorsque les exigences produit s'alignent avec le harnais managé : travail durable de longue durée, compaction et récupération du contexte gérées par la plateforme, capacités plus récentes du runtime d'agents, exécution en sandbox, gestion plus riche du cycle de vie hébergé, ou le désir de réduire la quantité de code d'orchestration que votre application exploite.

Le signal le plus fort n'est pas « l'ancien SDK est complet en fonctionnalités ». C'est « notre feuille de route dépend désormais de capacités dont le foyer naturel est le runtime managé de l'API Agents ».

Qu'est-ce qui changerait cette réponse ?

La stratégie de migration changerait si OpenAI publiait des outils de migration automatisés, introduisait des couches de compatibilité explicites, modifiait la sémantique des sessions de l'API Agents, élargissait ou réduisait la prise en charge des environnements auto-hébergés, ou modifiait la politique de support du SDK Agents.

Cela changerait aussi si vos exigences produit changent. Un simple assistant requête-réponse peut ne pas avoir besoin du tout d'un harnais managé durable. Un agent de codage, de recherche ou d'opérations de longue durée peut bénéficier beaucoup plus du modèle de propriété de l'API Agents.

Limites

Il n'existe pas de correspondance universelle un-à-un entre le SDK et l'API pour la migration, car les applications utilisent le SDK Agents différemment. Certaines s'appuient fortement sur les sessions et les transferts ; d'autres l'utilisent comme un simple exécuteur autour d'outils fonctionnels. La migration correcte dépend des responsabilités que votre application assume réellement aujourd'hui.

L'API Agents est également en bêta publique, donc les détails d'implémentation peuvent évoluer. Considérez les principes de propriété dans cet article comme plus durables que toute forme d'endpoint individuelle.

Conclusion

Migrer du SDK Agents vers l'API Agents se comprend mieux comme un déplacement de la frontière du runtime d'agents. Le harnais managé prend en charge davantage de la boucle, de la continuité de session, de la compaction et de la récupération. Votre application doit devenir plus explicite sur les responsabilités qui restent les vôtres : vérité métier, autorisation, effets de bord des fonctions, artefacts, auditabilité et cycle de vie produit.

Si une migration laisse en place toute l'ancienne machinerie d'orchestration et se contente de remplacer les appels SDK par des appels à l'API Agents, elle a probablement manqué l'opportunité architecturale. L'objectif n'est pas de reproduire l'ancien runtime au-dessus du nouveau. L'objectif est de décider quelles responsabilités de runtime n'appartiennent plus à votre application.

FAQ

Glossaire

Sources primaires et lectures complémentaires