Déclarer des tools dans le SDK

Les tools sont les capacités concrètes de votre agent. Sans tools, un agent ne peut que générer du texte. Avec des tools, il peut interroger des bases de données, appeler des API, envoyer des emails, et bien plus. Dans cette leçon, vous apprendrez à déclarer des tools de manière propre et maintenable.

Le décorateur @function_tool

La façon la plus simple de créer un tool est le décorateur @function_tool :

from agents import function_tool

@function_tool
def rechercher_client(email: str) -> str:
    """Recherche un client par son adresse email dans la base de données.

    Args:
        email: L'adresse email du client à rechercher.
    """
    # En production : appel à votre base de données
    clients = {
        "[email protected]": {"nom": "Alice Dupont", "plan": "Pro", "depuis": "2024"},
        "[email protected]": {"nom": "Bob Martin", "plan": "Starter", "depuis": "2025"},
    }
    client = clients.get(email)
    if client:
        return f"Client trouvé : {client['nom']}, plan {client['plan']}, client depuis {client['depuis']}"
    return f"Aucun client trouvé avec l'email {email}"

Le SDK extrait automatiquement :

Le nom de la fonction comme nom du tool
La docstring comme description du tool
Les type hints pour générer le schéma JSON des paramètres

Personnaliser le nom et la description

Vous pouvez surcharger le nom et la description par défaut :

@function_tool(
    name_override="chercher_dans_crm",
    description_override="Cherche un client dans le CRM par email, nom ou numéro de compte."
)
def rechercher_client(identifiant: str) -> str:
    """Recherche un client."""
    # ...
    return "Résultat"

Types de paramètres supportés

Le SDK supporte les types Python natifs et les modèles Pydantic :

from pydantic import BaseModel, Field
from typing import Optional
from agents import function_tool

class FiltreRecherche(BaseModel):
    categorie: str = Field(description="Catégorie du produit")
    prix_max: Optional[float] = Field(None, description="Prix maximum en euros")
    en_stock: bool = Field(True, description="Uniquement les produits en stock")

@function_tool
def rechercher_produits(filtre: FiltreRecherche) -> str:
    """Recherche des produits selon les critères spécifiés."""
    resultats = []
    # Logique de recherche avec filtre.categorie, filtre.prix_max, etc.
    return f"Trouvé {len(resultats)} produits dans {filtre.categorie}"

Les modèles Pydantic permettent de valider automatiquement les entrées et de fournir des descriptions riches au modèle.

Retourner des résultats structurés

Un tool retourne toujours une chaîne de caractères. Pour les données structurées, sérialisez en JSON :

import json
from agents import function_tool

@function_tool
def obtenir_statistiques_ventes(mois: str, annee: int) -> str:
    """Récupère les statistiques de ventes pour un mois donné."""
    stats = {
        "mois": mois,
        "annee": annee,
        "chiffre_affaires": 145000,
        "nombre_ventes": 342,
        "panier_moyen": 423.98,
        "top_produits": ["Laptop Pro", "Tablet Air", "Monitor 4K"]
    }
    return json.dumps(stats, ensure_ascii=False, indent=2)

Les tools hébergés par OpenAI

En plus de vos fonctions personnalisées, le SDK donne accès aux tools managés par OpenAI :

from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool

agent = Agent(
    name="Assistant polyvalent",
    instructions="Vous êtes un assistant capable de chercher sur le web, analyser des fichiers et exécuter du code.",
    tools=[
        WebSearchTool(),
        FileSearchTool(
            vector_store_ids=["vs_abc123"],
            max_num_results=10,
        ),
        CodeInterpreterTool(),
    ],
)

WebSearchTool

Permet à l’agent de chercher sur internet en temps réel. Aucune configuration nécessaire.

FileSearchTool

Recherche sémantique dans vos fichiers. Vous devez d’abord créer un vector store via l’API OpenAI et y uploader vos fichiers.

CodeInterpreterTool

L’agent peut écrire et exécuter du code Python dans un sandbox sécurisé. Idéal pour l’analyse de données et la génération de graphiques.

Combiner tools personnalisés et hébergés

La puissance réside dans la combinaison :

agent = Agent(
    name="Analyste financier",
    instructions="""Vous êtes un analyste financier.
    Utilisez les outils internes pour récupérer les données,
    le code interpreter pour les analyser,
    et la recherche web pour le contexte marché.""",
    tools=[
        obtenir_statistiques_ventes,
        rechercher_client,
        WebSearchTool(),
        CodeInterpreterTool(),
    ],
)

Points clés à retenir

@function_tool transforme une fonction Python en tool pour l’agent
La docstring et les type hints génèrent automatiquement le schéma JSON
Utilisez Pydantic pour des paramètres complexes avec validation
Les tools retournent toujours des chaînes de caractères (JSON si structuré)
Combinez vos tools personnalisés avec WebSearchTool, FileSearchTool et CodeInterpreterTool