RunContext: Управление на MCP клиента и агента
На тази страница
Диригентът на Вашия агент
RunContext е компонентът, който държи всичко заедно. Той свързва Вашия AI агент със сървъри на MCP и управлява целия им жизнен цикъл: свързване към сървърите, регистриране на инструменти, изпълнение на разговори, извличане на резултати и коректно спиране. В Mistral SDK той приема формата на асинхронен мениджър на контекста, който обхваща цялата тази логика. Вие отваряте блок, декларирате какво е позволено да използва агентът, провеждате разговора си и всичко се затваря автоматично при излизане.
Създаване на агента
RunContext не създава агента; той се прикачва към такъв. Първата Ви стъпка следователно е да инстанцирате агент чрез API.
from mistralai.client import Mistral
# Initialize the Mistral client
client = Mistral(api_key="YOUR_API_KEY")
# Create an agent
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}")
Този агент е постоянна entidade от страна на Mistral: той има модел, име и системни инструкции и оцелява отвъд Вашия скрипт. Инструментите на MCP обаче не са прикачени към агента. Вместо това, RunContext ги предоставя динамично при всяко изпълнение. Това разделение Ви позволява да стартирате един и същи агент с различни инструменти в зависимост от контекста.
Отваряне на контекста
Използвате RunContext с async with, което гарантира освобождаването на ресурсите дори при възникване на изключение.
from mistralai.extra.run.context import RunContext
from pydantic import BaseModel
# Optional: define a structured output format
class WeatherResult(BaseModel):
location: str
temperature: float
description: str
async with RunContext(
agent_id=agent.id,
output_format=WeatherResult, # Structured format (optional)
continue_on_fn_error=True, # Continue if a tool fails
) as run_ctx:
# Here, register MCP clients and start conversations
pass
Три параметъра контролират това поведение. agent_id посочва агента, който сте създали по-рано. output_format приема Pydantic модел и ограничава крайния отговор до тази структура – полезно, когато изходът се подава на друга програма, а не на човек. Накрая, continue_on_fn_error решава какво се случва с разговора, когато даден инструмент върне грешка: ако е зададено на True, контекстът продължава и моделът получава съобщението за грешка точно както би получил резултат.
Регистриране на MCP клиент
След като контекстът е отворен, Вие декларирате Вашите MCP клиенти в него.
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
# Configure the local 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:
# Register the MCP client
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)
# Synchronous execution (waits for the full response)
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. Create the agent (client.beta.agents.create)
↓
2. Open the RunContext (async with RunContext)
↓
3. Register MCP clients (register_mcp_client)
↓
4. Register local functions (register_func)
↓
5. Start conversations (conversations.run_async)
↓
6. Automatic cleanup (end of context manager)
Когато излезете от блока, контекстът спира всички STDIO сървърни процеси, които е стартирал – няма останали осиротели Python процеси след изключение.
Няколко думи в заключение за continue_on_fn_error=True, чиято стойност е най-очевидна в продукционна среда. Без него най-малката грешка в инструмент прекъсва целия разговор, оставяйки потребителя да гледа изключение. С него моделът получава грешката ясно и има пространство за маневриране: той може да преформулира заявката си с различни аргументи, да премине към друг инструмент или просто да обясни на потребителя какво се е объркало. Агент, който казва „услугата за времето не отговаря“, е безкрайно по-добър от агент, който се срива.
Ключови изводи
- RunContext оркестрира комуникацията между агента и MCP сървърите
- Използвайте го като мениджър на контекста
async with register_mcp_clientсвързва MCP сървър и открива неговите инструментиregister_funcрегистрира локални Python функции като инструментиcontinue_on_fn_error=Trueосигурява устойчивостта на Вашия агент- Целият работен поток е асинхронен (async/await)