Introduction aux handoffs multi-agents

Pourquoi orchestrer plusieurs agents ?

Jusqu’ici, vous avez travaillé avec des agents individuels : un agent, ses instructions, ses outils. Ce modèle atteint vite ses limites dès que la tâche demande des compétences hétérogènes. Prenez une demande d’étude de marché : il faut rechercher des données, les analyser numériquement, puis produire un rapport lisible. Vous pouvez tenter de tout confier à un seul agent, avec des instructions qui gonflent à chaque nouveau besoin, jusqu’à devenir un pavé contradictoire que le modèle applique de moins en moins bien. L’API Mistral propose l’alternative : des chaînes d’agents spécialisés qui se passent le relais.

C’est le concept de handoff : un agent transfère le contrôle de la conversation à un autre agent mieux équipé pour la sous-tâche en cours. La conversation, elle, ne change pas — c’est la main qui change.

Le principe des handoffs

Le fonctionnement reproduit exactement ce que fait une organisation humaine devant une demande composite. Un agent routeur reçoit la requête initiale, comme un standard reçoit un appel. Il analyse la demande et identifie quel agent spécialiste est le mieux placé pour la traiter, puis il lui transfère la conversation. Le spécialiste traite sa sous-tâche et, s’il rencontre à son tour un besoin qui le dépasse, peut transférer à un troisième agent. La réponse finale remonte à l’utilisateur, qui n’a vu qu’un seul interlocuteur.

Quatre bénéfices en découlent, et ils se renforcent mutuellement. La spécialisation d’abord : chaque agent a un périmètre limité et des instructions précises, l’agent de recherche web ne s’occupe pas de calculs et réciproquement, ce qui améliore la qualité des réponses parce qu’aucune instruction n’en contredit une autre. La maintenabilité ensuite : modifier le comportement d’un spécialiste n’impacte pas les autres, et vous pouvez changer son modèle, ses instructions ou ses outils sans rien toucher au reste du système. La scalabilité en découle directement — ajouter une capacité revient à créer un nouvel agent spécialiste et à l’inscrire comme cible de handoff, après quoi le routeur le sélectionnera quand la demande correspondra. La traçabilité enfin : chaque handoff génère un événement agent.handoff dans les outputs, ce qui vous permet de reconstituer après coup quel agent a traité quelle partie de la requête, sans instrumenter quoi que ce soit vous-même.

Architecture type

Utilisateur
    │
    ▼
Agent Routeur (orchestrateur)
    ├── Agent Recherche Web (web_search)
    ├── Agent Calculateur (code_interpreter)
    ├── Agent Rédacteur (instructions spécifiques)
    └── Agent Documentaire (document_library)

Le routeur décide dynamiquement vers quel agent transférer en fonction de la requête. Il n’est pas cantonné à un aiguillage unique : il peut aussi orchestrer des flux séquentiels, du type recherche puis calcul puis rédaction, chaque étape enrichissant le contexte de la suivante.

Suivons une requête réelle : « Trouve le taux d’intérêt actuel de la BCE et calcule l’effet composé sur 10 ans pour un investissement de 100K€. » L’agent Finance, qui joue le rôle de routeur, reçoit la demande et constate qu’elle contient deux besoins distincts. Il transfère d’abord à l’agent Web Search, qui va chercher le taux actuel de la BCE — une donnée qu’aucun modèle ne peut connaître de mémoire. Un second handoff passe la main à l’agent Calculateur, qui applique la formule d’intérêt composé au taux qui vient d’être trouvé. L’utilisateur reçoit un résultat unique, accompagné des sources de la recherche et du détail du calcul.

Modes d’exécution

L’API Mistral propose deux modes pour les handoffs, et le choix se fait au démarrage de la conversation. Le mode serveur est celui par défaut.

response = client.beta.conversations.start(
    agent_id=router_agent.id,
    inputs="Requête complexe",
    handoff_execution="server"
)

Mistral gère alors tout automatiquement : les transferts, l’exécution des agents et la synthèse de la réponse. Vous ne recevez que le résultat final, ce qui est confortable et suffisant tant que vous n’avez rien à intercaler entre les étapes.

response = client.beta.conversations.start(
    agent_id=router_agent.id,
    inputs="Requête complexe",
    handoff_execution="client"
)

En mode client, vous recevez les événements de handoff et décidez quoi faire à chaque étape. C’est le mode à choisir quand un humain doit valider un transfert sensible, quand vous devez journaliser chaque passage de relais pour un audit, ou quand votre logique métier impose un routage que le modèle ne peut pas deviner. La leçon consacrée à ces deux modes détaillera le compromis.

Événements de sortie

Quand un handoff se produit, trois types d’events apparaissent dans les outputs :

• agent.handoff — L’agent A transfère à l’agent B (contient les IDs des deux agents)
• tool.execution — L’agent B exécute ses outils
• message.output — La réponse de l’agent B

for entry in response.outputs:
    if entry.type == "agent.handoff":
        print(f"Transfert : {entry.from_agent} → {entry.to_agent}")
    elif entry.type == "tool.execution":
        print(f"Outil exécuté : {entry.tool_name}")
    elif entry.type == "message.output":
        print(f"Réponse : {entry.content}")

Cette boucle mérite d’être écrite dès vos premiers essais, avant même que le système ne soit complet. Un multi-agents qui répond correctement mais dont vous ignorez le cheminement devient impossible à corriger le jour où il répond de travers : vous ne saurez pas si le routeur a mal aiguillé, si le spécialiste a mal travaillé, ou si le relais s’est perdu en route. Trois print bien placés vous épargnent cette cécité.

Points clés à retenir

• Les handoffs permettent à un agent de transférer le contrôle à un autre agent spécialisé
• L’architecture type est : agent routeur → agents spécialistes
• Mode serveur = tout automatique ; mode client = contrôle manuel des transferts
• Chaque handoff génère un événement traçable dans les outputs
• Il n’y a pas de limite de profondeur de chaînage entre agents