RunContext: Gerir o Cliente MCP e o Agente
Nesta página
O maestro do seu agente
O RunContext é o componente que mantém tudo coeso. Liga o seu agente de IA aos servidores MCP e gere todo o seu ciclo de vida: ligação aos servidores, registo de ferramentas, execução de conversas, obtenção de resultados e encerramento limpo. No SDK da Mistral, assume a forma de um gestor de contexto assíncrono que encapsula toda esta lógica. Abre um bloco, declara o que o agente pode utilizar, conduz a sua conversa e tudo se fecha automaticamente ao sair.
Criar o agente
O RunContext não cria o agente; liga-se a um existente. O seu primeiro passo é, portanto, instanciar um agente através da API.
from mistralai.client import Mistral
# Inicializar o cliente Mistral
client = Mistral(api_key="YOUR_API_KEY")
# Criar um 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}")
Este agente é uma entidade persistente no lado da Mistral: possui um modelo, um nome e instruções de sistema, e sobrevive para além do seu script. As ferramentas MCP, no entanto, não estão ligadas ao agente. Em vez disso, o RunContext fornece-as dinamicamente em cada execução. Este desacoplamento permite-lhe executar o mesmo agente com ferramentas diferentes consoante o contexto.
Abrir o contexto
Utiliza o RunContext com async with, o que garante a libertação de recursos mesmo que ocorra uma exceção.
from mistralai.extra.run.context import RunContext
from pydantic import BaseModel
# Opcional: definir um formato de saída estruturado
class WeatherResult(BaseModel):
location: str
temperature: float
description: str
async with RunContext(
agent_id=agent.id,
output_format=WeatherResult, # Formato estruturado (opcional)
continue_on_fn_error=True, # Continuar se uma ferramenta falhar
) as run_ctx:
# Aqui, registe os clientes MCP e inicie as conversas
pass
Três parâmetros controlam este comportamento. agent_id especifica o agente que criou anteriormente. output_format aceita um modelo Pydantic e restringe a resposta final a essa estrutura — valioso quando a saída alimenta outro programa em vez de um humano. Por fim, continue_on_fn_error decide o que acontece à conversa quando uma ferramenta gera um erro: se definido como True, o contexto continua e o modelo recebe a mensagem de erro tal como receberia um resultado.
Registar um cliente MCP
Assim que o contexto estiver aberto, declara os seus clientes MCP dentro dele.
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
# Configurar o servidor local
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:
# Registar o cliente MCP
await run_ctx.register_mcp_client(mcp_client=mcp_client)
Esta única chamada a register_mcp_client desencadeia uma sequência completa: lançamento do processo do servidor em modo STDIO, negociação de capacidades, obtenção da lista de ferramentas e disponibilização dessas ferramentas ao modelo para conversas futuras. Não precisa de escrever nada disto manualmente.
Também não está limitado a um único servidor. Um único RunContext pode agregar múltiplas fontes, e o modelo vê a união das suas ferramentas como um único catálogo:
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)
Adicionar funções locais
Nem todas as capacidades precisam de se tornar num servidor MCP. Para uma função curta específica deste script, o decorador register_func é suficiente para a expor ao modelo como uma ferramenta padrão.
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")
Da perspetiva do modelo, não há diferença: vê simplesmente mais uma ferramenta. A diferença é para si — estas funções executam no seu processo Python, sem um servidor externo, pelo que não são reutilizáveis fora deste script.
Iniciar a conversa
Uma vez populado o contexto, só resta conversar.
async with RunContext(agent_id=agent.id) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
# Execução síncrona (aguarda pela resposta completa)
run_result = await client.beta.conversations.run_async(
run_ctx=run_ctx,
inputs="What is the weather in Paris?",
)
print(run_result.output)
Por detrás desta chamada, o modelo analisa a questão, consulta as ferramentas disponíveis — tanto dos servidores MCP como das funções locais — chama as que considera necessárias e, em seguida, elabora a sua resposta com base nos resultados obtidos.
Todo o ciclo funciona assim:
1. Criar o agente (client.beta.agents.create)
↓
2. Abrir o RunContext (async with RunContext)
↓
3. Registar clientes MCP (register_mcp_client)
↓
4. Registar funções locais (register_func)
↓
5. Iniciar conversas (conversations.run_async)
↓
6. Limpeza automática (fim do gestor de contexto)
Ao sair do bloco, o contexto para todos os processos de servidor STDIO que lançou — sem processos Python órfãos deixados pendentes após uma exceção.
Uma última palavra sobre continue_on_fn_error=True, cujo valor é mais evidente em produção. Sem ele, o mais pequeno erro numa ferramenta interrompe toda a conversa, deixando o utilizador a olhar para uma exceção. Com ele, o modelo recebe o erro claramente e tem margem de manobra: pode reformular o seu pedido com argumentos diferentes, recorrer a outra ferramenta ou simplesmente explicar ao utilizador o que falhou. Um agente que diz «o serviço meteorológico não está a responder» é infinitamente melhor do que um agente que colapsa.
Pontos-chave
- O RunContext orquestra a comunicação entre o agente e os servidores MCP
- Utilize-o como um gestor de contexto
async with register_mcp_clientliga um servidor MCP e descobre as suas ferramentasregister_funcregista funções Python locais como ferramentascontinue_on_fn_error=Truegarante a resiliência do seu agente- Todo o fluxo de trabalho é assíncrono (async/await)