Introduction
L'OpenAI Agents SDK permet de créer des agents autonomes capables d'orchestrer des tâches complexes. Contrairement aux appels simples à l'API, il gère la mémoire, les outils et les boucles de raisonnement. Ce tutoriel vous guide vers une architecture multi-agents scalable, essentielle pour les applications d'entreprise en 2026.
Prérequis
- Python 3.11+
- Clé API OpenAI avec accès aux modèles récents
- Connaissances solides en Pydantic et asyncio
- Notions de design patterns pour agents
Installation et configuration
pip install openai-agents pydantic
export OPENAI_API_KEY="sk-..."Installe le SDK officiel et configure la clé API. Utilisez un gestionnaire de secrets en production pour éviter les fuites.
Définition d'un agent de base
from agents import Agent, Runner
from pydantic import BaseModel
class ResearchAgent(Agent):
name = "researcher"
instructions = "Tu es un chercheur expert. Utilise les outils pour trouver des informations précises."
model = "gpt-4o"
agent = ResearchAgent()
result = Runner.run_sync(agent, "Analyse le marché de l'IA en 2026")
print(result.final_output)Crée un agent typé avec instructions claires. Runner.run_sync permet une exécution synchrone simple pour les tests.
Ajout d'outils personnalisés
from agents import function_tool
@function_tool
def search_web(query: str) -> str:
"""Recherche sur le web."""
# Implémentation réelle avec Tavily ou Serper
return f"Résultats pour {query}: données marché 2026..."
agent.tools = [search_web]Les décorateurs function_tool transforment vos fonctions en outils utilisables par l'agent. Toujours valider les entrées/sorties.
Orchestration multi-agents
from agents import Agent, Runner, handoff
researcher = Agent(name="researcher", instructions="...")
writer = Agent(name="writer", instructions="...")
handoff_tool = handoff(writer)
researcher.tools.append(handoff_tool)
result = Runner.run_sync(researcher, "Rédige un rapport sur l'IA")Le handoff permet de transférer le contrôle entre agents. Cela crée des workflows collaboratifs sans boucle infinie.
Gestion avancée du contexte
from agents import Agent, Runner, RunContext
class MyContext(BaseModel):
user_id: str
session_data: dict
agent = Agent(
name="contextual",
instructions="Utilise le contexte pour personnaliser les réponses.",
context=MyContext(user_id="123", session_data={})
)
result = Runner.run_sync(agent, "Recommande du contenu", context=agent.context)Pydantic permet un contexte typé et sérialisable. Évitez de passer trop de données pour rester sous les limites de tokens.
Bonnes pratiques
- Toujours typer les entrées/sorties des outils avec Pydantic
- Limiter le nombre d'outils par agent à 5-7 maximum
- Implémenter des timeouts et retries sur les appels externes
- Logger chaque décision de l'agent pour le débogage
- Utiliser des modèles de raisonnement (o1) pour les tâches critiques
Erreurs courantes à éviter
- Oublier de gérer les exceptions dans les outils (l'agent boucle)
- Passer un contexte trop volumineux et dépasser les tokens
- Ne pas définir d'instructions précises (hallucinations)
- Ignorer la gestion des états concurrents en production
Pour aller plus loin
Approfondissez ces concepts avec nos formations Learni sur les architectures d'agents IA avancées.