RunContext: Upravljanje MCP klijentom i agentom
Na ovoj stranici
Dirigent tvog agenta
RunContext je komponenta koja drži sve na okupu. Povezuje tvog AI agenta s MCP poslužiteljima i upravlja cijelim njihovim životnim ciklusom: spajanje na poslužitelje, registracija alata, izvršavanje razgovora, dohvaćanje rezultata i uredno gašenje. U Mistral SDK-u, on ima oblik asinkronog upravitelja konteksta (context manager) koji obuhvaća svu tu logiku. Otvaraš blok, deklariraš što agent smije koristiti, vodiš razgovor i sve se automatski zatvara kada izađeš iz bloka.
Kreiranje agenta
RunContext ne stvara agenta; on se na njega povezuje. Tvoj prvi korak je stoga instanciranje agenta putem API-ja.
from mistralai.client import Mistral
# Inicijaliziraj Mistral klijenta
client = Mistral(api_key="YOUR_API_KEY")
# Kreiraj 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}")
Ovaj agent je trajni entitet na strani Mistrala: ima model, ime i sistemske upute te opstaje izvan tvog skripta. MCP alati, međutim, nisu vezani uz agenta. Umjesto toga, RunContext ih osigurava dinamički pri svakom izvršavanju. Ovo odvajanje omogućuje ti pokretanje istog agenta s različitim alatima ovisno o kontekstu.
Otvaranje konteksta
RunContext koristiš s async with, što jamči oslobađanje resursa čak i ako dođe do iznimke.
from mistralai.extra.run.context import RunContext
from pydantic import BaseModel
# Opcionalno: definiranje strukturiranog formata izlaza
class WeatherResult(BaseModel):
location: str
temperature: float
description: str
async with RunContext(
agent_id=agent.id,
output_format=WeatherResult, # Strukturirani format (opcionalno)
continue_on_fn_error=True, # Nastavi ako alat zakaže
) as run_ctx:
# Ovdje registriraj MCP klijente i započni razgovore
pass
Tri parametra kontroliraju ovo ponašanje. agent_id specificira agenta kojeg si ranije kreirao. output_format prihvaća Pydantic model i ograničava konačni odgovor na tu strukturu – što je vrijedno kada izlaz napaja drugi program, a ne čovjeka. Konačno, continue_on_fn_error odlučuje što se događa s razgovorom kada alat podigne grešku: ako je postavljeno na True, kontekst se nastavlja i model prima poruku o grešci baš kao da je riječ o rezultatu.
Registracija MCP klijenta
Kada je kontekst otvoren, unutar njega deklariraš svoje MCP klijente.
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
# Konfiguriraj lokalni poslužitelj
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:
# Registriraj MCP klijenta
await run_ctx.register_mcp_client(mcp_client=mcp_client)
Ovaj jedan poziv register_mcp_client pokreće kompletan slijed: pokretanje procesa poslužitelja u STDIO načinu, pregovaranje o mogućnostima, dohvaćanje popisa alata i stavljanje tih alata na raspolaganje modelu za nadolazeće razgovore. Ne moraš ništa od ovoga pisati ručno.
Također nisi ograničen na jedan poslužitelj. Jedan RunContext može agregirati više izvora, a model vidi uniju njihovih alata kao jedinstveni 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)
Dodavanje lokalnih funkcija
Ne mora svaka mogućnost postati MCP poslužitelj. Za kratku funkciju specifičnu za ovu skriptu, dekorator register_func dovoljan je da je izložiš modelu kao standardni alat.
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")
S perspektive modela, nema razlike: on jednostavno vidi još jedan alat. Razlika je za tebe – ove funkcije se izvršavaju u tvom Python procesu, bez vanjskog poslužitelja, pa nisu ponovno upotrebljive izvan ove skripte.
Pokretanje razgovora
Kada je kontekst popunjen, preostaje samo razgovor.
async with RunContext(agent_id=agent.id) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
# Sinkrono izvršavanje (čeka puni odgovor)
run_result = await client.beta.conversations.run_async(
run_ctx=run_ctx,
inputs="What is the weather in Paris?",
)
print(run_result.output)
Iza ovog poziva, model analizira pitanje, konzultira dostupne alate – i one s MCP poslužitelja i lokalne funkcije – poziva one koje smatra potrebnima, a zatim sastavlja svoj odgovor na temelju dobivenih rezultata.
Cijeli ciklus izgleda ovako:
1. Kreiraj agenta (client.beta.agents.create)
↓
2. Otvori RunContext (async with RunContext)
↓
3. Registriraj MCP klijente (register_mcp_client)
↓
4. Registriraj lokalne funkcije (register_func)
↓
5. Pokreni razgovore (conversations.run_async)
↓
6. Automatsko čišćenje (kraj upravitelja konteksta)
Kada izađeš iz bloka, kontekst zaustavlja sve STDIO procese poslužitelja koje je pokrenuo – nema napuštenih Python procesa koji vise nakon iznimke.
Završna riječ o continue_on_fn_error=True, čija je vrijednost najuočljivija u produkciji. Bez njega, najmanja greška u alatu prekida cijeli razgovor, ostavljajući korisnika da zuri u iznimku. S njim, model jasno prima grešku i ima prostora za manevriranje: može ponovno formulirati svoj zahtjev s drugačijim argumentima, posegnuti za drugim alatom ili jednostavno objasniti korisniku što je pošlo po zlu. Agent koji kaže „usluga za vremensku prognozu ne odgovara“ beskonačno je bolji od agenta koji se sruši.
Ključne točke
- RunContext orchestrira komunikaciju između agenta i MCP poslužitelja
- Koristi ga kao upravitelja konteksta
async with register_mcp_clientpovezuje MCP poslužitelj i otkriva njegove alateregister_funcregistrira lokalne Python funkcije kao alatecontinue_on_fn_error=Trueosigurava otpornost tvog agenta- Cijeli radni tijek je asinkron (async/await)