Премини към основното съдържание
Български— Изберете език
Меню

RunContext: Управление на MCP клиента и агента

Урок 5 от 14 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Диригентът на Вашия агент
  2. Създаване на агента
  3. Отваряне на контекста
  4. Регистриране на MCP клиент
  5. Добавяне на локални функции
  6. Стартиране на разговора
  7. Ключови изводи

Диригентът на Вашия агент

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)