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 interroge des bases de données, appelle des API, envoie des emails. Encore faut-il les déclarer proprement, car la qualité d’un tool ne se juge pas seulement à son code : elle se joue aussi dans la façon dont le modèle le comprend.

Le décorateur @function_tool

La façon la plus simple de créer un tool est le décorateur @function_tool, qui transforme une fonction Python ordinaire en capacité appelable par l’agent.

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}"

Rien n’est déclaré deux fois : le SDK reprend le nom de la fonction comme nom du tool, la docstring comme description, et les type hints pour générer le schéma JSON des paramètres. Autrement dit, votre docstring n’est plus un commentaire pour vos collègues, c’est le texte que lit le modèle pour décider s’il doit appeler cette fonction. Une docstring vague produit des appels approximatifs.

Personnaliser le nom et la description

Quand le nom de la fonction obéit à vos conventions internes plutôt qu’à la logique métier, vous pouvez surcharger ce que voit le modèle.

@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

Au-delà des types Python natifs, le SDK accepte les modèles Pydantic. Dès qu’un tool prend trois paramètres ou plus, regroupez-les : le schéma devient plus lisible pour le modèle et la validation vous protège des valeurs aberrantes.

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 valident automatiquement les entrées et fournissent des descriptions riches au modèle, champ par champ.

Retourner des résultats structurés

Un tool retourne toujours une chaîne de caractères. Quand vos données ont une structure — plusieurs métriques, une liste, des types mêlés —, sérialisez-les en JSON plutôt que de composer une phrase : le modèle lira les clés avec bien plus de fiabilité qu’un texte libre.

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, qui s’exécutent côté plateforme.

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 et ne demande aucune configuration. FileSearchTool effectue une recherche sémantique dans vos fichiers, mais suppose un travail préalable : créer un vector store via l’API OpenAI et y uploader vos documents — d’où le vs_abc123 passé en paramètre. CodeInterpreterTool autorise l’agent à écrire et exécuter du code Python dans un sandbox sécurisé, ce qui en fait l’outil de choix 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. Un analyste financier a besoin de vos données internes, d’une capacité de calcul et du contexte marché : trois sources qu’aucun outil unique ne couvre.

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(),
    ],
)

Remarquez que les instructions indiquent à quoi sert chaque famille d’outils. Sans cette précision, un agent doté de quatre tools hésite, en essaie deux inutilement, et allonge la latence pour rien.

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