Agent bindings for Python in دالات Azure

تتيح لك روابط الوكلاء لتطبيقات وظائف Python إضافة سلوكيات وكالية إلى الدوال الموجودة. عندما تعمل الدالة، يقوم Agent الامتداد ببناء تعليمات من ماركداون ويحقنها في معالجك كمعامل مصنف. كودك يقرر متى وكيف تستدعي الوكيل إلى جانب منطق التطبيق الحتمي.

مهم

روابط الوكلاء لتطبيقات وظائف Python حاليا قيد المعاينة. يمكن أن تتغير الميزات وأسماء الحزم والتكوين قبل التوفر العام.

لمقارنة روابط الوكلاء مع ميزات أخرى متعلقة بالذكاء الاصطناعي، مثل المهارات المستضافة في دالات Azure وأدوات بروتوكول السياق النموذجي (MCP)، راجع خيارات تكامل الذكاء الاصطناعي ل دالات Azure.

ربط الوكيل هو ربط إدخال مملوك من قبل الامتداد يوفر كائنا مكتملا Agent لدالة Python. تقرأ الإضافة تعليمات الوكيل كنص خام من ملف .agent.md . يحتفظ كود التطبيق بتكوين الأدوات الخاصة بالعميل والمزود، بينما يمكن لمشروع تطبيق الوظيفة اكتشاف مهارات الوكلاء المعتمدين على الملفات وخوادم MCP البعيدة.

تدعم بنية ربط الوكيل كائنات الوكلاء من مجموعات SDK مختلفة عبر حزم امتدادات خاصة بالمزود. إطار عمل Microsoft Agent هو مجموعة تطوير الوكلاء الوحيدة المدعومة في المعاينة الحالية. لاستخدامه، قم بتثبيت الحزمة azurefunctions-agents-extensions-agent-framework .

متى تستخدم روابط الوكيل

استخدم ربط الوكلاء عندما تحتاج دالة Azure إلى التفكير الوكيل كجزء من سير العمل، لكن يجب على تطبيقك أن يحتفظ بالتحكم في المشغل، والتحقق من صحته، والتفرع، والتعامل مع الأخطاء، والاستجابة. تتضمن السيناريوهات الشائعة ما يلي:

• قيم طلب HTTP. تحقق من صحة الطلب باستخدام كود حتمي، واطلب من وكيل تقييم مخاطر التنفيذ، واستخدم النتيجة لبناء استجابة HTTP.
• إثراء أو تصنيف الأحداث. استلم رسالة طابور، حدث شبكة الحدث، أو حمولة محفزة أخرى واستخدم وكيلا لتصنيف أو تلخيص أو إثراء البيانات قبل أن تكتب دالة النتيجة.
• أضف التفكير إلى سير عمل مستدام. استدعي وكيلا من منسق Durable Functions عبر واجهة برمجة التطبيقات الآمنة context.call_agent() لإعادة التشغيل، ثم استخدم النتيجة في خطوات التنسيق اللاحقة.

روابط الوكيل تناسب جيدا عندما يبقى الرمز الحتمي للدالة هو المنسق. يقوم الوكيل بمهمة استدلالية محدودة ويعيد السيطرة إلى المعالج أو التنسيق.

لماذا تستخدم روابط الوكيل؟

تجمع العديد من سير العمل الإنتاجي بين خطوات يجب أن تكون حتمية وخطوات تستفيد من التفكير النموذجي. توفر روابط الوكلاء الفوائد التالية لهذه سير العمل الهجينة:

• أضف سلوك الوكلاء إلى الدوال الموجودة. استخدم التفكير الوكيل من HTTP-، والمؤقت-، والطابور-، وشبكة الأحداث-، و Service Bus-، وغيرها من الوظائف التي يتم تفعيلها.
• استدعاء عامل التحكم بأمان في الشيفرة. يقرر متى يتم استدعاء الوكيل، وفحص استجابته، وتحديد مخرجات الدالة. يغلق الامتداد الموارد المملوكة للاستدعاء بعد النجاح أو الفشل أو الإلغاء.
• تقليل كود إعداد الوكيل. استلم Configed Agent كمعامل معالج مصنف بدلا من بنائها وتوصيلها لكل استدعاء.
• افصل التعليمات عن تكوين وقت التشغيل. تخزين تعليمات اللغة الطبيعية في .agent.md ملف وقم بتكوين العملاء والأدوات الخاصة بمزود الخدمة بشكل صريح في Python.
• استخدم قدرات الوكيل المشترك. يكتشف الامتداد مهارات الوكلاء المعتمدة على الملفات وخوادم MCP المعتمدة على HTTP من جذر التطبيق ويجعلها متاحة لكل وكيل مرتبط.
• اتصل بالعملاء من الفرق الدائمة. يدير الامتداد عمل الوكلاء في نشاط مخفي بحيث يبقى إعادة تشغيل التوزيع حتميا.
• قم بتصحيح الأخطاء محليا باستخدام الأدوات المألوفة. شغل وتصحيح التطبيق محليا مثل أي تطبيق وظائف Python آخر. يمكنك تعيين نقاط توقف والمرور عبر كل من منطق الدوال الحتمية والكود الذي يستدعي الوكيل.

كيف يعمل ربط العامل

AgentFunctionApp يمتد azure.functions.FunctionApp، لذا له نفس القدرات مثل FunctionApp. markdown_agent يضيف المصمم مدخلا للعامل إلى دالة.

لكل ارتباط وكيل، يقوم الامتداد بتنفيذ العمليات التالية:

1. يحل الملف المطلوب .agent.md من جذر تطبيق الوظائف أو دليله agents/ .
2. يقوم بتحميل الملف الكامل كتعليمات UTF-8 الخام.
3. يجمع التعليمات مع مصنع العميل المكون، وأدوات المزود المهيأة بشكل صريح، ومهارات الوكلاء المكتشفة وخوادم MCP.
4. يخلق حالة جديدة Agent ويفتح الموارد المملوكة للاستدعاء.
5. يحقن في Agent معامل المعالج.
6. يغلق الموارد المملوكة للاستدعاء عند انتهاء التنفيذ.

يمكن للإضافة تخزين اكتشاف المزودين وتعريفات الربط المجمعة مؤقتا. لا يقوم بتخزين أو إعادة استخدام موارد الاستدعاء الحية عبر استدعاءات الدوال.

تعريف ربط الوكيل

المثال التالي يستخدم مزود Microsoft Agent Framework المدعوم حاليا لإضافة إلى Agent دالة يتم تفعيلها بواسطة HTTP. تقوم الدالة ببناء المهمة في الشيفرة، وتستدعي الوكيل، وتعيد استجابة الوكيل:

import azure.functions as func
from agent_framework import Agent
from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.function_name(name="ProcessOrder")
@app.route(route="orders/{orderId}", methods=["POST"])
@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    task = (
        "Validate the order and return fulfillment guidance for "
        f"{req.route_params['orderId']}."
    )
    response = await order_agent.run(task)
    return func.HttpResponse(response.text)

يجب أن تتطابق القيمة arg_name مع معامل المعالج المحقون. لحقن عدة وكلاء في نفس الدالة، قم بتكديس markdown_agent الديكورات واستخدام معامل فريد arg_name ومعامل معالج لكل ربط وكيل. agent_name القيمة تحدد ملف التعليمات. في هذا المثال، order-fulfillment يجب أن تحل إلى واحد من هذه المواقع بالضبط:

<app_root>/order-fulfillment.agent.md
<app_root>/agents/order-fulfillment.agent.md

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

تكوين عميل الوكيل والأدوات

قم بتكوين وسيط client_factory صفري عند بناء AgentFunctionApp. المصنع يعيد عميلا جديدا مدعوما من حزمة المزود. يمكنك أيضا تمرير كائنات أدوات Microsoft Agent Framework أو ملفات Python القابلة للاستدعاء عبر المعلمة tools على مستوى التطبيق. يمكن للربط أن يتجاوز مصنع وأدوات العميل على مستوى التطبيق عندما يتطلب سلوكا مختلفا.

على سبيل المثال، تستخدم الدالة التالية التي تعمل بتقنية HTTP ربطا للوكيل يتوفر lookup_inventory كأداة فقط ل order_agent:

def lookup_inventory(product_id: str) -> str:
    """Return the available inventory for a product."""
    return f"Inventory is available for {product_id}."


@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
    tools=[lookup_inventory],
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    response = await order_agent.run(req.get_body().decode())
    return func.HttpResponse(response.text)

ضع هذه الاعتبارات في اعتبارك عند تكوين عميل الوكيل والأدوات:

• امتداد الوكيل الأساسي محايد من قبل المزود. تدمج حزمة المزود مجموعة SDK الخاصة بوكيل معين وتحدد أنواع العميل والوكيل المدعومين.
• حزمة مزود إطار عمل Microsoft Agent المدعومة حاليا لا تختار أو تحدد مزود نموذج لتطبيقك. يحدد مصنع العميل أي عميل دردشة مدعوم من Microsoft Agent Framework ونموذج يستخدمه الوكيل.
• يمرر الامتداد الملف بالكامل .agent.md إلى المزود المكون كتعليمات وكيل. لا يقوم بتحليل إعدادات النماذج أو الأدوات أو مواد YAML الأمامية أو أي إعدادات وقت تشغيل أخرى من الملف.

مهارات الوكيل المشتركة وخوادم MCP

يكتشف الامتداد تلقائيا قدرات الوكيل المشترك من جذر التطبيق:

القدرة	الموقع	السلوك
مهارات الوكيل	skills/<skill-name>/SKILL.md او Skills/<skill-name>/SKILL.md	حزمة المزود تقوم بتحميل والتحقق من مهارة الوكيل المعتمد على الملفات.
خوادم MCP البعيدة	mcp.json	تقوم الإضافة بتكوين خوادم HTTP المدعومة أو خوادم HTTP القابلة للبث وقوائم أدوات اختيارية.
أدوات المزودين	تكوين التطبيق أو الربط	يتم توفير كائنات أدوات Microsoft Agent Framework أو القابلات للاستدعاء في Python بشكل صريح بدلا من اكتشافها.

ضع هذه الاعتبارات في اعتبارك عند استخدام قدرات الوكيل المشترك:

• كل ربط وكيل في تطبيق الدالة يستقبل جميع مهارات الوكيل المكتشفة وخوادم MCP.
• مهارات الوكيل المعتمد على الملفات هي قدرات يمكن للوكيل تحميلها. ليست مهارات مستضافة من دالات Azure، والتي تستخدم نموذج تنفيذ منفصل.
• المعاينة الحالية لإضافة الوكيل لا تدعم اختيار مجموعة فرعية من القدرات لتطبيق أو ربط فردي.
• مهارات الوكيل وأدوات MCP يمكنها تنفيذ عمليات مميزة. ضع فقط القدرات التي يسمح لكل وكيل في التطبيق باستخدامها، واستخدم تطبيقات وظائف منفصلة عندما يحتاج الوكلاء إلى حدود قدرات مختلفة.

يمكن لتكوين MCP الإشارة إلى متغيرات البيئة لعناوين URL، والرؤوس، ونطاق المصادقة، ومعرفات العملاء. يتم حل المراجع لكل استدعاء، قبل أن يتصل الامتداد بالخادم. لا تخزن الأسرار مباشرة في ملف يتحكم mcp.json فيه المصدر.

خوادم MCP المحلية وخوادم الإدخال/الإخراج القياسية (stdio) غير مدعومة. دعم MCP هو تبعية اختيارية، وتبقى عمليات استيراد الحزم العادية آمنة عندما لا تكون مثبتة.

استخدم روابط الوكيل مع Durable Functions

تدعم روابط الوكلاء سير عمل هجين وطويل الأمد من خلال تكامل اختياري مع Durable Functions. يقوم منسق المولد المتزامن باستدعاء context.call_agent() ويعطي المهمة الناتجة:

from typing import Any

from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.orchestration_trigger(context_name="context")
def order_orchestrator(context: Any):
    assessment = yield context.call_agent(
        "order-fulfillment",
        {"order": context.get_input()},
    )
    return assessment

call_agent() يجدول نشاطا مخفيا يحل تعريف الوكيل وينفذ جميع عمليات النموذج، ونظام الملفات، وبيانات الاعتماد، والأداة، والشبكة. يقوم المنسق فقط بإنشاء طلب مخطط v1 حتمي قابل للتسلسل عبر JSON. وبالتالي، لا يكرر إعادة تشغيل التوزيع عمليات الوكيل غير الحتمية.

تستخدم مكالمات الوكيل الدائم المزود والقدرات المشتركة المكونة بواسطة AgentFunctionApp. يجب أن تكون المدخلات والمخرجات قابلة للتسلسلي ب JSON.

دعم Durable Functions اختياري. التطبيقات التي لا تستخدمها لا تحتاج إلى تثبيت أو استيراد Durable Functions. لاستخدام orchestration_trigger و context.call_agent()، قم بتثبيت حزمة المزود المدعوم مع ميزة الاعتماد الدائم الإضافية.

ملفات Project

التطبيق الفعال للوكيل هو تطبيق دالة قياسي على Python v2 مع تبعيات امتدادات الوكيل وملف أو أكثر من ملفات التعليمات:

ملف أو مجلد	الغرض
function_app.py	يحدد AgentFunctionApp، مشغلات الوظائف القياسية، وروابط الوكلاء، ومصانع العملاء، وأدوات المزود المكونة صراحة.
host.json	Conconfiguration the دالات Azure host.
requirements.txt	يتضمن حزمة مزود وكيل مدعوم وأي حزمة عميل خاصة ب SDK. للمعاينة الحالية، استخدم azurefunctions-agents-extensions-agent-framework. تتيح الإضافات الاختيارية دعم Durable Functions وMCP.
*.agent.md او agents/*.agent.md	يحتوي على تعليمات UTF-8 الخام للوكيل. يجب أن يحل كل اسم مرجع إلى ملف واحد بالضبط.
skills/ او Skills/	(اختياري) يحتوي على مهارات الوكيل القائمة على الملفات التي يشاركها جميع ربطات الوكلاء.
mcp.json	(اختياري) يحدد خوادم MCP البعيدة المعتمدة على HTTP والتي تشاركها جميع الروابط الوكيلية.

للاطلاع على هيكل المشروع Python القياسي، راجع دليل المطور دالات Azure Python.

التحقق والتشخيص

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

• ملفات مفقودة أو غامضة .agent.md .
• توقيعات المعالج غير صالحة، بما في ذلك معامل حقن مفقود أو غير متطابق.
• خيارات أو قدرات مزود غير مدعوم.
• أدلة المهارات غير صالحة وتكوين MCP غير مشوه.
• نقل MCP غير مدعوم وقيم بيئية مفقودة.
• حمولات أو قيم غير صالحة Durable غير قابلة للتسلسلي عبر JSON.

حيثما توفرت التوفر، يحافظ الامتداد على اسم دالة Azure، ومعرف الاستدعاء، ومعرف الحالة الدائمة عند حدود المزود لدعم الارتباط والتشخيص.

المقالات ذات الصلة

• خيارات AI integration for دالات Azure
• استخدم وكيل Microsoft Agent Framework في دالة Python
• استخدم ربط وكيل Microsoft Agent Framework في تنسيق Durable
• نظرة عامة على إطار عمل وكلاء مايكروسوفت