Créer des agents spécialisés et un routeur

De la théorie à la pratique

Dans la leçon précédente, vous avez découvert le concept de handoff. Maintenant, vous allez créer concrètement un système multi-agents : un agent routeur et plusieurs agents spécialistes.

Étape 1 : Créer les agents spécialistes

Chaque agent a un domaine d’expertise précis :

from mistralai import Mistral
from mistralai.models import CompletionArgs, ResponseFormat, JSONSchema
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Agent de recherche web
web_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="web-search-agent",
    description="Agent qui recherche des informations en ligne.",
    instructions="Effectuez des recherches web précises. Citez toujours vos sources.",
    tools=[{"type": "web_search"}]
)

# Agent financier
finance_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="finance-agent",
    description="Agent spécialisé dans les questions financières.",
    instructions="""Vous êtes un expert financier.
- Utilisez des données chiffrées
- Expliquez les concepts clairement
- Signalez les risques"""
)

# Agent calculateur
calculator_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="calculator-agent",
    description="Agent pour les calculs mathématiques détaillés.",
    instructions="Expliquez chaque étape du calcul. Utilisez le code interpreter pour les calculs complexes.",
    tools=[{"type": "code_interpreter"}]
)

Bonnes pratiques pour les agents spécialistes

• name — Utilisez un nom descriptif en kebab-case
• description — C’est ce que le routeur lit pour décider du transfert. Soyez précis.
• instructions — Spécifiques au domaine, pas génériques
• tools — Uniquement les outils nécessaires à cette spécialité

Étape 2 : Créer l’agent routeur

Le routeur est un agent sans outils spécifiques. Son rôle est d’analyser la requête et de transférer au bon spécialiste :

router_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="router-agent",
    description="Agent routeur qui distribue les requêtes.",
    instructions="""Vous êtes un orchestrateur.
Analysez chaque requête et transférez au bon agent :
- Questions nécessitant des données en ligne → web-search-agent
- Questions financières → finance-agent
- Calculs et analyses numériques → calculator-agent

Ne répondez jamais directement — transférez toujours."""
)

Étape 3 : Définir les cibles de handoff

C’est l’étape clé : indiquer au routeur vers quels agents il peut transférer :

router_agent = client.beta.agents.update(
    agent_id=router_agent.id,
    handoffs=[web_agent.id, finance_agent.id, calculator_agent.id]
)

Le paramètre handoffs prend une liste d’IDs d’agents. Le routeur peut transférer vers n’importe lequel de ces agents.

Handoffs imbriqués

Les agents spécialistes peuvent aussi avoir des handoffs :

# L'agent finance peut transférer au web search et au calculateur
finance_agent = client.beta.agents.update(
    agent_id=finance_agent.id,
    handoffs=[web_agent.id, calculator_agent.id]
)

Cela permet des chaînes comme : routeur → finance → web search → calculator.

Étape 4 : Lancer la conversation

response = client.beta.conversations.start(
    agent_id=router_agent.id,
    inputs="Trouve le taux directeur actuel de la BCE et calcule l'intérêt composé sur 10 ans pour 100 000€."
)

# Analyser le flux
for entry in response.outputs:
    if entry.type == "agent.handoff":
        print(f"[HANDOFF] → {entry.to_agent}")
    elif entry.type == "tool.execution":
        print(f"[OUTIL] {entry.tool_name}")
    elif entry.type == "message.output":
        print(f"[RÉPONSE] {entry.content[:200]}...")

Le rôle crucial de la description

Le routeur choisit l’agent cible en se basant sur la description de chaque agent. C’est pourquoi elle doit être orientée tâche :

# Mauvais — trop vague
description="Un agent utile."

# Bon — le routeur sait quand transférer
description="Agent qui recherche des informations actuelles sur Internet et cite ses sources."

Exemple complet

from mistralai import Mistral
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# 1. Agents spécialistes
research = client.beta.agents.create(
    model="mistral-large-latest",
    name="research-agent",
    description="Recherche d'informations en ligne avec sources.",
    tools=[{"type": "web_search"}]
)

analyst = client.beta.agents.create(
    model="mistral-large-latest",
    name="analyst-agent",
    description="Analyse de données et calculs avec Python.",
    tools=[{"type": "code_interpreter"}]
)

writer = client.beta.agents.create(
    model="mistral-large-latest",
    name="writer-agent",
    description="Rédaction de rapports structurés et professionnels.",
    instructions="Rédigez des rapports clairs avec introduction, analyse et recommandations."
)

# 2. Routeur avec handoffs
router = client.beta.agents.create(
    model="mistral-large-latest",
    name="router",
    description="Orchestre les requêtes complexes.",
    instructions="Analysez la requête et transférez au spécialiste approprié.",
    handoffs=[research.id, analyst.id, writer.id]
)

# 3. Lancer
response = client.beta.conversations.start(
    agent_id=router.id,
    inputs="Analyse le marché européen du cloud computing en 2026 : taille, acteurs, tendances."
)

Points clés à retenir

• Créez des agents spécialistes avec des descriptions précises orientées tâche
• Le routeur utilise les descriptions pour choisir l’agent cible
• client.beta.agents.update(handoffs=[...]) définit les cibles de transfert
• Les handoffs peuvent être imbriqués (agent A → agent B → agent C)
• La description de chaque agent est le levier principal de la qualité du routage