Créer un agent Python avec le SDK OpenAI

Un agent Python OpenAI, dans le SDK officiel, est un objet Agent avec un nom et des instructions, exécuté par Runner. Ce n’est pas un serveur, ni un accès à vos fichiers. Le quickstart Python s’arrête à une question d’histoire, puis à un outil qui renvoie une phrase fixe.

Deux pages officielles décrivent le même parcours et ne s’accordent pas sur les imports. Celle-ci suit le quickstart du dépôt Python, relu le 2026-10-18. Elle signale l’autre page au lieu de fusionner les extraits. Les commandes n’ont pas été rejouées le 2026-10-18 : aucun terminal de publication n’a affiché de réponse de modèle.

Ce que vous allez suivre

Le quickstart du SDK Python, puis l’écart avec la page Agents de la documentation API. Le README du même dépôt ajoute Runner.run_sync et exige Python 3.10 ou plus récent. Ne mélangez pas ces trois sources dans un seul fichier.

Pour un outil qui parle à un serveur MCP plutôt qu’à une fonction Python, le protocole est ailleurs : MCP, c’est quoi ? et créer un serveur MCP en TypeScript. Le README du SDK cite MCP parmi les outils. Il ne donne pas, sur la page relue, le code pour brancher un serveur.

Prérequis

Le README, relu le 2026-10-18, demande Python 3.10 ou plus récent. Le quickstart demande ensuite un environnement virtuel, le paquet openai-agents, et une clé API. La création de clé est renvoyée vers la page quickstart de la plateforme, ancre create-and-export-an-api-key. Cette page-ci n’a pas revérifié le formulaire du tableau de bord.

Commande :

python --version

Résultat attendu, d’après le README : le premier nombre est 3, le second est 10 ou plus. Le texte exact d’un Python trop ancien n’est pas dans les pages relues. Arrêtez si la version est inférieure.

Erreur fréquente : installer le paquet dans le Python du système, puis lancer le script avec un autre interpréteur. Le quickstart active un venv avant pip install.

1. Créer le projet

Le quickstart dit de ne faire cette partie qu’une fois. Le nom my_project vient de cette page. Rien n’a été renommé ici.

Commande :

mkdir my_project
cd my_project
python -m venv .venv

Sous macOS ou Linux, à chaque nouveau terminal :

source .venv/bin/activate

Sous Windows, la même page donne .venv\Scripts\activate.

Résultat attendu : le préfixe du shell change. Les pages relues ne donnent pas la chaîne exacte. Si which python (ou where python) ne pointe pas dans .venv, vous n’êtes pas dans l’environnement du quickstart.

2. Installer le SDK et poser la clé

Le quickstart et le README installent le même paquet, sans numéro de version. Ne figez pas une version lue ailleurs.

Commande :

pip install openai-agents

Le README propose aussi uv init puis uv add openai-agents. Choisissez un des deux. Le quickstart commente que uv add openai-agents est une alternative, sur la même ligne que pip.

La clé se pose pour la session courante. La valeur sk-... est le placeholder du quickstart, pas une clé. Ne la commitez pas, ne la collez pas dans le fichier Python.

export OPENAI_API_KEY=sk-...

Windows PowerShell, même page : $env:OPENAI_API_KEY = "sk-...". L’invite de commandes Windows : set "OPENAI_API_KEY=sk-...".

Résultat attendu : pip se termine sans erreur et écrit les versions réellement résolues. Notez-les depuis la sortie ou le fichier de gel si vous en créez un. Cette page n’a pas lancé pip, donc elle ne publie aucun numéro.

Erreur fréquente : exporter la clé dans un terminal et lancer le script dans un autre. La variable ne traverse pas.

3. Définir l’agent et le lancer

Le quickstart définit un tuteur d’histoire, sans champ model. Il passe par asyncio et Runner.run. Le README, lui, montre Runner.run_sync sur un autre agent, avec un haïku en commentaire. Ce haïku est un exemple écrit dans le README. Ce n’est pas une sortie observée ici, et ce n’est pas le script du quickstart.

Fichier du quickstart, recopié :

import asyncio
from agents import Agent, Runner

agent = Agent(
    name="History Tutor",
    instructions="You answer history questions clearly and concisely.",
)

async def main():
    result = await Runner.run(agent, "When did the Roman Empire fall?")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

Commande : le quickstart ne nomme pas le fichier. Enregistrez ce bloc, puis lancez-le avec le Python du venv. Ne lancez pas en plus run_sync dans le même processus pour « voir si les deux marchent ».

Résultat attendu : la page API, relue le même jour, dit qu’une réponse concise doit apparaître dans le terminal. Le quickstart Python ne colle pas d’exemple de phrase. Aucune réponse n’est imprimée ici, parce que les commandes n’ont pas été rejouées le 2026-10-18.

Erreur fréquente : copier le model="gpt-6-astra" de la page API dans cet extrait. Le quickstart Python relu ne passe pas de modèle. Si vous voulez ce champ, suivez la page API en entier, pas un mélange.

4. Ne pas fusionner avec l’autre quickstart

La page Quickstart de l’API, relue le 2026-10-18, installe aussi openai-agents et exporte OPENAI_API_KEY. Son exemple Python importe function_tool depuis agents, décore avec @function_tool, et fixe model à gpt-6-astra.

Le quickstart du dépôt, le même jour, importe tool depuis agents.decorators et décore avec @tool. Il ne fixe pas de modèle. Les deux outils d’exemple s’appellent history_fun_fact et retournent la chaîne Sharks are older than trees. C’est le retour écrit dans la fonction, pas une réponse du modèle.

Si un import échoue, comparez-le à la page dont vous avez copié le bloc. Ne forcez pas l’autre décorateur pour faire passer le fichier.

5. Ajouter l’outil du quickstart Python

Toujours le quickstart du dépôt, pas la page API. L’outil n’a pas d’argument. L’instruction dit de l’utiliser quand il aide.

import asyncio
from agents import Agent, Runner
from agents.decorators import tool


@tool
def history_fun_fact() -> str:
    """Return a short history fact."""
    return "Sharks are older than trees."


agent = Agent(
    name="History Tutor",
    instructions="Answer history questions clearly. Use history_fun_fact when it helps.",
    tools=[history_fun_fact],
)


async def main():
    result = await Runner.run(
        agent,
        "Tell me something surprising about ancient life on Earth.",
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

Résultat attendu : le quickstart n’affiche pas la sortie. Il ne garantit pas que le modèle appellera l’outil. Le seul texte certain, dans la page, est le retour de la fonction si elle est appelée. Nous ne l’avons pas observé le 2026-10-18.

Erreur fréquente : remplacer le retour par un appel réseau ou une lecture de fichier, puis croire que le quickstart couvre encore le cas. Le quickstart distingue ensuite les agents bac à sable, pour un espace de travail isolé. Ce n’est pas ce fichier.

6. Lire les traces, sans inventer le tour suivant

Le quickstart envoie vers le visionneur de traces. La page API dit que le chemin SDK côté serveur trace par défaut, et qu’il faut ouvrir ce tableau dès le premier run, avant d’ajuster les prompts. Nous n’avons pas ouvert de trace le 2026-10-18. Si la liste est vide, le quickstart ne donne pas le message d’erreur : vérifiez la clé et le projet du tableau, ne collez pas une capture trouvée ailleurs.

Pour un second tour, le quickstart Python propose trois pistes, à ne pas combiner au hasard : result.to_input_list(), une session, ou previous_response_id / conversation_id. La page API nomme result.to_input_list() côté Python et result.history côté TypeScript. Après un handoff, elle dit de réutiliser last_agent si le spécialiste doit garder la main.

Le même quickstart montre ensuite un agent de triage avec handoffs vers un tuteur d’histoire et un tuteur de maths, puis imprime result.last_agent.name. Le script complet est dans la page et dans examples/agent_patterns/routing.py. Ce guide s’arrête avant ce fichier : le premier run et l’outil suffisent à vérifier que vous suivez une seule doc.

Lectures liées, qui ne remplacent pas le SDK

Claude Code et Cursor comparent des éditeurs. Ils n’installent pas openai-agents et ne tranchent pas entre @tool et @function_tool.

Sources et limites

Quickstart du SDK Python : venv, install, agent, outil, handoffs. Source principale de cette page.
README openai-agents-python : Python 3.10+, run_sync, mention de MCP parmi les outils.
Quickstart Agents de l’API : autre import, modèle gpt-6-astra. Ne pas fusionner.
Traces : page indiquée pour relire un run.

Les commandes n’ont pas été rejouées le 2026-10-18. Aucune version de paquet n’est figée. Si le quickstart du dépôt et la page API divergent encore à la lecture, suivez-en une seule jusqu’au premier print.