RunContext: Hallitse MCP-asiakasta ja agenttia
Tällä sivulla
Agenttisi kapellimestari
RunContext on komponentti, joka pitää kaiken koossa. Se yhdistää tekoälyagenttisi MCP-palvelimiin ja hallitsee niiden koko elinkaaren: yhteyden muodostamisen palvelimiin, työkalujen rekisteröinnin, keskustelujen suorittamisen, tulosten hakemisen ja siistin sammutuksen. Mistral SDK:ssa se on asynkroninen kontekstinhallinta (context manager), joka kapseloi kaiken tämän logiikan. Avaat lohkon, määrittelet, mitä agentti saa käyttää, käyt keskustelun, ja kaikki sulkeutuu automaattisesti poistuessasi lohkosta.
Luo agentti
RunContext ei luo agenttia; se kiinnittyy olemassa olevaan. Ensimmäinen vaiheesi onkin luoda agentti API:n kautta.
from mistralai.client import Mistral
# Alusta Mistral-asiakas
client = Mistral(api_key="YOUR_API_KEY")
# Luo agentti
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}")
Tämä agentti on pysyvä entiteetti Mistralin puolella: sillä on malli, nimi ja järjestelmäohjeet, ja se säilyy skriptisi suorituksen jälkeenkin. MCP-työkaluja ei kuitenkaan liitetä agenttiin. Sen sijaan RunContext tarjoaa ne dynaamisesti jokaisessa suorituksessa. Tämä irrottaminen mahdollistaa saman agentin käyttämisen eri työkaluilla kontekstista riippuen.
Avaa konteksti
Käytä RunContextiä async with -rakenteella, mikä takaa resurssien vapautumisen jopa poikkeustilanteissa.
from mistralai.extra.run.context import RunContext
from pydantic import BaseModel
# Valinnainen: määritä jäsennetty tulostemuoto
class WeatherResult(BaseModel):
location: str
temperature: float
description: str
async with RunContext(
agent_id=agent.id,
output_format=WeatherResult, # Jäsennetty muoto (valinnainen)
continue_on_fn_error=True, # Jatka, jos työkalu epäonnistuu
) as run_ctx:
# Täällä rekisteröidään MCP-asiakkaat ja aloitetaan keskustelut
pass
Kolme parametria ohjaavat tätä toimintaa. agent_id määrittää aiemmin luomasi agentin. output_format hyväksyy Pydantic-mallin ja rajoittaa lopullisen vastauksen kyseiseen rakenteeseen – tämä on arvokasta, kun syöte syötetään toiseen ohjelmaan eikä ihmiselle. Lopuksi continue_on_fn_error päättää, mitä keskustelulle tapahtuu, jos työkalu heittää virheen: jos arvo on True, konteksti jatkuu, ja malli saa virheilmoituksen aivan kuin se olisi tulos.
Rekisteröi MCP-asiakas
Kun konteksti on auki, ilmoitat MCP-asiakkaasi sen sisällä.
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
# Määritä paikallinen palvelin
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:
# Rekisteröi MCP-asiakas
await run_ctx.register_mcp_client(mcp_client=mcp_client)
Tämä yksi register_mcp_client-kutsu laukaisee täydellisen sekvenssin: palvelinprosessin käynnistäminen STDIO-tilassa, ominaisuuksien neuvottelu, työkalulistan hakeminen ja näiden työkalujen tekeminen saatavilla mallille tulevia keskusteluja varten. Sinun ei tarvitse kirjoittaa mitään tästä käsin.
Et myöskään rajoitu yhteen palvelimeen. Yksi RunContext voi kerätä useita lähteitä, ja malli näkee niiden työkalujen yhdistelmän yhtenä luettelona:
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)
Lisää paikallisia funktioita
Jokaisen ominaisuuden ei tarvitse olla MCP-palvelin. Lyhyelle, vain tätä skriptiä varten tarkoitetulle funktiolle register_func-koriste riittää exposing sen mallille vakiotyökaluna.
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")
Mallin näkökulmasta eroa ei ole: se näkee vain yhden työkalun lisää. Ero on sinua varten – nämä funktiot suoritetaan Python-prosessissasi ilman ulkoista palvelinta, joten niitä ei voi käyttää uudelleen tämän skriptin ulkopuolella.
Aloita keskustelu
Kun konteksti on täytetty, jäljellä on vain puhuminen.
async with RunContext(agent_id=agent.id) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
# Synkroninen suoritus (odottaa koko vastausta)
run_result = await client.beta.conversations.run_async(
run_ctx=run_ctx,
inputs="What is the weather in Paris?",
)
print(run_result.output)
Tämän kutsun takana malli analysoi kysymyksen, konsultoi käytettävissä olevia työkaluja – sekä MCP-palvelimilta että paikallisista funktioista – kutsuu niitä, jotka se katsoo tarpeellisiksi, ja laatii vastauksensa saatujen tulosten perusteella.
Koko sykli näyttää tältä:
1. Luo agentti (client.beta.agents.create)
↓
2. Avaa RunContext (async with RunContext)
↓
3. Rekisteröi MCP-asiakkaat (register_mcp_client)
↓
4. Rekisteröi paikalliset funktiot (register_func)
↓
5. Aloita keskustelut (conversations.run_async)
↓
6. Automaattinen siivous (kontekstinhallinnan loppu)
Kun poistut lohkosta, konteksti pysäyttää kaikki käynnistämänsä STDIO-palvelinprosessit – ei jääneitä Python-prosesseja roikkumaan poikkeustilanteen jälkeen.
Viimeinen sana aiheesta continue_on_fn_error=True, jonka arvo käy ilmeiseksi tuotantoympäristössä. Ilman sitä pieninkin virhe työkalussa keskeyttää koko keskustelun, jättäen käyttäjän tuijottamaan poikkeusta. Sen kanssa malli saa virheen selkeästi ja sillä on liikkumavaraa: se voi muotoilla pyyntönsä uudelleen eri argumenteilla, turvautua toiseen työkaluun tai yksinkertaisesti selittää käyttäjälle, mikä epäonnistui. Agentti, joka sanoo “sääpalvelu ei vastaa”, on äärettömästi parempi kuin agentti, joka kaatuu.
Keskeiset asiat
- RunContext orkestroi viestintää agentin ja MCP-palvelimien välillä
- Käytä sitä
async with-kontekstinhallintana register_mcp_clientyhdistää MCP-palvelimen ja löytää sen työkalutregister_funcrekisteröi paikalliset Python-funktiot työkaluiksicontinue_on_fn_error=Truevarmistaa agenttisi vikasietoisuuden- Koko työnkulku on asynkroninen (async/await)