Blog

استخدام واجهة برمجة تطبيقات ميسترال مع MCP: ما مدى جودتها؟

Mark Ponomarev

Mark Ponomarev

28 مايو 2025

استخدام واجهة برمجة تطبيقات ميسترال مع MCP: ما مدى جودتها؟

يتجاوز الذكاء الاصطناعي (AI) بسرعة مجرد توليد النصوص أو التعرف على الصور. الحدود التالية تتعلق بالذكاء الاصطناعي الذي يمكنه اتخاذ الإجراءات وحل المشكلات والتفاعل مع العالم بطرق ذات مغزى. اتخذت Mistral AI، وهي اسم بارز في هذا المجال، خطوة هامة في هذا الاتجاه من خلال **واجهة برمجة تطبيقات وكلاء Mistral (Mistral Agents API)** القوية. تتيح هذه المجموعة القوية من الأدوات للمطورين بناء وكلاء ذكاء اصطناعي متطورين يمكنهم القيام بأكثر بكثير من نماذج اللغة التقليدية.

في جوهرها، تم تصميم واجهة برمجة تطبيقات الوكلاء (Agents API) للتغلب على قيود نماذج الذكاء الاصطناعي القياسية، والتي غالباً ما تكون ممتازة في فهم اللغة وتوليدها ولكنها تكافح في أداء الإجراءات، أو تذكر التفاعلات السابقة باستمرار، أو استخدام الأدوات الخارجية بفعالية. تتصدى واجهة برمجة تطبيقات وكلاء Mistral (Mistral Agents API) لهذه التحديات من خلال تزويد نماذجها اللغوية القوية بميزات مثل الموصلات المدمجة لمختلف الأدوات، والذاكرة المستمرة عبر المحادثات، والقدرة على تنسيق المهام المعقدة.

فكر في الأمر وكأنه ترقية من أمين مكتبة واسع المعرفة يمكنه التحدث فقط عن الكتب، إلى فريق من الباحثين الخبراء الذين لا يستطيعون الوصول إلى المعلومات فحسب، بل يمكنهم أيضاً إجراء التجارب وكتابة التقارير والتعاون مع بعضهم البعض. تعمل واجهة برمجة التطبيقات الجديدة هذه كأساس لإنشاء تطبيقات ذكاء اصطناعي على مستوى المؤسسات يمكنها أتمتة سير العمل، والمساعدة في اتخاذ القرارات المعقدة، وتقديم تجارب تفاعلية حقيقية.

💡
هل تريد أداة رائعة لاختبار واجهات برمجة التطبيقات (API Testing) تولد توثيقاً جميلاً لواجهة برمجة التطبيقات (API Documentation)؟

هل تريد منصة متكاملة وشاملة لفريق المطورين الخاص بك للعمل معاً بأقصى إنتاجية؟

Apidog يلبي جميع متطلباتك، ويحل محل Postman بسعر أقل بكثير!
button

ما الذي يجعل وكلاء Mistral بهذه القدرة؟

نماذج اللغة التقليدية، على الرغم من كفاءتها في توليد النصوص، غالباً ما تقصر عندما يتعلق الأمر بتنفيذ الإجراءات أو تذكر المعلومات عبر التفاعلات الممتدة. تتصدى واجهة برمجة تطبيقات وكلاء Mistral (Mistral Agents API) لهذه القيود مباشرةً من خلال دمج نماذج لغة Mistral المتطورة مع مجموعة من الميزات القوية المصممة لسير العمل الوكيلية.

القدرات الأساسية:

في جوهرها، توفر واجهة برمجة تطبيقات الوكلاء (Agents API):

الذاكرة المستمرة: يمكن للوكلاء الحفاظ على السياق عبر المحادثات، مما يؤدي إلى تفاعلات طويلة الأمد أكثر تماسكاً وذات مغزى.

التنسيق الوكيلي: تسمح واجهة برمجة التطبيقات بتنسيق العديد من الوكلاء، الذين قد يتخصص كل منهم في مهام مختلفة، لحل المشكلات المعقدة بشكل تعاوني.

هذه الواجهة البرمجية ليست مجرد امتداد لواجهة برمجة تطبيقات إكمال الدردشة (Chat Completion API) الخاصة بهم؛ إنها إطار عمل مخصص مصمم خصيصاً لتبسيط تنفيذ حالات الاستخدام الوكيلية. تم تصميمها لتكون العمود الفقري للمنصات الوكيلية على مستوى المؤسسات، مما يمكّن الشركات من نشر الذكاء الاصطناعي بطرق أكثر عملية وتأثيراً وتوجهاً نحو العمل.

وكلاء Mistral قيد العمل: تطبيقات واقعية

يتم عرض تعدد استخدامات واجهة برمجة تطبيقات الوكلاء (Agents API) من خلال تطبيقات مبتكرة مختلفة:

الذاكرة، السياق، والمحادثات ذات الحالة (Stateful)

حجر الزاوية في واجهة برمجة تطبيقات الوكلاء (Agents API) هو نظام إدارة المحادثات القوي الخاص بها. يضمن هذا النظام أن التفاعلات ذات حالة (stateful)، مما يعني الاحتفاظ بالسياق بمرور الوقت. يمكن للمطورين بدء المحادثات بطريقتين رئيسيتين:

  1. مع وكيل: بتحديد agent_id، فإنك تستفيد من القدرات والأدوات والتعليمات المكونة مسبقاً لوكيل معين.
  2. الوصول المباشر: يمكنك بدء محادثة عن طريق تحديد النموذج ومعلمات الإكمال مباشرةً، مما يوفر وصولاً سريعاً إلى الموصلات المدمجة دون الحاجة إلى وكيل محدد مسبقاً.

تحافظ كل محادثة على سجل منظم من خلال "إدخالات المحادثة"، مما يضمن الحفاظ على السياق بدقة. تسمح هذه الحالة (statefulness) للمطورين بعرض المحادثات السابقة، متابعة أي تفاعل بسلاسة، أو حتى التفرع لبدء مسارات محادثة جديدة من أي نقطة في السجل. علاوة على ذلك، تدعم واجهة برمجة التطبيقات مخرجات البث المباشر (streaming)، مما يتيح تحديثات في الوقت الفعلي وتفاعلات ديناميكية.

تنسيق الوكلاء: قوة التعاون

تظهر القوة المميزة الحقيقية لواجهة برمجة تطبيقات الوكلاء (Agents API) في قدرتها على تنسيق العديد من الوكلاء. لا يتعلق الأمر بذكاء اصطناعي أحادي متجانس؛ بل يتعلق بتناغم من الوكلاء المتخصصين الذين يعملون معاً. من خلال التنسيق الديناميكي، يمكن إضافة الوكلاء أو إزالتهم من المحادثة حسب الحاجة، حيث يساهم كل منهم بمهاراته الفريدة لمعالجة جوانب مختلفة من مشكلة معقدة.

لبناء سير عمل وكيلي مع تسليم المهام (handoffs):

  1. إنشاء الوكلاء: قم بتعريف وإنشاء جميع الوكلاء الضروريين، كل منهم مجهز بأدوات ونماذج وتعليمات محددة مصممة خصيصاً لدوره.
  2. تحديد تسليم المهام (Handoffs): حدد الوكلاء الذين يمكنهم تفويض المهام للآخرين. على سبيل المثال، قد يقوم وكيل خدمة العملاء الرئيسي بتسليم استعلام فني إلى وكيل متخصص في استكشاف الأخطاء وإصلاحها أو استعلام عن الفوترة إلى وكيل مالي.

تتيح عمليات تسليم المهام (handoffs) هذه سلسلة سلسة من الإجراءات. يمكن لطلب مستخدم واحد أن يؤدي إلى سلسلة متتالية من المهام عبر وكلاء متعددين، يتعامل كل منهم بشكل مستقل مع الجزء المخصص له. يفتح هذا النهج التعاوني كفاءة وفعالية غير مسبوقتين في حل المشكلات للتطبيقات الواقعية المعقدة.

الاستخدام الأساسي لواجهة برمجة تطبيقات وكلاء Mistral (Mistral Agents API)

بعد فهم قدرات واجهة برمجة تطبيقات وكلاء Mistral (Mistral Agents API)، دعنا نستكشف كيفية التفاعل معها. تقدم الواجهة البرمجية ثلاثة كائنات أساسية جديدة:

تجدر الإشارة إلى أنه يمكنك الاستفادة من العديد من الميزات، مثل المحادثات ذات الحالة (stateful) والموصلات المدمجة، دون إنشاء كائن "وكيل" رسمي والرجوع إليه صراحةً أولاً. يوفر هذا مرونة لحالات الاستخدام الأبسط.

إنشاء وكيل

لتحديد وكيل متخصص، تقوم بتقديم طلب إلى الواجهة البرمجية مع تحديد عدة معلمات:

إليك مثال على طلب cURL لإنشاء وكيل بسيط:

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

تحديث وكيل

يمكن تحديث الوكلاء بعد الإنشاء. المعلمات هي نفسها المستخدمة في الإنشاء. تؤدي هذه العملية إلى كائن وكيل جديد بالإعدادات المحدثة، مما يسمح بشكل فعال بإصدار وكلاءك.

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

إدارة المحادثات

بمجرد إنشاء وكيل (أو إذا كنت تستخدم الوصول المباشر)، يمكنك بدء المحادثات.

بدء محادثة:
تحتاج إلى توفير:

مثال (إدخال سلسلة نصية بسيطة):

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

متابعة محادثة:
لإضافة إلى محادثة موجودة:

مثال:

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

بث المخرجات (Streaming)

للتفاعلات في الوقت الفعلي، يمكن بث بدء المحادثات ومتابعتها عن طريق تعيين stream: true والتأكد من أن رأس Accept هو 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"
     }'

عند البث (streaming)، ستتلقى أنواعاً مختلفة من الأحداث تشير إلى تقدم ومحتوى الاستجابة، مثل:

تشكل هذه العمليات الأساسية الأساس لبناء تطبيقات ديناميكية وتفاعلية باستخدام وكلاء Mistral.

دمج واجهة برمجة تطبيقات وكلاء Mistral (Mistral Agents API) مع بروتوكول سياق النموذج (MCP)

في حين أن الموصلات المدمجة توفر قوة كبيرة، فإن قابلية توسيع وكلاء Mistral الحقيقية تتألق عند دمجها مع بروتوكول سياق النموذج (MCP).

ما هو MCP؟

بروتوكول سياق النموذج (MCP) هو معيار مفتوح مصمم لتبسيط دمج نماذج الذكاء الاصطناعي مع مصادر البيانات الخارجية والأدوات وواجهات برمجة التطبيقات (APIs) المتنوعة. يوفر واجهة موحدة وآمنة تسمح لأنظمة الذكاء الاصطناعي بالوصول إلى المعلومات السياقية الواقعية واستخدامها بكفاءة. بدلاً من بناء وصيانة العديد من عمليات التكامل المخصصة، يقدم MCP طريقة موحدة لنماذج الذكاء الاصطناعي للاتصال بالبيانات والأنظمة الحية، مما يؤدي إلى استجابات أكثر ملاءمة ودقة وقوة. للحصول على معلومات مفصلة، ارجع إلى التوثيق الرسمي لبروتوكول سياق النموذج (Model Context Protocol).

توفر حزمة تطوير برامج Python (SDK) من Mistral آليات تكامل سلسة لربط الوكلاء مع عملاء MCP. يتيح هذا لوكلائك التفاعل مع أي خدمة أو مصدر بيانات يعرض واجهة MCP، سواء كانت أداة محلية، أو واجهة برمجة تطبيقات (API) تابعة لجهة خارجية، أو نظام مؤسسي خاص.

سنستكشف ثلاثة سيناريوهات شائعة لاستخدام MCP مع وكلاء Mistral: خادم MCP محلي، وخادم MCP بعيد بدون مصادقة، وخادم MCP بعيد مع مصادقة. ستستخدم جميع الأمثلة كود Python غير متزامن.

السيناريو الأول: استخدام خادم MCP محلي

تخيل أن لديك سكربت أو خدمة محلية (على سبيل المثال، مزود معلومات طقس مخصص) تريد أن يتفاعل معها وكيل Mistral الخاص بك.

الخطوة 1: تهيئة عميل Mistral والإعداد
استورد الوحدات الضرورية من mistralai و mcp. يشمل ذلك Mistral، RunContext، StdioServerParameters (لخوادم MCP القائمة على العمليات المحلية)، و 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())

في هذا الإعداد، سيكون stdio_server.py هو السكربت الخاص بك الذي ينفذ منطق خادم MCP، ويتواصل عبر stdin/stdout. يدير RunContext التفاعل، وتجعل register_mcp_client خادم MCP المحلي متاحاً كأداة للوكيل. يمكنك أيضاً تسجيل دوال Python المحلية مباشرةً باستخدام @run_ctx.register_func.

البث المباشر (Streaming) مع خادم MCP محلي:
للبث، استخدم client.beta.conversations.run_stream_async ومعالجة الأحداث فور وصولها:

    # 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

السيناريو الثاني: استخدام خادم MCP بعيد بدون مصادقة

قد تعرض العديد من الخدمات العامة أو الداخلية واجهة MCP عبر HTTP/SSE دون الحاجة إلى مصادقة.

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

هنا، يتم استخدام MCPClientSSE مع SSEServerParams التي تشير إلى عنوان URL البعيد. يمكن للوكيل بعد ذلك الاستفادة من الأدوات التي يوفرها خادم MCP البعيد هذا. يتبع البث المباشر (Streaming) نفس النمط المستخدم في مثال MCP المحلي، باستخدام run_stream_async.

السيناريو الثالث: استخدام خادم MCP بعيد مع مصادقة (OAuth)

بالنسبة للخدمات التي تتطلب مصادقة OAuth2 (مثل Linear، Jira، إلخ)، تتضمن العملية بضع خطوات إضافية للتعامل مع تدفق التفويض.

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

يتضمن ذلك إعداد خادم HTTP محلي لالتقاط إعادة توجيه OAuth، وتوجيه المستخدم عبر صفحة تفويض المزود، وتبادل الكود المستلم مقابل رمز وصول (access token)، ثم تكوين MCPClientSSE باستخدام هذا الرمز. بمجرد المصادقة، يمكن للوكيل التفاعل مع خدمة MCP المحمية. يتبع البث المباشر (Streaming) مرة أخرى النمط المعمول به.

خاتمة: المستقبل وكيلي ومترابط

توفر واجهة برمجة تطبيقات وكلاء Mistral (Mistral Agents API)، خاصة عند تعزيزها ببروتوكول سياق النموذج (Model Context Protocol)، منصة قوية ومرنة لبناء تطبيقات الذكاء الاصطناعي من الجيل التالي. من خلال تمكين الوكلاء ليس فقط من التفكير والتواصل، بل أيضاً من التفاعل مع نظام بيئي واسع من الأدوات ومصادر البيانات والخدمات، يمكن للمطورين إنشاء أنظمة ذكية حقاً قادرة على معالجة المشكلات المعقدة في العالم الواقعي. سواء كنت تقوم بأتمتة سير العمل المعقد، أو تقديم مساعدة سياقية عميقة، أو ريادة أشكال جديدة من التعاون بين الإنسان والذكاء الاصطناعي، فإن الجمع بين وكلاء Mistral و MCP يوفر مجموعة الأدوات الأساسية لهذا المستقبل المثير. مع اكتساب معيار MCP اعتماداً أوسع، ستستمر إمكانية إنشاء وكلاء ذكاء اصطناعي مترابطين وذوي قدرات عالية في النمو.

💡
هل تريد أداة رائعة لاختبار واجهات برمجة التطبيقات (API Testing) تولد توثيقاً جميلاً لواجهة برمجة التطبيقات (API Documentation)؟

هل تريد منصة متكاملة وشاملة لفريق المطورين الخاص بك للعمل معاً بأقصى إنتاجية؟

Apidog يلبي جميع متطلباتك، ويحل محل Postman بسعر أقل بكثير!
button

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات

التسجيل مجانًاتحميل