Introduction aux handoffs multi-agents

Pourquoi orchestrer plusieurs agents ?

Jusqu’ici, vous avez travaillé avec des agents individuels. Mais certaines tâches complexes nécessitent des compétences différentes : rechercher des données, les analyser, produire un rapport. Plutôt que de surcharger un seul agent, l’API Mistral permet de créer 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.

Le principe des handoffs

Un handoff fonctionne comme une organisation humaine :

1. Un agent routeur reçoit la requête initiale
2. Il analyse la demande et identifie quel agent spécialiste est le mieux placé
3. Il transfère la conversation à cet agent
4. L’agent spécialiste traite la sous-tâche et peut à son tour transférer à un autre agent
5. La réponse finale remonte à l’utilisateur

Avantages du multi-agents

Spécialisation

Chaque agent a un périmètre limité et des instructions précises. Un agent de recherche web ne s’occupe pas de calculs, et vice versa. Cette spécialisation améliore la qualité des réponses.

Maintenabilité

Modifier le comportement d’un agent spécialiste n’impacte pas les autres. Vous pouvez changer le modèle, les instructions ou les outils d’un agent sans toucher au reste du système.

Scalabilité

Ajouter une nouvelle capacité = créer un nouvel agent spécialiste et l’ajouter comme cible de handoff. Le routeur le sélectionnera quand la demande correspond.

Traçabilité

Chaque handoff génère un événement agent.handoff dans les outputs, permettant de suivre exactement quel agent a traité quelle partie de la requête.

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 peut aussi gérer des flux séquentiels : recherche → calcul → rédaction.

Exemple de flux

Requête : “Trouve le taux d’intérêt actuel de la BCE et calcule l’effet composé sur 10 ans pour un investissement de 100K€.”

1. Agent Finance (routeur) → reçoit la requête
2. Handoff → Agent Web Search → cherche le taux actuel de la BCE
3. Handoff → Agent Calculateur → calcule l’intérêt composé
4. Réponse finale → L’utilisateur reçoit le résultat avec sources et calculs

Modes d’exécution

L’API Mistral propose deux modes pour les handoffs :

Mode serveur (défaut)

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

Mistral gère tout automatiquement : les transferts, l’exécution des agents, et la synthèse de la réponse. Vous recevez le résultat final.

Mode client

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

Vous recevez les événements de handoff et décidez quoi faire à chaque étape. Utile quand vous avez besoin de contrôle (validation humaine, logging, routage custom).

É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}")

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