Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

RunContext: Verwalten Sie den MCP-Client und den Agenten

Lektion 5 von 14 Aktualisiert am 2. November 2026 Entwickler
Auf dieser Seite
  1. Der Dirigent Ihres Agenten
  2. Erstellen Sie den Agenten
  3. Öffnen Sie den Kontext
  4. Registrieren Sie einen MCP-Client
  5. Fügen Sie lokale Funktionen hinzu
  6. Starten Sie das Gespräch
  7. Kernaussagen

Der Dirigent Ihres Agenten

Der RunContext ist die Komponente, die alles zusammenhält. Er verbindet Ihren KI-Agenten mit MCP-Servern und verwaltet deren gesamten Lebenszyklus: die Verbindung zu Servern, das Registrieren von Tools, die Ausführung von Gesprächen, das Abrufen von Ergebnissen und den sauberen Abschluss. Im Mistral SDK nimmt er die Form eines asynchronen Kontext-Managers an, der diese gesamte Logik kapselt. Sie öffnen einen Block, deklarieren, welche Tools der Agent verwenden darf, führen das Gespräch durch, und alles schließt sich automatisch, wenn Sie den Block verlassen.

Erstellen Sie den Agenten

Der RunContext erstellt den Agenten nicht; er hängt sich an einen an. Ihr erster Schritt besteht daher darin, einen Agenten über die API zu instanzen.

from mistralai.client import Mistral

# Initialisieren Sie den Mistral-Client
client = Mistral(api_key="YOUR_API_KEY")

# Erstellen Sie einen Agenten
agent = client.beta.agents.create(
    model="mistral-medium-latest",
    name="assistant-mcp",
    instructions="Sie sind ein Assistent, der MCP-Tools verwenden kann.",
)

print(f"Agent erstellt: {agent.id}")

Dieser Agent ist eine persistente Entität auf der Mistral-Seite: Er verfügt über ein Modell, einen Namen und Systemanweisungen und überdauert Ihr Skript. MCP-Tools werden jedoch nicht dem Agenten angehängt. Stattdessen stellt der RunContext sie dynamisch bei jeder Ausführung bereit. Diese Entkopplung ermöglicht es Ihnen, denselben Agenten mit unterschiedlichen Tools abhängig vom Kontext auszuführen.

Öffnen Sie den Kontext

Sie verwenden RunContext mit async with, was die Freigabe von Ressourcen garantiert, auch wenn eine Ausnahme auftritt.

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

# Optional: Definieren Sie ein Format für strukturierte Ausgaben
class WeatherResult(BaseModel):
    location: str
    temperature: float
    description: str

async with RunContext(
    agent_id=agent.id,
    output_format=WeatherResult,      # Strukturiertes Format (optional)
    continue_on_fn_error=True,         # Weitermachen, wenn ein Tool fehlschlägt
) as run_ctx:
    # Hier registrieren Sie MCP-Clients und starten Gespräche
    pass

Drei Parameter steuern dieses Verhalten. agent_id gibt den Agenten an, den Sie zuvor erstellt haben. output_format akzeptiert ein Pydantic-Modell und beschränkt die finale Antwort auf diese Struktur – von Wert, wenn die Ausgabe einem anderen Programm statt einem Menschen zugeführt wird. Schließlich entscheidet continue_on_fn_error, was mit dem Gespräch passiert, wenn ein Tool eine Ausnahme wirft: Wenn auf True gesetzt, setzt der Kontext fort, und das Modell erhält die Fehlermeldung genau so, wie es ein Ergebnis erhalten würde.

Registrieren Sie einen MCP-Client

Sobald der Kontext geöffnet ist, deklarieren Sie Ihre MCP-Clients innerhalb desselben.

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

# Konfigurieren Sie den lokalen Server
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:
    # Registrieren Sie den MCP-Client
    await run_ctx.register_mcp_client(mcp_client=mcp_client)

Dieser einzelne Aufruf von register_mcp_client löst eine vollständige Sequenz aus: Starten des Serverprozesses im STDIO-Modus, Aushandlung der Fähigkeiten, Abrufen der Tool-Liste und Bereitstellen dieser Tools für das Modell für kommende Gespräche. Sie müssen nichts davon manuell schreiben.

Sie sind auch nicht auf einen einzigen Server beschränkt. Ein einzelner RunContext kann mehrere Quellen aggregieren, und das Modell sieht die Vereinigung ihrer Tools als einen einzigen 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)

Fügen Sie lokale Funktionen hinzu

Nicht jede Fähigkeit muss zu einem MCP-Server werden. Für eine kurze Funktion, die spezifisch für dieses Skript ist, reicht der register_func-Decorator, um sie als Standard-Tool für das Modell freizugeben.

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:
        """Ruft die Position eines Benutzers ab.

        Args:
            username: Der Benutzername

        Returns:
            Die Stadt des Benutzers
        """
        locations = {"alice": "Paris", "bob": "Lyon", "charlie": "Marseille"}
        return locations.get(username, "Unknown")

Aus Sicht des Modells gibt es keinen Unterschied: Es sieht einfach nur ein weiteres Tool. Der Unterschied besteht für Sie: Diese Funktionen laufen in Ihrem Python-Prozess, ohne einen externen Server, sodass sie außerhalb dieses Skripts nicht wiederverwendbar sind.

Starten Sie das Gespräch

Sobald der Kontext mit Inhalten gefüllt ist, bleibt nur noch das Sprechen.

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

    # Synchroner Ablauf (wartet auf die vollständige Antwort)
    run_result = await client.beta.conversations.run_async(
        run_ctx=run_ctx,
        inputs="Wie ist das Wetter in Paris?",
    )

    print(run_result.output)

Hinter diesem Aufruf analysiert das Modell die Frage, konsultiert die verfügbaren Tools – sowohl von MCP-Servern als auch von lokalen Funktionen –, ruft die aus seiner Sicht notwendigen auf und entwirft daraufhin seine Antwort basierend auf den erhaltenen Ergebnissen.

Der gesamte Zyklus sieht wie folgt aus:

1. Erstellen Sie den Agenten (client.beta.agents.create)
       ↓
2. Öffnen Sie den RunContext (async with RunContext)
       ↓
3. Registrieren Sie MCP-Clients (register_mcp_client)
       ↓
4. Registrieren Sie lokale Funktionen (register_func)
       ↓
5. Starten Sie Gespräche (conversations.run_async)
       ↓
6. Automatischer Aufräumarbeiten (Ende des Kontext-Managers)

Wenn Sie den Block verlassen, stoppt der Kontext alle STDIO-Serverprozesse, die er gestartet hat – keine verwaisten Python-Prozesse hängen nach einer Ausnahme.

Ein letztes Wort zu continue_on_fn_error=True, dessen Wert in der Produktion am deutlichsten wird. Ohne diesen Parameter unterbricht der geringste Fehler in einem Tool das gesamte Gespräch und lässt den Nutzer auf eine Ausnahme starren. Mit diesem Parameter erhält das Modell den Fehler klar und hat Spielraum zur Manövrierfähigkeit: Es kann seine Anfrage mit anderen Argumenten neu formulieren, auf ein anderes Tool zurückgreifen oder dem Nutzer einfach erklären, was fehlgeschlagen ist. Ein Agent, der sagt “der Wetterdienst reagiert nicht”, ist unendlich besser als ein Agent, der abstürzt.

Kernaussagen

  • Der RunContext orchestriert die Kommunikation zwischen dem Agenten und MCP-Servern
  • Verwenden Sie ihn als async with-Kontext-Manager
  • register_mcp_client verbindet einen MCP-Server und entdeckt seine Tools
  • register_func registriert lokale Python-Funktionen als Tools
  • continue_on_fn_error=True gewährleistet die Resilienz Ihres Agenten
  • Der gesamte Workflow ist asynchron (async/await)