RunContext: Håndtér MCP-klienten og agenten
På denne side
Dirigenten for din agent
RunContext er den komponent, der holder det hele sammen. Den forbinder din AI-agent med MCP-servere og styrer hele deres livscyklus: oprettelse af forbindelse til servere, registrering af værktøjer, udførelse af samtaler, hentning af resultater og pæn nedlukning. I Mistral SDK tager den form af en asynkron kontekststyring (context manager), der kapsler al denne logik. Du åbner en blok, erklærer hvad agenten må bruge, fører din samtale, og alt lukkes automatisk, når du forlader blokken.
Opret agenten
RunContext opretter ikke agenten; den kobler sig til en eksisterende. Dit første skridt er derfor at instantiere en agent via API’et.
from mistralai.client import Mistral
# Initialiser Mistral-klienten
client = Mistral(api_key="YOUR_API_KEY")
# Opret en 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}")
Denne agent er en vedvarende enhed på Mistral-siden: den har en model, et navn og systeminstruktioner, og den overlever ud over dit script. MCP-værktøjer er derimod ikke knyttet til agenten. I stedet leverer RunContext dem dynamisk ved hver kørsel. Denne afkobling giver dig mulighed for at køre den samme agent med forskellige værktøjer afhængigt af konteksten.
Åbn konteksten
Du bruger RunContext med async with, hvilket garanterer frigivelse af ressourcer, selv hvis der opstår en undtagelse.
from mistralai.extra.run.context import RunContext
from pydantic import BaseModel
# Valgfrit: definer et struktureret outputformat
class WeatherResult(BaseModel):
location: str
temperature: float
description: str
async with RunContext(
agent_id=agent.id,
output_format=WeatherResult, # Struktureret format (valgfrit)
continue_on_fn_error=True, # Fortsæt hvis et værktøj fejler
) as run_ctx:
# Her registreres MCP-klienter og samtaler startes
pass
Tre parametre styrer denne adfærd. agent_id specificerer den agent, du oprettede tidligere. output_format accepterer en Pydantic-model og begrænser det endelige svar til denne struktur – værdifuldt når outputtet skal bruges af et andet program snarere end et menneske. Endelig bestemmer continue_on_fn_error, hvad der sker med samtalen, når et værktøj kaster en fejl: hvis sat til True, fortsætter konteksten, og modellen modtager fejlmeddelelsen præcis som om det var et resultat.
Registrer en MCP-klient
Når konteksten er åben, deklarerer du dine MCP-klienter inden i den.
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
# Konfigurer den lokale server
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:
# Registrer MCP-klienten
await run_ctx.register_mcp_client(mcp_client=mcp_client)
Dette ene kald til register_mcp_client udløser en komplet sekvens: start af serverprocessen i STDIO-tilstand, forhandling af kapaciteter, hentning af listen over værktøjer og tilgængeliggørelse af disse værktøjer for modellen til kommende samtaler. Du behøver ikke skrive noget af dette manuelt.
Du er heller ikke begrænset til en enkelt server. En enkelt RunContext kan aggregere flere kilder, og modellen ser foreningen af deres værktøjer som én enkelt katalog:
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)
Tilføj lokale funktioner
Ikke enhver funktionsevne behøver at blive til en MCP-server. For en kort funktion specifik for dette script er dekoreratoren register_func nok til at eksponere den for modellen som et standardværktøj.
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")
Fra modellens perspektiv er der ingen forskel: den ser blot endnu et værktøj. Forskellen er for dig – disse funktioner kører i din Python-proces uden en ekstern server, så de er ikke genanvendelige uden for dette script.
Start samtalen
Når konteksten er befolket, er alt der resterer at tale.
async with RunContext(agent_id=agent.id) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
# Synkron eksekvering (venter på det fulde svar)
run_result = await client.beta.conversations.run_async(
run_ctx=run_ctx,
inputs="What is the weather in Paris?",
)
print(run_result.output)
Bag dette kald analyserer modellen spørgsmålet, konsulterer de tilgængelige værktøjer – både fra MCP-servere og lokale funktioner – kalder dem, den finder nødvendige, og udarbejder derefter sit svar baseret på de opnåede resultater.
Hele cyklussen ser sådan ud:
1. Opret agenten (client.beta.agents.create)
↓
2. Åbn RunContext (async with RunContext)
↓
3. Registrer MCP-klienter (register_mcp_client)
↓
4. Registrer lokale funktioner (register_func)
↓
5. Start samtaler (conversations.run_async)
↓
6. Automatisk oprydning (slutningen af kontekststyringen)
Når du forlader blokken, stopper konteksten alle STDIO-serverprocesser, den har lanceret – ingen forældreløse Python-processer hænger tilbage efter en undtagelse.
Et sidste ord om continue_on_fn_error=True, hvis værdi er mest tydelig i produktion. Uden den vil den mindste fejl i et værktøj afbryde hele samtalen og efterlade brugeren stirrende på en undtagelse. Med den modtager modellen fejlen tydeligt og har spillerum: den kan omformulere sin anmodning med andre argumenter, falde tilbage på et andet værktøj eller simpelthen forklare brugeren, hvad der gik galt. En agent, der siger „vejr-tjenesten svarer ikke”, er uendeligt bedre end en agent, der crascher.
Vigtige pointer
- RunContext orchestrerer kommunikationen mellem agenten og MCP-servere
- Brug den som en
async withkontekststyring register_mcp_clientforbinder en MCP-server og opdager dens værktøjerregister_funcregistrerer lokale Python-funktioner som værktøjercontinue_on_fn_error=Truesikrer din agents robusthed- Hele workflowet er asynkront (async/await)