Anatomie du SDK : Agent, Runner, Tool, Guardrail

Anatomie du SDK : Agent, Runner, Tool, Guardrail

Le Agents SDK repose sur quatre concepts fondamentaux : Agent, Runner, Tool et Guardrail. Chacun a une responsabilité unique, et c’est précisément leur articulation — qui décide, qui exécute, qui agit, qui contrôle — qui rend le SDK lisible une fois qu’on l’a en tête.

Agent : la configuration

La classe Agent est purement déclarative : elle ne lance rien, elle décrit. Tout ce qui définit le comportement de votre agent y est rassemblé en un seul endroit.

from agents import Agent, function_tool, WebSearchTool

@function_tool
def obtenir_prix(produit: str) -> str:
    """Récupère le prix d'un produit."""
    prix = {"widget": "29.99€", "gadget": "49.99€"}
    return prix.get(produit, "Produit inconnu")

agent = Agent(
    name="Agent de vente",
    instructions="""Vous êtes un agent commercial pour une boutique en ligne.
    Aidez les clients à trouver des produits et à connaître les prix.
    Répondez toujours en français avec un ton professionnel.""",
    model="gpt-5.6-terra",
    tools=[obtenir_prix, WebSearchTool()],
    handoff_description="Agent spécialisé dans la vente de produits",
    output_type=None,  # ou un type Pydantic pour forcer un format de sortie
)

Les paramètres clés de Agent :

• name : identifiant lisible de l’agent
• instructions : le prompt système qui définit le comportement
• model : le modèle à utiliser (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
• tools : la liste des outils disponibles
• handoff_description : description pour les handoffs entre agents
• output_type : type Pydantic pour structurer la sortie

Runner : l’exécution

Le Runner est le moteur qui fait tourner votre agent : il gère la boucle complète et se décline en trois modes selon le contexte d’appel.

from agents import Runner

# Mode synchrone (développement)
result = Runner.run_sync(agent, "Quel est le prix du widget ?")

# Mode asynchrone (production)
result = await Runner.run(agent, "Quel est le prix du widget ?")

# Mode streaming (temps réel)
result = Runner.run_streamed(agent, "Quel est le prix du widget ?")

Quel que soit le mode, vous récupérez un RunResult, qui contient bien plus que la réponse affichable. L’historique complet vous servira à relancer une conversation, et last_agent deviendra indispensable dès que plusieurs agents se passeront la main.

result = Runner.run_sync(agent, "Quel est le prix du widget ?")

# La réponse finale de l'agent
print(result.final_output)

# L'historique complet des échanges
print(result.to_input_list())

# Le dernier agent actif (utile avec les handoffs)
print(result.last_agent.name)

Tool : les capacités

Les tools se déclarent de trois façons dans le SDK, du plus courant au plus architectural.

1. Function tools (le plus courant)

Une fonction Python décorée devient un outil ; le SDK en déduit le schéma à partir de la signature et de la docstring.

from agents import function_tool

@function_tool
def envoyer_email(destinataire: str, sujet: str, corps: str) -> str:
    """Envoie un email à un destinataire."""
    # Votre logique d'envoi ici
    return f"Email envoyé à {destinataire}"

2. Tools hébergés par OpenAI

Ces outils s’exécutent chez OpenAI : vous n’écrivez ni le code de recherche ni le sandbox Python.

from agents import WebSearchTool, FileSearchTool, CodeInterpreterTool

tools = [
    WebSearchTool(),                               # Recherche web
    FileSearchTool(vector_store_ids=["vs_123"]),   # Recherche fichiers
    CodeInterpreterTool(),                          # Exécution code
]

3. Agents comme tools

Un agent peut en utiliser un autre comme outil. Le coordinateur ci-dessous délègue la recherche sans jamais céder le contrôle de la conversation, ce qui le distingue d’un handoff.

agent_recherche = Agent(
    name="Chercheur",
    instructions="Vous cherchez des informations précises.",
    tools=[WebSearchTool()],
)

agent_principal = Agent(
    name="Coordinateur",
    instructions="Vous coordonnez les recherches.",
    tools=[agent_recherche.as_tool(
        tool_name="rechercher",
        tool_description="Effectue une recherche approfondie"
    )],
)

Guardrail : la sécurité

Un guardrail est un agent de contrôle placé devant votre agent métier. Ici, un vérificateur juge si la requête relève bien des ventes avant que l’agent commercial ne réponde.

from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner

guardrail_agent = Agent(
    name="Vérificateur",
    instructions="Déterminez si la requête concerne les ventes. Répondez true ou false.",
    output_type=bool,
)

async def verifier_sujet(ctx, agent, input_data):
    result = await Runner.run(guardrail_agent, input_data, context=ctx)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=not result.final_output,
    )

agent_protege = Agent(
    name="Agent ventes protégé",
    instructions="Vous êtes un agent commercial.",
    input_guardrails=[
        InputGuardrail(guardrail_function=verifier_sujet),
    ],
)

Si le guardrail est déclenché (tripwire_triggered=True), l’exécution s’arrête et une exception InputGuardrailTripwireTriggered est levée. Prévoyez donc de la capturer dans votre application, sous peine de renvoyer une erreur 500 à un utilisateur qui a simplement posé une question hors sujet.

Comment ces briques interagissent

Le flux complet se déroule ainsi :

1. Vous appelez Runner.run(agent, message)
2. Le Runner vérifie les input guardrails
3. Le Runner envoie le message au modèle de l’Agent
4. Si le modèle demande un tool, le Runner l’exécute
5. Le Runner renvoie le résultat au modèle (retour à l’étape 3)
6. Quand le modèle produit une réponse finale, le Runner vérifie les output guardrails
7. Le RunResult est retourné

Points clés à retenir

• Agent définit le comportement (instructions, modèle, tools)
• Runner orchestre l’exécution de la boucle agent
• Les tools se déclarent avec @function_tool, les classes built-in, ou .as_tool()
• Les guardrails valident les entrées et sorties pour la sécurité
• Le RunResult contient la réponse finale et l’historique complet