Créer des agents spécialisés et un routeur
Op deze pagina
De la théorie à la pratique
La leçon précédente a introduit le concept de transferts (handoffs). Vous allez maintenant construire le système complet dans l’ordre réel de construction : d’abord les spécialistes, puis le routeur, ensuite le câblage entre eux, et enfin la conversation qui met tout en mouvement. Cet ordre n’est pas arbitraire : le routeur ne peut pointer que vers des agents qui existent déjà.
Étape 1 : Créer les agents spécialistes
Chaque agent reçoit un domaine d’expertise précis et rien d’autre.
from mistralai.client import Mistral
from mistralai.client.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 numériques
- Expliquez clairement les concepts
- Signalez les risques"""
)
# Agent calculatrice
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 l'interpréteur de code pour les calculs complexes.",
tools=[{"type": "code_interpreter"}]
)
Ces quatre champs jouent des rôles très différents, et l’un d’eux mérite une attention particulière. Le name en kebab-case est pour vous : il apparaît dans vos journaux et tests, et un nom lisible vous évite de comparer des identifiants opaques. Les instructions s’adressent au modèle une fois qu’il commence à travailler ; elles doivent donc être spécifiques au domaine : « signaler les risques » a un sens pour un agent financier, tandis que « soyez utile » ne signifie rien pour personne. Les tools suivent le principe de la stricte nécessité : l’agent financier ci-dessus n’a aucun outil car il raisonne sans en avoir besoin, et lui en donner inviterait simplement à un mauvais usage. Enfin, la description n’est pas de la documentation : c’est le texte que le routeur lit pour décider s’il doit transférer ici ou ailleurs.
Étape 2 : Créer l’agent routeur
Le routeur n’a aucun outil. Sa seule tâche consiste à analyser la demande et à choisir le destinataire.
router_agent = client.beta.agents.create(
model="mistral-large-latest",
name="router-agent",
description="Agent routeur qui distribue les demandes.",
instructions="""Vous êtes un orchestrateur.
Analysez chaque demande et transférez-la 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."""
)
Cette dernière ligne empêche le système de s’effondrer. Sans elle, un routeur basé sur un grand modèle répondra aux questions qui lui semblent faciles, contournera vos spécialistes et produira des réponses sans utiliser les outils qu’ils auraient employés. Vous vous retrouvez alors avec une architecture multi-agents où la moitié des agents ne sont jamais utilisés.
Étape 3 : Définir les cibles de transfert
Vous devez maintenant indiquer au routeur vers quels agents il est autorisé à 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 accepte une liste d’identifiants d’agents, et le routeur peut transférer vers n’importe lequel d’entre eux. Ce n’est pas un privilège réservé au routeur : les spécialistes peuvent également déclarer leurs propres cibles.
# L'agent financier peut transférer vers la recherche web et la calculatrice
finance_agent = client.beta.agents.update(
agent_id=finance_agent.id,
handoffs=[web_agent.id, calculator_agent.id]
)
Une chaîne telle que routeur → finance → recherche web → calculatrice devient alors possible. Lorsque l’agent financier fait face à une question nécessitant un taux actuel, il ne revient pas au routeur : il va directement vers le spécialiste dont il a besoin, tout comme un consultant qui appelle un collègue plutôt que de repasser par la réception.
Étape 4 : Démarrer la conversation
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Trouvez le taux directeur actuel de la BCE et calculez les intérêts composés sur 10 ans pour 100 000 €."
)
# Analyser le flux
for entry in response.outputs:
if entry.type == "agent.handoff":
print(f"[HANDOFF] → {entry.next_agent_id}")
elif entry.type == "tool.execution":
print(f"[TOOL] {entry.tool_name}")
elif entry.type == "message.output":
print(f"[RESPONSE] {entry.content[:200]}...")
Exécutez cette demande et observez la trace avant de regarder la réponse. Vous devriez voir deux transferts et au moins une exécution d’outil ; si vous n’en voyez aucun, votre routeur a répondu seul et il est temps de renforcer ses instructions.
Le levier principal : la description
Lorsque le routage échoue, la description est presque toujours en cause. Le routeur ne connaît pas vos intentions ; il lit uniquement ce texte pour chaque agent candidat.
# 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."
Rédigez chaque description comme une réponse à la question « dans quel cas dois-je appeler cet agent ? » plutôt que comme un résumé de ce qu’il est. Le deuxième exemple nomme la situation — informations actuelles, sur Internet — tandis que le premier laisse le routeur deviner. Vérifiez également qu’aucune paire de descriptions ne se chevauche : deux agents décrits en des termes similaires produiront un routage instable d’une exécution à l’autre.
Exemple complet
Voici la version condensée, avec handoffs passés directement lors de la création du routeur, car les spécialistes existent déjà à ce stade.
from mistralai.client 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 une introduction, une analyse et des recommandations."
)
# 2. Routeur avec transferts
router = client.beta.agents.create(
model="mistral-large-latest",
name="router",
description="Orchestre les demandes complexes.",
instructions="Analysez la demande et transférez-la au spécialiste approprié.",
handoffs=[research.id, analyst.id, writer.id]
)
# 3. Lancement
response = client.beta.conversations.start(
agent_id=router.id,
inputs="Analysez le marché européen du cloud computing en 2026 : taille, acteurs, tendances."
)
Belangrijkste punten
- Créez des agents spécialistes avec des descriptions précises et orientées vers la tâche
- Le routeur utilise les descriptions pour choisir l’agent cible
client.beta.agents.update(handoffs=[...])définit les cibles de transfert- Les transferts peuvent être imbriqués (agent A → agent B → agent C)
- La description de chaque agent est le levier principal pour la qualité du routage