RunContext: Gestion du client MCP et de l'agent
Pe această pagină
Le chef d’orchestre de votre agent
Le RunContext est le composant qui assure la cohésion de l’ensemble. Il connecte votre agent IA aux serveurs MCP et gère leur cycle de vie complet : connexion aux serveurs, enregistrement des outils, exécution des conversations, récupération des résultats et arrêt propre. Dans le SDK Mistral, il se présente sous la forme d’un gestionnaire de contexte asynchrone qui encapsule toute cette logique. Vous ouvrez un bloc, déclarez ce que l’agent est autorisé à utiliser, menez votre conversation, et tout se ferme automatiquement à la sortie.
Créer l’agent
Le RunContext ne crée pas l’agent ; il s’y attache. Votre première étape consiste donc à instancier un agent via l’API.
from mistralai.client import Mistral
# Initialiser le client Mistral
client = Mistral(api_key="YOUR_API_KEY")
# Créer un agent
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="assistant-mcp",
instructions="You are an assistant capable of using MCP tools.",
)
print(f"Agent created: {agent.id}")
Cet agent est une entité persistante côté Mistral : il possède un modèle, un nom et des instructions système, et il survit au-delà de votre script. Les outils MCP, en revanche, ne sont pas attachés à l’agent. C’est le RunContext qui les fournit dynamiquement à chaque exécution. Ce découplage vous permet d’exécuter le même agent avec différents outils selon le contexte.
Ouvrir le contexte
Vous utilisez RunContext avec async with, ce qui garantit la libération des ressources même en cas d’exception.
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 outil échoue
) as run_ctx:
# Ici, enregistrez les clients MCP et démarrez les conversations
pass
Trois paramètres contrôlent ce comportement. agent_id spécifie l’agent que vous avez créé précédemment. output_format accepte un modèle Pydantic et contraint la réponse finale à cette structure, ce qui est précieux lorsque la sortie alimente un autre programme plutôt qu’un humain. Enfin, continue_on_fn_error décide du sort de la conversation lorsqu’un outil lève une erreur : s’il est défini sur True, le contexte se poursuit et le modèle reçoit le message d’erreur comme s’il s’agissait d’un résultat.
Enregistrer un client MCP
Une fois le contexte ouvert, vous y déclarez vos clients MCP.
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
# Configurer le serveur local
server_params = StdioServerParameters(
command="python",
args=["weather_server.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)
Cet unique appel à register_mcp_client déclenche une séquence complète : lancement du processus serveur en mode STDIO, négociation des capacités, récupération de la liste des outils et mise de ces outils à disposition du modèle pour les conversations à venir. Vous n’avez rien à écrire manuellement pour cela.
Vous n’êtes pas non plus limité à un seul serveur. Un seul RunContext peut agréger plusieurs sources, et le modèle voit l’union de leurs outils comme un catalogue unique :
async with RunContext(agent_id=agent.id) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client_weather)
await run_ctx.register_mcp_client(mcp_client=mcp_client_github)
await run_ctx.register_mcp_client(mcp_client=mcp_client_calendar)
Ajouter des fonctions locales
Toute capacité n’a pas besoin de devenir un serveur MCP. Pour une fonction courte spécifique à ce script, le décorateur register_func suffit à l’exposer au modèle comme un outil standard.
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:
"""Retrieves a user's location.
Args:
username: The username
Returns:
The user's city
"""
locations = {"alice": "Paris", "bob": "Lyon", "charlie": "Marseille"}
return locations.get(username, "Unknown")
Du point de vue du modèle, il n’y a aucune différence : il voit simplement un outil de plus. La différence réside pour vous dans le fait que ces fonctions s’exécutent dans votre processus Python, sans serveur externe, et ne sont donc pas réutilisables en dehors de ce script.
Démarrer la conversation
Une fois le contexte peuplé, il ne reste plus qu’à dialoguer.
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="What is the weather in Paris?",
)
print(run_result.output)
Derrière cet appel, le modèle analyse la question, consulte les outils disponibles (tant ceux des serveurs MCP que les fonctions locales), appelle ceux qu’il juge nécessaires, puis rédige sa réponse sur la base des résultats obtenus.
Le cycle complet se présente ainsi :
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. Démarrer les conversations (conversations.run_async)
↓
6. Nettoyage automatique (fin du gestionnaire de contexte)
Lorsque vous sortez du bloc, le contexte arrête tous les processus serveur STDIO qu’il a lancés : aucun processus Python orphelin ne reste suspendu après une exception.
Un dernier mot sur continue_on_fn_error=True, dont la valeur est particulièrement apparente en production. Sans lui, la moindre erreur dans un outil interrompt toute la conversation, laissant l’utilisateur face à une exception. Avec lui, le modèle reçoit clairement l’erreur et dispose d’une marge de manœuvre : il peut reformuler sa demande avec d’autres arguments, se rabattre sur un autre outil, ou simplement expliquer à l’utilisateur ce qui a échoué. Un agent qui dit « le service météo ne répond pas » est infiniment préférable à un agent qui plante.
Puncte cheie
- Le RunContext orchestre la communication entre l’agent et les serveurs MCP
- Utilisez-le comme gestionnaire de contexte
async with register_mcp_clientconnecte un serveur MCP et découvre ses outilsregister_funcenregistre des fonctions Python locales en tant qu’outilscontinue_on_fn_error=Trueassure la résilience de votre agent- L’intégralité du flux de travail est asynchrone (async/await)