RunContext: Správa klienta MCP a agenta
Na tejto strane
Dirigent tvojho agenta
RunContext je komponent, ktorý drží všetko pohromade. Spája tvojho AI agenta so servermi MCP a spravuje ich celý životný cyklus: pripojenie k serverom, registráciu nástrojov, vykonávanie konverzácií, získavanie výsledkov a korektné vypnutie. V Mistral SDK má formu asynchrónneho správcu kontextu, ktorý zapuzdruje celú túto logiku. Otvoríš blok, deklaruješ, čo môže agent používať, vedieš konverzáciu a po ukončení bloku sa všetko automaticky uzavrie.
Vytvorenie agenta
RunContext nevytvára agenta; pripája sa k nemu. Tvojím prvým krokom je preto vytvorenie inštancie agenta prostredníctvom API.
from mistralai.client import Mistral
# Inicializácia klienta Mistral
client = Mistral(api_key="YOUR_API_KEY")
# Vytvorenie 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 strane Mistral: má model, meno a systémové inštrukcie a prežíva aj po skončení tvojho skriptu. Nástroje MCP však nie sú k agentovi pripojené natrvalo. Namiesto toho ich RunContext poskytuje dynamicky pri každom spustení. Toto oddelenie ti umožňuje spúšťať toho istého agenta s rôznymi nástrojmi v závislosti od kontextu.
Otvorenie kontextu
RunContext používaš pomocou async with, čo zaručuje uvoľnenie zdrojov aj v prípade výnimky.
from mistralai.extra.run.context import RunContext
from pydantic import BaseModel
# Voliteľné: definovanie štruktúrovaného formátu výstupu
class WeatherResult(BaseModel):
location: str
temperature: float
description: str
async with RunContext(
agent_id=agent.id,
output_format=WeatherResult, # Štruktúrovaný formát (voliteľné)
continue_on_fn_error=True, # Pokračovať, ak nástroj zlyhá
) as run_ctx:
# Tu zaregistruješ klientov MCP a spustíš konverzácie
pass
Toto správanie riadia tri parametre. agent_id určuje agenta, ktorého si predtým vytvoril. output_format akceptuje model Pydantic a obmedzuje konečnú odpoveď na túto štruktúru – čo je cenné, keď výstup slúži ako vstup pre iný program, nie pre človeka. Nakoniec, continue_on_fn_error rozhoduje, čo sa stane s konverzáciou, keď nástroj vyhodí chybu: ak je nastavené na True, kontext pokračuje a model dostane chybovú správu rovnako ako bežný výsledok.
Registrácia klienta MCP
Akonáhle je kontext otvorený, deklarujesz v ňom svojich klientov MCP.
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
# Konfigurácia lokálneho servera
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:
# Registrácia klienta MCP
await run_ctx.register_mcp_client(mcp_client=mcp_client)
Toto jediné volanie register_mcp_client spustí kompletnú sekvenciu: spustenie procesu servera v režime STDIO, vyjednanie schopností, získanie zoznamu nástrojov a sprístupnenie týchto nástrojov modelu pre nadchádzajúce konverzácie. Nič z toho nemusíš písať ručne.
Nie si obmedzený len na jeden server. Jeden RunContext môže agregovať viacero zdrojov a model vidí zjednotenie ich nástrojov ako jeden katalóg:
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)
Pridanie lokálnych funkcií
Nie každá schopnosť musí byť serverom MCP. Pre krátku funkciu špecifickú pre tento skript stačí dekorátor register_func, ktorý ju exponuje modelu ako štandardný 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 pohľadu modelu nie je žiadny rozdiel: vidí len ďalší nástroj. Rozdiel je pre teba – tieto funkcie bežia priamo v tvojom procese Python, bez externého servera, takže nie sú opätovne použiteľné mimo tohto skriptu.
Spustenie konverzácie
Akonáhle je kontext naplnený, zostáva už len komunikovať.
async with RunContext(agent_id=agent.id) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
# Synchronné vykonanie (čaká na úplnú odpoveď)
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 volaním model analyzuje otázku, konzultuje dostupné nástroje – či už zo serverov MCP alebo lokálnych funkcií – zavolá tie, ktoré považuje za potrebné, a následne na základe získaných výsledkov zostaví svoju odpoveď.
Celý cyklus vyzerá takto:
1. Vytvorenie agenta (client.beta.agents.create)
↓
2. Otvorenie RunContext (async with RunContext)
↓
3. Registrácia klientov MCP (register_mcp_client)
↓
4. Registrácia lokálnych funkcií (register_func)
↓
5. Spustenie konverzácií (conversations.run_async)
↓
6. Automatické vyčistenie (koniec správcu kontextu)
Keď opustíš blok, kontext zastaví všetky procesy serverov STDIO, ktoré spustil – po výnimke nezostanú visieť žiadne osirelé procesy Python.
Ešte jedna poznámka k continue_on_fn_error=True, ktorej hodnota je najviac viditeľná v produkcii. Bez neho aj tá najmenšia chyba v nástroji preruší celú konverzáciu a používateľ zostane hľadieť na výnimku. S ním model dostane chybu jasne a má priestor na manéver: môže preformulovať svoju požiadavku s inými argumentmi, použiť iný nástroj alebo jednoducho používateľovi vysvetliť, čo zlyhalo. Agent, ktorý povie „služba počasia neodpovedá“, je nekonečne lepší ako agent, ktorý spadne.
Kľúčové poznatky
- RunContext orchestruje komunikáciu medzi agentom a servermi MCP
- Používaj ho ako správcu kontextu
async with register_mcp_clientpripojí server MCP a objaví jeho nástrojeregister_funczaregistruje lokálne funkcie Python ako nástrojecontinue_on_fn_error=Truezabezpečuje odolnosť tvojho agenta- Celý pracovný postup je asynchrónny (async/await)