Utilisez l’API Responses
Commencez toujours par l’API Responses. C’est l’API phare d’OpenAI et le meilleur moyen d’accéder aux comportements les plus récents des modèles, aux outils intégrés, aux workflows avec état et aux fonctionnalités des agents.
Choisissez un modèle adapté à la charge de travail
Évaluez la famille de modèles GPT-6 sur vos tâches. Utilisez gpt-6-astra pour bénéficier des capacités les plus avancées, gpt-6.1-sol pour les travaux complexes de programmation et les tâches professionnelles à moindre coût qu’avec Astra, et gpt-6-luna pour traiter efficacement des tâches répétables. Choisissez le modèle qui obtient de bons résultats sur des tâches représentatives plutôt que d’acheminer systématiquement les requêtes vers le modèle le plus performant.
Lors de la migration vers GPT-6, conservez le rôle de votre modèle actuel dans le traitement des tâches ainsi que son effort de raisonnement effectif lorsque le nouveau modèle le prend en charge. Utilisez l’API Responses pour raisonner avec des outils. GPT-6 Astra et GPT-6.1 Sol nécessitent Responses pour les appels d’outils. GPT-6 Sol et GPT-6 Luna prennent en charge les appels de fonctions dans Chat Completions uniquement avec reasoning_effort: "none". Lorsque l’effort de raisonnement diffère de none, supprimez temperature, top_p et top_logprobs. Supprimez également logprobs des requêtes Chat Completions et message.output_text.logprobs du tableau include de Responses. Vérifiez les conditions d’éligibilité à la résidence des données avant de choisir un modèle ou un niveau de traitement. Consultez le guide de migration des modèles pour les autres vérifications de compatibilité. Exécutez des évaluations représentatives avant de modifier les prompts ou d’ajouter de nouvelles fonctionnalités. Comparez le taux de réussite des tâches, la latence, le nombre de tokens en entrée, en sortie, consacrés au raisonnement et écrits en cache, ainsi que le coût par tâche réussie.
Configurez reasoning.effort
Utilisez reasoning.effort pour régler l’effort que le modèle consacre au raisonnement avant de répondre.
GPT-6 Astra, GPT-6.1 Sol, GPT-6 Sol et GPT-6 Luna prennent en charge low, medium, high, xhigh et max. GPT-6 Sol et GPT-6 Luna prennent également en charge none, contrairement à GPT-6 Astra et GPT-6.1 Sol. Un effort moindre accélère la réponse et consomme moins de tokens de raisonnement. Un effort supérieur donne au modèle davantage de temps pour planifier, déboguer, faire une synthèse ou arbitrer entre plusieurs options au fil des étapes.
Utilisez low pour les tâches qui consistent principalement à extraire, acheminer ou classer des informations, ou à effectuer une reformulation simple. Utilisez medium ou high lorsque le modèle doit diagnostiquer un problème, comparer des options, rédiger un plan ou analyser la logique du code. N’utilisez xhigh ou max que si des évaluations représentatives montrent que le gain de qualité justifie la latence et le coût supplémentaires. Si vous utilisiez minimal, ou si vous utilisiez none et passez à GPT-6 Astra ou GPT-6.1 Sol, commencez par low et comparez les résultats. Dans les autres cas, conservez l’effort effectif actuel et testez les changements au regard de vos objectifs de qualité, de latence et de coût.
Pour les tâches les plus difficiles où la qualité prime, comparez aussi reasoning.mode: "pro" au mode standard à effort égal. Le mode et l’effort de raisonnement sont indépendants. En mode Pro, le modèle effectue davantage de travail avant de fournir une seule réponse finale. Cela peut améliorer la fiabilité, mais augmente la latence et la consommation de tokens.
from openai import OpenAI
client = OpenAI()
prompt = """
Our CI job started failing after a dependency bump.
Error:
TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'
Identify the likeliest root cause and the smallest safe fix.
"""
response = client.responses.create(
model="gpt-6-astra",
reasoning={"effort": "xhigh", "mode": "pro"},
input=prompt,
)
print(response.output_text)Modifiez l’effort de raisonnement en cours de conversation
Avec les modèles GPT-6 en mode standard à agent unique, ajoutez un élément d’entrée configuration_update avant le prochain message de l’utilisateur pour modifier l’effort entre deux réponses. Conservez la valeur de reasoning.effort au niveau de la requête pour que le préfixe initial du prompt reste éligible à la mise en cache. La mise à jour prend effet à la prochaine réponse et reste en vigueur jusqu’à ce qu’une nouvelle mise à jour la remplace. Les mises à jour de configuration sont incompatibles avec le compactage automatique et la troncature, et /responses/compact rejette les historiques qui en contiennent. Pour compacter l’historique, incluez un élément compaction_trigger, puis ajoutez une nouvelle mise à jour.
Configurez text.verbosity
text.verbosity est le principal paramètre permettant de trouver un équilibre entre concision et exhaustivité. Choisissez une valeur faible si votre produit nécessite une réponse rapide et succincte. Augmentez-la si la réponse doit fournir des explications plus détaillées, une structure plus claire ou tout le contexte nécessaire. Une valeur faible réduit le nombre de tokens de sortie. Le modèle génère donc moins de texte et répond plus vite.
Pour les tâches de programmation, medium et high produisent généralement des réponses plus longues, mieux organisées et plus clairement structurées. Avec low, la réponse se limite davantage à l’essentiel.
Lors de la migration, vérifiez si des instructions générales comme « Soyez concis » restent utiles. Privilégiez text.verbosity pour régler le niveau de détail par défaut, puis précisez dans le prompt le contenu, la structure et la longueur attendus.
Les prompts influent également sur la qualité, la consommation de tokens, le coût et la latence. Lorsque vous réglez le niveau de détail, consultez les bonnes pratiques de rédaction des prompts pour les modèles récents, notamment les conseils sur les tests et les vérifications pour les agents de programmation.
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6-astra",
text={"verbosity": "low"},
input="""
Summarize this incident for the next on-call engineer.
- checkout latency spiked from 220 ms to 4.8 s
- only us-east-1 was affected
- rollback is complete
- likely trigger: cache stampede after deploy
""",
)
print(response.output_text)Configurez le paramètre phase de l’assistant
phase est une étiquette associée aux messages de l’assistant dans l’historique de la conversation. Elle indique au modèle si un message antérieur de l’assistant était un commentaire en cours de travail ou la réponse finale. Utilisez phase: "commentary" pour les points d’avancement, les notes précédant un appel d’outil et les autres messages intermédiaires. Utilisez phase: "final_answer" pour la réponse achevée.
L’assistant peut par exemple envoyer ce message :
{
"role": "assistant",
"phase": "commentary",
"content": "I'm checking the logs and comparing them to the last successful deploy."
}Il s’agit d’un point d’avancement. La réponse vient plus tard, par exemple :
{
"role": "assistant",
"phase": "final_answer",
"content": "The deploy failed because the migration referenced a column that does not exist in production."
}Cette distinction est utile dans les workflows de longue durée ou faisant de nombreux appels d’outils, où l’assistant peut afficher des points d’avancement avant de terminer. Lorsque vous renvoyez cet historique dans les requêtes suivantes à gpt-5.3-codex ou aux modèles ultérieurs, conservez et renvoyez phase dans les messages de l’assistant pour que le modèle puisse distinguer les points d’avancement du résultat final. Cela limite les arrêts prématurés et augmente les chances que l’agent poursuive son travail jusqu’à la réponse finale.
Utilisez tool_search
Au lieu de charger tout le catalogue d’outils à chaque requête, utilisez la recherche d’outils. Ajoutez {"type": "tool_search"} et marquez les définitions d’outils coûteuses à charger avec defer_loading: true. Le modèle peut ainsi charger uniquement les outils dont il a besoin à l’exécution. Au début de la requête, il ne voit que le nom et la description de l’outil de recherche. S’il estime avoir besoin d’un outil à chargement différé, il lance la recherche. C’est seulement alors que les définitions différées sont chargées dans le contexte et que le modèle peut appeler les outils correspondants. Cette approche économise des tokens et préserve les performances du cache.
La recherche d’outils propose deux modes :
- La recherche d’outils hébergée est l’option la plus simple. Utilisez-la lorsque vous savez déjà quels outils pourraient être disponibles pour la requête.
- La recherche d’outils côté client convient lorsque votre application doit déterminer les outils disponibles, par exemple en fonction du tenant de l’utilisateur, de son projet, de ses autorisations ou d’un registre interne.
Commencez par la recherche d’outils hébergée, sauf si votre application doit elle-même contrôler la découverte des outils.
Regroupez vos outils selon l’intention de l’utilisateur. Utilisez si possible un espace de noms ou un serveur MCP. Le modèle choisit plus facilement parmi quelques groupes bien définis que dans une longue liste de fonctions sans hiérarchie. Nous recommandons de rester sous la dizaine de fonctions par espace de noms pour optimiser la consommation de tokens et les performances du modèle.
Rédigez des descriptions courtes qui permettent de distinguer les espaces de noms. Placez les instructions détaillées dans les définitions d’outils à chargement différé. Évitez de réunir tous les outils dans un seul grand espace de noms.
from openai import OpenAI
client = OpenAI()
billing_namespace = {
"type": "namespace",
"name": "billing",
"description": "Billing tools for invoices, payments, taxes, and credits.",
"tools": [
{
"type": "function",
"name": "lookup_invoice",
"description": "Look up invoice state, taxes, credits, and payment attempts.",
"parameters": {
"type": "object",
"properties": {
"invoice_id": {"type": "string"},
},
"required": ["invoice_id"],
"additionalProperties": False,
},
"strict": True,
"defer_loading": True,
}
],
}
crm_namespace = {
"type": "namespace",
"name": "crm",
"description": "CRM tools for account ownership, plans, health, and payment history.",
"tools": [
{
"type": "function",
"name": "get_account",
"description": "Fetch account owner, plan, health, and payment history.",
"parameters": {
"type": "object",
"properties": {
"account_id": {"type": "string"},
},
"required": ["account_id"],
"additionalProperties": False,
},
"strict": True,
"defer_loading": True,
}
],
}
response = client.responses.create(
model="gpt-6-astra",
input=(
"Find the right billing tool and explain why invoice INV-1043 still "
"shows overdue after a payment yesterday."
),
tools=[billing_namespace, crm_namespace, {"type": "tool_search"}],
)
print(response.output)Appelez des outils par programmation
L’appel d’outils par programmation permet aux modèles compatibles d’écrire du JavaScript qui appelle des outils éligibles et réduit le volume de leurs résultats intermédiaires dans un environnement d’exécution hébergé. Utilisez-le pour des étapes bien délimitées où le code peut filtrer, joindre, classer, dédupliquer, combiner ou vérifier de gros volumes de résultats avant de renvoyer au modèle un résultat structuré plus compact.
Ajoutez l’outil programmatic_tool_calling et activez cette fonctionnalité pour chaque outil éligible. Utilisez allowed_callers: ["programmatic"] pour les outils que seuls les programmes peuvent appeler, ou allowed_callers: ["direct", "programmatic"] si le modèle peut aussi appeler l’outil directement. Conservez les appels directs lorsque chaque résultat peut influer sur la prochaine décision du modèle, qu’une action exige une approbation ou que la réponse finale doit conserver des citations ou des artefacts natifs. Documentez les champs renvoyés par les outils et leur comportement en cas d’erreur pour que le modèle puisse écrire un programme correct sans examiner un premier résultat.
Votre boucle d’appels d’outils doit traiter les éléments program et program_output, ainsi que les éléments function_call émis par le programme et les éléments function_call_output correspondants. Conservez chaque call_id et copiez le champ caller de l’appel de fonction dans sa sortie pour que le service puisse reprendre le bon programme.
Testez à la fois program_output et le message final de l’assistant. Même si le programme produit un résultat correct, la réponse finale peut être incomplète. Comparez le taux de réussite des tâches, les éléments de preuve requis, le nombre total de tokens, la latence et le coût avec ceux du même workflow utilisant des appels directs.
Utilisez le mode multi-agent pour travailler en parallèle
Le mode multi-agent permet aux modèles compatibles, dont ceux de la famille GPT-6, de déléguer des travaux indépendants à des sous-agents et d’en synthétiser les résultats. Utilisez-le lorsque vous pouvez diviser un travail de recherche, d’analyse ou de développement en tâches concrètes et bien délimitées, chacune disposant de son propre contexte et pouvant s’exécuter en parallèle.
Définissez multi_agent.enabled sur true dans la requête. Pour HTTP, utilisez le SDK bêta de Responses avec client.beta.responses et passez responses_multi_agent=v1 dans betas. Pour les connexions HTTP directes ou WebSocket, envoyez OpenAI-Beta: responses_multi_agent=v1. Les schémas des éléments peuvent évoluer tant que le mode multi-agent est en bêta.
Privilégiez un seul agent pour les tâches courtes, les séquences où chaque étape dépend de la précédente ou les travaux qui modifient une même ressource. Les sous-agents peuvent augmenter la consommation de tokens. Commencez donc avec la valeur par défaut de max_concurrent_subagents, soit 3, et mesurez la qualité, la latence et le coût de bout en bout. Pour les workflows multi-agents de longue durée ou faisant de nombreux appels d’outils, le mode WebSocket peut réduire le surcoût lié à la poursuite du traitement.
Avant d’activer le mode multi-agent, tenez compte de ses limites actuelles. Il ne prend pas en charge /responses/compact, reasoning.summary ni max_tool_calls. Le serveur compacte automatiquement le contexte de l’agent racine et celui de chaque sous-agent.
Appelez des outils de façon asynchrone
Sur les modèles GPT-6, définissez async: true sur une fonction ou un outil personnalisé lorsque le modèle peut continuer à travailler pendant que votre application l’exécute. Lancez tôt les appels d’outils lents et laissez le modèle traiter les tâches indépendantes. Votre application reste chargée d’exécuter et de suivre l’appel, puis d’en renvoyer le résultat dans une requête Responses ultérieure avec le call_id d’origine. L’exécution asynchrone ne s’applique ni aux outils intégrés ni aux appels d’outils par programmation. En mode multi-agent, ne combinez pas les outils asynchrones avec les appels d’outils parallèles. Consultez le guide des appels d’outils asynchrones pour connaître le déroulement complet.
Exploitez les outils intégrés
Les outils intégrés sont des fonctionnalités natives de l’API. Vous pouvez donner au modèle accès à des outils qui fonctionnent déjà dans l’API Responses sans avoir à développer chacun d’eux. Le modèle peut ensuite décider quand les utiliser.
OpenAI ajoute régulièrement des outils natifs. Commencez donc par les outils intégrés lorsqu’ils conviennent à votre workflow. Créez des outils personnalisés lorsque les options natives ne couvrent pas la tâche. Les outils intégrés et options associées comprennent actuellement :
- Recherche web : recherchez des informations à jour sur le Web.
- Recherche de fichiers : effectuez des recherches dans les fichiers importés ou les bases vectorielles.
- Interpréteur de code : exécutez du Python pour analyser des données, effectuer des calculs, créer des graphiques et traiter des fichiers.
- Shell : exécutez des commandes shell dans un conteneur hébergé ou dans votre propre environnement d’exécution.
- Utilisation de l’ordinateur : interagissez avec une interface à l’aide de captures d’écran, de clics, de saisies au clavier et de défilements.
- Génération d’images : générez ou modifiez des images.
- MCP/connecteurs : connectez le modèle à des services et outils externes.
- Skills : joignez des ensembles d’instructions réutilisables et des fichiers de workflow.
- Application de correctifs : apportez des modifications structurées au code.
La qualité des résultats du modèle est une autre raison de privilégier ces outils. Les outils intégrés font partie de la distribution de données utilisée lors du post-entraînement : les modèles sont entraînés et évalués sur leurs structures, leurs comportements et leurs sorties. Avec des outils intégrés, les modèles OpenAI sélectionnent mieux les outils, les exécutent plus efficacement et rencontrent moins d’échecs qu’avec de nouveaux outils.
Exploitez le compactage
Le compactage est un outil d’ingénierie du contexte qui détermine les informations que le modèle conserve au fil des tours. Pour un agent qui travaille longtemps, la question dépasse « Vais-je atteindre la limite de contexte ? ». Les anciens messages, les journaux d’outils, les nouvelles tentatives et les détails périmés finissent par prendre la place des informations d’état dont le modèle a besoin.
Le compactage permet de réduire de façon contrôlée la taille du contexte tout en conservant l’état nécessaire aux tours suivants. Après une étape importante, par exemple à la fin d’une phase de débogage ou lorsque vous avez mieux cerné la cause d’un problème, vous pouvez compacter la fenêtre de contexte précédente et poursuivre à partir du résultat. Le modèle reste ainsi concentré sur l’essentiel : le tour suivant s’appuie sur les informations d’état pertinentes, sans s’encombrer de chaque raisonnement intermédiaire, commande échouée ou piste abandonnée.
Vous pouvez utiliser le compactage de deux façons :
- Confiez-le au serveur : si vous utilisez
previous_response_id, activezcontext_managementavec un seuilcompact_threshold. Le serveur compacte automatiquement la conversation lorsqu’elle devient trop volumineuse. Vous continuez à envoyer uniquement le dernier message de l’utilisateur. - Gérez-le vous-même : si vous gérez vous-même l’intégralité du tableau d’entrée, appelez
client.responses.compact(). Vous obtenez une fenêtre de contexte plus petite. Utilisez directement la sortie renvoyée dans le prochain appel àresponses.create().
Ne modifiez pas la sortie compactée. Elle contient l’état machine dont le modèle a besoin pour poursuivre son travail, sous une forme différente d’un résumé destiné à un lecteur. Transmettez-la telle quelle, puis ajoutez le prochain message de l’utilisateur.
from openai import OpenAI
client = OpenAI()
# Full window collected from a long debugging session:
# user messages, assistant outputs, tool calls, and tool outputs.
long_window = session_items
compacted = client.responses.compact(
model="gpt-6-astra",
input=long_window,
)
next_response = client.responses.create(
model="gpt-6-astra",
store=False,
input=[
*compacted.output, # Use compact output as-is.
{
"type": "message",
"role": "user",
"content": (
"We found the bad cache invalidation path. Write the fix plan "
"and the verification checklist."
),
},
],
)
print(next_response.output_text)Optimisez la mise en cache des prompts
La mise en cache des prompts réduit automatiquement la latence et le coût lorsque des requêtes réutilisent un même préfixe long. Placez d’abord les instructions stables, les exemples et les documents de référence, puis le contenu dynamique propre à l’utilisateur. Conservez les mêmes définitions d’outils et le même ordre. Ajoutez les nouveaux tours de conversation à la suite sans réécrire le contexte précédent.
GPT-5.6 a introduit la mise en cache explicite des prompts. La mise en cache implicite reste activée par défaut, mais les modèles GPT-5.6 et les familles ultérieures prennent aussi en charge les points de coupure explicites du cache et une politique de cache applicable à toute la requête. Si un suffixe variable suit un préfixe stable, ajoutez un prompt_cache_breakpoint explicite à la fin de la partie réutilisable. Définissez prompt_cache_options.mode sur explicit uniquement si la requête doit utiliser exclusivement les points de coupure que vous fournissez, sans point de coupure implicite. Les modèles antérieurs continuent à utiliser uniquement la mise en cache automatique des prompts.
Si vous migrez depuis GPT-5.5 ou une version antérieure, remplacez prompt_cache_retention par prompt_cache_options.ttl: "30m". Consultez les différences de mise en cache des prompts selon les modèles avant de modifier les paramètres du cache.
Sur les modèles GPT-5.6 et les familles ultérieures, les écritures en cache coûtent 1,25 fois le tarif des tokens d’entrée hors cache. Consignez cached_tokens et cache_write_tokens, puis comparez le volume des écritures à celui des lectures ultérieures pour mesurer le coût net et ajuster la position des points de coupure.
Utilisez une valeur stable de prompt_cache_key pour les requêtes qui partagent un préfixe réutilisable. Cela facilite leur acheminement vers le même cache et optimise le taux de succès du cache sur les modèles antérieurs à GPT-5.6. Pour les groupes à fort trafic, suivez les conseils de répartition du trafic sur davantage de clés.
À partir de GPT-5.6, prompt_cache_key est facultatif. Vous pouvez obtenir un taux de succès optimal du cache sans ce paramètre. Il permet toutefois de comptabiliser séparément l’utilisation du cache par client, utilisateur ou espace de travail. Il est alors plus facile d’expliquer à chaque groupe sa consommation de tokens en cache et sa facturation. Attribuez une clé distincte à chaque client et conservez-la pour toutes ses requêtes apparentées. Des clés distinctes contribuent aussi à empêcher un client de sonder le cache pour détecter les accès d’un autre client. Consultez la section Comptabilisez séparément l’utilisation du cache à l’aide de clés.
from openai import OpenAI
client = OpenAI()
instructions = """
You are the support agent for Acme.
Follow the Acme support policy and escalation rubric.
Use the same tone, safety rules, and tool plan for each ticket.
"""
response = client.responses.create(
model="gpt-6-astra",
prompt_cache_key="tenant-acme-support-agent",
instructions=instructions,
input="Summarize the current escalation for the on-call lead.",
)
print(response.output_text)Utilisez reasoning.encrypted_content
Les modèles compatibles, dont les modèles GPT-6, peuvent conserver le raisonnement d’un appel à l’autre. Utilisez reasoning.context: "all_turns" lorsque les objectifs, les hypothèses et les priorités de la tâche restent stables. Utilisez current_turn lorsque le raisonnement antérieur n’est plus pertinent et risque de maintenir le modèle sur une piste dépassée. Si vous omettez reasoning.context ou lui attribuez la valeur auto, vérifiez le champ reasoning.context de la réponse pour confirmer le mode effectif.
La persistance du raisonnement fonctionne uniquement si les éléments de raisonnement antérieurs sont disponibles. Utilisez previous_response_id pour les réponses stockées. Si votre politique de non-conservation des données (ZDR) interdit le stockage des données de réponse, le contenu de raisonnement chiffré permet de passer le relais sans état côté serveur.
Par défaut, les éléments de raisonnement en sortie de la réponse contiennent le raisonnement sous forme chiffrée. Vous pouvez accéder à ce contenu via la propriété encrypted_content de chaque élément de raisonnement. Votre application n’a pas besoin d’interpréter cette valeur. Elle conserve chaque élément exactement tel qu’il a été renvoyé et le transmet au tour suivant pour que le modèle puisse poursuivre le workflow.
from openai import OpenAI
client = OpenAI()
history = [
{
"role": "user",
"content": "Investigate why invoice INV-1043 has mismatched tax totals.",
}
]
first = client.responses.create(
model="gpt-6-astra",
store=False,
reasoning={"effort": "medium", "context": "current_turn"},
input=history,
)
history.extend(item.to_dict() for item in first.output)
history.append(
{
"role": "user",
"content": "Now write the customer-facing explanation in plain English.",
}
)
second = client.responses.create(
model="gpt-6-astra",
store=False,
reasoning={"effort": "medium", "context": "all_turns"},
input=history,
)
print(second.output_text)Adaptez le niveau de détail des images à la tâche
Pour les images, detail vaut auto par défaut. Le redimensionnement dépend du modèle. Les grandes images peuvent consommer davantage de tokens d’entrée et augmenter la latence. Consultez le tableau de redimensionnement par modèle et, avant le déploiement, mesurez la consommation de tokens des images et vérifiez les limites avec le modèle choisi.
Choisissez la valeur de detail en fonction de la tâche. Redimensionnez l’image, utilisez low lorsque les détails visuels fins importent peu, ou utilisez high pour une analyse d’image standard à haute fidélité. Lorsque le modèle le prend en charge, utilisez original si le détail supplémentaire améliore la qualité, par exemple pour les images grandes ou denses, les tâches sensibles aux coordonnées, la reconnaissance optique de caractères, la localisation ou l’inspection visuelle. Avant le déploiement, mesurez la consommation de tokens des images et la latence dans le pire des cas.
Envoyez un identifiant de sécurité
Si votre application s’adresse à des utilisateurs finaux, envoyez avec chaque requête un safety_identifier stable qui préserve leur confidentialité. Il aide OpenAI à détecter les abus et donne à votre équipe un moyen fiable de retracer les violations des règles. Il réduit également le risque qu’un abus commis par un utilisateur perturbe l’accès de toute votre organisation.
Hachez le nom d’utilisateur ou l’adresse e-mail au lieu d’envoyer des informations permettant d’identifier la personne. Pour les utilisateurs non connectés, utilisez un identifiant de session stable.
Gérez les résultats de la surveillance des défauts d’alignement
Dans les workflows d’agents utilisant GPT-6 Astra, prévoyez la surveillance des défauts d’alignement. Si une requête renvoie 403 avec misalignment_policy_violation, cessez de lancer des actions pour cette conversation et ne relancez pas automatiquement le workflow bloqué. Traitez aussi les erreurs lors de la diffusion en continu et vérifiez les actions qui ont pu être exécutées. Abonnez-vous à safety.alert.created si votre équipe a besoin d’alertes au niveau du projet. Le webhook ne remplace pas la gestion des erreurs de requête. Consultez le guide pour savoir quelles requêtes Responses peuvent être arrêtées automatiquement.
Gérez les hausses rapides de trafic et la surcharge du modèle
Vérifiez le statut HTTP et error.code avant de décider de la marche à suivre. Un statut 429 avec slow_down indique que le débit des requêtes a augmenté trop rapidement. Respectez Retry-After s’il est présent, réduisez le trafic, puis augmentez-le progressivement. Un statut 503 avec server_is_overloaded signifie que le modèle demandé est temporairement surchargé. Respectez Retry-After s’il est présent, puis réessayez. En l’absence de cet en-tête, augmentez de manière exponentielle le délai entre les tentatives, ajoutez une variation aléatoire et limitez le nombre de tentatives. Les erreurs de facturation, de dépenses ou de quota exigent une intervention avant toute nouvelle tentative. Ne traitez pas chaque 429 comme une limite de débit temporaire. Consultez les limites de débit et les codes d’erreur.
Utilisez background=True
Utilisez background=True pour les requêtes susceptibles de prendre du temps. Au lieu de maintenir la connexion du client ouverte, l’API lance une tâche et renvoie un identifiant. Votre application peut interroger périodiquement la tâche jusqu’à ce qu’elle se termine, échoue ou soit annulée. Utilisez ce mode pour les analyses volumineuses, les exécutions d’outils de longue durée ou les travaux dont vous devez suivre l’état et gérer les nouvelles tentatives.
# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI
import time
client = OpenAI()
log_bundle_file_id = "file_123"
job = client.responses.create(
model="gpt-6-astra",
background=True,
store=False,
input="Analyze this large log bundle and cluster the primary failure modes.",
tools=[
{
"type": "code_interpreter",
"container": {
"type": "auto",
"file_ids": [log_bundle_file_id],
},
}
],
)
while job.status in {"queued", "in_progress"}:
time.sleep(2)
job = client.responses.retrieve(job.id)
print(job.output_text)Vous pouvez combiner ce mode avec stream=True pour recevoir des événements de progression, mais le premier événement peut mettre plus de temps à arriver qu’avec une requête ordinaire.
Dans l’interface, le mode en arrière-plan peut se présenter ainsi : « Le traitement est en cours. Voici son état. Le résultat s’affichera ici dès qu’il sera prêt. »
Utilisez le mode WebSocket
Le mode WebSocket est conçu pour les workflows de longue durée qui font de nombreux appels d’outils. Vous maintenez une connexion ouverte et poursuivez le traitement en envoyant uniquement les nouveaux éléments d’entrée et previous_response_id. Pour les workflows comportant au moins 20 appels d’outils, nous avons observé une exécution de bout en bout jusqu’à environ 40 % plus rapide.
Fonctionnement : le premier message ressemble à une requête Responses ordinaire. Il contient le modèle, les instructions, les outils et l’entrée de l’utilisateur. Le serveur renvoie les événements en continu. Si le modèle demande un outil, votre application l’exécute. Puis, au lieu d’envoyer une nouvelle requête HTTP, vous envoyez un autre événement response.create sur la même connexion avec le previous_response_id de la réponse précédente et le nouvel élément. C’est à cette étape que la latence diminue. En HTTP classique, chaque échange ultérieur nécessite une nouvelle requête. En mode WebSocket, la connexion reste ouverte et l’état de la dernière réponse reste immédiatement disponible en mémoire pour cette connexion. Lorsque le tour suivant reprend à partir de cette réponse, le service a moins de travail préparatoire à effectuer.
Si votre workflow consiste en une requête et une réponse, conservez HTTP. S’il fonctionne comme un agent qui travaille sur la durée, essayez le mode WebSocket.
Utilisez des valeurs de stream_id distinctes pour les conversations parallèles sur une même connexion et acheminez les événements entrelacés selon leur stream_id. Une connexion prend en charge jusqu’à 16 réponses actives, tandis que les requêtes d’un même flux s’exécutent dans l’ordre. Une connexion peut rester ouverte jusqu’à 60 minutes. Pour poursuivre une conversation, previous_response_id fonctionne comme en mode HTTP, avec un cache propre à la connexion qui contient la dernière réponse de chaque flux.
Remarque : le mode WebSocket est compatible avec la politique ZDR, car vos données sont conservées uniquement en mémoire, sans écriture sur disque.
L’exemple Python utilise pip install "openai[realtime]>=3.8.0".
L’exemple JavaScript utilise npm install openai@^7.10.0 ws.
L’exemple Ruby utilise gem install openai async-websocket.
Pour Go, exécutez go get github.com/openai/openai-go/v3@v3.98.0.
Pour Java, ajoutez la dépendance Maven com.openai:openai-java:4.101.0.
Ces versions des SDK Go et Java prennent nativement en charge les connexions WebSocket à l’API Responses.
from openai import OpenAI
from openai.types.responses import FunctionToolParam
test_log_tool: FunctionToolParam = {
"type": "function",
"name": "search_test_logs",
"description": "Search test logs.",
"parameters": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
"additionalProperties": False,
},
"strict": True,
}
code_search_tool: FunctionToolParam = {
"type": "function",
"name": "search_code",
"description": "Search source code.",
"parameters": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
"additionalProperties": False,
},
"strict": True,
}
client = OpenAI()
with client.responses.connect() as connection:
# Use the same typed parameters as client.responses.create(...).
connection.response.create(
model="gpt-6-astra",
store=False,
input=[
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": (
"Find the flaky test in this run, call the tools "
"you need, and keep going until you can explain "
"the root cause."
),
}
],
}
],
tools=[test_log_tool, code_search_tool],
)
for event in connection:
if event.type == "response.completed":
print(event.response.output)
break
if event.type in {"response.failed", "response.incomplete", "error"}:
raise RuntimeError(event.to_json())
else:
raise RuntimeError("Connection closed before the response finished.")Réorientez le modèle en cours de tour
Si les utilisateurs peuvent ajouter des exigences pendant qu’un modèle GPT-6 travaille, utilisez une connexion WebSocket à l’API Responses. Envoyez response.steer avec l’identifiant de la réponse active dans previous_response_id et la nouvelle entrée de l’utilisateur. Continuez à lire les événements pour suivre le traitement. L’événement response.steer.accepted indique que la mise à jour est en file d’attente. La réorientation ne modifie pas les sorties déjà envoyées à votre application et n’annule pas les appels d’outils déjà lancés. Consultez le guide de réorientation en cours de tour pour connaître la séquence des événements et savoir comment traiter les résultats des outils.
À retenir
L’API Responses permet de bâtir des applications OpenAI plus intelligentes et plus performantes. Son principal atout est de permettre aux développeurs de passer de prompts ponctuels à des workflows durables qui utilisent des outils, tiennent compte du contexte et s’adaptent à la complexité de la tâche. Appliquez les recommandations de ce guide pour améliorer les performances de vos déploiements en conditions réelles.