Bonnes pratiques et prochaines étapes

Ce que vous avez parcouru

Vous avez traversé l’ensemble de l’API Agents de Mistral. Reprenons le fil avant d’aborder les pratiques de production, car chaque bloc du cours s’appuie sur le précédent.

Les trois premières leçons ont posé les fondations : un agent IA est un système autonome doté d’une boucle perception-action, l’API repose sur trois objets — Agent, Conversation, Entry — et ce qui sépare un agent d’un chatbot tient à la persistance, aux outils et aux handoffs. Les leçons 4 à 7 ont rendu ces objets manipulables : créer et configurer des agents avec client.beta.agents.create(), tenir des conversations persistantes avec conversations.start() et conversations.append(), et recourir au mode direct sans agent quand vous prototypez et que la persistance n’apporte rien.

Les leçons 8 à 11 ont ajouté les capacités. web_search ouvre l’accès à l’information actuelle avec citations automatiques ; code_interpreter exécute du Python dans un sandbox et donne à l’agent des résultats exacts là où le modèle seul approximerait ; image_generation produit des visuels à partir de prompts textuels ; document_library apporte un RAG intégré sur vos propres documents. Les leçons 12 à 16 ont ensuite fait travailler plusieurs agents ensemble : les handoffs transfèrent le contrôle d’un agent à un autre, l’architecture de référence associe un routeur central à des spécialistes, le mode serveur automatise là où le mode client vous rend la main, et le chaînage illimité se décline en patterns linéaire, étoile et hybride. La leçon 17, enfin, a encadré tout cela par les guardrails, le principe du moindre privilège et la modération en amont.

Concevoir des agents qui tiennent

La règle qui condense tout le cours tient en une phrase : un agent, une responsabilité, une description qui dit quand l’appeler. Le contraste ci-dessous rend l’écart tangible.

# BON — agent spécialisé avec description précise
agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="invoice-processor",
    description="Traite les factures : extraction de montants, dates, fournisseurs.",
    instructions="Extraire les informations des factures au format JSON structuré.",
    tools=[{"type": "document_library", "library_ids": [invoices_lib.id]}]
)

# MAUVAIS — agent générique et vague
agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="helper",
    description="Un agent utile.",
    tools=[{"type": "web_search"}, {"type": "code_interpreter"}, {"type": "image_generation"}]
)

Le second agent échouera de deux manières à la fois. Aucun routeur ne saura quand lui transférer une requête, puisque « un agent utile » ne décrit aucune situation. Et lorsqu’il sera sollicité, ses trois outils lui laisseront le choix d’aller chercher sur le web ce qu’il aurait dû calculer, ou d’illustrer ce qu’on lui demandait d’analyser.

Encaisser les erreurs

Un appel réseau échoue tôt ou tard. Une reprise avec temporisation croissante suffit à absorber les incidents passagers sans transformer un ralentissement momentané en panne visible.

import time

def safe_conversation(agent_id, query, max_retries=3):
    """Conversation avec gestion d'erreurs et retry."""
    for attempt in range(max_retries):
        try:
            response = client.beta.conversations.start(
                agent_id=agent_id,
                inputs=query
            )
            return response
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Backoff exponentiel
    return None

Le backoff exponentiel — une seconde, puis deux, puis quatre — distingue une reprise civilisée d’un acharnement qui ne fait qu’alourdir un service déjà en difficulté. Notez aussi que la dernière tentative relance l’exception plutôt que de retourner None : votre appelant doit savoir que l’opération a échoué.

Voir ce qui se passe

En production, un workflow multi-agents dont vous n’observez rien devient indéboguable. Le mode client offre exactement les points d’accroche nécessaires.

import logging
import time

logger = logging.getLogger("agents")

def monitored_conversation(agent_id, query):
    """Conversation avec monitoring."""
    start = time.time()

    response = client.beta.conversations.start(
        agent_id=agent_id,
        inputs=query,
        handoff_execution="client"
    )

    handoff_count = 0
    tool_count = 0

    for entry in response.outputs:
        if entry.type == "agent.handoff":
            handoff_count += 1
            logger.info(f"Handoff #{handoff_count}: → {entry.to_agent}")
        elif entry.type == "tool.execution":
            tool_count += 1
            logger.info(f"Tool #{tool_count}: {entry.tool_name}")

    duration = time.time() - start
    logger.info(f"Terminé en {duration:.1f}s — {handoff_count} handoffs, {tool_count} outils")

    return response

Les deux compteurs valent plus que leur simplicité ne le suggère : une dérive du nombre moyen de handoffs signale un routeur qui hésite, une explosion du nombre d’outils désigne les requêtes qui coûtent cher.

La maîtrise des coûts se joue ensuite sur des décisions concrètes. Surveillez le nombre de tokens par conversation, puisque c’est l’unité de facturation réelle. Utilisez mistral-medium-latest partout où mistral-large-latest n’apporte rien — le premier niveau d’un support en est l’exemple type. Bornez max_tokens dans les completion_args pour éviter les réponses interminables sur des questions simples, et désactivez le stockage avec store=False quand la persistance n’est pas requise.

Tester le routage

Un système multi-agents se teste comme n’importe quel aiguillage : on lui soumet des cas dont on connaît la destination attendue et on vérifie où ils atterrissent.

def test_agent_routing():
    """Vérifie que le routeur distribue correctement."""
    test_cases = [
        ("Quel est le cours du Bitcoin ?", "web-search-agent"),
        ("Calcule 25 * 48", "calculator-agent"),
        ("Résume ce document", "doc-agent"),
    ]

    for query, expected_agent_name in test_cases:
        response = client.beta.conversations.start(
            agent_id=router.id,
            inputs=query,
            handoff_execution="client"
        )

        for entry in response.outputs:
            if entry.type == "agent.handoff":
                target = client.beta.agents.retrieve(agent_id=entry.to_agent)
                assert target.name == expected_agent_name, \
                    f"Routage incorrect pour '{ query}': {target.name} au lieu de {expected_agent_name}"

Constituez ce jeu de cas au fil de l’eau : chaque mauvais aiguillage constaté en production devient une ligne de plus dans test_cases, et vous saurez qu’une reformulation de description corrige le cas visé sans en casser un autre.

Architecture de référence

Pour un projet de production, voici une architecture recommandée :

Application
    │
    ▼
Agent Modérateur (filtre les requêtes)
    │
    ▼
Agent Routeur (distribue aux spécialistes)
    ├── Agent Recherche (web_search)
    ├── Agent Analyse (code_interpreter)
    ├── Agent Documents (document_library)
    └── Agent Création (image_generation)
    │
    ▼
Logging + Monitoring + Alerting

Elle réunit tout le cours : le modérateur filtre avant toute exécution, le routeur aiguille sans jamais répondre lui-même, les spécialistes portent chacun un outil et une responsabilité, et l’observation enveloppe l’ensemble.

Pour aller plus loin

Quatre directions prolongent ce que vous savez faire. Le function calling vous permet de créer vos propres outils custom au-delà des built-in : appeler une API métier, interroger une base de données, déclencher un service interne. Les MCP Servers intègrent le protocole Model Context Protocol, qui standardise la mise à disposition d’outils. Les structured outputs forcent les réponses au format JSON schema, ce qui change tout dès que la sortie d’un agent alimente un autre système plutôt qu’un lecteur humain. Le streaming, enfin, restitue les réponses en temps réel plutôt qu’en bloc — décisif sur les chaînes longues, où l’attente silencieuse devient inconfortable.

Trois ressources accompagnent cette suite : la documentation officielle sur docs.mistral.ai/agents, les cookbooks Mistral qui donnent des exemples d’implémentation complets, et l’API Référence qui documente chaque endpoint en détail.

Points clés à retenir

• Spécialisez vos agents — un agent = une responsabilité
• Monitorez — loggez chaque handoff et exécution d’outil
• Testez — validez le routage et les réponses de chaque agent
• Sécurisez — guardrails, moindre privilège, modération en amont
• Optimisez les coûts — modèle adapté, max_tokens, store=False quand possible
• Les agents Mistral sont en beta — suivez les évolutions de l’API

Testez vos connaissances

Agents, outils intégrés, handoffs : l’API Agents n’a plus de zones d’ombre ?

1. Quand un agent est-il nécessaire — et quand un chatbot suffit-il ?

Réponse : L’agent se justifie quand il faut des outils, de la persistance et des décisions multi-étapes ; pour du question-réponse simple, une conversation classique suffit — l’architecture suit le besoin.

2. Que gèrent les conversations persistantes de l'API Agents ?

Réponse : L’historique côté Mistral : on poursuit une conversation par son identifiant sans renvoyer tout le contexte — l’état devient un service.

3. Citez les outils intégrés disponibles et leur usage.

Réponse : web_search (informations en temps réel), code_interpreter (exécuter du Python), image_generation (créer des images), document_library (QnA sur vos fichiers) — des capacités prêtes à l’emploi, sans implémentation.

4. Comment fonctionne un système multi-agents avec handoffs ?

Réponse : Un routeur qualifie la demande et la transmet à l’agent spécialisé compétent ; chaque agent reste simple, l’orchestration fait la couverture — et les handoffs se chaînent en profondeur.

5. Comment sécurise-t-on des agents en production ?

Réponse : Par des guardrails sur les entrées/sorties, des outils au périmètre limité, la traçabilité des actions et des validations humaines sur ce qui engage — l’autonomie se mérite par le contrôle.

Agents spécialisés, outils intégrés, routage, garde-fous : l’architecture complète tient en quatre mots — et le cours vous a fait construire chacun.