Architecture d'un agent : boucle outil-raisonnement

Architecture d’un agent : la boucle outil-raisonnement

Pour construire des agents efficaces, vous devez comprendre leur architecture interne. Un agent OpenAI fonctionne selon une boucle de raisonnement : il reçoit une tâche, réfléchit, utilise un outil, observe le résultat, puis décide s’il a terminé ou s’il doit continuer.

Le cycle de vie d’un agent

Chaque exécution d’un agent suit ce cycle :

1. Réception : l’agent reçoit le message de l’utilisateur et ses instructions système
2. Raisonnement : le modèle analyse la demande et décide de la prochaine action
3. Appel d’outil : si nécessaire, l’agent appelle un ou plusieurs outils
4. Observation : l’agent reçoit les résultats des outils
5. Décision : l’agent décide s’il doit continuer (retour à l’étape 2) ou répondre
6. Réponse : l’agent produit sa réponse finale

Cette boucle peut s’exécuter plusieurs fois. Un agent peut enchaîner 5, 10, ou même 20 appels d’outils avant de produire sa réponse finale.

from agents import Agent, Runner, function_tool

@function_tool
def rechercher_produit(nom: str) -> str:
    """Recherche un produit dans le catalogue."""
    # Simulation - en production, appel à votre base de données
    catalogue = {
        "laptop-pro": {"prix": 1299, "stock": 45},
        "tablet-air": {"prix": 599, "stock": 120},
    }
    produit = catalogue.get(nom)
    if produit:
        return f"Produit {nom}: {produit[prix]}€, stock: {produit[stock]}"
    return f"Produit {nom} non trouvé"

@function_tool
def calculer_remise(prix: float, pourcentage: float) -> str:
    """Calcule le prix après remise."""
    prix_final = prix * (1 - pourcentage / 100)
    return f"Prix après {pourcentage}% de remise : {prix_final:.2f}€"

agent = Agent(
    name="Agent commercial",
    instructions="Vous aidez les clients à trouver des produits et calculer des remises.",
    tools=[rechercher_produit, calculer_remise],
    model="gpt-5.3",
)

# L'agent va : 1) chercher le produit, 2) calculer la remise, 3) répondre
result = Runner.run_sync(
    agent,
    "Quel est le prix du laptop-pro avec 15% de remise ?"
)
print(result.final_output)

Dans cet exemple, l’agent effectue automatiquement deux appels d’outils en séquence : d’abord rechercher_produit, puis calculer_remise avec le prix obtenu.

La structure interne : items et messages

La Responses API structure chaque interaction en items. Quand l’agent tourne, il accumule des items dans sa conversation :

• message : un message texte (de l’utilisateur ou de l’agent)
• function_call : un appel d’outil décidé par l’agent
• function_call_output : le résultat retourné par l’outil

result = Runner.run_sync(agent, "Cherche le tablet-air")

# Inspecter les étapes de raisonnement
for item in result.raw_responses:
    print(f"Type: {type(item).__name__}")
    # Vous verrez : message input → function_call → function_call_output → message output

Appels parallèles vs. séquentiels

L’agent peut décider d’appeler plusieurs outils en parallèle quand les appels sont indépendants :

@function_tool
def obtenir_meteo(ville: str) -> str:
    """Obtient la météo actuelle pour une ville."""
    meteos = {"Paris": "18°C, ensoleillé", "Lyon": "16°C, nuageux"}
    return meteos.get(ville, "Données non disponibles")

agent = Agent(
    name="Agent voyage",
    instructions="Vous aidez à planifier des voyages.",
    tools=[obtenir_meteo, rechercher_produit],
    model="gpt-5.3",
)

# L'agent appellera obtenir_meteo("Paris") et obtenir_meteo("Lyon") en parallèle
result = Runner.run_sync(
    agent,
    "Quelle est la météo à Paris et à Lyon ?"
)

Le SDK gère automatiquement le parallélisme. Si le modèle décide que deux appels sont indépendants, il les lance simultanément, ce qui réduit la latence.

Le paramètre max_turns

Pour éviter qu’un agent boucle indéfiniment, vous pouvez limiter le nombre de tours :

result = Runner.run_sync(
    agent,
    "Analyse complète du catalogue",
    max_turns=10  # Maximum 10 itérations de la boucle
)

Si l’agent atteint la limite, il s’arrête avec les résultats obtenus jusque-là. En production, c’est une sécurité essentielle.

Points clés à retenir

• Un agent fonctionne en boucle : raisonnement → outil → observation → décision
• Cette boucle peut s’exécuter plusieurs fois avant de produire une réponse
• Le modèle décide automatiquement quels outils appeler et dans quel ordre
• Les appels d’outils indépendants sont exécutés en parallèle
• max_turns permet de limiter le nombre d’itérations pour la sécurité