Chat Completions → Responses

Migrez Messages, Choices et les fragments Chat vers les Input, Output Items et événements Responses.

Chat Completions organise les conversations via messages et choices ; Responses utilise input, Typed Items et output pour les entrées, les appels d’outils et les résultats. La migration exige un nouvel endpoint, mais aussi une adaptation des entrées, de l’analyse des réponses, de la boucle d’outils et de la machine à états du streaming.

Vérifiez d’abord le support de Responses

Le support des champs, événements et outils Responses varie selon le modèle. Avant de migrer, vérifiez le modèle dans le catalogue de modèles et exécutez une requête textuelle minimale.

Faut-il migrer ?

Le passage à Responses convient si :

Un nouveau projet souhaite utiliser des Typed Input et Output Items unifiés ;
Vous avez besoin d’un état multitour tel que previous_response_id ;
Vous avez besoin des outils intégrés déjà pris en charge par Responses ;
L’application peut traiter le texte, les appels d’outils et les autres sorties selon le type d’Item.

Vous pouvez conserver Chat Completions si :

L’application fonctionne de manière stable avec messages, choices et Chat Delta ;
Le modèle ou les outils requis ne prennent en charge que Chat Completions ;
Les tests de régression ne couvrent pas suffisamment les outils, le multitour et le streaming ;
Les bénéfices ne justifient pas le coût de modification de l’analyse des réponses et de la gestion d’état.

Principaux changements

Chat Completions	Responses	Action de migration
`POST /v1/chat/completions`	`POST /v1/responses`	Changer la méthode Client ou le chemin de requête
`messages`	`input` / Input Items	Conserver le sens des rôles et du contenu dans la structure d’entrée Responses
Message système ou développeur	`instructions` ou Typed Input	Définir la frontière entre instructions et historique
`max_completion_tokens`	`max_output_tokens`	Renommer le champ
`response_format`	`text.format`	Déplacer la configuration de sortie structurée
`choices[].message`	Items `output[]`	Parcourir selon les types d’Item et de Content
`tool_calls`	Item `function_call`	Conserver le nom de fonction, les arguments et l’ID d’appel
Tool Message	Item `function_call_output`	Renvoyer le résultat avec le `call_id` correspondant
Chat Delta	Événements `response.*`	Réécrire la répartition des événements de streaming
`prompt_tokens` / `completion_tokens`	`input_tokens` / `output_tokens`	Adapter la lecture de Usage

Requête minimale : avant et après

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "Répondez de manière concise et précise."
    },
    {
      "role": "user",
      "content": "Présentez AGTCloud en une phrase."
    }
  ]
}

Avec OpenAI SDK, la Base URL du Client reste https://api.agtcloud.cn/v1. Remplacez client.chat.completions.create(...) par client.responses.create(...). Consultez OpenAI SDK pour l’initialisation Python et TypeScript.

Migrer la lecture des réponses

Chat Completions lit généralement le message de l’assistant depuis le premier Choice :

choices[0].message.content

Responses renvoie un output[] ordonné pouvant contenir des messages, des appels de fonctions, des appels de recherche et d’autres Item. Le output_text du SDK permet de lire le texte agrégé, mais pour les outils et les autres sorties, parcourez tout output.

response.output_text
response.output[]

Ne supposez pas que output[0] contient du texte

Des appels d’outils ou d’autres Item peuvent précéder les messages textuels. Répartissez le traitement selon type et conservez des journaux ou un chemin compatible pour les Item encore inconnus.

Migrer l’état multitour

Approche	Utilisation	Points d’attention
Relecture côté client	Réinsérer les Input et Output Items historiques dans le prochain `input`	L’application contrôle la conservation, la réduction et la confidentialité
Association de réponses	Transmettre `previous_response_id` à la prochaine requête	Vérifier d’abord le support par le modèle et l’interface

Avec previous_response_id, les instructions précédentes ne sont pas héritées automatiquement. Définissez de nouveau les instructions nécessaires à chaque tour.

Après migration, ne rejouez pas un historique complet tout en le référençant via previous_response_id : cela peut dupliquer le contexte.

Migrer Function Calling

Définitions des outils

Chat Completions place la définition de fonction dans tools[].function :

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Consulter la météo d’une ville",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" }
      },
      "required": ["city"]
    }
  }
}

Responses place les informations de fonction directement dans l’objet Function Tool :

{
  "type": "function",
  "name": "get_weather",
  "description": "Consulter la météo d’une ville",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string" }
    },
    "required": ["city"]
  }
}

Renvoi des résultats

Chat : lisez les appels dans assistant.tool_calls[], puis ajoutez un Tool Message avec tool_call_id.
Responses : lisez function_call dans output[], puis envoyez function_call_output avec le même call_id que l’appel initial.

Quel que soit le protocole, votre application exécute les fonctions. N’exécutez pas directement des arguments non validés et ne présentez pas une erreur d’outil comme un résultat normal.

Migrer le streaming

Chat Completions renvoie les fragments via choices[].delta dans chaque Chunk, généralement jusqu’à [DONE].

Responses utilise des événements nommés, par exemple :

response.created ;
response.output_item.added ;
response.content_part.added ;
response.output_text.delta ;
response.output_text.done ;
response.completed.

Remplacez l’assemblage du texte seul par une répartition des événements : traitez d’abord leur type, puis mettez à jour l’état correspondant à output_index, content_index, item_id et aux autres identifiants.

Une interruption de flux n’est pas une fin réussie

Marquez un tour comme réussi uniquement après réception de l’événement de fin et vérification de l’état de la réponse. Traitez séparément les interruptions, les échecs et les états incomplets.

Migrer Structured Outputs

Chat Completions configure le format dans response_format ; Responses le place dans text.format. Adaptez simultanément :

L’emplacement des champs de requête ;
La structure d’enveloppe du JSON Schema ;
Les utilitaires d’analyse du SDK ;
Le traitement des refus, des réponses incomplètes et des échecs de validation du Schema.

Consultez Chat Completions et OpenAI Responses pour les champs détaillés.

Migrer Web Search

Les deux protocoles ont des points d’entrée de recherche différents :

Chat Completions utilise web_search_options et exige un modèle prenant en charge la recherche ;
Responses active un Web Search Tool pris en charge dans tools et peut renvoyer des Item d’appel de recherche et des citations.

Le filtrage des domaines, les listes de sources, la localisation et l’accès Internet en temps réel dépendent du protocole et du modèle. Consultez OpenAI Web Search pour les exemples complets.

Usage, erreurs et interruptions

Pour adapter le suivi et la lecture de facturation, modifiez au minimum :

Chat Completions	Responses
`usage.prompt_tokens`	`usage.input_tokens`
`usage.completion_tokens`	`usage.output_tokens`
`usage.total_tokens`	`usage.total_tokens`
`finish_reason`	État ou erreur de la Response, de l’Item et du contenu

Conservez aussi le code HTTP, l’objet d’erreur et le Request ID. Ne vous limitez pas au texte d’exception du SDK ; les journaux doivent distinguer l’échec d’authentification, le modèle inaccessible, la limite de débit, l’erreur de service et l’interruption.

Migration par étapes

Migrer le parcours textuel minimal

Commencez par la création de requêtes et la lecture du texte, sans streaming, outils ni état multitour.

Adapter la répartition des Output Item

Prenez en charge les messages et les appels de fonctions, tout en restant compatible avec les Item inconnus sans les supprimer directement.

Migrer l’état et les événements de streaming

Validez séparément la relecture de l’historique côté client, previous_response_id, les fragments de texte, les fragments d’arguments d’outils et les événements de fin.

Rétablir les capacités avancées

Activez progressivement les sorties structurées, Web Search et les entrées multimodales, avec un cas de régression distinct pour chaque capacité.

Liste de régression et de repli

Texte ordinaire, sortie vide, refus, états incomplets et échecs ;
Un ou plusieurs outils, échecs d’outils et erreurs de validation des arguments ;
Relecture d’historique sans état et previous_response_id ;
Fin normale du streaming, interruptions et événements dupliqués ;
Échecs de validation Structured Outputs ;
Usage, erreurs, Request ID, délais et limites de débit ;
Repli vers Chat Completions lorsqu’une capacité Responses n’est pas prise en charge par le modèle.

Avant la bascule en production, conservez des configurations distinctes et un commutateur contrôlable pour Chat et Responses. Retirez l’ancien parcours d’analyse après stabilisation des indicateurs métier, des journaux et du traitement des erreurs.

Étapes suivantes

Configurez un Client Python ou TypeScript avec OpenAI SDK ;
Consultez Texte et conversation pour le parcours habituel d’appel Responses ;
Vérifiez tous les champs et les réponses dans OpenAI Responses ;
En cas d’erreur d’appel, consultez Erreurs et dépannage.

Chat Completions → Responses

Sur cette page