Le SDK d’Agents d’OpenAI : Un Guide Complet pour Construire des Agents IA Puissants

Le SDK d’Agents d’OpenAI : Un Guide Complet pour Construire des Agents IA Puissants

Le SDK d’Agents d’OpenAI : Un Guide Complet pour Construire des Agents IA Puissants

Il y a quelques mois, OpenAI a lancé Swarm, un framework open-source pour agents IA qui permet d’écrire du code Python simple et élégant pour construire des agents IA et les connecter ensemble afin de réaliser des tâches puissantes. J’avais couvert ce sujet sur ma chaîne il y a quelques mois et j’étais impressionné, mais OpenAI avait clairement indiqué que Swarm était expérimental et destiné principalement à des fins éducatives, pas un framework prêt pour la production.

Mais aujourd’hui, OpenAI a lancé son tout nouveau SDK d’Agents. Il est construit sur Swarm, toujours complètement gratuit et open-source, mais ils affirment qu’il est maintenant prêt pour la production et très facile à utiliser pour construire des applications complètes basées sur des agents IA avec très peu d’abstractions. Ces affirmations semblent audacieuses, alors dans cet article, nous allons explorer le SDK d’Agents, construire quelques agents puissants avec lui, et voir s’il vaut vraiment la peine d’être utilisé par rapport aux autres options déjà disponibles comme LangChain et Crew AI ou Pantic AI.

Plan de l’article

Voici notre plan :

  1. Démontrer ce que vous pouvez faire avec le SDK d’Agents
  2. Commencer par un exemple basique puis passer à des systèmes d’agents plus complexes
  3. Évaluer honnêtement si ce SDK est réellement prêt pour la production comme le prétend OpenAI
  4. Comparer avec d’autres frameworks comme Pantic AI et LangGraph

Concepts fondamentaux du SDK d’Agents

Le SDK d’Agents d’OpenAI s’articule autour de quatre concepts clés :

  • Agents : Donner des instructions et des outils à vos LLMs
  • Handoffs (transferts) : Permettre à différents agents spécialisés de travailler ensemble
  • Guardrails (garde-fous) : Mettre en place des vérifications de sécurité pour valider les entrées/sorties et éviter les hallucinations
  • Tracing (traçage) : Observer le fonctionnement interne de vos LLMs et agents pour déboguer et surveiller

Mise en route avec le SDK d’Agents

La mise en route avec le SDK d’Agents est extrêmement simple. L’installation se fait avec une seule ligne de commande pip :

pip install openai-agent-sdk

Construction d’un agent de base (Version 1)

Commençons par construire un agent très simple. Voici le code de base :

# Importation des bibliothèques
import os
from openai import OpenAI
from agent_sdk import Agent, runner
from dotenv import load_dotenv

# Chargement des variables d'environnement
load_dotenv()
openai_api_key = os.getenv("OPENAI_API_KEY")

# Définition de l'agent
agent = Agent(
    name="Assistant de base",
    instructions="Tu es un assistant IA utile et concis.",
    model="gpt-4o-mini"
)

# Fonction principale
def main():
    # Exécution de l'agent avec une requête utilisateur
    final_output = runner.run_sync(
        agent=agent,
        user_message="Écris-moi un haïku sur la récursion en programmation"
    )

    # Affichage de la réponse
    print(final_output)

if __name__ == "__main__":
    main()

C’est vraiment aussi simple que ça ! Quelques lignes de code suffisent pour configurer un agent de base avec le SDK d’OpenAI.

Ajout de sorties structurées (Version 2)

Les sorties structurées permettent de standardiser les réponses d’un modèle de langage, en le forçant à donner une réponse JSON avec des valeurs spécifiques que nous pouvons toujours attendre. Pour notre agent de planification de voyage, nous voulons qu’il fournisse systématiquement une destination, un budget recommandé et une liste d’activités.

Voici comment implémenter des sorties structurées :

from pydantic import BaseModel
from typing import List

# Définition du modèle de sortie
class TravelPlan(BaseModel):
    destination: str
    duration: str
    budget: str
    recommended_activities: List[str]
    notes: str

# Définition de l'agent avec sortie structurée
agent = Agent(
    name="Planificateur de voyage",
    instructions="""Tu es un assistant de planification de voyage expert.
    Aide les utilisateurs à planifier leurs voyages en fonction de leurs préférences.
    Fournis des recommandations détaillées sur la destination, la durée, le budget et les activités.""",
    model=os.getenv("LLM_MODEL"),
    output_type=TravelPlan
)

En utilisant des sorties structurées, nous obtenons une réponse cohérente à chaque fois, ce qui est essentiel pour réduire les hallucinations des LLMs.

Ajout d’outils (Version 3)

Les outils permettent aux agents IA d’interagir avec le monde extérieur, comme rechercher des vols, réserver des hôtels ou obtenir des informations météorologiques. Ajoutons un outil météo à notre agent de voyage :

from agent_sdk import function_tool

@function_tool
def get_weather_forecast(city: str, date: str) -> str:
    """Obtient les prévisions météorologiques pour une ville à une date donnée.
    Utilise cet outil lorsque l'utilisateur demande des informations sur la météo ou lorsque tu planifies un voyage."""

    # Données météo simulées (dans un cas réel, vous utiliseriez une API météo)
    weather_data = {
        "Miami": "Ensoleillé avec des températures entre 25 et 35°C",
        "Tokyo": "Partiellement nuageux avec des températures entre 15 et 25°C",
        "Paris": "Généralement ensoleillé avec des températures entre 12 et 22°C",
        "New York": "Nuageux avec des températures entre 10 et 20°C"
    }

    if city in weather_data:
        return f"Prévisions météo pour {city} : {weather_data[city]}"
    else:
        return f"Prévisions météo non disponibles pour {city}"

# Définition de l'agent avec l'outil météo
agent = Agent(
    name="Planificateur de voyage",
    instructions="""Tu es un assistant de planification de voyage expert.
    Aide les utilisateurs à planifier leurs voyages en fonction de leurs préférences.
    Utilise l'outil météo pour obtenir des informations actualisées.""",
    model=os.getenv("LLM_MODEL"),
    output_type=TravelPlan,
    tools=[get_weather_forecast]
)

Mise en place des handoffs entre agents (Version 4)

Plutôt que de surcharger un seul agent avec trop d’outils, il est préférable d’avoir plusieurs agents spécialisés travaillant ensemble. Créons des agents spécialisés pour les vols et les hôtels :

# Modèle pour les recommandations de vol
class FlightRecommendation(BaseModel):
    airline: str
    departure_time: str
    arrival_time: str
    price: str
    duration: str
    justification: str

@function_tool
def search_flights(wrapper, origin: str, destination: str, date: str) -> str:
    """Recherche des vols disponibles entre l'origine et la destination à la date spécifiée."""
    # Données de vol simulées
    flight_options = [
        {"airline": "Ocean Air", "departure": "08:00", "arrival": "10:30", "price": "$350", "duration": "2h30"},
        {"airline": "Sky Routes", "departure": "10:15", "arrival": "12:45", "price": "$420", "duration": "2h30"},
        {"airline": "Global Wings", "departure": "14:30", "arrival": "17:00", "price": "$380", "duration": "2h30"}
    ]

    # Trier par compagnies aériennes préférées si spécifiées
    if hasattr(wrapper.user_context, 'preferred_airlines') and wrapper.user_context.preferred_airlines:
        flight_options.sort(key=lambda x: x["airline"] in wrapper.user_context.preferred_airlines, reverse=True)

    return f"Vols disponibles de {origin} à {destination} le {date}:\n" + \
           "\n".join([f"{f['airline']} - Départ: {f['departure']}, Arrivée: {f['arrival']}, Prix: {f['price']}, Durée: {f['duration']}" for f in flight_options])

# Agent spécialisé pour les vols
flight_agent = Agent(
    name="Spécialiste des vols",
    handoff_description="Spécialiste pour trouver et recommander des vols",
    instructions="""Tu es un spécialiste des vols. Aide les utilisateurs à trouver les meilleurs vols
    en fonction de leurs préférences. Utilise l'outil de recherche de vols pour obtenir des options.""",
    model=os.getenv("LLM_MODEL"),
    tools=[search_flights],
    output_type=FlightRecommendation
)

# Modèle pour les recommandations d'hôtel
class HotelRecommendation(BaseModel):
    hotel_name: str
    location: str
    price: str
    amenities: List[str]
    justification: str

@function_tool
def search_hotels(wrapper, city: str, check_in_date: str, check_out_date: str, max_price: str = None) -> str:
    """Recherche des hôtels disponibles dans une ville pour les dates spécifiées, en filtrant éventuellement par prix maximum."""
    # Données d'hôtel simulées
    hotel_options = [
        {"name": "Grand Hôtel Central", "location": "Centre-ville", "price": "$250/nuit", "amenities": ["WiFi", "Piscine", "Gym", "Restaurant"]},
        {"name": "Séjour Élégant", "location": "Quartier des affaires", "price": "$180/nuit", "amenities": ["WiFi", "Gym", "Bar sur le toit"]},
        {"name": "Vue sur l'Océan", "location": "Front de mer", "price": "$320/nuit", "amenities": ["WiFi", "Piscine", "Spa", "Accès plage"]}
    ]

    # Filtrer par prix maximum si spécifié
    if max_price:
        max_price_value = int(max_price.replace("$", ""))
        filtered_options = [h for h in hotel_options if int(h["price"].split("/")[0].replace("$", "")) <= max_price_value]
    else:
        filtered_options = hotel_options

    return f"Hôtels disponibles à {city} du {check_in_date} au {check_out_date}:\n" + \
           "\n".join([f"{h['name']} - {h['location']} - {h['price']} - Équipements: {', '.join(h['amenities'])}" for h in filtered_options])

# Agent spécialisé pour les hôtels
hotel_agent = Agent(
    name="Spécialiste des hôtels",
    handoff_description="Spécialiste pour trouver et recommander des hôtels",
    instructions="""Tu es un spécialiste des hôtels. Aide les utilisateurs à trouver les meilleurs hôtels
    en fonction de leurs préférences. Utilise l'outil de recherche d'hôtels pour obtenir des options.""",
    model=os.getenv("LLM_MODEL"),
    tools=[search_hotels],
    output_type=HotelRecommendation
)

# Agent principal avec handoffs vers les agents spécialisés
agent = Agent(
    name="Planificateur de voyage",
    instructions="""Tu es un assistant de planification de voyage expert.
    Aide les utilisateurs à planifier leurs voyages en fonction de leurs préférences.
    Utilise l'outil météo pour obtenir des informations actualisées.
    Transmets les demandes spécifiques aux agents spécialisés appropriés.""",
    model=os.getenv("LLM_MODEL"),
    output_type=TravelPlan,
    tools=[get_weather_forecast],
    handoffs=[flight_agent, hotel_agent]
)

La configuration des handoffs est incroyablement simple avec le SDK d’Agents. Il suffit d’ajouter les agents spécialisés à la liste handoffs de l’agent principal.

Ajout de guardrails, contexte utilisateur et traçage (Version 5)

Les guardrails permettent de vérifier si une demande est réaliste avant que l’agent ne commence à planifier un voyage. Par exemple, si un utilisateur demande un voyage à Dubaï pour seulement 300 $, nous voulons éviter que l’agent essaie de planifier ce voyage impossible.

# Modèle pour l'analyse de budget
class BudgetAnalysis(BaseModel):
    is_realistic: bool
    reasoning: str
    suggested_budget: str

# Agent d'analyse de budget
budget_analysis_agent = Agent(
    name="Analyseur de budget",
    instructions="""Tu es un expert en analyse de budget de voyage.
    Détermine si le budget proposé par l'utilisateur est réaliste pour la destination et la durée mentionnées.
    Si le budget n'est pas réaliste, explique pourquoi et suggère un budget plus approprié.""",
    model=os.getenv("LLM_MODEL"),
    output_type=BudgetAnalysis
)

# Fonction de guardrail pour le budget
def budget_guardrail(user_message, user_context):
    try:
        # Analyse du budget par l'agent spécialisé
        budget_analysis = runner.run_sync(
            agent=budget_analysis_agent,
            user_message=f"Analyse si ce budget est réaliste: {user_message}"
        )

        # Si le budget n'est pas réaliste, déclencher le guardrail
        if not budget_analysis.is_realistic:
            print(f"\n⚠️ Votre budget pour votre voyage peut ne pas être réaliste.\n")
            print(f"Raison: {budget_analysis.reasoning}\n")
            return {
                "tripwire_triggered": True,
                "reasoning": budget_analysis.reasoning,
                "suggested_budget": budget_analysis.suggested_budget
            }

        return {"tripwire_triggered": False}
    except Exception as e:
        print(f"Erreur lors de l'analyse du budget: {e}")
        return {"tripwire_triggered": False}

# Classe pour le contexte utilisateur
class UserContext:
    def __init__(self, user_id, preferred_airlines, preferred_hotel_amenities, budget_level):
        self.user_id = user_id
        self.preferred_airlines = preferred_airlines
        self.preferred_hotel_amenities = preferred_hotel_amenities
        self.budget_level = budget_level

# Agent principal avec guardrails
agent = Agent(
    name="Planificateur de voyage",
    instructions="""Tu es un assistant de planification de voyage expert.
    Aide les utilisateurs à planifier leurs voyages en fonction de leurs préférences.
    Utilise l'outil météo pour obtenir des informations actualisées.
    Transmets les demandes spécifiques aux agents spécialisés appropriés.""",
    model=os.getenv("LLM_MODEL"),
    output_type=TravelPlan,
    tools=[get_weather_forecast],
    handoffs=[flight_agent, hotel_agent],
    input_guardrails=[budget_guardrail]
)

# Configuration du traçage avec LogFire
import logfire
logfire.configure(api_key="votre_cle_logfire")
from agent_sdk.tracing import configure_tracing
configure_tracing(provider="logfire")

# Fonction principale avec contexte utilisateur
def main():
    # Définition du contexte utilisateur
    user_context = UserContext(
        user_id="user123",
        preferred_airlines=["Ocean Air"],
        preferred_hotel_amenities=["WiFi", "Piscine", "Gym"],
        budget_level="medium"
    )

    # Exécution de l'agent avec le contexte utilisateur
    final_output = runner.run_sync(
        agent=agent,
        user_message="Je veux aller à Tokyo pendant une semaine pour 3000 $",
        user_context=user_context
    )

    print(final_output)

Le contexte utilisateur permet de stocker des métadonnées comme les compagnies aériennes préférées ou les équipements d’hôtel souhaités, sans les inclure dans le prompt du LLM. Ces informations sont accessibles dans les outils pour personnaliser les résultats.

Pour le traçage, le SDK s’intègre facilement avec des services comme LogFire, qui offre 10 millions de traces par mois gratuitement.

Interface utilisateur Streamlit

Pour créer une interface utilisateur complète, nous pouvons utiliser Streamlit. Cela permet aux utilisateurs de définir leurs préférences via une barre latérale et d’avoir une conversation avec notre agent de voyage.

L’interface affiche les réponses formatées de manière élégante et permet de suivre la conversation. De plus, avec LogFire, nous pouvons visualiser tous les appels d’agents, les garde-fous activés et les réponses structurées dans un tableau de bord complet.

Évaluation du SDK d’Agents d’OpenAI

Après avoir exploré en profondeur le SDK d’Agents d’OpenAI, voici mon évaluation :

Points forts

  • Simplicité d’utilisation : Construire des agents complexes avec très peu de code
  • Fonctionnalités intégrées : Handoffs, guardrails et traçage sont tous inclus
  • Sorties structurées : Facilite l’obtention de réponses cohérentes
  • Open-source et gratuit : Accessible à tous les développeurs

Points faibles

  • Niveau d’abstraction : Tend vers une abstraction plus élevée comme LangChain et Crew AI
  • Limitations des handoffs : Manque de flexibilité pour des règles personnalisées avant/après les handoffs
  • Absence d’humain dans la boucle : Contrairement à LangGraph, pas de fonctionnalité intégrée pour l’approbation humaine
  • Manque d’outils de test : Peu de support pour tester et évaluer les agents sans utiliser un vrai LLM

Conclusion

Le SDK d’Agents d’OpenAI est un framework impressionnant qui simplifie considérablement la création d’agents IA sophistiqués. Il est certainement plus facile à utiliser que des frameworks comme LangChain et Crew AI, mais il n’offre pas encore le niveau de contrôle et de personnalisation que l’on trouve dans Pantic AI et LangGraph.

Pour les développeurs qui débutent avec les agents IA ou qui ont besoin de mettre en place rapidement un système d’agents fonctionnel, le SDK d’Agents est un excellent choix. Pour les applications de production plus complexes nécessitant un contrôle granulaire, Pantic AI et LangGraph restent probablement les meilleurs choix pour l’instant.

Cependant, étant donné que ce SDK est tout nouveau, il est probable qu’OpenAI ajoutera de nombreuses fonctionnalités dans les mois à venir. Il vaut certainement la peine de le surveiller de près, car il pourrait devenir un acteur majeur dans l’espace des frameworks d’agents IA.