إنشاء سير عمل ذكي متعدد الوكلاء باستخدام ميزة عمليات التسليم في واجهة برمجة تطبيقات وكلاء Mistral

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

مقدمة

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

الخطوة الأولى: إعداد التبعيات

تثبيت المكتبات

استخدم الأمر التالي لتثبيت المكتبات اللازمة:

pip install mistralai pydantic

تحميل مفتاح واجهة برمجة تطبيقات Mistral

يمكنك الحصول على مفتاح واجهة برمجة تطبيقات من الرابط التالي: https://console.mistral.ai/api-keys

from getpass import getpass
MISTRAL_API_KEY = getpass('أدخل مفتاح واجهة برمجة تطبيقات Mistral: ')

الخطوة الثانية: متطلبات الوكيل وإعداده

تهيئة الوكيل

from mistralai import CompletionArgs, ResponseFormat, JSONSchema
from pydantic import BaseModel
from mistralai import Mistral
client = Mistral(MISTRAL_API_KEY)

إنشاء الدالة المخصصة

تُحسب دالة adjust_for_inflation قيمة مبلغ معين من المال بعد حساب التضخم على مر الزمن. تستخدم الصيغة المركبة بناءً على عدد السنوات ومعدل التضخم السنوي. إذا كانت السنة النهائية قبل السنة الابتدائية، فإنها تُرجع خطأ. خلاف ذلك، فإنها تُرجع القيمة المُعدّلة مع تفاصيل الإدخال. على سبيل المثال، يُظهر adjust_for_inflation(1000, 1899, 2025, 10) قيمة 1000 روبية هندية من عام 1899 في عام 2025 بمعدل تضخم 10%.

def adjust_for_inflation(amount: float, start_year: int, end_year: int, annual_inflation_rate: float):
    """تحسب القيمة المعدلة للتضخم باستخدام الصيغة المركبة."""
    if end_year < start_year:
        return {"error": "يجب أن تكون السنة النهائية أكبر من أو تساوي السنة الابتدائية."}
    years = end_year - start_year
    adjusted_value = amount * ((1 + annual_inflation_rate / 100) ** years)
    return {
        "original_amount": amount,
        "start_year": start_year,
        "end_year": end_year,
        "inflation_rate": annual_inflation_rate,
        "adjusted_value": round(adjusted_value, 2)
    }

adjust_for_inflation(1000, 1899, 2025, 10)

إنشاء مخرجات منظمة للتفكير الرياضي

class CalcResult(BaseModel):
    reasoning: str
    result: str

inflation_tool = {
    "type": "function",
    "function": {
        "name": "adjust_for_inflation",
        "description": "احسب قيمة المال المعدلة للتضخم خلال فترة زمنية.",
        "parameters": {
            "type": "object",
            "properties": {
                "amount": {
                    "type": "number",
                    "description": "المبلغ الأصلي من المال"
                },
                "start_year": {
                    "type": "integer",
                    "description": "السنة الابتدائية لضبط التضخم"
                },
                "end_year": {
                    "type": "integer",
                    "description": "السنة النهائية لضبط التضخم"
                },
                "annual_inflation_rate": {
                    "type": "number",
                    "description": "معدل التضخم السنوي كنسبة مئوية"
                }
            },
            "required": ["amount", "start_year", "end_year", "annual_inflation_rate"]
        }
    }
}

الخطوة الثالثة: إنشاء الوكلاء

تعريف الوكلاء المختلفين

في هذا الإعداد، نُعرّف نظامًا متعدد الوكلاء باستخدام واجهة برمجة تطبيقات وكلاء Mistral للتعامل مع الاستعلامات الاقتصادية المتعلقة بالتضخم. يعمل الوكيل الرئيسي (economics-agent) كمنسق يُوجّه المهام إلى وكلاء متخصصين. يقوم وكيل التضخم (inflation-agent) بإجراء عمليات حسابية لضبط التضخم باستخدام دالة مخصصة. إذا كان معدل التضخم مفقودًا من الاستعلام، فإن وكيل البحث على الويب (websearch-agent) يستخرجه من الإنترنت. يتعامل وكيل الحاسبة (calculator-agent) مع العمليات الحسابية المعقدة مع التفكير خطوة بخطوة، بينما يستخدم وكيل الرسم البياني (graph-agent) مُفسّر التعليمات البرمجية لتصور اتجاهات التضخم بمرور الوقت. تعمل هذه الوكلاء معًا عبر عمليات التسليم لتقديم استجابات دقيقة وديناميكية للاستعلامات الاقتصادية.

# الوكيل الرئيسي
economics_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="economics-agent",
    description="يتعامل مع الاستعلامات الاقتصادية ويُوكل حسابات التضخم.",
)

# وكيل دالة التضخم
inflation_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="inflation-agent",
    description="الوكيل الذي يحسب القيمة المعدلة للتضخم باستخدام دالة مخصصة.",
    tools=[inflation_tool],
)

# وكيل البحث على الويب
websearch_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="websearch-agent",
    description="الوكيل الذي يمكنه البحث في الإنترنت عن البيانات الاقتصادية المفقودة مثل معدلات التضخم.",
    tools=[{"type": "web_search"}]
)

# وكيل الحاسبة
calculator_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="calculator-agent",
    description="الوكيل المستخدم لإجراء حسابات مفصلة.",
    instructions="عند إجراء الحسابات، اشرح خطوة بخطوة.",
    completion_args=CompletionArgs(
        response_format=ResponseFormat(
            type="json_schema",
            json_schema=JSONSchema(
                name="calc_result",
                schema=CalcResult.model_json_schema(),
            )
        )
    )
)

# وكيل الرسم البياني
graph_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="graph-agent",
    description="الوكيل الذي يُنشئ الرسوم البيانية باستخدام مُفسّر التعليمات البرمجية.",
    instructions="استخدم مُفسّر التعليمات البرمجية لرسم اتجاهات التضخم.",
    tools=[{"type": "code_interpreter"}]
)

تعريف مسؤوليات عمليات التسليم

يُعرّف هذا التكوين كيفية قيام الوكلاء بتفويض المهام لبعضهم البعض:

• الوكيل الرئيسي (economics_agent): يعمل كنقطة دخول ويُوكل الاستعلامات إما إلى inflation_agent (لإجراء حسابات التضخم) أو websearch_agent (لاستخراج البيانات المفقودة مثل معدلات التضخم).
• وكيل التضخم (inflation_agent): بعد استلام الاستعلام من المستخدم أو البيانات المستخرجة من الويب، يمكنه تمرير المهام إلى calculator_agent (للحسابات التفصيلية) أو graph_agent (للتصور).
• وكيل البحث على الويب (websearch-agent): يمكنه تمرير التحكم إلى inflation_agent بعد استخراج المعلومات المطلوبة، مثل معدل التضخم.
• calculator_agent و graph_agent: يُعتبران وكلاء نهائيين. ومع ذلك، تم تمكين عملية التسليم المتبادلة الاختيارية في حالة الحاجة إلى إجراء عمل متابعة (مثل رسم بياني لنتيجة محسوبة أو العكس).

# الوكيل الرئيسي يُوكل إلى inflation_agent و websearch_agent
economics_agent = client.beta.agents.update(
    agent_id=economics_agent.id,
    handoffs=[inflation_agent.id, websearch_agent.id]
)

# وكيل التضخم يمكنه التفويض إلى calculator_agent أو graph_agent إذا كانت هناك حاجة لتحليل أعمق أو تصور
inflation_agent = client.beta.agents.update(
    agent_id=inflation_agent.id,
    handoffs=[calculator_agent.id, graph_agent.id]
)

# وكيل البحث على الويب يمكنه التفويض إلى inflation_agent (بعد العثور على المعدل المفقود)
websearch_agent = client.beta.agents.update(
    agent_id=websearch_agent.id,
    handoffs=[inflation_agent.id]
)

# وكلاء الحاسبة والرسم البياني نهائيين - لا يُوكلون أكثر
# لكن إذا لزم الأمر، يمكننا السماح لهم بالتسليم لبعضهم البعض:
calculator_agent = client.beta.agents.update(
    agent_id=calculator_agent.id,
    handoffs=[graph_agent.id]  # اختياري
)
graph_agent = client.beta.agents.update(
    agent_id=graph_agent.id,
    handoffs=[calculator_agent.id]  # اختياري
)

الخطوة الرابعة: تشغيل الوكيل

مثال أ: ما هو معدل التضخم الحالي في الهند؟

في هذا المثال، يتم تمرير المطالبة “ما هو معدل التضخم الحالي في الهند؟” إلى economics_agent، وهي نقطة الدخول الرئيسية للتعامل مع الاستعلامات الاقتصادية. نظرًا لأن السؤال يتطلب بيانات في الوقت الفعلي غير مدرجة في معرفة الوكيل الثابتة، فإن economics_agent يُوكل تلقائيًا الاستعلام إلى websearch_agent، المجهز بقدرات البحث على الويب.

prompt = "ما هو معدل التضخم الحالي في الهند؟"
response = client.beta.conversations.start(
    agent_id=economics_agent.id, inputs=prompt
)
print(response.outputs[-1].content[0].text)

مثال ب: ما هي القيمة المعدلة للتضخم لـ 5000 من عام 2010 إلى 2023 بمعدل تضخم سنوي قدره 6.5٪؟ اشرح خطوات الحساب وارسم رسمًا بيانيًا مع تسميات البيانات

يقوم هذا الكتلة البرمجية بإرسال المطالبة إلى وكيل الاقتصاد، ويتحقق مما إذا كان الوكيل يُشغّل مُكالمة دالة محددة (adjust_for_inflation)، وينفذ هذه الدالة محليًا باستخدام الوسائط المُقدمة، ثم يُرجع النتيجة المحسوبة إلى الوكيل. أخيرًا، يقوم بطباعة استجابة الوكيل، والتي تتضمن شرح حساب التضخم، بالإضافة إلى رمز Python لرسم الاتجاه.

import json
from mistralai.models import FunctionResultEntry

prompt = """ما هي القيمة المعدلة للتضخم لـ 5000 من عام 2010 إلى 2023 بمعدل تضخم سنوي قدره 6.5٪؟ اشرح خطوات الحساب وارسم رسمًا بيانيًا مع تسميات البيانات"""
response = client.beta.conversations.start(
    agent_id=economics_agent.id, inputs=prompt
)

# التحقق من مكالمة الدالة
if response.outputs[-1].type == "function.call" and response.outputs[-1].name == "adjust_for_inflation":
    args = json.loads(response.outputs[-1].arguments)
    # تشغيل الدالة المحلية
    function_result = json.dumps(adjust_for_inflation(**args))
    #

المصدر: MarkTechPost