API Responses vs Chat Completions pour les agents : choisir un contrat

Pour les charges de travail d'agents, l'API Responses est le meilleur choix par défaut : elle vous offre un état de conversation côté serveur via previous_response_id, des éléments de sortie typés au lieu d'un bloc de message unique, et des événements de streaming sémantiques. Ces fonctionnalités réduisent la charge de gestion que votre couche d'orchestration devrait autrement assumer. Chat Completions reste un choix valable lorsque vous souhaitez un contrôle total sur l'historique des messages ou si vous intégrez des outils conçus autour du format de message de chat d'OpenAI, mais pour les agents effectuant des appels d'outils multi-tours, Responses est l'option la plus directe.

Les deux endpoints sont documentés sur les pages de référence des modèles actuels pour GPT-5.6 et GPT-5.5, et le contrat de requête/réponse partagé pour Responses est spécifié dans la référence de création Responses.

Points clés à retenir

• Chat Completions est géré par l'appelant : vous envoyez le tableau messages complet à chaque requête et reconstruisez l'historique vous-même.
• Responses est assisté par le serveur : vous envoyez input ainsi que des instructions optionnelles, et vous pouvez enchaîner les tours avec previous_response_id au lieu de renvoyer l'historique.
• L'appel d'outils diffère structurellement : Chat Completions imbrique les appels sous choices[0].message.tool_calls ; Responses les émet sous forme d'éléments typés dans un tableau output plat.
• Les résultats des outils sont mis en correspondance par tool_call_id (Chat) contre call_id sur un élément function_call_output (Responses).
• Le streaming est basé sur des deltas de fragments dans Chat Completions, contre des événements sémantiques nommés dans Responses.
• Le support d'outils hébergés (recherche web, interpréteur de code, recherche de fichiers, etc.) dépend du modèle dans les deux API ; vérifiez la page du modèle avant de supposer leur disponibilité.

Comparaison au niveau des champs

Préoccupation	Chat Completions	Responses
Endpoint	POST /v1/chat/completions	POST /v1/responses
Entrée principale	messages: [] (tableau complet à chaque appel)	input (chaîne ou tableau d'éléments)
Guidage de type système	messages[0].role = "system"	Champ instructions au niveau supérieur
Continuation multi-tour	L'appelant renvoie tout l'historique messages	previous_response_id référence le tour précédent côté serveur
Forme de sortie	choices[0].message (objet message unique)	output: [], un tableau d'éléments typés (message, function_call, etc.)
Emplacement de l'appel d'outil	choices[0].message.tool_calls[]	Éléments dans output avec type: "function_call"
Soumission du résultat d'outil	Nouveau message avec role: "tool", tool_call_id	Élément avec type: "function_call_output", call_id
Streaming	Fragments chunk.choices[0].delta	Événements nommés (response.output_text.delta, response.completed, etc.)

previous_response_id : Ce qu'il fait réellement

Dans Chat Completions, la mémoire de la conversation est entièrement sous votre responsabilité. Chaque requête doit inclure l'historique complet des messages, et le serveur n'a aucune notion du tour précédent. L'API Responses renvoie quant à elle un id sur chaque objet de réponse. Si votre application persiste cet id et le renvoie en tant que previous_response_id lors de l'appel suivant, le serveur reconstruit l'état de la conversation précédente de son côté. Vous n'avez besoin d'envoyer que le nouvel input pour le tour actuel ainsi que (optionnellement) de nouvelles instructions. Cela déplace la gestion de l'état de votre couche applicative vers l'infrastructure d'OpenAI, ce qui est important pour les agents effectuant de nombreux appels d'outils séquentiels, car vous évitez de re-sérialiser et de re-transmettre un historique grandissant à chaque saut.

Le compromis est que votre application doit toujours persister l'id dans un endroit durable (un magasin de session, une ligne de base de données) entre les tours ; l'API ne vous offre pas une rétention infinie ou une recherche sur les réponses passées, elle vous permet simplement de référencer celle qui précède immédiatement comme point de continuation.

Exemples de requêtes actuelles (gpt-5.6)

Chat Completions : vous gérez l'historique complet :

{
  "model": "gpt-5.6",
  "messages": [
    { "role": "system", "content": "You are a support agent." },
    { "role": "user", "content": "Check order #4471 status." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } }
      }
    }
  ]
}

Responses : premier tour avec instructions et input :

{
  "model": "gpt-5.6",
  "instructions": "You are a support agent.",
  "input": "Check order #4471 status.",
  "tools": [
    {
      "type": "function",
      "name": "get_order_status",
      "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } }
    }
  ]
}

Responses : tour de suivi, aucun historique renvoyé :

{
  "model": "gpt-5.6",
  "previous_response_id": "resp_abc123",
  "input": "What about order #4472?"
}

Cycle de vie des appels de fonction

Chat Completions :

1. Le modèle renvoie choices[0].message.tool_calls, chacun avec un id et le nom/arguments de la fonction.
2. Vous exécutez la fonction localement.
3. Vous ajoutez le message de l'assistant (avec tool_calls) à votre tableau messages, puis ajoutez un nouveau message : { "role": "tool", "tool_call_id": "<id>", "content": "<result>" }.
4. Vous renvoyez tout le tableau messages mis à jour pour continuer.

Responses :

1. Le tableau output contient un élément avec type: "function_call", incluant un call_id, name, et arguments.
2. Vous exécutez la fonction localement.
3. Vous envoyez une nouvelle requête avec previous_response_id défini sur l'id de la réponse précédente, et input contenant un élément avec type: "function_call_output", correspondant au call_id, et le résultat.
4. Le serveur a déjà conservé le contexte de l'appel de fonction, vous ne renvoyez donc pas les tours précédents.

La différence structurelle entre des éléments de sortie typés plats et un message unique avec un tableau imbriqué tend à simplifier la logique d'analyse dans Responses, car vous pouvez itérer sur output et basculer sur le type plutôt que de fouiller dans les champs optionnels d'un message.

Liste de contrôle pour la décision

• Vous construisez un agent multi-tour avec des appels d'outils ? Utilisez Responses par défaut ; previous_response_id supprime la gestion de l'historique.
• Besoin d'un contrôle exact sur ce qui se trouve dans l'historique (rédaction, résumé personnalisé, injection de messages non standard) ? Chat Completions vous donne ce contrôle explicitement, puisque vous assemblez vous-même les messages.
• Migration d'une intégration Chat Completions existante ? Pesez le coût de refactorisation par rapport aux économies de gestion d'état ; pour des appels courts et à tour unique, l'avantage est moindre.
• Dépendance aux outils hébergés (recherche, interpréteur de code, outils de fichiers) ? Vérifiez le support sur la page du modèle spécifique avant de vous engager, car la disponibilité varie selon le modèle et l'endpoint.
• Besoin de streaming avec une sémantique d'événements fine (par exemple, distinguer les deltas de texte des deltas d'appels d'outils sans inspecter la forme du delta) ? Les événements nommés de Responses sont plus explicites que les fragments delta génériques de Chat Completions.
• Travail au sein d'un framework ou SDK existant construit autour des messages de chat ? Confirmez la maturité de son support pour Responses avant de changer de contrat en cours de projet.

Agents multi-fournisseurs et traduction de contrat

Les agents restent rarement longtemps chez un seul fournisseur. Un agent de codage pourrait s'orienter vers Claude Sonnet 5 ou Kimi K2.7 Code pour le travail d'implémentation, se rabattre sur DeepSeek V4 Flash ou Gemini 3.5 Flash pour des brouillons bon marché, et appeler occasionnellement GLM-5.2 ou Qwen3.7 Plus pour le contrôle des coûts des modèles open-weight. Aucun de ces fournisseurs n'expose nécessairement le contrat Chat Completions ou Responses d'OpenAI de manière native.

C'est là qu'une couche de routage prend tout son sens. La documentation de TokenLab sur docs.tokenlab.sh décrit une surface d'API unique et une clé utilisée pour atteindre plusieurs fournisseurs de modèles, ce qui élimine le besoin d'écrire manuellement une intégration client distincte par contrat de fournisseur. Notre article connexe sur les alias d'en-têtes pour la compatibilité des contrats explique comment les en-têtes de requête peuvent être mappés afin que le code écrit pour une forme de contrat puisse atteindre des modèles qui ne le gèrent pas nativement. Si vous construisez un chatbot ou un agent qui doit appeler plus d'une famille de modèles, notre guide sur la construction d'un chatbot IA avec une seule clé API détaille la configuration en termes plus concrets.

Pour la liste complète et actuelle des modèles accessibles via TokenLab, y compris les options de pointe, de codage et de routage à faible coût référencées ci-dessus, consultez notre page de modèles. Confirmez la disponibilité actuelle et toute note spécifique au contrat avant de finaliser votre architecture, car les gammes de modèles changent plus souvent que les contrats d'API.

Limitations

Cet article ne reformule pas la référence exacte de l'API au niveau des champs d'OpenAI pour l'un ou l'autre contrat, car ces détails sont versionnés et peuvent changer. Ne traitez pas l'exemple de forme de requête ci-dessus comme du code prêt pour la production. Nous n'avons pas non plus couvert en profondeur le contrat natif de chaque fournisseur ; Claude, Gemini, DeepSeek et GLM publient chacun leurs propres références d'API, et aucun d'entre eux n'est obligé de correspondre aux formes Chat Completions ou Responses d'OpenAI. Si votre agent a besoin de garanties sur l'ordre des appels d'outils, les formats d'événements de streaming ou le comportement de traitement par lots, vérifiez ces spécificités par rapport à la documentation actuelle du fournisseur nommé, et non par rapport à cet article.

FAQ

L'API Responses est-elle un remplacement de Chat Completions ? La documentation de démarrage rapide d'OpenAI positionne l'API Responses comme le chemin actuel pour le nouveau développement, y compris les cas d'utilisation agentiques, tandis que Chat Completions reste une partie de leur surface d'API documentée. Le fait que Chat Completions soit obsolète, arrêté ou simplement considéré comme un héritage à un moment donné est quelque chose que vous devriez confirmer directement dans les documents actuels d'OpenAI, car le statut du support peut changer.

D'autres fournisseurs comme Claude, Gemini ou DeepSeek utilisent-ils les mêmes contrats ? Pas nativement. Chaque fournisseur définit sa propre forme de requête et de réponse. Si vous devez exécuter un agent sur des modèles OpenAI et des fournisseurs comme Claude Sonnet 5 ou DeepSeek V4 Pro, prévoyez une couche de traduction plutôt que de supposer un contrat partagé.

Le changement de contrat modifie-t-il la qualité de sortie du modèle ? Non. Le contrat est le transport et la structure de la requête et de la réponse, pas le modèle lui-même. La qualité de sortie est régie par le modèle que vous appelez (par exemple GPT-5.5 contre Claude Sonnet 5), et non par le fait que vous ayez utilisé Chat Completions ou l'API Responses pour l'appeler.

Si vous évaluez quel contrat et quels modèles conviennent à votre agent, commencez par une petite construction de test par rapport aux endpoints documentés de TokenLab et comparez directement la surcharge d'orchestration. Commencez sur docs.tokenlab.sh pour exécuter cette comparaison par rapport à votre propre charge de travail.