Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

RunContext: Hallitse MCP-asiakasta ja agenttia

Oppitunti 5 / 14 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Agenttisi kapellimestari
  2. Luo agentti
  3. Avaa konteksti
  4. Rekisteröi MCP-asiakas
  5. Lisää paikallisia funktioita
  6. Aloita keskustelu
  7. Keskeiset asiat

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_client yhdistää MCP-palvelimen ja löytää sen työkalut
  • register_func rekisteröi paikalliset Python-funktiot työkaluiksi
  • continue_on_fn_error=True varmistaa agenttisi vikasietoisuuden
  • Koko työnkulku on asynkroninen (async/await)