Guide

OpenAI Agents SDK : peu d'abstractions, beaucoup de contrôle

OpenAI Agents SDK repose sur cinq concepts : agent, outil, handoff, guardrail et session. Exemples Python, traçage, mise en production et alternatives.

L'équipe CodeWorlds14 min de lecture ·

Pratique Python dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article13

La bibliothèque est née d'une expérience appelée Swarm et a gardé sa principale qualité : très peu de concepts à apprendre. Agent, outil, handoff, guardrail et session. Ces cinq éléments soutiennent un système assez complexe, et chacun se comprend en quelques minutes.

Cela la distingue des bibliothèques qui introduisent leur propre modèle de flux, un graphe d'états ou une couche intermédiaire au-dessus des fournisseurs de modèles. Ici tu écris du Python ou du TypeScript ordinaire, et la bibliothèque ajoute la boucle d'appel et l'observabilité.

Agent et outils

Un agent est un modèle avec des instructions et un ensemble d'outils. Un outil est une fonction dont le schéma d'arguments vient des annotations de type.

Bash
pip install openai-agents
Python
from agents import Agent, Runner, function_tool

@function_tool
def check_status(number: str) -> str:
    """Returns the status of the order with the given number.

    Call this when a customer asks about their order.
    """
    return db.status(number)

agent = Agent(
    name="Support",
    instructions="You answer questions about orders. No preamble.",
    tools=[check_status],
)

result = Runner.run_sync(agent, "Where is order 1841?")
print(result.final_output)

La docstring de la fonction n'est pas ici un commentaire pour un développeur mais une description pour le modèle. Une phrase qui dit quand appeler l'outil améliore la précision plus que n'importe quel changement de l'instruction système. C'est l'optimisation la moins chère qui existe.

La version TypeScript porte le même ensemble de concepts, en décrivant les arguments par un schéma plutôt que par des annotations. Une équipe qui travaille sur le front-end peut donc garder les agents dans le même langage que le reste de l'application.

Handoffs

Ce mécanisme est le cœur de la bibliothèque et sa caractéristique la plus distinctive. Au lieu d'un agent avec vingt outils, tu construis plusieurs agents spécialisés et tu les laisses se passer la conversation.

Python
returns_agent = Agent(
    name="Returns",
    instructions="You handle returns and complaints.",
    tools=[file_return, check_policy],
)

billing_agent = Agent(
    name="Billing",
    instructions="You handle invoices and payments.",
    tools=[fetch_invoice, explain_charge],
)

front_desk = Agent(
    name="Front desk",
    instructions="You route the conversation to the right department.",
    handoffs=[returns_agent, billing_agent],
)

Techniquement, un handoff est un appel d'outil, donc il apparaît dans la trace comme n'importe quelle autre action. Cela compte pour le diagnostic, car une conversation qui a atterri dans le mauvais service a un moment visible où la décision a été prise.

L'avantage de la séparation est une instruction plus courte et un ensemble d'outils plus petit par agent. Un modèle qui choisit parmi quatre outils se trompe moins souvent que celui qui choisit parmi vingt, et une instruction qui couvre un seul domaine est plus précise que celle qui essaie de tout couvrir.

Le piège est d'exagérer dans l'autre sens. Huit agents qui se passent la conversation en rond forment un système que personne ne suivra. Trois à cinq rôles suffisent pour la plupart des applications.

Guardrails, ou contrôle des entrées et des sorties

Un guardrail est un contrôle séparé qui s'exécute en parallèle de l'agent et arrête le travail quand une condition échoue.

Python
from agents import input_guardrail, GuardrailFunctionOutput

@input_guardrail
async def orders_only(ctx, agent, user_input: str):
    verdict = await Runner.run(classifier, user_input)
    return GuardrailFunctionOutput(
        output_info=verdict.final_output,
        tripwire_triggered=not verdict.final_output.about_orders,
    )

L'intérêt est à la fois économique et pratique. Un contrôle peu coûteux avec un modèle léger rejette les demandes hors périmètre avant que l'agent plus coûteux, qui a accès aux outils, ne démarre. Tu économises des tokens et tu réduis la surface où les choses peuvent mal tourner.

Un guardrail de sortie fonctionne de la même façon sur les réponses. Les usages typiques sont de vérifier qu'une réponse ne contient aucune donnée personnelle, respecte la politique de l'entreprise et ne promet rien qu'elle ne doit pas promettre.

Rappelle-toi qu'un guardrail n'est pas une protection au sens de la sécurité des systèmes. Il protège contre les mauvais comportements typiques plutôt que contre une attaque délibérée. Continue d'appliquer les permissions dans le code des outils en vérifiant qui appelle l'opération.

Si les exigences vont plus loin, en couvrant la détection d'injections de prompt et les fuites de données personnelles au niveau de la politique de l'entreprise, un guardrail écrit par toi ne suffira pas et il te faut un produit séparé, Prompt Security par exemple. Note toutefois que le projet n'est plus indépendant : SentinelOne l'a acquis en septembre 2025, donc au lieu d'acheter une offre tu te retrouves face à une discussion commerciale avec un éditeur de sécurité.

Un agent comme outil, la seconde voie

Un handoff passe la conversation en bloc sans retour possible. C'est gênant quand tu veux seulement un deuxième avis puis reprendre ton propre fil. Le second mécanisme sert à cela : un agent exposé comme outil.

Python
translator = Agent(name="Translator", instructions="You translate text into Polish.")

main = Agent(
    name="Editor",
    instructions="You prepare replies for customers.",
    tools=[translator.as_tool(
        tool_name="translate",
        tool_description="Translates the given text into Polish.",
    )],
)

La différence est fondamentale pour le flux. Avec un handoff, un autre agent prend le contrôle et termine la conversation. Avec un agent comme outil, le résultat revient à l'agent appelant, qui poursuit le fil.

La règle de sélection est simple. Si le sujet relève d'un autre service et doit y finir, utilise un handoff. Si tu as besoin d'une réponse partielle pour construire la tienne, utilise un agent comme outil.

Ce dernier arrangement offre aussi un avantage de coût. Un agent spécialisé peut tourner sur un modèle moins cher, car sa tâche est étroite, tandis que l'agent principal tourne sur un modèle plus puissant. Découper en étapes te permet d'adapter le modèle à la difficulté plutôt que de payer le tarif maximal pour tout.

Pause pour une décision humaine

Toutes les actions ne doivent pas s'exécuter seules. Un remboursement, un message à un client ou une modification des données du système sont des opérations pour lesquelles il vaut la peine de demander à un humain.

La bibliothèque te permet de marquer un outil comme nécessitant une approbation. Une exécution s'arrête alors au point d'appel, signale une décision en attente, et tu la reprends après avoir approuvé ou rejeté.

En pratique, ce mécanisme résout le problème de déploiement le plus courant. Les équipes craignent de mettre en production un agent qui a accès à des opérations irréversibles, donc elles retiennent ces outils ou ne déploient pas du tout. Approuver des actions choisies te permet de commencer avec un arrangement où l'agent propose et un humain approuve, puis de lever les restrictions peu à peu à mesure qu'il se montre correct.

Marque les opérations par leurs conséquences plutôt que par leur difficulté. Lire des données client peut être techniquement difficile et parfaitement sûr, alors qu'un appel de remboursement d'une ligne est une opération simple aux conséquences sérieuses.

Réponses en streaming

Un agent qui fait trois appels d'outils répond après plusieurs secondes, et l'utilisateur regarde un écran vide pendant tout ce temps. Le streaming te permet d'afficher la progression au fur et à mesure.

Python
result = Runner.run_streamed(agent, "Where is order 1841?")

async for event in result.stream_events():
    if event.type == "raw_response_event":
        show_chunk(event.data)

Diffuser les événements d'appels d'outils compte autant que diffuser le texte. Un message « vérification du statut de la commande » affiché en cours d'exécution change davantage la sensation de l'interface que gagner une seconde sur la réponse.

Sessions et mémoire de conversation

Sans session, chaque exécution part de rien et tu transmets l'historique à la main. Une session le fait pour toi, en stockant l'échange sous un identifiant.

Python
from agents import SQLiteSession

session = SQLiteSession("customer-1841", "conversations.db")

Runner.run_sync(agent, "Where is my order?", session=session)
Runner.run_sync(agent, "And when will it arrive?", session=session)

La deuxième question fonctionne parce que l'agent voit l'échange précédent. Sans session, elle serait incompréhensible.

La limite est la même partout : l'historique grandit et finit par coûter plus cher que la réponse elle-même. Pour les conversations longues ou récurrentes, il vaut la peine d'ajouter une couche de mémoire comme Mem0, qui extrait des faits plutôt que de tout stocker.

Traçage

La bibliothèque collecte une trace de chaque exécution : appels de modèle, appels d'outils, handoffs et guardrails. Elle fonctionne par défaut sans configuration et c'est l'un des arguments les plus forts en faveur de cette option.

Diagnostiquer un agent sans trace revient à deviner pourquoi il a fait quelque chose d'étrange. Avec une trace, tu vois exactement quel outil il a appelé, avec quels arguments, et ce qui est revenu.

Les traces peuvent aussi être acheminées vers des systèmes d'observabilité externes, Langfuse par exemple, si tu veux tout au même endroit avec le reste de l'application.

Une chose est à décider avant le déploiement, car le comportement par défaut surprend : les traces contiennent le contenu des conversations et arrivent sur le tableau de bord de traçage du fournisseur du modèle plutôt que sur ton propre disque. Avec des données sensibles, tu as trois issues : désactiver la capture du contenu lui-même, désactiver entièrement le traçage via une variable d'environnement ou un réglage d'exécution, ou attacher ton propre processeur de traces et acheminer les traces uniquement vers ta propre infrastructure. Un cas à part est celui des organisations en rétention zéro des données chez le fournisseur, où le traçage n'est pas du tout disponible.

Du prototype à la production

Un agent qui marche sur dix questions vérifiées à la main et un agent qui sert du trafic sont deux choses différentes. Quelques étapes séparent l'un de l'autre.

La première est les limites. Fixe un nombre maximal d'étapes par exécution et un timeout. Sans eux, une boucle où l'agent appelle un outil, reçoit une erreur et recommence brûlera le budget d'une journée en un quart d'heure.

La deuxième est la gestion des erreurs des outils. Une fonction qui lève une exception interrompt l'exécution, alors que le meilleur comportement est généralement de renvoyer au modèle un message sur lequel il peut agir. La phrase « aucune commande trouvée avec ce numéro » permet à l'agent de demander au client, tandis qu'une exception termine la conversation sur une erreur.

La troisième est un jeu de cas de test. Rassemble trente vraies conversations, marque le résultat attendu et relance-les après chaque changement d'instruction. C'est le seul moyen de remarquer qu'une correction aide un cas tout en en cassant trois autres.

La quatrième est le coût d'une exécution. Additionne les tokens du champ usage du résultat sur dix vraies conversations et multiplie par le volume attendu. Ce chiffre en dit plus que n'importe quelle estimation, car il reflète tes outils et tes instructions.

La cinquième est un plan pour le moment où l'agent ne sait pas. La réponse « je n'ai pas cette information, je vous passe un conseiller » vaut mieux qu'un contenu inventé, mais un modèle la choisit rarement spontanément. Écris-la explicitement dans l'instruction et vérifie-la sur les cas de test.

Des instructions qui marchent vraiment

Une instruction d'agent n'est pas une fiche de poste mais un ensemble de règles de décision. Cette différence se traduit directement en comportement.

Une instruction qui dit « tu es un assistant de service client serviable » ne change rien, car le modèle essaie déjà d'être serviable. Une instruction qui dit « sur une question concernant le statut d'une commande, appelle toujours l'outil, ne devine jamais d'après la conversation » change un comportement précis dans une situation précise.

Le deuxième principe concerne les limites. Dis clairement ce que l'agent ne fait pas et ce qu'il doit faire à la place. La phrase « tu ne promets pas de dates de livraison, tu cites uniquement la date du système » ferme toute une catégorie de problèmes.

Le troisième concerne la longueur. Une instruction de trois pages fonctionne moins bien qu'une d'une demi-page, car le modèle perd des morceaux du milieu. Si les règles sont nombreuses, cela signale généralement un agent qui en fait trop et qu'il faut découper.

Face aux alternatives

OutilPoint fortPoint faibleÀ choisir quand
OpenAI Agents SDKPeu de concepts, handoffs, traçage sans configurationOrienté vers un seul fournisseurUne équipe de rôles couvrant différents domaines
LangGraphContrôle total du flux, état durable, pausesPlus de travail sur les cas simplesProcessus avec embranchements et décision humaine
PydanticAISortie typée, tests sans modèleMoins d'intégrations prêtesUn résultat qui alimente directement du code
CrewAIRépartition lisible des rôles, démarrage rapideMoins de contrôle sur le détailPrototype d'une équipe d'agents

La bibliothèque prend en charge d'autres modèles que ceux par défaut via une interface compatible avec le format de ce fournisseur. Note toutefois que certaines fonctionnalités sont conçues pour un seul écosystème et sont plus minces avec des modèles externes.

Une remarque pratique pour clore la comparaison : le choix de la bibliothèque décide rarement du succès. Ce qui détermine la qualité d'un agent, ce sont les descriptions des outils, les limites dans les instructions et le fait d'avoir un jeu de cas pour mesurer les changements. Ces trois éléments passent d'une bibliothèque à l'autre presque sans changement, donc le travail qui y est investi n'est pas perdu lors d'une migration ultérieure.

Erreurs courantes

La première est de rédiger les descriptions d'outils pour un développeur. Le modèle lit le même texte et a besoin d'une phrase sur le moment où appeler l'outil, pas d'une description de l'implémentation.

La deuxième est un seul agent qui détient tous les outils. À vingt fonctions, la précision de sélection baisse, et l'instruction grossit jusqu'à une taille où le modèle en perd des parties.

La troisième est de ne mettre aucun plafond au nombre d'étapes. Un agent qui fait des handoffs en boucle ou appelle sans cesse le même outil brûlera autant de tokens que tu le permets.

La quatrième est de traiter un guardrail comme un mécanisme de sécurité. Un contrôle basé sur un modèle peut être contourné, donc applique les permissions dans le code en vérifiant l'identité de l'appelant.

La cinquième est de passer l'identifiant de l'utilisateur dans les arguments des outils. Le modèle peut fournir celui de quelqu'un d'autre, donc l'identité doit venir du contexte d'exécution et non du schéma.

La sixième est de n'avoir aucun jeu de tests. Un changement d'instruction qui améliore subjectivement une conversation en casse généralement une autre, et sans quelques dizaines de cas enregistrés personne ne le remarque.

FAQ

En quoi est-ce différent de Swarm ?

Swarm était une expérience éducative sans prise en charge de la production. Cette bibliothèque en est la successeure destinée à la production, avec des guardrails, des sessions et du traçage en plus. Les concepts sont restés les mêmes, donc la migration est simple.

Fonctionne-t-il avec d'autres modèles qu'OpenAI ?

Oui, via une interface compatible avec le format de ce fournisseur, donc tu peux brancher des modèles locaux servis via Ollama entre autres. Certaines fonctionnalités sont toutefois conçues pour un seul écosystème, donc vérifie ce qui fonctionne exactement avec des modèles externes.

OpenAI Agents SDK ou LangGraph ?

Choisis cette bibliothèque quand le problème se découpe naturellement en rôles qui se passent une conversation et que tu veux démarrer vite. Choisis LangGraph quand le flux a des étapes explicites, des embranchements et des points où le processus s'arrête pour une décision humaine.

Existe-t-il une version TypeScript ?

Oui, avec le même ensemble de concepts : outils, handoffs, guardrails, sessions, traçage et pause pour une décision humaine. Une équipe qui travaille dans Next.js peut donc garder les agents dans le même langage que le reste du code.

Combien ça coûte ?

La bibliothèque elle-même est gratuite et open source. Tu paies les appels de modèle, les guardrails et les classifieurs étant des appels supplémentaires, généralement sur un modèle moins cher. Chiffre une conversation complète sur dix vrais cas avant que le processus ne devienne permanent.

La documentation se trouve sur le site du projet, et la version TypeScript dans le dépôt GitHub.

À lire aussi