API Mistral Agents com MCP: Quão Bom É?

A Inteligência Artificial (IA) está rapidamente indo além de simplesmente gerar texto ou reconhecer imagens. A próxima fronteira é sobre IA que pode agir, resolver problemas e interagir com o mundo de maneiras significativas. A Mistral AI, um nome proeminente na área, deu um passo significativo nessa direção com sua Mistral Agents API. Este poderoso kit de ferramentas permite que desenvolvedores construam agentes de IA sofisticados que podem fazer muito mais do que modelos de linguagem tradicionais.

Em sua essência, a Agents API foi projetada para superar as limitações dos modelos de IA padrão, que são frequentemente ótimos em entender e gerar linguagem, mas têm dificuldade em executar ações, lembrar interações passadas de forma consistente ou usar ferramentas externas de forma eficaz. A Mistral Agents API aborda esses desafios equipando seus poderosos modelos de linguagem com recursos como conectores integrados a várias ferramentas, memória persistente entre conversas e a capacidade de coordenar tarefas complexas.

Pense nisso como uma atualização de um bibliotecário muito experiente que só pode falar sobre livros para uma equipe de pesquisadores especialistas que podem não apenas acessar informações, mas também conduzir experimentos, escrever relatórios e colaborar uns com os outros. Esta nova API serve como base para a criação de aplicações de IA de nível empresarial que podem automatizar fluxos de trabalho, auxiliar na tomada de decisões complexas e proporcionar experiências verdadeiramente interativas.

O Que Torna os Mistral Agents Tão Capazes?

Modelos de linguagem tradicionais, embora proficientes na geração de texto, frequentemente ficam aquém quando se trata de executar ações ou lembrar informações ao longo de interações estendidas. A Mistral Agents API aborda diretamente essas limitações sinergizando os modelos de linguagem de ponta da Mistral com um conjunto de recursos poderosos projetados para fluxos de trabalho agentivos.

Capacidades Essenciais:

Em sua essência, a Agents API oferece:

• Conectores Integrados: São ferramentas pré-implementadas que os agentes podem chamar sob demanda. Eles incluem:
• Execução de Código: Permite que os agentes executem código Python em um sandbox seguro, útil para cálculos, análise de dados e computação científica.
• Busca na Web: Capacita os agentes com acesso a informações atualizadas da internet, melhorando significativamente a precisão e a relevância das respostas. Por exemplo, no benchmark SimpleQA, o Mistral Large com busca na web alcançou uma pontuação de 75%, uma melhoria massiva em relação aos 23% sem ela.
• Geração de Imagens: Aproveitando modelos como o Black Forest Lab FLUX1.1 [pro] Ultra, os agentes podem criar imagens diversas para aplicações que vão desde materiais educacionais até gráficos de marketing.
• Biblioteca de Documentos: Permite que os agentes acessem e utilizem documentos do Mistral Cloud, impulsionando a Geração Aumentada por Recuperação (RAG) integrada para aprimorar sua base de conhecimento.
• Ferramentas MCP: Facilita a integração perfeita com sistemas externos via Model Context Protocol, que exploraremos em profundidade na Parte 3.
• Memória Persistente: Os agentes podem manter o contexto entre conversas, levando a interações de longo prazo mais coerentes e significativas.
• Orquestração Agentiva: A API permite a coordenação de múltiplos agentes, cada um potencialmente especializado em diferentes tarefas, para resolver problemas complexos de forma colaborativa.

Esta API não é meramente uma extensão de sua Chat Completion API; é um framework dedicado especificamente projetado para simplificar a implementação de casos de uso agentivos. Foi projetada para ser a espinha dorsal de plataformas agentivas de nível empresarial, permitindo que as empresas implementem IA de maneiras mais práticas, impactantes e orientadas para a ação.

Mistral Agents em Ação: Aplicações no Mundo Real

A versatilidade da Agents API é demonstrada através de várias aplicações inovadoras:

• Assistente de Codificação com GitHub: Um fluxo de trabalho agentivo onde um agente supervisiona um agente desenvolvedor (alimentado por DevStral) que interage com o GitHub, automatizando tarefas de desenvolvimento de software com autoridade total sobre o repositório.
• Assistente de Tickets Linear: Um assistente inteligente usando uma arquitetura MCP multi-servidor para transformar transcrições de chamadas em Documentos de Requisitos de Produto (PRDs), depois em issues acionáveis no Linear e, subsequentemente, rastrear entregas de projeto.
• Analista Financeiro: Um agente consultivo orquestrando múltiplos servidores MCP para obter métricas financeiras, compilar insights e arquivar resultados de forma segura, demonstrando agregação e análise de dados complexos.
• Assistente de Viagens: Uma ferramenta de IA abrangente para ajudar usuários a planejar viagens, reservar acomodações e gerenciar diversas necessidades relacionadas a viagens.
• Assistente Nutricional: Um companheiro de dieta baseado em IA que ajuda usuários a definir metas, registrar refeições, receber sugestões personalizadas de alimentos, acompanhar o progresso diário e encontrar restaurantes alinhados com seus objetivos nutricionais.

Memória, Contexto e Conversas Stateful

Um pilar fundamental da Agents API é seu robusto sistema de gerenciamento de conversas. Ele garante que as interações sejam stateful, o que significa que o contexto é retido ao longo do tempo. Desenvolvedores podem iniciar conversas de duas maneiras principais:

1. Com um Agente: Ao especificar um agent_id, você aproveita as capacidades, ferramentas e instruções pré-configuradas de um agente específico.
2. Acesso Direto: Você pode iniciar uma conversa especificando diretamente o modelo e os parâmetros de conclusão, proporcionando acesso rápido aos conectores integrados sem um agente pré-definido.

Cada conversa mantém um histórico estruturado através de "entradas de conversa", garantindo que o contexto seja meticulosamente preservado. Este statefulness permite que desenvolvedores visualizem conversas passadas, continuem qualquer interação de forma contínua ou até mesmo se ramifiquem para iniciar novos caminhos conversacionais a partir de qualquer ponto no histórico. Além disso, a API suporta saídas de streaming, permitindo atualizações em tempo real e interações dinâmicas.

Orquestração de Agentes: O Poder da Colaboração

O verdadeiro poder diferenciador da Agents API emerge em sua capacidade de orquestrar múltiplos agentes. Não se trata de uma única IA monolítica; trata-se de uma sinfonia de agentes especializados trabalhando em conjunto. Através da orquestração dinâmica, agentes podem ser adicionados ou removidos de uma conversa conforme necessário, cada um contribuindo com suas habilidades únicas para abordar diferentes facetas de um problema complexo.

Para construir um fluxo de trabalho agentivo com transferências:

1. Criar Agentes: Defina e crie todos os agentes necessários, cada um equipado com ferramentas, modelos e instruções específicas adaptadas ao seu papel.
2. Definir Transferências: Especifique quais agentes podem delegar tarefas a outros. Por exemplo, um agente de atendimento ao cliente primário pode transferir uma consulta técnica para um agente de solução de problemas especializado ou uma consulta de faturamento para um agente financeiro.

Estas transferências permitem uma cadeia de ações contínua. Uma única solicitação do usuário pode desencadear uma cascata de tarefas em múltiplos agentes, cada um lidando autonomamente com sua parte designada. Esta abordagem colaborativa desbloqueia eficiência e eficácia sem precedentes na resolução de problemas para aplicações sofisticadas do mundo real.

Uso Básico da Mistral Agents API

Tendo compreendido as capacidades da Mistral Agents API, vamos explorar como interagir com ela. A API introduz três novos objetos primários:

• Agentes: São configurações que aumentam as capacidades de um modelo. A definição de um agente inclui valores pré-selecionados como o modelo a usar, ferramentas que pode acessar, instruções do sistema (prompts) e parâmetros de conclusão padrão.
• Conversa: Este objeto representa o histórico de interações e eventos passados com um assistente. Inclui mensagens do usuário, respostas do assistente e registros de execuções de ferramentas.
• Entrada: Uma entrada é uma ação ou evento individual dentro de uma conversa, criado pelo usuário ou por um assistente. Oferece uma maneira flexível e expressiva de representar interações, permitindo um controle mais preciso sobre a descrição de eventos.

Notavelmente, você pode aproveitar muitos recursos, como conversas stateful e conectores integrados, sem criar e referenciar explicitamente um objeto "Agente" formal primeiro. Isso proporciona flexibilidade para casos de uso mais simples.

Criando um Agente

Para definir um agente especializado, você faz uma requisição à API especificando vários parâmetros:

• model: O modelo Mistral subjacente (por exemplo, mistral-medium-latest).
• name: Um nome descritivo para o seu agente.
• description: Uma breve explicação do propósito do agente ou da tarefa que ele foi projetado para realizar.
• instructions (opcional): O prompt do sistema que guia o comportamento e as respostas do agente.
• tools (opcional): Uma lista de ferramentas que o agente pode usar. Os tipos de ferramentas incluem:
• function: Ferramentas definidas pelo usuário, semelhantes à chamada de função padrão em conclusões de chat.
• web_search / web_search_premium: Ferramentas de busca na web integradas.
• code_interpreter: A ferramenta integrada para execução de código.
• image_generation: A ferramenta integrada para gerar imagens.
• completion_args (opcional): Argumentos padrão do sampler de conclusão de chat, como temperature, top_p, etc.

Aqui está um exemplo de requisição cURL para criar um agente simples:

curl --location "https://api.mistral.ai/v1/agents" \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --data '{
         "model": "mistral-medium-latest",
         "name": "Simple Agent",
         "description": "A simple Agent with persistent state."
     }'

Atualizando um Agente

Agentes podem ser atualizados após a criação. Os argumentos são os mesmos da criação. Esta operação resulta em um novo objeto agente com as configurações atualizadas, permitindo efetivamente o versionamento dos seus agentes.

curl --location "https://api.mistral.ai/v1/agents/<agent_id>" \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --data '{
         "completion_args": {
           "temperature": 0.3,
           "top_p": 0.95
         },
         "description": "An edited simple agent."
     }'

Gerenciando Conversas

Uma vez que um agente é criado (ou se você estiver usando acesso direto), você pode iniciar conversas.

Iniciando uma Conversa:
Você precisa fornecer:

• agent_id: O ID do agente (se estiver usando um agente pré-definido).
• inputs: A mensagem inicial, que pode ser uma string simples ou uma lista de objetos de mensagem.
  Esta requisição retorna um conversation_id.

Exemplo (entrada de string simples):

curl --location "https://api.mistral.ai/v1/conversations" \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --data '{
         "inputs": "Who is Albert Einstein?",
         "stream": false,
         "agent_id": "<agent_id>"
     }'

Continuando uma Conversa:
Para adicionar a uma conversa existente:

• conversation_id: O ID da conversa a continuar.
• inputs: A próxima mensagem ou resposta (string ou lista de mensagens).
  Cada continuação fornece um novo conversation_id se o estado for armazenado. Você pode optar por não armazenar na nuvem definindo store=False. O parâmetro handoff_execution controla como as transferências de agente são gerenciadas: server (padrão, tratado pela nuvem da Mistral) ou client (a resposta é retornada ao usuário para gerenciar a transferência).

Exemplo:

curl --location "https://api.mistral.ai/v1/conversations/<conv_id>" \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --data '{
         "inputs": "Translate to French.",
         "stream": false,
         "store": true,
         "handoff_execution": "server"
     }'

Saída de Streaming

Para interações em tempo real, tanto iniciar quanto continuar conversas podem ser transmitidos via streaming definindo stream: true e garantindo que o cabeçalho Accept seja text/event-stream.

curl --location "https://api.mistral.ai/v1/conversations" \
     --header 'Content-Type: application/json' \
     --header 'Accept: text/event-stream' \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --data '{
         "inputs": "Who is Albert Einstein?",
         "stream": true,
         "agent_id": "ag_06811008e6e07cb48000fd3f133e1771"
     }'

Ao transmitir via streaming, você receberá vários tipos de eventos indicando o progresso e o conteúdo da resposta, tais como:

• conversation.response.started: Marca o início da resposta da conversa.
• message.output.delta: Um pedaço de conteúdo (tokens) para a resposta do modelo.
• tool.execution.started / tool.execution.done: Indicam o ciclo de vida de uma execução de ferramenta.
• agent.handoff.started / agent.handoff.done: Sinalizam o início e o fim de uma transferência de agente.

Estas operações básicas formam a base para a construção de aplicações dinâmicas e interativas com agentes Mistral.

Integrando a Mistral Agents API com o Model Context Protocol (MCP)

Embora os conectores integrados ofereçam um poder significativo, a verdadeira extensibilidade dos Mistral Agents brilha quando combinada com o Model Context Protocol (MCP).

O Que é o MCP?

O Model Context Protocol (MCP) é um padrão aberto projetado para otimizar a integração de modelos de IA com diversas fontes de dados externas, ferramentas e APIs. Ele fornece uma interface padronizada e segura que permite que sistemas de IA acessem e utilizem informações contextuais do mundo real de forma eficiente. Em vez de construir e manter inúmeras integrações personalizadas, o MCP oferece uma maneira unificada para modelos de IA se conectarem a dados e sistemas em tempo real, levando a respostas mais relevantes, precisas e poderosas. Para informações detalhadas, consulte a documentação oficial do Model Context Protocol.

O SDK Python da Mistral fornece mecanismos de integração perfeita para conectar agentes com Clientes MCP. Isso permite que seus agentes interajam com qualquer serviço ou fonte de dados que exponha uma interface MCP, seja uma ferramenta local, uma API de terceiros ou um sistema empresarial proprietário.

Exploraremos três cenários comuns para usar o MCP com Mistral Agents: um servidor MCP local, um servidor MCP remoto sem autenticação e um servidor MCP remoto com autenticação. Todos os exemplos utilizarão código Python assíncrono.

Cenário 1: Usando um Servidor MCP Local

Imagine que você tenha um script ou serviço local (por exemplo, um provedor personalizado de informações meteorológicas) com o qual você deseja que seu agente Mistral interaja.

Passo 1: Inicializar o Cliente Mistral e Configuração
Importe os módulos necessários de mistralai e mcp. Isso inclui Mistral, RunContext, StdioServerParameters (para servidores MCP baseados em processo local) e MCPClientSTDIO.

import asyncio
import os
from pathlib import Path
from mistralai import Mistral
from mistralai.extra.run.context import RunContext
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from mistralai.types import BaseModel

cwd = Path(__file__).parent
MODEL = "mistral-medium-latest" # Or your preferred model

async def main_local_mcp():
    api_key = os.environ["MISTRAL_API_KEY"]
    client = Mistral(api_key=api_key)

    # Define parameters for the local MCP server (e.g., running a Python script)
    server_params = StdioServerParameters(
        command="python",
        args=[str((cwd / "mcp_servers/stdio_server.py").resolve())], # Path to your MCP server script
        env=None,
    )

    # Create an agent
    weather_agent = client.beta.agents.create(
        model=MODEL,
        name="Local Weather Teller",
        instructions="You can tell the weather using a local MCP tool.",
        description="Fetches weather from a local source.",
    )

    # Define expected output format (optional, but good for structured data)
    class WeatherResult(BaseModel):
        user: str
        location: str
        temperature: float

    # Create a Run Context
    async with RunContext(
        agent_id=weather_agent.id,
        output_format=WeatherResult, # Optional: For structured output
        continue_on_fn_error=True,
    ) as run_ctx:
        # Create and register MCP client
        mcp_client = MCPClientSTDIO(stdio_params=server_params)
        await run_ctx.register_mcp_client(mcp_client=mcp_client)

        # Example of registering a local Python function as a tool
        import random
        @run_ctx.register_func
        def get_location(name: str) -> str:
            """Function to get a random location for a user."""
            return random.choice(["New York", "London", "Paris"])

        # Run the agent
        run_result = await client.beta.conversations.run_async(
            run_ctx=run_ctx,
            inputs="Tell me the weather in John's location currently.",
        )

        print("Local MCP - All run entries:")
        for entry in run_result.output_entries:
            print(f"{entry}\n")
        if run_result.output_as_model:
            print(f"Local MCP - Final model output: {run_result.output_as_model}")
        else:
            print(f"Local MCP - Final text output: {run_result.output_as_text}")

# if __name__ == "__main__":
#     asyncio.run(main_local_mcp())

Nesta configuração, stdio_server.py seria seu script implementando a lógica do servidor MCP, comunicando-se via stdin/stdout. O RunContext gerencia a interação, e register_mcp_client torna o servidor MCP local disponível como uma ferramenta para o agente. Você também pode registrar funções Python locais diretamente usando @run_ctx.register_func.

Streaming com um Servidor MCP Local:
Para fazer streaming, use client.beta.conversations.run_stream_async e processe os eventos conforme eles chegam:

    # Inside RunContext, after MCP client registration
    # events = await client.beta.conversations.run_stream_async(
    #     run_ctx=run_ctx,
    #     inputs="Tell me the weather in John's location currently, stream style.",
    # )
    # streamed_run_result = None
    # async for event in events:
    #     if isinstance(event, RunResult): # Assuming RunResult is defined or imported
    #         streamed_run_result = event
    #     else:
    #         print(f"Stream event: {event}")
    # if streamed_run_result:
    #     # Process streamed_run_result
    #     pass

Cenário 2: Usando um Servidor MCP Remoto Sem Autenticação

Muitos serviços públicos ou internos podem expor uma interface MCP via HTTP/SSE sem exigir autenticação.

from mistralai.extra.mcp.sse import MCPClientSSE, SSEServerParams

async def main_remote_no_auth_mcp():
    api_key = os.environ["MISTRAL_API_KEY"]
    client = Mistral(api_key=api_key)

    # Define the URL for the remote MCP server (e.g., Semgrep's public MCP)
    server_url = "https://mcp.semgrep.ai/sse"
    mcp_client = MCPClientSSE(sse_params=SSEServerParams(url=server_url, timeout=100))

    async with RunContext(
        model=MODEL, # Can use agent_id too if an agent is pre-created
    ) 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="Can you write a hello_world.py file and then check it for security vulnerabilities using available tools?",
        )

        print("Remote No-Auth MCP - All run entries:")
        for entry in run_result.output_entries:
            print(f"{entry}\n")
        print(f"Remote No-Auth MCP - Final Response: {run_result.output_as_text}")

# if __name__ == "__main__":
#     asyncio.run(main_remote_no_auth_mcp())

Aqui, MCPClientSSE é usado com SSEServerParams apontando para a URL remota. O agente pode então aproveitar as ferramentas fornecidas por este servidor MCP remoto. O streaming segue o mesmo padrão do exemplo de MCP local, usando run_stream_async.

Cenário 3: Usando um Servidor MCP Remoto Com Autenticação (OAuth)

Para serviços que exigem autenticação OAuth2 (como Linear, Jira, etc.), o processo envolve alguns passos adicionais para lidar com o fluxo de autorização.

from http.server import BaseHTTPRequestHandler, HTTPServer
import threading
import webbrowser
from mistralai.extra.mcp.auth import build_oauth_params

CALLBACK_PORT = 16010 # Ensure this port is free

# Callback server setup (simplified from source)
def run_callback_server_util(callback_func, auth_response_dict):
    class OAuthCallbackHandler(BaseHTTPRequestHandler):
        def do_GET(self):
            if "/callback" in self.path or "/oauth/callback" in self.path: # More robust check
                auth_response_dict["url"] = self.path
                self.send_response(200)
                self.send_header("Content-type", "text/html")
                self.end_headers()
                self.wfile.write(b"<html><body>Authentication successful. You may close this window.</body></html>")
                callback_func() # Signal completion
                threading.Thread(target=self.server.shutdown).start()
            else:
                self.send_response(404)
                self.end_headers()

    server_address = ("localhost", CALLBACK_PORT)
    httpd = HTTPServer(server_address, OAuthCallbackHandler)
    threading.Thread(target=httpd.serve_forever, daemon=True).start() # Use daemon thread
    redirect_url = f"http://localhost:{CALLBACK_PORT}/oauth/callback"
    return httpd, redirect_url

async def main_remote_auth_mcp():
    api_key = os.environ["MISTRAL_API_KEY"]
    client = Mistral(api_key=api_key)

    server_url = "https://mcp.linear.app/sse" # Example: Linear MCP
    mcp_client_auth = MCPClientSSE(sse_params=SSEServerParams(url=server_url))

    callback_event = asyncio.Event()
    event_loop = asyncio.get_event_loop()
    auth_response_holder = {"url": ""}

    if await mcp_client_auth.requires_auth():
        httpd, redirect_url = run_callback_server_util(
            lambda: event_loop.call_soon_threadsafe(callback_event.set),
            auth_response_holder
        )
        try:
            oauth_params = await build_oauth_params(mcp_client_auth.base_url, redirect_url=redirect_url)
            mcp_client_auth.set_oauth_params(oauth_params=oauth_params)
            login_url, state = await mcp_client_auth.get_auth_url_and_state(redirect_url)

            print(f"Please go to this URL and authorize: {login_url}")
            webbrowser.open(login_url, new=2)
            await callback_event.wait() # Wait for OAuth callback

            token = await mcp_client_auth.get_token_from_auth_response(
                auth_response_holder["url"], redirect_url=redirect_url, state=state
            )
            mcp_client_auth.set_auth_token(token)
            print("Authentication successful.")
        except Exception as e:
            print(f"Error during authentication: {e}")
            return # Exit if auth fails
        finally:
            if 'httpd' in locals() and httpd:
                httpd.shutdown()
                httpd.server_close()
    
    async with RunContext(model=MODEL) as run_ctx: # Or agent_id
        await run_ctx.register_mcp_client(mcp_client=mcp_client_auth)

        run_result = await client.beta.conversations.run_async(
            run_ctx=run_ctx,
            inputs="Tell me which projects do I have in my Linear workspace?",
        )
        print(f"Remote Auth MCP - Final Response: {run_result.output_as_text}")

# if __name__ == "__main__":
#     asyncio.run(main_remote_auth_mcp())

Isso envolve configurar um servidor HTTP local para capturar o redirecionamento OAuth, guiar o usuário pela página de autorização do provedor, trocar o código recebido por um token de acesso e, em seguida, configurar o MCPClientSSE com este token. Uma vez autenticado, o agente pode interagir com o serviço MCP protegido. O streaming novamente segue o padrão estabelecido.

Conclusão: O Futuro é Agentivo e Interconectado

A Mistral Agents API, especialmente quando aumentada pelo Model Context Protocol, oferece uma plataforma robusta e flexível para a construção de aplicações de IA de próxima geração. Ao permitir que os agentes não apenas raciocinem e se comuniquem, mas também interajam com um vasto ecossistema de ferramentas, fontes de dados e serviços, os desenvolvedores podem criar sistemas verdadeiramente inteligentes capazes de lidar com problemas complexos do mundo real. Quer você esteja automatizando fluxos de trabalho intrincados, fornecendo assistência profundamente contextualizada ou sendo pioneiro em novas formas de colaboração humano-IA, a combinação de Mistral Agents e MCP fornece o kit de ferramentas fundamental para este futuro emocionante. À medida que o padrão MCP ganha maior adoção, o potencial para criar agentes de IA interconectados e altamente capazes só continuará a crescer.