Blog

Menggunakan Mistral Agents API dengan MCP: Seberapa Bagus?

Mark Ponomarev

Mark Ponomarev

28 May 2025

Menggunakan Mistral Agents API dengan MCP: Seberapa Bagus?

Kecerdasan Buatan (AI) bergerak cepat melampaui sekadar menghasilkan teks atau mengenali gambar. Batas berikutnya adalah tentang AI yang dapat mengambil tindakan, memecahkan masalah, dan berinteraksi dengan dunia secara bermakna. Mistral AI, nama terkemuka di bidang ini, telah mengambil langkah signifikan ke arah ini dengan Mistral Agents API-nya. Toolkit yang canggih ini memungkinkan pengembang untuk membangun agen AI yang canggih yang dapat melakukan lebih dari sekadar model bahasa tradisional.

Intinya, Agents API dirancang untuk mengatasi keterbatasan model AI standar, yang seringkali sangat baik dalam memahami dan menghasilkan bahasa tetapi kesulitan dalam melakukan tindakan, mengingat interaksi sebelumnya secara konsisten, atau menggunakan alat eksternal secara efektif. Mistral Agents API mengatasi tantangan ini dengan melengkapi model bahasanya yang canggih dengan fitur-fitur seperti konektor bawaan ke berbagai alat, memori persisten di seluruh percakapan, dan kemampuan untuk mengoordinasikan tugas-tugas kompleks.

Bayangkan seperti meningkatkan dari pustakawan yang sangat berpengetahuan yang hanya bisa berbicara tentang buku menjadi tim peneliti ahli yang tidak hanya dapat mengakses informasi tetapi juga melakukan eksperimen, menulis laporan, dan berkolaborasi satu sama lain. API baru ini berfungsi sebagai fondasi untuk menciptakan aplikasi AI tingkat perusahaan yang dapat mengotomatiskan alur kerja, membantu pengambilan keputusan yang kompleks, dan memberikan pengalaman yang benar-benar interaktif.

💡
Ingin alat Pengujian API hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform Terintegrasi, All-in-One untuk Tim Pengembang Anda bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button

Apa yang Membuat Agen Mistral Begitu Mampu?

Model bahasa tradisional, meskipun mahir dalam menghasilkan teks, seringkali kurang efektif dalam hal mengeksekusi tindakan atau mengingat informasi di seluruh interaksi yang diperpanjang. Mistral Agents API secara langsung mengatasi keterbatasan ini dengan menyinergikan model bahasa mutakhir Mistral dengan serangkaian fitur canggih yang dirancang untuk alur kerja berbasis agen.

Kemampuan Inti:

Intinya, Agents API menyediakan:

API ini bukan sekadar ekstensi dari Chat Completion API mereka; ini adalah kerangka kerja khusus yang direkayasa secara spesifik untuk menyederhanakan implementasi kasus penggunaan berbasis agen. API ini dirancang untuk menjadi tulang punggung platform berbasis agen tingkat perusahaan, memungkinkan bisnis menerapkan AI dengan cara yang lebih praktis, berdampak, dan berorientasi tindakan.

Agen Mistral dalam Aksi: Aplikasi Dunia Nyata

Fleksibilitas Agents API ditunjukkan melalui berbagai aplikasi inovatif:

Memori, Konteks, dan Percakapan Stateful

Landasan Agents API adalah sistem manajemen percakapannya yang kuat. Ini memastikan bahwa interaksi bersifat stateful, artinya konteks dipertahankan seiring waktu. Pengembang dapat memulai percakapan dalam dua cara utama:

  1. Dengan Agen: Dengan menentukan agent_id, Anda memanfaatkan kemampuan, alat, dan instruksi yang telah dikonfigurasi sebelumnya dari agen tertentu.
  2. Akses Langsung: Anda dapat memulai percakapan dengan langsung menentukan model dan parameter penyelesaian, menyediakan akses cepat ke konektor bawaan tanpa agen yang telah ditentukan sebelumnya.

Setiap percakapan mempertahankan riwayat terstruktur melalui "entri percakapan," memastikan konteks terjaga dengan cermat. Sifat stateful ini memungkinkan pengembang untuk melihat percakapan sebelumnya, melanjutkan interaksi apa pun dengan lancar, atau bahkan bercabang untuk memulai jalur percakapan baru dari titik mana pun dalam riwayat. Selain itu, API mendukung keluaran streaming, memungkinkan pembaruan waktu nyata dan interaksi dinamis.

Orkestrasi Agen: Kekuatan Kolaborasi

Kekuatan pembeda sejati dari Agents API muncul dalam kemampuannya untuk mengorkestrasi banyak agen. Ini bukan tentang AI monolitik tunggal; ini tentang simfoni agen khusus yang bekerja bersama. Melalui orkestrasi dinamis, agen dapat ditambahkan atau dihapus dari percakapan sesuai kebutuhan, masing-masing menyumbangkan keterampilan uniknya untuk menangani berbagai aspek masalah yang kompleks.

Untuk membangun alur kerja berbasis agen dengan serah terima (handoff):

  1. Buat Agen: Definisikan dan buat semua agen yang diperlukan, masing-masing dilengkapi dengan alat, model, dan instruksi spesifik yang disesuaikan dengan perannya.
  2. Definisikan Serah Terima (Handoffs): Tentukan agen mana yang dapat mendelegasikan tugas kepada agen lain. Misalnya, agen layanan pelanggan utama dapat menyerahkan pertanyaan teknis kepada agen pemecahan masalah khusus atau pertanyaan penagihan kepada agen keuangan.

Serah terima ini memungkinkan rantai tindakan yang mulus. Satu permintaan pengguna dapat memicu serangkaian tugas di banyak agen, masing-masing secara mandiri menangani bagian yang ditugaskan. Pendekatan kolaboratif ini membuka efisiensi dan efektivitas yang belum pernah terjadi sebelumnya dalam pemecahan masalah untuk aplikasi dunia nyata yang canggih.

Penggunaan Dasar Mistral Agents API

Setelah memahami kemampuan Mistral Agents API, mari kita jelajahi cara berinteraksi dengannya. API ini memperkenalkan tiga objek utama baru:

Perlu dicatat, Anda dapat memanfaatkan banyak fitur, seperti percakapan stateful dan konektor bawaan, tanpa secara eksplisit membuat dan mereferensikan objek "Agen" formal terlebih dahulu. Ini memberikan fleksibilitas untuk kasus penggunaan yang lebih sederhana.

Membuat Agen

Untuk mendefinisikan agen khusus, Anda membuat permintaan ke API dengan menentukan beberapa parameter:

Berikut contoh permintaan cURL untuk membuat agen sederhana:

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."
     }'

Memperbarui Agen

Agen dapat diperbarui setelah dibuat. Argumennya sama dengan argumen untuk pembuatan. Operasi ini menghasilkan objek agen baru dengan pengaturan yang diperbarui, secara efektif memungkinkan pembuatan versi agen Anda.

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."
     }'

Mengelola Percakapan

Setelah agen dibuat (atau jika Anda menggunakan akses langsung), Anda dapat memulai percakapan.

Memulai Percakapan:
Anda perlu menyediakan:

Contoh (input string sederhana):

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>"
     }'

Melanjutkan Percakapan:
Untuk menambahkan ke percakapan yang sudah ada:

Contoh:

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"
     }'

Keluaran Streaming

Untuk interaksi waktu nyata, memulai dan melanjutkan percakapan dapat di-stream dengan mengatur stream: true dan memastikan header Accept adalah 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"
     }'

Saat melakukan streaming, Anda akan menerima berbagai jenis peristiwa yang menunjukkan kemajuan dan konten respons, seperti:

Operasi dasar ini membentuk fondasi untuk membangun aplikasi yang dinamis dan interaktif dengan agen Mistral.

Mengintegrasikan Mistral Agents API dengan Model Context Protocol (MCP)

Meskipun konektor bawaan menawarkan kekuatan yang signifikan, ekstensibilitas sejati Agen Mistral bersinar ketika dikombinasikan dengan Model Context Protocol (MCP).

Apa itu MCP?

Model Context Protocol (MCP) adalah standar terbuka yang dirancang untuk menyederhanakan integrasi model AI dengan berbagai sumber data eksternal, alat, dan API. Ini menyediakan antarmuka yang terstandarisasi dan aman yang memungkinkan sistem AI mengakses dan memanfaatkan informasi kontekstual dunia nyata secara efisien. Alih-alih membangun dan memelihara banyak integrasi khusus, MCP menawarkan cara terpadu bagi model AI untuk terhubung ke data dan sistem langsung, menghasilkan respons yang lebih relevan, akurat, dan kuat. Untuk informasi rinci, lihat dokumentasi resmi Model Context Protocol.

SDK Python Mistral menyediakan mekanisme integrasi tanpa batas untuk menghubungkan agen dengan Klien MCP. Ini memungkinkan agen Anda berinteraksi dengan layanan atau sumber data apa pun yang mengekspos antarmuka MCP, baik itu alat lokal, API pihak ketiga, atau sistem perusahaan proprietary.

Kita akan menjelajahi tiga skenario umum penggunaan MCP dengan Agen Mistral: server MCP lokal, server MCP jarak jauh tanpa otentikasi, dan server MCP jarak jauh dengan otentikasi. Semua contoh akan menggunakan kode Python asinkron.

Skenario 1: Menggunakan Server MCP Lokal

Bayangkan Anda memiliki skrip atau layanan lokal (misalnya, penyedia informasi cuaca khusus) yang ingin Anda interaksikan dengan agen Mistral Anda.

Langkah 1: Inisialisasi Klien Mistral dan Pengaturan
Impor modul yang diperlukan dari mistralai dan mcp. Ini mencakup Mistral, RunContext, StdioServerParameters (untuk server MCP berbasis proses lokal), dan 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())

Dalam pengaturan ini, stdio_server.py akan menjadi skrip Anda yang mengimplementasikan logika server MCP, berkomunikasi melalui stdin/stdout. RunContext mengelola interaksi, dan register_mcp_client membuat server MCP lokal tersedia sebagai alat bagi agen. Anda juga dapat mendaftarkan fungsi Python lokal secara langsung menggunakan @run_ctx.register_func.

Streaming dengan Server MCP Lokal:
Untuk melakukan streaming, gunakan client.beta.conversations.run_stream_async dan proses peristiwa saat tiba:

    # 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

Skenario 2: Menggunakan Server MCP Jarak Jauh Tanpa Otentikasi

Banyak layanan publik atau internal mungkin mengekspos antarmuka MCP melalui HTTP/SSE tanpa memerlukan otentikasi.

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())

Di sini, MCPClientSSE digunakan dengan SSEServerParams yang menunjuk ke URL jarak jauh. Agen kemudian dapat memanfaatkan alat yang disediakan oleh server MCP jarak jauh ini. Streaming mengikuti pola yang sama dengan contoh MCP lokal, menggunakan run_stream_async.

Skenario 3: Menggunakan Server MCP Jarak Jauh Dengan Otentikasi (OAuth)

Untuk layanan yang memerlukan otentikasi OAuth2 (seperti Linear, Jira, dll.), prosesnya melibatkan beberapa langkah tambahan untuk menangani alur otorisasi.

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())

Ini melibatkan pengaturan server HTTP lokal untuk menangkap pengalihan OAuth, memandu pengguna melalui halaman otorisasi penyedia, menukar kode yang diterima dengan token akses, dan kemudian mengonfigurasi MCPClientSSE dengan token ini. Setelah diautentikasi, agen dapat berinteraksi dengan layanan MCP yang dilindungi. Streaming kembali mengikuti pola yang telah ditetapkan.

Kesimpulan: Masa Depan adalah Berbasis Agen dan Saling Terhubung

Mistral Agents API, terutama ketika diperkuat oleh Model Context Protocol, menawarkan platform yang kuat dan fleksibel untuk membangun aplikasi AI generasi berikutnya. Dengan memungkinkan agen tidak hanya bernalar dan berkomunikasi tetapi juga berinteraksi dengan ekosistem alat, sumber data, dan layanan yang luas, pengembang dapat menciptakan sistem yang benar-benar cerdas yang mampu menangani masalah dunia nyata yang kompleks. Baik Anda mengotomatiskan alur kerja yang rumit, memberikan bantuan yang sangat kontekstual, atau merintis bentuk baru kolaborasi manusia-AI, kombinasi Mistral Agents dan MCP menyediakan toolkit dasar untuk masa depan yang menarik ini. Seiring dengan semakin luasnya adopsi standar MCP, potensi untuk menciptakan agen AI yang saling terhubung dan sangat mampu akan terus berkembang.

💡
Ingin alat Pengujian API hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform Terintegrasi, All-in-One untuk Tim Pengembang Anda bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button

Mengembangkan API dengan Apidog

Apidog adalah alat pengembangan API yang membantu Anda mengembangkan API dengan lebih mudah dan efisien.

Daftar gratisUnduh
Menggunakan Mistral Agents API dengan MCP: Seberapa Bagus?