RunContext : Gérer le Client MCP et l'Agent

Le rôle central du RunContext

Le RunContext est le composant qui orchestre la communication entre votre agent IA et les serveurs MCP. Il gère le cycle de vie complet : connexion aux serveurs, enregistrement des tools, exécution des conversations et récupération des résultats.

Dans le SDK Mistral, le RunContext est un context manager asynchrone qui encapsule toute la logique d’interaction.

Créer un agent avec le SDK Mistral

Avant d’utiliser le RunContext, vous devez créer un agent via l’API :

from mistralai import Mistral

# Initialiser le client Mistral
client = Mistral(api_key="VOTRE_CLE_API")

# Créer un agent
agent = client.beta.agents.create(
    model="mistral-medium-latest",
    name="assistant-mcp",
    instructions="Vous êtes un assistant capable d utiliser des outils MCP.",
)

print(f"Agent créé : {agent.id}")

L’agent est une entité persistante côté Mistral. Il a un modèle, un nom, et des instructions système. Les tools MCP seront enregistrés dynamiquement via le RunContext.

Initialiser le RunContext

Le RunContext s’utilise comme un context manager async with :

from mistralai.extra.run.context import RunContext
from pydantic import BaseModel

# Optionnel : définir un format de sortie structuré
class WeatherResult(BaseModel):
    location: str
    temperature: float
    description: str

async with RunContext(
    agent_id=agent.id,
    output_format=WeatherResult,      # Format structuré (optionnel)
    continue_on_fn_error=True,         # Continuer si un tool échoue
) as run_ctx:
    # Ici, on enregistre les clients MCP et on lance les conversations
    pass

Les paramètres du RunContext

• agent_id : l’identifiant de l’agent créé précédemment
• output_format : un modèle Pydantic pour structurer la réponse finale (optionnel)
• continue_on_fn_error : si True, le contexte ne s’arrête pas quand un tool échoue — le modèle reçoit l’erreur et peut adapter sa stratégie

Enregistrer un client MCP

Une fois le RunContext initialisé, vous enregistrez vos clients MCP :

from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO

# Configurer le serveur local
server_params = StdioServerParameters(
    command="python",
    args=["serveur_meteo.py"],
)
mcp_client = MCPClientSTDIO(stdio_params=server_params)

async with RunContext(
    agent_id=agent.id,
    continue_on_fn_error=True,
) as run_ctx:
    # Enregistrer le client MCP
    await run_ctx.register_mcp_client(mcp_client=mcp_client)

L’appel register_mcp_client :

1. Lance le processus du serveur MCP (en mode STDIO)
2. Effectue la négociation des capabilities
3. Récupère la liste des tools disponibles
4. Les rend accessibles au modèle lors des conversations

Vous pouvez enregistrer plusieurs clients MCP dans le même RunContext :

async with RunContext(agent_id=agent.id) as run_ctx:
    await run_ctx.register_mcp_client(mcp_client=mcp_client_meteo)
    await run_ctx.register_mcp_client(mcp_client=mcp_client_github)
    await run_ctx.register_mcp_client(mcp_client=mcp_client_calendar)

Enregistrer des fonctions locales

En plus des tools MCP, vous pouvez enregistrer des fonctions Python locales directement dans le RunContext :

import random

async with RunContext(agent_id=agent.id) as run_ctx:
    await run_ctx.register_mcp_client(mcp_client=mcp_client)

    @run_ctx.register_func
    def get_user_location(username: str) -> str:
        """Récupère la localisation d un utilisateur.

        Args:
            username: Le nom d utilisateur

        Returns:
            La ville de l utilisateur
        """
        locations = {"alice": "Paris", "bob": "Lyon", "charlie": "Marseille"}
        return locations.get(username, "Inconnue")

Ces fonctions locales sont traitées comme des tools par le modèle. La différence : elles s’exécutent dans votre processus Python, pas via un serveur MCP externe.

Lancer une conversation

Une fois le contexte configuré, lancez la conversation :

async with RunContext(agent_id=agent.id) as run_ctx:
    await run_ctx.register_mcp_client(mcp_client=mcp_client)

    # Exécution synchrone (attend la réponse complète)
    run_result = await client.beta.conversations.run_async(
        run_ctx=run_ctx,
        inputs="Quelle est la météo à Paris ?",
    )

    print(run_result.output)

Le modèle va :

1. Analyser la question
2. Consulter les tools disponibles (MCP + fonctions locales)
3. Appeler les tools nécessaires
4. Formuler la réponse avec les résultats

Le cycle de vie complet

1. Créer l agent (client.beta.agents.create)
       ↓
2. Ouvrir le RunContext (async with RunContext)
       ↓
3. Enregistrer les clients MCP (register_mcp_client)
       ↓
4. Enregistrer les fonctions locales (register_func)
       ↓
5. Lancer les conversations (conversations.run_async)
       ↓
6. Fermeture automatique (fin du context manager)

À la fermeture du RunContext, tous les processus serveur STDIO sont arrêtés proprement.

Gestion des erreurs

Le paramètre continue_on_fn_error=True est essentiel en production. Sans lui, une erreur dans un tool arrête toute la conversation. Avec, le modèle reçoit le message d’erreur et peut :

• Reformuler sa requête
• Utiliser un autre tool
• Informer l’utilisateur du problème

Points clés à retenir

• Le RunContext orchestre la communication agent ↔ serveurs MCP
• Il s’utilise comme context manager async with
• register_mcp_client connecte un serveur MCP et découvre ses tools
• register_func enregistre des fonctions Python locales comme tools
• continue_on_fn_error=True assure la résilience de votre agent
• Tout le workflow est asynchrone (async/await)