Vai al contenuto principale
Italiano— Scegli una lingua
Menu

RunContext: gestire il client MCP e l'agente

Lezione 5 di 14 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Il direttore d’orchestra del tuo agente
  2. Creare l’agente
  3. Aprire il contesto
  4. Registrare un client MCP
  5. Aggiungere funzioni locali
  6. Avviare la conversazione
  7. Punti chiave

Il direttore d’orchestra del tuo agente

Il RunContext è il componente che tiene insieme tutto. Collega il tuo agente AI ai server MCP e ne gestisce l’intero ciclo di vita: connessione ai server, registrazione degli strumenti, esecuzione delle conversazioni, recupero dei risultati e arresto pulito. Nell’SDK Mistral, si presenta come un gestore di contesto asincrono che incapsula tutta questa logica. Apri un blocco, dichiari cosa l’agente può utilizzare, conduci la tua conversazione e tutto si chiude automaticamente all’uscita.

Creare l’agente

Il RunContext non crea l’agente; vi si aggancia. Il tuo primo passo consiste quindi nell’istanziare un agente tramite l’API.

from mistralai.client import Mistral

# Inizializza il client Mistral
client = Mistral(api_key="YOUR_API_KEY")

# Crea un agente
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}")

Questo agente è un’entità persistente sul lato Mistral: possiede un modello, un nome e istruzioni di sistema, e sopravvive oltre la durata del tuo script. Gli strumenti MCP, invece, non sono allegati all’agente. È il RunContext a fornirli dinamicamente a ogni esecuzione. Questo disaccoppiamento ti permette di eseguire lo stesso agente con strumenti diversi a seconda del contesto.

Aprire il contesto

Utilizzi RunContext con async with, il che garantisce il rilascio delle risorse anche in caso di eccezione.

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

# Opzionale: definisci un formato di output strutturato
class WeatherResult(BaseModel):
    location: str
    temperature: float
    description: str

async with RunContext(
    agent_id=agent.id,
    output_format=WeatherResult,      # Formato strutturato (opzionale)
    continue_on_fn_error=True,         # Continua se uno strumento fallisce
) as run_ctx:
    # Qui, registra i client MCP e avvia le conversazioni
    pass

Tre parametri controllano questo comportamento. agent_id specifica l’agente creato in precedenza. output_format accetta un modello Pydantic e vincola la risposta finale a quella struttura: è prezioso quando l’output alimenta un altro programma piuttosto che un essere umano. Infine, continue_on_fn_error decide cosa succede alla conversazione quando uno strumento solleva un errore: se impostato su True, il contesto prosegue e il modello riceve il messaggio di errore esattamente come se fosse un risultato.

Registrare un client MCP

Una volta aperto il contesto, dichiari al suo interno i tuoi client MCP.

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

# Configura il server locale
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:
    # Registra il client MCP
    await run_ctx.register_mcp_client(mcp_client=mcp_client)

Questa singola chiamata a register_mcp_client innesca una sequenza completa: avvio del processo server in modalità STDIO, negoziazione delle capacità, recupero dell’elenco degli strumenti e messa a disposizione di tali strumenti per il modello nelle conversazioni successive. Non devi scrivere nulla di tutto ciò a mano.

Non sei nemmeno limitato a un singolo server. Un unico RunContext può aggregare più fonti e il modello vede l’unione dei loro strumenti come un unico catalogo:

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)

Aggiungere funzioni locali

Non ogni capacità deve diventare un server MCP. Per una breve funzione specifica di questo script, il decoratore register_func è sufficiente per esporla al modello come strumento 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:
        """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")

Dal punto di vista del modello, non c’è differenza: vede semplicemente uno strumento in più. La differenza sta per te: queste funzioni vengono eseguite nel tuo processo Python, senza un server esterno, quindi non sono riutilizzabili al di fuori di questo script.

Avviare la conversazione

Una volta popolato il contesto, non resta che parlare.

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

    # Esecuzione sincrona (attende la risposta completa)
    run_result = await client.beta.conversations.run_async(
        run_ctx=run_ctx,
        inputs="What is the weather in Paris?",
    )

    print(run_result.output)

Dietro questa chiamata, il modello analizza la domanda, consulta gli strumenti disponibili (sia dai server MCP che dalle funzioni locali), chiama quelli che ritiene necessari e quindi elabora la sua risposta basandosi sui risultati ottenuti.

L’intero ciclo appare così:

1. Crea l'agente (client.beta.agents.create)
       ↓
2. Apri il RunContext (async with RunContext)
       ↓
3. Registra i client MCP (register_mcp_client)
       ↓
4. Registra le funzioni locali (register_func)
       ↓
5. Avvia le conversazioni (conversations.run_async)
       ↓
6. Pulizia automatica (fine del gestore di contesto)

Quando esci dal blocco, il contesto arresta tutti i processi server STDIO avviati: nessun processo Python orfano rimane in sospeso dopo un’eccezione.

Un’ultima parola su continue_on_fn_error=True, il cui valore emerge chiaramente in produzione. Senza di esso, il minimo errore in uno strumento interrompe l’intera conversazione, lasciando l’utente davanti a un’eccezione. Con esso, il modello riceve l’errore in modo chiaro e ha spazio di manovra: può riformulare la richiesta con argomenti diversi, ripiegare su un altro strumento o semplicemente spiegare all’utente cosa non ha funzionato. Un agente che dice «il servizio meteo non risponde» è infinitamente migliore di un agente che va in crash.

Punti chiave

  • Il RunContext orchestra la comunicazione tra l’agente e i server MCP
  • Usalo come gestore di contesto async with
  • register_mcp_client connette un server MCP e scopre i suoi strumenti
  • register_func registra funzioni Python locali come strumenti
  • continue_on_fn_error=True garantisce la resilienza del tuo agente
  • L’intero flusso di lavoro è asincrono (async/await)