RunContext: Διαχείριση του πελάτη MCP και του πράκτορα
Σε αυτήν τη σελίδα
Ο μαέστρος του πράκτορά σας
Το RunContext είναι το στοιχείο που συγκρατεί τα πάντα. Συνδέει τον πράκτορα τεχνητής νοημοσύνης σας με τους διακομιστές MCP και διαχειρίζεται ολόκληρο τον κύκλο ζωής τους: σύνδεση με τους διακομιστές, καταχώρηση εργαλείων, εκτέλεση συνομιλιών, ανάκτηση αποτελεσμάτων και ομαλή τερματισμό. Στο Mistral SDK, λαμβάνει τη μορφή ενός ασύγχρονου διαχειριστή πλαισίου (context manager) που περικλείει όλη αυτή τη λογική. Ανοίγετε ένα μπλοκ, δηλώνετε τι επιτρέπεται να χρησιμοποιήσει ο πράκτορας, διεξάγετε τη συνομιλία σας και όλα κλείνουν αυτόματα όταν εξέρχεστε.
Δημιουργία του πράκτορα
Το RunContext δεν δημιουργεί τον πράκτορα· συνδέεται σε έναν υπάρχοντα. Επομένως, το πρώτο σας βήμα είναι να δημιουργήσετε ένα στιγμιότυπο ενός πράκτορα μέσω του API.
from mistralai.client import Mistral
# Αρχικοποίηση του πελάτη Mistral
client = Mistral(api_key="YOUR_API_KEY")
# Δημιουργία ενός πράκτορα
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}")
Αυτός ο πράκτορας είναι μια μόνιμη οντότητα στην πλευρά του Mistral: διαθέτει μοντέλο, όνομα και οδηγίες συστήματος, και επιβιώνει πέρα από το σενάριό σας. Τα εργαλεία MCP, ωστόσο, δεν συνδέονται στον πράκτορα. Αντίθετα, το RunContext τα παρέχει δυναμικά σε κάθε εκτέλεση. Αυτός ο αποσυζευγμός σάς επιτρέπει να εκτελείτε τον ίδιο πράκτορα με διαφορετικά εργαλεία ανάλογα με το πλαίσιο.
Άνοιγμα του πλαισίου
Χρησιμοποιείτε το RunContext με async with, γεγονός που εγγυάται την απελευθέρωση των πόρων ακόμη και αν συμβεί κάποια εξαίρεση.
from mistralai.extra.run.context import RunContext
from pydantic import BaseModel
# Προαιρετικά: ορισμός μιας δομημένης μορφής εξόδου
class WeatherResult(BaseModel):
location: str
temperature: float
description: str
async with RunContext(
agent_id=agent.id,
output_format=WeatherResult, # Δομημένη μορφή (προαιρετικό)
continue_on_fn_error=True, # Συνέχεια σε περίπτωση σφάλματος εργαλείου
) as run_ctx:
# Εδώ, καταχωρείτε πελάτες MCP και ξεκινάτε συνομιλίες
pass
Τρεις παράμετροι ελέγχουν αυτή τη συμπεριφορά. Το agent_id καθορίζει τον πράκτορα που δημιουργήσατε προηγουμένως. Το output_format δέχεται ένα μοντέλο Pydantic και περιορίζει την τελική απάντηση σε αυτή τη δομή—χρήσιμο όταν η έξοδος τροφοδοτεί ένα άλλο πρόγραμμα και όχι έναν άνθρωπο. Τέλος, το continue_on_fn_error αποφασίζει τι συμβαίνει στη συνομιλία όταν ένα εργαλείο προκαλεί σφάλμα: αν οριστεί σε True, το πλαίσιο συνεχίζεται και το μοντέλο λαμβάνει το μήνυμα σφάλματος ακριβώς όπως θα λάμβανε ένα αποτέλεσμα.
Καταχώρηση ενός πελάτη MCP
Μόλις ανοίξει το πλαίσιο, δηλώνετε τους πελάτες MCP μέσα σε αυτό.
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
# Διαμόρφωση του τοπικού διακομιστή
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:
# Καταχώρηση του πελάτη MCP
await run_ctx.register_mcp_client(mcp_client=mcp_client)
Αυτή η μοναδική κλήση στο register_mcp_client ενεργοποιεί μια πλήρη ακολουθία: εκκίνηση της διαδικασίας του διακομιστή σε λειτουργία STDIO, διαπραγμάτευση δυνατοτήτων, ανάκτηση της λίστας εργαλείων και διάθεση αυτών των εργαλείων στο μοντέλο για τις επερχόμενες συνομιλίες. Δεν χρειάζεται να γράψετε τίποτα από αυτά χειροκίνητα.
Επίσης, δεν περιορίζεστε σε έναν μόνο διακομιστή. Ένα μοναδικό RunContext μπορεί να συγκεντρώσει πολλαπλές πηγές και το μοντέλο βλέπει την ένωση των εργαλείων τους ως έναν ενιαίο κατάλογο:
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)
Προσθήκη τοπικών συναρτήσεων
Δεν χρειάζεται κάθε δυνατότητα να γίνει διακομιστής MCP. Για μια σύντομη συνάρτηση ειδική για αυτό το σενάριο, ο διακοσμητής register_func αρκεί για να την εκθέσει στο μοντέλο ως τυπικό εργαλείο.
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")
Από την οπτική γωνία του μοντέλου, δεν υπάρχει καμία διαφορά: βλέπει απλώς ένα ακόμη εργαλείο. Η διαφορά αφορά εσάς—αυτές οι συναρτήσεις εκτελούνται στη διαδικασία Python σας, χωρίς εξωτερικό διακομιστή, επομένως δεν είναι επαναχρησιμοποιήσιμες εκτός αυτού του σεναρίου.
Έναρξη της συνομιλίας
Μόλις συμπληρωθεί το πλαίσιο, το μόνο που απομένει είναι να μιλήσετε.
async with RunContext(agent_id=agent.id) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
# Σύγχρονη εκτέλεση (αναμονή για την πλήρη απάντηση)
run_result = await client.beta.conversations.run_async(
run_ctx=run_ctx,
inputs="What is the weather in Paris?",
)
print(run_result.output)
Πίσω από αυτή την κλήση, το μοντέλο αναλύει την ερώτηση, συμβουλεύεται τα διαθέσιμα εργαλεία—τόσο από διακομιστές MCP όσο και από τοπικές συναρτήσεις—καλεί όσα κρίνει απαραίτητα και στη συνέχεια συντάσσει την απάντησή του με βάση τα αποτελέσματα που έλαβε.
Ολόκληρος ο κύκλος έχει ως εξής:
1. Δημιουργία του πράκτορα (client.beta.agents.create)
↓
2. Άνοιγμα του RunContext (async with RunContext)
↓
3. Καταχώρηση πελατών MCP (register_mcp_client)
↓
4. Καταχώρηση τοπικών συναρτήσεων (register_func)
↓
5. Έναρξη συνομιλιών (conversations.run_async)
↓
6. Αυτόματος καθαρισμός (τέλος του διαχειριστή πλαισίου)
Όταν εξέρχεστε από το μπλοκ, το πλαίσιο σταματά όλες τις διαδικασίες διακομιστή STDIO που εκκίνησε—δεν μένουν orphaned διαδικασίες Python να εκκρεμούν μετά από μια εξαίρεση.
Μια τελευταία παρατήρηση για το continue_on_fn_error=True, του οποίου η αξία είναι πιο εμφανής στην παραγωγή. Χωρίς αυτό, το παραμικρό σφάλμα σε ένα εργαλείο διακόπτει ολόκληρη τη συνομιλία, αφήνοντας τον χρήστη να κοιτάζει μια εξαίρεση. Με αυτό, το μοντέλο λαμβάνει το σφάλμα καθαρά και έχει περιθώρια ελιγμών: μπορεί να διατυπώσει εκ νέου το αίτημά του με διαφορετικά ορίσματα, να καταφύγει σε ένα άλλο εργαλείο ή απλώς να εξηγήσει στον χρήστη τι απέτυχε. Ένας πράκτορας που λέει «η υπηρεσία καιρού δεν ανταποκρίνεται» είναι απείρως καλύτερος από έναν πράκτορα που καταρρέει.
Βασικά σημεία
- Το RunContext συντονίζει την επικοινωνία μεταξύ του πράκτορα και των διακομιστών MCP
- Χρησιμοποιήστε το ως διαχειριστή πλαισίου
async with - Το
register_mcp_clientσυνδέει έναν διακομιστή MCP και ανακαλύπτει τα εργαλεία του - Το
register_funcκαταχωρεί τοπικές συναρτήσεις Python ως εργαλεία - Το
continue_on_fn_error=Trueδιασφαλίζει την ανθεκτικότητα του πράκτορά σας - Ολόκληρη η ροή εργασίας είναι ασύγχρονη (async/await)