RunContext: Správa klienta MCP a agenta
Na této stránce
Dirigent tvého agenta
RunContext je komponenta, která drží vše pohromadě. Propojuje tvého AI agenta se servery MCP a spravuje jejich celý životní cyklus: připojení k serverům, registraci nástrojů, provádění konverzací, získávání výsledků a čisté ukončení. V Mistral SDK má podobu asynchronního správce kontextu, který zapouzdřuje veškerou tuto logiku. Otevřeš blok, deklarujete, co smí agent používat, provedeš konverzaci a při výstupu se vše automaticky uzavře.
Vytvoření agenta
RunContext agenta nevytváří; pouze se k němu připojí. Tvým prvním krokem je tedy vytvoření instance agenta prostřednictvím API.
from mistralai.client import Mistral
# Inicializace klienta Mistral
client = Mistral(api_key="YOUR_API_KEY")
# Vytvoření agenta
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}")
Tento agent je trvalou entitou na straně Mistral: má model, jméno a systémové instrukce a přežívá ukončení tvého skriptu. Nástroje MCP však nejsou k agentovi připojeny natrvalo. Místo toho je RunContext poskytuje dynamicky při každém spuštění. Toto oddělení ti umožňuje spouštět stejného agenta s různými nástroji v závislosti na kontextu.
Otevření kontextu
RunContext používáš s async with, což zaručí uvolnění zdrojů, i když dojde k výjimce.
from mistralai.extra.run.context import RunContext
from pydantic import BaseModel
# Volitelné: definování strukturovaného formátu výstupu
class WeatherResult(BaseModel):
location: str
temperature: float
description: str
async with RunContext(
agent_id=agent.id,
output_format=WeatherResult, # Strukturovaný formát (volitelné)
continue_on_fn_error=True, # Pokračovat, pokud nástroj selže
) as run_ctx:
# Zde registruj klienty MCP a spusť konverzace
pass
Toto chování řídí tři parametry. agent_id určuje agenta, kterého jsi vytvořil dříve. output_format přijímá model Pydantic a omezuje konečnou odpověď na tuto strukturu – což je cenné, když výstup zpracovává další program, nikoliv člověk. Nakonec continue_on_fn_error rozhoduje, co se stane s konverzací, když nástroj vyhodí chybu: pokud je nastaveno na True, kontext pokračuje a model obdrží chybovou zprávu stejně jako běžný výsledek.
Registrace klienta MCP
Jakmile je kontext otevřen, deklarujete v něm své klienty MCP.
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
# Konfigurace lokálního serveru
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:
# Registrace klienta MCP
await run_ctx.register_mcp_client(mcp_client=mcp_client)
Toto jediné volání register_mcp_client spustí kompletní sekvenci: spuštění procesu serveru v režimu STDIO, vyjednání schopností, získání seznamu nástrojů a zpřístupnění těchto nástrojů modelu pro nadcházející konverzace. Nic z toho nemusíš psát ručně.
Nejsi také omezen na jediný server. Jeden RunContext může agregovat více zdrojů a model vidí sjednocení jejich nástrojů jako jediný 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)
Přidání lokálních funkcí
Ne každá schopnost musí být serverem MCP. Pro krátkou funkci specifickou pro tento skript stačí dekorátor register_func, který ji exponuje modelu jako standardní nástroj.
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")
Z pohledu modelu není žádný rozdíl: vidí pouze jeden nástroj navíc. Rozdíl je pro tebe – tyto funkce běží v tvém Python procesu bez externího serveru, takže nejsou znovu použitelné mimo tento skript.
Spuštění konverzace
Jakmile je kontext naplněn, stačí již jen komunikovat.
async with RunContext(agent_id=agent.id) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
# Synchronní执行 (čeká na úplnou odpověď)
run_result = await client.beta.conversations.run_async(
run_ctx=run_ctx,
inputs="What is the weather in Paris?",
)
print(run_result.output)
Za tímto voláním model analyzuje otázku, konzultuje dostupné nástroje – jak ze serverů MCP, tak lokální funkce – zavolá ty, které považuje za nutné, a následně na základě získaných výsledků sestaví svou odpověď.
Celý cyklus vypadá takto:
1. Vytvoření agenta (client.beta.agents.create)
↓
2. Otevření RunContext (async with RunContext)
↓
3. Registrace klientů MCP (register_mcp_client)
↓
4. Registrace lokálních funkcí (register_func)
↓
5. Spuštění konverzací (conversations.run_async)
↓
6. Automatické čištění (konec správce kontextu)
Když opustíš blok, kontext zastaví všechny procesy serverů STDIO, které spustil – žádné osiřelé procesy Pythonu nezůstanou viset po výjimce.
Ještě poslední slovo k continue_on_fn_error=True, jehož hodnota je nejvíce patrná v produkci. Bez něj sebemenší chyba v nástroji přeruší celou konverzaci a uživatel zůstane hledět na výjimku. S ním model obdrží chybu jasně a má prostor pro manévr: může přeformulovat svůj požadavek s jinými argumenty, přejít na jiný nástroj, nebo jednoduše uživateli vysvětlit, co selhalo. Agent, který řekne „služba počasí neodpovídá“, je nekonečně lepší než agent, který spadne.
Klíčové poznatky
- RunContext orchestruje komunikaci mezi agentem a servery MCP
- Používej jej jako správce kontextu
async with register_mcp_clientpřipojí server MCP a objeví jeho nástrojeregister_funcregistruje lokální funkce Pythonu jako nástrojecontinue_on_fn_error=Truezajišťuje odolnost tvého agenta- Celý pracovní postup je asynchronní (async/await)