Comment utiliser le SDK OpenAI Agents ?

Le SDK OpenAI Agents est une bibliothèque Python conçue pour simplifier le développement d'agents d'IA alimentés par les modèles de langage d'OpenAI. Il fournit aux développeurs des outils pour créer des agents spécifiques à des tâches, intégrer des fonctionnalités externes, gérer la délégation de tâches entre agents, appliquer la validation des entrées/sorties et surveiller les flux d'exécution. Ce guide fournit une présentation technique détaillée de l'installation, de la configuration et de l'utilisation efficace du SDK, garantissant un minimum de 2000 mots axés sur la précision et l'application pratique.

💡

Avant de commencer, voici une astuce rapide : Puisque nous allons beaucoup travailler avec les API dans ce guide, vous voudrez peut-être vous procurer Apidog. C'est un outil gratuit qui facilite grandement le test et le débogage des API, parfait pour expérimenter avec le SDK OpenAI Agents. Vous pouvez télécharger Apidog gratuitement ici. Croyez-moi, cela vous évitera des maux de tête plus tard !

button

Introduction

Le SDK OpenAI Agents fournit un cadre structuré pour la création de systèmes multi-agents où chaque agent est conçu pour effectuer des tâches spécifiques. Ces agents peuvent interagir avec les utilisateurs, exécuter des actions via des outils intégrés et collaborer en passant des tâches à d'autres agents. Les principaux composants du SDK incluent :

Agents : Instances de modèles de langage configurées avec des instructions et des rôles spécifiques.
Outils : Fonctions ou services (par exemple, recherche Web, code Python personnalisé) qui étendent les capacités des agents.
Transferts : Mécanismes permettant aux agents de déléguer des tâches à d'autres agents de manière transparente.
Garde-fous : Couches de validation pour garantir que les entrées et les sorties répondent aux critères définis.
Traçage : Journaux d'exécution pour le débogage et l'analyse des performances.

Ce guide est conçu pour les développeurs ayant une compréhension de base de Python et des interactions API, fournissant des explications détaillées, des exemples de code et les meilleures pratiques pour créer une ressource robuste et complète.

Installation et configuration

Une configuration appropriée est essentielle pour utiliser efficacement le SDK OpenAI Agents. Cette section couvre les prérequis, la configuration de l'environnement, l'installation et la vérification.

Prérequis

Avant de continuer, assurez-vous de ce qui suit :

Python 3.8+ : Vérifiez votre version de Python avec python --version. Installez à partir de python.org si nécessaire.

Clé API OpenAI : Obtenez votre clé à partir de platform.openai.com sous les paramètres de votre compte. Cette clé authentifie les requêtes vers les serveurs d'OpenAI.

Étape 1 : Configurer un environnement virtuel

Un environnement virtuel isole les dépendances du projet, évitant les conflits avec d'autres projets Python. Pour en créer et en activer un :

Linux/macOS :

python -m venv agents_env
source agents_env/bin/activate

Windows :

python -m venv agents_env
agents_env\Scripts\activate

Une fois activé, l'invite de votre terminal doit refléter l'environnement (par exemple, (agents_env)). Cette étape est une bonne pratique pour le développement Python, garantissant un espace de travail propre.

Étape 2 : Installer le SDK

Avec l'environnement virtuel actif, installez le SDK à l'aide de pip :

pip install openai-agents

Cette commande récupère la dernière version du SDK et ses dépendances depuis PyPI. Pour confirmer l'installation, exécutez :

pip show openai-agents-python

Cela affiche les métadonnées, y compris le numéro de version, confirmant que le package est installé.

Étape 3 : Configurer la clé API

Le SDK nécessite une clé API OpenAI pour fonctionner. Définissez-la comme variable d'environnement pour éviter de l'intégrer dans votre code, ce qui améliore la sécurité :

Linux/macOS :

export OPENAI_API_KEY='your-api-key'

Windows :

set OPENAI_API_KEY='your-api-key'

Pour que cela soit persistant entre les sessions, ajoutez la commande à votre fichier de configuration shell (par exemple, .bashrc ou .zshrc sur les systèmes Unix). Vous pouvez également le définir par programmation en Python, bien que cela soit moins sûr :

import os
os.environ["OPENAI_API_KEY"] = "your-api-key"

Étape 4 : Vérifier l'installation

Testez la configuration avec un agent minimal pour vous assurer que tout fonctionne :

from agents import Agent, Runner

agent = Agent(name="TestAgent", instructions="Return 'Setup successful'")
result = Runner.run_sync(agent, "Run test")
print(result.final_output)  # Expected output: "Setup successful"

Si cela affiche "Setup successful", votre installation est fonctionnelle. Les problèmes courants incluent :

Clé API non valide : Vérifiez la clé et assurez-vous qu'il n'y a pas d'espaces supplémentaires ou de fautes de frappe.
Erreurs réseau : Vérifiez votre connexion Internet et l'état du serveur d'OpenAI.

Création d'agents

Les agents sont les éléments constitutifs fondamentaux du SDK, chacun étant défini par un rôle et un comportement uniques.

Initialisation de l'agent

La classe Agent est utilisée pour instancier les agents. Les paramètres clés incluent :

name : Un identifiant de chaîne (par exemple, "MathAgent").
instructions : Une chaîne spécifiant le but de l'agent (par exemple, "Résoudre des problèmes mathématiques").
model : Le modèle OpenAI à utiliser (par défaut : gpt-4).
temperature : Un nombre à virgule flottante compris entre 0 et 1 contrôlant le caractère aléatoire de la sortie (par défaut : 0,7).

Exemple : Agent de base

Voici un agent simple pour l'arithmétique :

from agents import Agent, Runner

agent = Agent(
    name="MathAgent",
    instructions="Solve arithmetic expressions."
)
result = Runner.run_sync(agent, "Calculate 10 * 2")
print(result.final_output)  # Output: "20"

La méthode Runner.run_sync exécute l'agent de manière synchrone, renvoyant un objet de résultat avec l'attribut final_output.

Configuration avancée

Personnalisez les agents pour des besoins spécifiques en ajustant les paramètres :

agent = Agent(
    name="CreativeWriter",
    instructions="Write a short story based on the prompt.",
    model="gpt-4",
    temperature=0.9
)
result = Runner.run_sync(agent, "A robot in a distant galaxy")
print(result.final_output)  # Output: A creative story

Modèle : gpt-4 offre un raisonnement supérieur, tandis que gpt-3.5-turbo est plus rapide et moins cher pour les tâches plus simples.
Température : Des valeurs plus basses (par exemple, 0,2) produisent des sorties prévisibles ; des valeurs plus élevées (par exemple, 0,9) augmentent la créativité.

Exemple de plusieurs agents

Créez des agents distincts pour différentes tâches :

support_agent = Agent(
    name="SupportBot",
    instructions="Answer technical support questions."
)
code_agent = Agent(
    name="CodeHelper",
    instructions="Generate Python code snippets."
)

support_result = Runner.run_sync(support_agent, "How do I install Python?")
code_result = Runner.run_sync(code_agent, "Write a function to add two numbers")
print(support_result.final_output)  # Output: Installation instructions
print(code_result.final_output)     # Output: "def add(a, b): return a + b"

Cela démontre la flexibilité du SDK dans la gestion de rôles divers.

Intégration d'outils

Les outils améliorent les agents en leur permettant d'effectuer des actions externes. Le SDK prend en charge les outils hébergés, les outils de fonction personnalisés et les outils basés sur des agents.

Utilisation d'outils hébergés

Les outils hébergés, comme web_search, sont pré-construits et prêts à l'emploi :

from agents import Agent, Runner, web_search

agent = Agent(
    name="ResearchAgent",
    instructions="Answer questions using web search.",
    tools=[web_search]
)
result = Runner.run_sync(agent, "What is the capital of France?")
print(result.final_output)  # Output: "The capital of France is Paris."

L'agent invoque automatiquement web_search pour récupérer des données en temps réel.

Création d'outils de fonction personnalisés

Définissez des outils personnalisés avec le décorateur @function_tool. Les outils doivent accepter et renvoyer des chaînes.

Exemple : Outil de récupération de données

from agents import Agent, Runner, function_tool

@function_tool
def fetch_data(id: str) -> str:
    """Return data for the given ID."""
    # Simulated database lookup
    return f"Data for ID {id}: active"

agent = Agent(
    name="DataAgent",
    instructions="Retrieve data using the tool.",
    tools=[fetch_data]
)
result = Runner.run_sync(agent, "Fetch data for ID 123")
print(result.final_output)  # Output: "Data for ID 123: active"

Intégration d'API externes

Les outils peuvent se connecter à des services externes. Voici un exemple d'outil météo :

import requests
from agents import function_tool, Agent, Runner

@function_tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    api_key = "your-weather-api-key"  # Replace with a real key
    url = f"http://api.weatherapi.com/v1/current.json?key={api_key}&q={city}"
    response = requests.get(url)
    if response.status_code == 200:
        data = response.json()
        return f"The weather in {city} is {data['current']['condition']['text']}."
    return "Weather data unavailable."

agent = Agent(
    name="WeatherAgent",
    instructions="Provide weather updates using the tool.",
    tools=[get_weather]
)
result = Runner.run_sync(agent, "What's the weather in Tokyo?")
print(result.final_output)  # Output: "The weather in Tokyo is Sunny." (example)

Inscrivez-vous pour obtenir une clé API gratuite sur weatherapi.com pour tester cela.

Combinaison de plusieurs outils

Les agents peuvent utiliser plusieurs outils simultanément :

@function_tool
def log_entry(text: str) -> str:
    """Log a message."""
    return f"Logged: {text}"

agent = Agent(
    name="MultiToolAgent",
    instructions="Use tools to search and log.",
    tools=[web_search, log_entry]
)
result = Runner.run_sync(agent, "Search for AI trends and log the query")
print(result.final_output)  # Output includes search results and log confirmation

Transferts d'agents

Les transferts permettent aux agents de déléguer des tâches, ce qui permet des flux de travail complexes.

Configuration des transferts

Définissez un agent principal avec accès aux agents secondaires via le paramètre handoffs :

from agents import Agent, Runner

english_agent = Agent(
    name="EnglishHelper",
    instructions="Respond in English only."
)
spanish_agent = Agent(
    name="SpanishHelper",
    instructions="Respond in Spanish only."
)
triage_agent = Agent(
    name="LanguageRouter",
    instructions="Detect the language and hand off to the appropriate agent.",
    handoffs=[english_agent, spanish_agent]
)

result = Runner.run_sync(triage_agent, "Hola, ¿qué tal?")
print(result.final_output)  # Output: "¡Bien, gracias!" (or similar)

Le triage_agent analyse l'entrée et délègue à l'agent spécifique à la langue appropriée.

Logique de transfert

La décision de transfert repose sur les instructions de l'agent principal. Par exemple :

"Si l'entrée contient des mots espagnols, transférez-la à SpanishHelper."
"Pour les entrées en anglais, utilisez EnglishHelper."

Testez avec une entrée en anglais :

result = Runner.run_sync(triage_agent, "How are you?")
print(result.final_output)  # Output: "I'm good, thanks!"

Transferts imbriqués

Pour des flux de travail plus approfondis, les agents peuvent se transférer à d'autres agents avec des transferts :

analysis_agent = Agent(
    name="AnalysisBot",
    instructions="Analyze data and hand off for reporting."
)
report_agent = Agent(
    name="ReportBot",
    instructions="Generate a report from analysis."
)
main_agent = Agent(
    name="WorkflowManager",
    instructions="Start with analysis.",
    handoffs=[analysis_agent, report_agent]
)

result = Runner.run_sync(main_agent, "Analyze sales data")
print(result.final_output)  # Output: A generated report

Mise en œuvre de garde-fous

Les garde-fous appliquent des contraintes sur les entrées et les sorties à l'aide de modèles Pydantic.

Définition d'un garde-fou

Créez un modèle pour valider la structure de sortie :

from pydantic import BaseModel
from agents import Agent, Runner

class QuestionCheck(BaseModel):
    is_question: bool
    reason: str

guard_agent = Agent(
    name="QuestionGuard",
    instructions="Determine if the input is a question.",
    output_type=QuestionCheck
)

result = Runner.run_sync(guard_agent, "What is the capital of France?")
print(result.final_output)  # Output: {"is_question": true, "reason": "Ends with a question mark"}

Intégration du flux de travail

Utilisez des garde-fous pour filtrer les entrées :

task_agent = Agent(
    name="TaskProcessor",
    instructions="Process questions only.",
    handoffs=[guard_agent]
)
result = Runner.run_sync(task_agent, "Tell me a story")
print(result.final_output)  # Output indicates it’s not a question

Traçage et débogage

Le traçage enregistre les détails de l'exécution de l'agent, accessibles via le Tableau de bord OpenAI.

Activation du traçage

Le traçage est automatique. Chaque exécution génère une trace avec :

Données d'entrée/sortie
Appels d'outils
Événements de transfert
Erreurs

Exemple de débogage

Si un agent échoue, examinez la trace pour identifier :

Paramètres d'outil incorrects
Mauvais routage de transfert
Erreurs d'API

Meilleures pratiques

Optimisation des performances

Choix du modèle : Utilisez gpt-3.5-turbo pour la vitesse, gpt-4 pour un raisonnement complexe.
Température : 0,2 pour la précision, 0,9 pour la créativité.
Exécution asynchrone : Utilisez Runner.run_async pour les tâches parallèles.

Gestion des erreurs

Outils : Renvoyez des messages d'erreur clairs (par exemple, "ID non valide").
Transferts : Incluez un agent de secours en cas d'échec.

Conception du flux de travail

Modularité : Divisez les tâches entre les agents.
Clarté : Écrivez des instructions non ambiguës.
Validation : Appliquez des garde-fous aux étapes clés.

Conclusion

Le SDK OpenAI Agents permet aux développeurs de créer des systèmes d'IA sophistiqués avec des agents spécialisés, des outils intégrés et des flux de travail collaboratifs. Ce guide fournit une base technique pour exploiter tout son potentiel, avec des exemples et les meilleures pratiques.

Alors, quelle est la prochaine étape ? Commencez à expérimenter ! Jouez avec différentes instructions, outils et flux de travail. Et si vous rencontrez un problème, des outils comme Apidog peuvent vous aider avec les tests API, obtenez-le gratuitement.

button