RunContext: Immaniġġja l-Klijent MCP u l-Aġent
F'din il-paġna
Id-direttur tal-aġent tiegħek
Ir-RunContext huwa l-komponent li jżomm kollox flimkien. Jgħaqqad l-aġent tal-AI tiegħek mas-servers MCP u jimmaniġġja ċ-ċiklu tal-ħajja kollu tagħhom: il-konnessjoni mas-servers, ir-reġistrazzjoni tal-għodod, l-eżekuzzjoni tal-konversazzjonijiet, l-irkupru tar-riżultati u l-għeluq korrett. Fis-SDK ta’ Mistral, jieħu l-forma ta’ maniġer tal-kuntest asinkronu li jinkapsula din il-loġika kollha. Tiftaħ blokk, tiddikjara x’jista’ juża l-aġent, tagħmel il-konversazzjoni tiegħek, u kollox jingħalaq awtomatikament meta toħroġ.
Oħloq l-aġent
Ir-RunContext ma joħloqx l-aġent; jinhemeż ma’ wieħed eżistenti. L-ewwel pass tiegħek huwa għalhekk li tistanzja aġent permezz tal-API.
from mistralai.client import Mistral
# Inizzjalizza l-klijent ta' Mistral
client = Mistral(api_key="YOUR_API_KEY")
# Oħloq aġent
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="assistant-mcp",
instructions="Int assistent kapaċi juża għodod MCP.",
)
print(f"Aġent maħluq: {agent.id}")
Dan l-aġent huwa entità persistenti fuq in-naħa ta’ Mistral: għandu mudell, isem u istruzzjonijiet tas-sistema, u jibqa’ ħaj wara li jispiċċa l-iskritt tiegħek. Madankollu, l-għodod MCP mhumiex imwaħħla mal-aġent. Minflok, ir-RunContext jipprovdihom b’mod dinamiku f’kull eżekuzzjoni. Dan id-diakkoppjar jippermettilek tħaddem l-istess aġent b’għodod differenti skont il-kuntest.
Iftaħ il-kuntest
Tuża r-RunContext ma’ async with, li jiggarantixxi r-rilaxx tar-riżorsi anke jekk iseħħ eċċezzjoni.
from mistralai.extra.run.context import RunContext
from pydantic import BaseModel
# Opzjonali: iddefinixxi format ta' output strutturat
class WeatherResult(BaseModel):
location: str
temperature: float
description: str
async with RunContext(
agent_id=agent.id,
output_format=WeatherResult, # Format strutturat (opzjonali)
continue_on_fn_error=True, # Kompli jekk għodda tfalli
) as run_ctx:
# Hawnhekk, irreġistra klijenti MCP u ibda konversazzjonijiet
pass
Tliet parametri jikkontrollaw dan l-imġiba. agent_id jispeċifika l-aġent li ħloqt qabel. output_format jaċċetta mudell Pydantic u jillimita r-risposta finali għal dik l-istruttura—valuż meta l-output jingħata lil programm ieħor minflok bniedem. Fl-aħħar nett, continue_on_fn_error jiddeċiedi x’jiġri mill-konversazzjoni meta għodda tqajjem żball: jekk issettjat għal True, il-kuntest ikompli, u l-mudell jirċievi l-messaġġ ta’ żball eżattament kif ikun jirċievi riżultat.
Irreġistra klijent MCP
Ladarba l-kuntest ikun miftuħ, tiddikjara l-klijenti MCP tiegħek fih.
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
# Ikkonfigura s-server lokali
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:
# Irreġistra l-klijent MCP
await run_ctx.register_mcp_client(mcp_client=mcp_client)
Din is-sejħa waħda għal register_mcp_client tniedi sekwenza sħiħa: tniedi l-proċess tas-server f’modalità STDIO, tinnegozja l-kapaċitajiet, tirrikupra l-lista tal-għodod, u tagħmel dawk l-għodod disponibbli għall-mudell għall-konversazzjonijiet li jmiss. M’għandekx bżonn tikteb xejn minn dan bl-idejn.
M’intix limitat għal server wieħed biss. RunContext wieħed jista’ jiġbor flimkien sorsi multipli, u l-mudell jara l-unjoni tal-għodod tagħhom bħala katalogu wieħed:
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)
Żid funzjonijiet lokali
Mhux kull kapaċità trid issir server MCP. Għal funzjoni qasira speċifika għal dan l-iskritt, id-dekoratur register_func huwa biżżejjed biex jesponiha lill-mudell bħala għodda standard.
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:
"""Tirkupra l-post ta' utent.
Args:
username: L-isem tal-utent
Returns:
Il-belt tal-utent
"""
locations = {"alice": "Paris", "bob": "Lyon", "charlie": "Marseille"}
return locations.get(username, "Unknown")
Mill-perspettiva tal-mudell, m’hemm l-ebda differenza: sempliċiment jara għodda oħra. Id-differenza hija għalik—dawn il-funzjonijiet jiġu eżegwiti fil-proċess Python tiegħek, mingħajr server estern, allura mhumiex riutilizzabbli barra minn dan l-iskritt.
Ibda l-konversazzjoni
Ladarba l-kuntest ikun mimli, kollox li jifdal huwa li titkellem.
async with RunContext(agent_id=agent.id) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
# Eżekuzzjoni sinkrona (tistenna r-risposta sħiħa)
run_result = await client.beta.conversations.run_async(
run_ctx=run_ctx,
inputs="X'inhu t-temp f'Pariġi?",
)
print(run_result.output)
Wara din is-sejħa, il-mudell janalizza l-mistoqsija, jikkonsulta l-għodod disponibbli—kemm mis-servers MCP kif ukoll mill-funzjonijiet lokali—isejjaħ dawk li jqis meħtieġa, u mbagħad ifassal ir-risposta tiegħu abbażi tar-riżultati miksuba.
Iċ-ċiklu sħiħ jidher hekk:
1. Oħloq l-aġent (client.beta.agents.create)
↓
2. Iftaħ ir-RunContext (async with RunContext)
↓
3. Irreġistra klijenti MCP (register_mcp_client)
↓
4. Irreġistra funzjonijiet lokali (register_func)
↓
5. Ibda konversazzjonijiet (conversations.run_async)
↓
6. Tindifa awtomatika (tmiem il-maniġer tal-kuntest)
Meta toħroġ mill-blokk, il-kuntest iwaqqaf il-proċessi kollha tas-server STDIO li ntedew—l-ebda proċess Python orfni ma jibqa’ mdendel wara eċċezzjoni.
Kelma finali dwar continue_on_fn_error=True, li l-valur tiegħu jidher l-aktar fil-produzzjoni. Mingħajru, l-iżgħar żball f’għodda jinterrompi l-konversazzjoni kollha, u jħalli lill-utent iħares lejn eċċezzjoni. Bih, il-mudell jirċievi l-iżball b’mod ċar u jkollu spazju biex jimmanuvra: jista’ jifformula mill-ġdid it-talba tiegħu b’argumenti differenti, jerġa’ lura għal għodda oħra, jew sempliċiment jispjega lill-utent x’falla. Aġent li jgħid “is-servizz tat-temp ma qed jirrispondix” huwa infinitament aħjar minn aġent li jikkraċċja.
Punti Ewlenin
- Ir-RunContext jikkoordina l-komunikazzjoni bejn l-aġent u s-servers MCP
- Użah bħala maniġer tal-kuntest
async with register_mcp_clientjgħaqqad server MCP u jiskopri l-għodod tiegħuregister_funcjirreġistra funzjonijiet Python lokali bħala għododcontinue_on_fn_error=Truejiżgura r-reżiljenza tal-aġent tiegħek- Ix-xogħol kollu huwa asinkronu (async/await)