RunContext: gestión del cliente MCP y del agente
En esta página
El director de orquesta de tu agente
El RunContext es el componente que mantiene todo unido. Conecta tu agente de IA con los servidores MCP y gestiona todo su ciclo de vida: conexión a los servidores, registro de herramientas, ejecución de conversaciones, obtención de resultados y cierre limpio. En el SDK de Mistral, adopta la forma de un gestor de contexto asíncrono que encapsula toda esta lógica. Abres un bloque, declaras qué puede usar el agente, mantienes tu conversación y todo se cierra automáticamente al salir.
Crear el agente
El RunContext no crea el agente; se acopla a uno existente. Por tanto, tu primer paso es instanciar un agente mediante la API.
from mistralai.client import Mistral
# Inicializar el cliente de Mistral
client = Mistral(api_key="YOUR_API_KEY")
# Crear un agente
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}")
Este agente es una entidad persistente en el lado de Mistral: tiene un modelo, un nombre e instrucciones del sistema, y sobrevive más allá de la ejecución de tu script. Sin embargo, las herramientas MCP no están vinculadas al agente. En su lugar, el RunContext las proporciona dinámicamente en cada ejecución. Este desacoplamiento te permite ejecutar el mismo agente con distintas herramientas según el contexto.
Abrir el contexto
Utilizas RunContext con async with, lo que garantiza la liberación de recursos incluso si se produce una excepción.
from mistralai.extra.run.context import RunContext
from pydantic import BaseModel
# Opcional: definir un formato de salida estructurado
class WeatherResult(BaseModel):
location: str
temperature: float
description: str
async with RunContext(
agent_id=agent.id,
output_format=WeatherResult, # Formato estructurado (opcional)
continue_on_fn_error=True, # Continuar si falla una herramienta
) as run_ctx:
# Aquí, registrar clientes MCP e iniciar conversaciones
pass
Tres parámetros controlan este comportamiento. agent_id especifica el agente que has creado anteriormente. output_format acepta un modelo Pydantic y restringe la respuesta final a esa estructura, algo valioso cuando la salida alimenta otro programa en lugar de a un humano. Por último, continue_on_fn_error decide qué ocurre con la conversación cuando una herramienta lanza un error: si se establece en True, el contexto continúa y el modelo recibe el mensaje de error igual que si fuera un resultado.
Registrar un cliente MCP
Una vez abierto el contexto, declaras tus clientes MCP dentro de él.
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
# Configurar el servidor 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:
# Registrar el cliente MCP
await run_ctx.register_mcp_client(mcp_client=mcp_client)
Esta única llamada a register_mcp_client desencadena una secuencia completa: lanzamiento del proceso del servidor en modo STDIO, negociación de capacidades, obtención de la lista de herramientas y puesta a disposición de dichas herramientas para el modelo en las próximas conversaciones. No necesitas escribir nada de esto manualmente.
Tampoco estás limitado a un único servidor. Un solo RunContext puede agregar múltiples fuentes, y el modelo ve la unión de sus herramientas como un único catálogo:
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)
Añadir funciones locales
No todas las capacidades necesitan convertirse en un servidor MCP. Para una función breve específica de este script, el decorador register_func es suficiente para exponerla al modelo como una herramienta estándar.
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")
Desde la perspectiva del modelo, no hay diferencia: simplemente ve una herramienta más. La diferencia radica en ti: estas funciones se ejecutan en tu proceso de Python, sin un servidor externo, por lo que no son reutilizables fuera de este script.
Iniciar la conversación
Una vez poblado el contexto, solo queda hablar.
async with RunContext(agent_id=agent.id) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
# Ejecución síncrona (espera la respuesta completa)
run_result = await client.beta.conversations.run_async(
run_ctx=run_ctx,
inputs="What is the weather in Paris?",
)
print(run_result.output)
Detrás de esta llamada, el modelo analiza la pregunta, consulta las herramientas disponibles (tanto de servidores MCP como de funciones locales), invoca las que considera necesarias y redacta su respuesta basándose en los resultados obtenidos.
Todo el ciclo tiene este aspecto:
1. Crear el agente (client.beta.agents.create)
↓
2. Abrir el RunContext (async with RunContext)
↓
3. Registrar clientes MCP (register_mcp_client)
↓
4. Registrar funciones locales (register_func)
↓
5. Iniciar conversaciones (conversations.run_async)
↓
6. Limpieza automática (fin del gestor de contexto)
Al salir del bloque, el contexto detiene todos los procesos de servidor STDIO que ha lanzado: no quedan procesos de Python huérfanos colgados tras una excepción.
Una última palabra sobre continue_on_fn_error=True, cuyo valor resulta más evidente en producción. Sin él, el más mínimo error en una herramienta interrumpe toda la conversación, dejando al usuario frente a una excepción. Con él, el modelo recibe el error claramente y tiene margen de maniobra: puede reformular su solicitud con argumentos distintos, recurrir a otra herramienta o simplemente explicar al usuario qué ha fallado. Un agente que dice «el servicio meteorológico no responde» es infinitamente mejor que un agente que se bloquea.
Puntos clave
- El RunContext orquesta la comunicación entre el agente y los servidores MCP
- Úsalo como un gestor de contexto
async with register_mcp_clientconecta un servidor MCP y descubre sus herramientasregister_funcregistra funciones locales de Python como herramientascontinue_on_fn_error=Truegarantiza la resiliencia de tu agente- Todo el flujo de trabajo es asíncrono (async/await)