Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

RunContext: Immaniġġja l-Klijent MCP u l-Aġent

Lezzjoni 5 / 14 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Id-direttur tal-aġent tiegħek
  2. Oħloq l-aġent
  3. Iftaħ il-kuntest
  4. Irreġistra klijent MCP
  5. Żid funzjonijiet lokali
  6. Ibda l-konversazzjoni
  7. Punti Ewlenin

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_client jgħaqqad server MCP u jiskopri l-għodod tiegħu
  • register_func jirreġistra funzjonijiet Python lokali bħala għodod
  • continue_on_fn_error=True jiżgura r-reżiljenza tal-aġent tiegħek
  • Ix-xogħol kollu huwa asinkronu (async/await)