Créer des agents spécialisés et un routeur
På denna sida
De la théorie à la pratique
La leçon précédente a introduit le concept de transferts (handoffs). Tu vas 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="Effectue des recherches web précises. Cite toujours tes 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="""Tu es un expert financier.
- Utilise des données numériques
- Explique clairement les concepts
- Signale 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="Explique chaque étape du calcul. Utilise 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 toi : il apparaît dans tes journaux et tes tests, et un nom lisible t’é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 « être utile » ne veut rien dire 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 donner des outils 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. Tout son travail 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="""Tu es un orchestrateur.
Analyse chaque demande et transfère-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éponds jamais directement : transfère 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 tes spécialistes et produira des réponses sans les outils qu’ils auraient utilisés. Tu te retrouves avec une architecture multi-agents où la moitié des agents ne sont jamais utilisés.
Étape 3 : Définir les cibles de transfert
Tu dois 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 prend 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 aussi 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 comme 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="Trouve le taux directeur actuel de la BCE et calcule 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écute cette demande et observe la trace avant de regarder la réponse. Tu devrais voir deux transferts et au moins une exécution d’outil ; si tu n’en vois aucun, ton routeur a répondu tout seul, et il est temps de resserrer ses instructions.
Le levier principal : la description
Lorsque le routage échoue, la description est presque toujours en cause. Le routeur ne connaît pas tes 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édige 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érifie é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 puisque 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édige 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="Analyse la demande et transfère-la au spécialiste approprié.",
handoffs=[research.id, analyst.id, writer.id]
)
# 3. Lancement
response = client.beta.conversations.start(
agent_id=router.id,
inputs="Analyse le marché européen du cloud computing en 2026 : taille, acteurs, tendances."
)
Viktiga punkter
- Crée des agents spécialistes avec des descriptions précises et 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 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