Przejdź do głównej treści
Polski— Wybierz język
Menu

RunContext: Zarządzanie klientem MCP i agentem

Lekcja 5 z 14 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Dyrygent Twojego agenta
  2. Tworzenie agenta
  3. Otwieranie kontekstu
  4. Rejestracja klienta MCP
  5. Dodawanie funkcji lokalnych
  6. Rozpoczynanie rozmowy
  7. Kluczowe wnioski

Dyrygent Twojego agenta

RunContext to komponent, który scala wszystko w całość. Łączy on Twojego agenta AI z serwerami MCP i zarządza ich pełnym cyklem życia: łączeniem z serwerami, rejestrowaniem narzędzi, wykonywaniem rozmów, pobieraniem wyników oraz poprawnym zamykaniem połączeń. W SDK Mistral przybiera formę asynchronicznego menedżera kontekstu, który enkapsuluje całą tę logikę. Otwierasz blok, deklarujesz, z czego agent może korzystać, prowadzisz rozmowę, a po wyjściu z bloku wszystko zamyka się automatycznie.

Tworzenie agenta

RunContext nie tworzy agenta; dołącza do istniejącego. Twoim pierwszym krokiem jest zatem utworzenie instancji agenta za pomocą API.

from mistralai.client import Mistral

# Inicjalizacja klienta Mistral
client = Mistral(api_key="YOUR_API_KEY")

# Utworzenie 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}")

Ten agent jest trwałą encją po stronie Mistral: posiada model, nazwę i instrukcje systemowe, a jego istnienie wykracza poza czas działania Twojego skryptu. Narzędzia MCP nie są jednak przypisane do agenta na stałe. Zamiast tego RunContext dostarcza je dynamicznie przy każdym wykonaniu. To rozdzielenie pozwala uruchamiać tego samego agenta z różnymi narzędziami w zależności od kontekstu.

Otwieranie kontekstu

Używasz RunContext wraz z async with, co gwarantuje zwolnienie zasobów nawet w przypadku wystąpienia wyjątku.

from mistralai.extra.run.context import RunContext
from pydantic import BaseModel

# Opcjonalnie: zdefiniowanie struktury wyjścia
class WeatherResult(BaseModel):
    location: str
    temperature: float
    description: str

async with RunContext(
    agent_id=agent.id,
    output_format=WeatherResult,      # Struktura wyjścia (opcjonalne)
    continue_on_fn_error=True,         # Kontynuuj, jeśli narzędzie zwróci błąd
) as run_ctx:
    # Tutaj rejestrujesz klientów MCP i rozpoczynasz rozmowy
    pass

Trzy parametry kontrolują to zachowanie. agent_id wskazuje agenta utworzonego wcześniej. output_format akceptuje model Pydantic i wymusza, aby końcowa odpowiedź miała tę strukturę – jest to cenne, gdy wynik jest przetwarzany przez inny program, a nie przez człowieka. Ostatni parametr, continue_on_fn_error, decyduje o losie rozmowy, gdy narzędzie zgłosi błąd: jeśli ustawisz go na True, kontekst działa dalej, a model otrzymuje komunikat o błędzie tak samo, jakby był to zwykły wynik.

Rejestracja klienta MCP

Gdy kontekst jest już otwarty, deklarujesz w nim swoich klientów MCP.

from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO

# Konfiguracja serwera lokalnego
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:
    # Rejestracja klienta MCP
    await run_ctx.register_mcp_client(mcp_client=mcp_client)

To pojedyncze wywołanie register_mcp_client uruchamia pełną sekwencję: start procesu serwera w trybie STDIO, negocjację możliwości, pobranie listy narzędzi i udostępnienie ich modelowi do nadchodzących rozmów. Nie musisz niczego z tego pisać ręcznie.

Nie jesteś też ograniczony do jednego serwera. Pojedynczy RunContext może agregować wiele źródeł, a model widzi sumę ich narzędzi jako jeden 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)

Dodawanie funkcji lokalnych

Nie każda funkcjonalność musi stać się serwerem MCP. W przypadku krótkiej funkcji specyficznej dla tego skryptu, dekorator register_func wystarczy, aby udostępnić ją modelowi jako standardowe narzędzie.

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")

Z perspektywy modelu nie ma żadnej różnicy: widzi on po prostu kolejne dostępne narzędzie. Różnica leży po Twojej stronie – te funkcje działają w procesie Pythona, bez zewnętrznego serwera, więc nie można ich użyć poza tym skryptem.

Rozpoczynanie rozmowy

Gdy kontekst jest już wypełniony, pozostaje tylko rozmowa.

async with RunContext(agent_id=agent.id) as run_ctx:
    await run_ctx.register_mcp_client(mcp_client=mcp_client)

    # Wykonanie synchroniczne (czeka na pełną odpowiedź)
    run_result = await client.beta.conversations.run_async(
        run_ctx=run_ctx,
        inputs="What is the weather in Paris?",
    )

    print(run_result.output)

Za tym wywołaniem model analizuje pytanie, konsultuje dostępne narzędzia – zarówno z serwerów MCP, jak i funkcji lokalnych – wywołuje te, które uzna za konieczne, a następnie formułuje odpowiedź na podstawie uzyskanych wyników.

Cały cykl wygląda następująco:

1. Utwórz agenta (client.beta.agents.create)
       ↓
2. Otwórz RunContext (async with RunContext)
       ↓
3. Zarejestruj klientów MCP (register_mcp_client)
       ↓
4. Zarejestruj funkcje lokalne (register_func)
       ↓
5. Rozpocznij rozmowy (conversations.run_async)
       ↓
6. Automatyczne czyszczenie (koniec menedżera kontekstu)

Gdy wyjdziesz z bloku, kontekst zatrzymuje wszystkie procesy serwerów STDIO, które uruchomił – nie zostają żadne osierocone procesy Pythona zawieszone po wystąpieniu wyjątku.

Na koniec warto wspomnieć o continue_on_fn_error=True, którego wartość najbardziej docenisz w środowisku produkcyjnym. Bez niego najmniejszy błąd w narzędziu przerywa całą rozmowę, pozostawiając użytkownika z wyjątkiem na ekranie. Dzięki niemu model otrzymuje jasny komunikat o błędzie i ma pole manewru: może przeformułować żądanie z innymi argumentami, skorzystać z innego narzędzia lub po prostu wyjaśnić użytkownikowi, co poszło nie tak. Agent, który mówi „usługa pogodowa nie odpowiada“, jest nieskończenie lepszy niż agent, który ulega awarii.

Kluczowe wnioski

  • RunContext koordynuje komunikację między agentem a serwerami MCP
  • Używaj go jako menedżera kontekstu async with
  • register_mcp_client łączy serwer MCP i odkrywa jego narzędzia
  • register_func rejestruje lokalne funkcje Pythona jako narzędzia
  • continue_on_fn_error=True zapewnia odporność Twojego agenta
  • Cały przepływ pracy jest asynchroniczny (async/await)