Ir para o conteúdo principal
Português— Escolher um idioma
Menu

RunContext: Gerir o Cliente MCP e o Agente

Aula 5 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. O maestro do seu agente
  2. Criar o agente
  3. Abrir o contexto
  4. Registar um cliente MCP
  5. Adicionar funções locais
  6. Iniciar a conversa
  7. Pontos-chave

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_client liga um servidor MCP e descobre as suas ferramentas
  • register_func regista funções Python locais como ferramentas
  • continue_on_fn_error=True garante a resiliência do seu agente
  • Todo o fluxo de trabalho é assíncrono (async/await)