RunContext : Gérer le client MCP et l'agent
Šiame puslapyje
Le chef d’orchestre de ton agent
Le RunContext est le composant qui maintient l’ensemble cohérent. Il connecte ton 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. Tu ouvres un bloc, tu déclares ce que l’agent est autorisé à utiliser, tu mènes ta conversation, et tout se ferme automatiquement lorsque tu sors du bloc.
Créer l’agent
Le RunContext ne crée pas l’agent ; il s’y attache. Ta 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 ton 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 te permet d’exécuter le même agent avec différents outils selon le contexte.
Ouvrir le contexte
Tu utilises RunContext avec async with, ce qui garantit la libération des ressources même si une exception survient.
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, enregistre les clients MCP et lance les conversations
pass
Trois paramètres contrôlent ce comportement. agent_id spécifie l’agent que tu as 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 continue et le modèle reçoit le message d’erreur comme s’il s’agissait d’un résultat normal.
Enregistrer un client MCP
Une fois le contexte ouvert, tu déclares tes clients MCP à l’intérieur.
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 à disposition de ces outils pour le modèle lors des prochaines conversations. Tu n’as pas besoin d’écrire tout cela à la main.
Tu n’es 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 est pour toi : ces fonctions s’exécutent dans ton processus Python, sans serveur externe, elles 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 ressemble à ceci :
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 tu sors 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 l’erreur clairement 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.
Svarbiausi punktai
- Le RunContext orchestre la communication entre l’agent et les serveurs MCP
- Utilise-le comme un 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 ton agent- L’intégralité du flux de travail est asynchrone (async/await)