مشاركة عبر

إنشاء سير عمل وكلاء مستضاف في Visual Studio Code (معاينة)

إنشاء واختبار ونشر مستضاف Foundry Agent Workflows باستخدام Microsoft Foundry لإضافة Visual Studio Code. تسمح سير العمل المستضافة لعدة وكلاء بالتعاون بالتتابع، لكل منهم نموذجه وأدواته وتعليماته الخاصة.

قبل أن تبدأ، بناء وكيل في Foundry Agent Service باستخدام الامتداد. يمكنك بعد ذلك إضافة سير عمل مستضاف إلى ذلك الوكيل.

تغطي هذه المقالة إنشاء project سير عمل، تشغيله محليا، تصور التنفيذ، ونشره في مساحة عمل Foundry الخاصة بك.

المتطلبات المسبقه

  • project Foundry مع نموذج منشور، أو مورد Azure OpenAI.
  • تم تثبيت Microsoft Foundry for Visual Studio Code على التواصل.
  • تم إدارة هوية project مع تعيين أدوار Azure AI User وAcrPull. كما قم بتعيين دور acrPull لهوية إدارة project Foundry حيث تخطط لنشر الوكيل المستضاف.
  • منطقة مدعومة للوكلاء المستضافين.
  • بايثون 3.10 أو أعلى.

إنشاء سير عمل وكيل مستضاف

يمكنك استخدام إضافة Foundry for Visual Studio Code لإنشاء سير عمل للوكلاء المستضافين. سير عمل الوكيل المستضاف هو تسلسل من الوكلاء الذين يعملون معا لإنجاز مهمة معينة. يمكن أن يكون لكل عامل في سير العمل نموذجه وأدواته وإرشاداته الخاصة.

  1. افتح لوحة الأوامر (Ctrl+Shift+P).

  2. قم بتشغيل هذا الأمر: >Microsoft Foundry: Create a New Hosted Agent.

  3. حدد لغة برمجة.

  4. حدد مجلدا تريد حفظ سير العمل الجديد فيه.

  5. أدخل اسما لسير العمل project.

يتم إنشاء مجلد جديد يحتوي على الملفات اللازمة ل project الوكيل المستضاف، بما في ذلك ملف كود نموذجي لمساعدتك على البدء.

تثبيت التبعيات

قم بتثبيت التبعيات المطلوبة لوكيلك المستضاف project. تختلف التبعيات حسب لغة البرمجة التي اخترتها عند إنشاء project.

  1. أنشئ بيئة افتراضية.

     python -m venv .venv

  2. نشّط البيئة الظاهرية.

    # PowerShell
./.venv/Scripts/Activate.ps1

# Windows cmd
.venv\Scripts\activate.bat

# Unix/MacOS
source .venv/bin/activate

  3. تثبيت الحزمة التالية:

    pip install azure-ai-agentserver-agentframework

  1. اذهب إلى مجلد project الخاص بك وشغل هذا الأمر للحصول على حزم NuGet اللازمة:

    dotnet restore

شغل سير العمل المستضاف محليا

ينشئ project النموذج لسير العمل ملف .env يحتوي على المتغيرات الضرورية للبيئة. أنشئ أو حدث ملف .env باستخدام بيانات اعتماد Foundry الخاصة بك:

AZURE_AI_PROJECT_ENDPOINT=https://<your-resource-name>.services.ai.azure.com/api/projects/<your-project-name>

AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

مهم

لا تقم أبدا بتثبيت الملف .env على التحكم في الإصدار. أضفه إلى ملفك .gitignore .

تحقق من صحة وكيلك المستضاف

عينة الوكيل المستضاف تصادق باستخدام DefaultAzureCredential. قم بتكوين بيئة التطوير الخاصة بك لتوفير بيانات الاعتماد عبر أحد المصادر المدعومة، على سبيل المثال:

  • Azure CLI (az login)
  • تسجيل دخول حساب Visual Studio Code
  • تسجيل دخول حساب Visual Studio
  • متغيرات البيئة لمبدأ الخدمة (AZURE_TENANT_ID، AZURE_CLIENT_ID، AZURE_CLIENT_SECRET)

تأكد من المصادقة محليا بتشغيل أوامر Azure CLI az account show أو az account get-access-token قبل تشغيل العينة.

يمكنك تشغيل الوكيل المستضاف في الوضع التفاعلي أو وضع الحاوية.

شغل وكيلك المستضاف في الوضع التفاعلي

اضغط F5 في VS Code لبدء التصحيح. بدلا من ذلك، يمكنك استخدام قائمة تصحيح أخطاء VS Code:

  1. افتح عرض التشغيل والتصحيح (Ctrl+Shift+D / cmd+Shift+D)
  2. اختر "تصحيح سير العمل المحلي HTTP Server" من القائمة المنسدلة
  3. اختر زر بدء التصحيح الأخضر (أو اضغط F5)

سيؤدي ذلك إلى:

  1. شغل خادم HTTP مع تفعيل التصحيح
  2. افتح أداة AI Toolkit Agent Inspector للاختبار التفاعلي
  3. يسمح لك بتعيين نقاط توقف وفحص تنفيذ سير العمل في الوقت الحقيقي.

شغل الوكيل المستضاف في وضع الحاوية

نصيحة

افتح الملعب المحلي قبل بدء وكيل الحاوية للتأكد من أن التصور يعمل بشكل صحيح.

لتشغيل الوكيل المستضاف في وضع الحاوية:

  1. افتح لوحة أوامر الشيفرة Visual Studio ونفذ أمر Microsoft Foundry: Open Container Agent Playground Locally.
  2. نفذ main.py لتهيئة الوكيل المستضاف المعبأ في الحاويات.
  3. قدم طلبا إلى الوكيل عبر واجهة الملعب. على سبيل المثال، أدخل طلبا مثل: "أنشئ شعارا لسيارة SUV كهربائية جديدة بأسعار معقولة وممتعة في القيادة."
  4. راجع رد الوكيل في واجهة الملعب.

ينشئ project النموذج لسير العمل ملف .env يحتوي على المتغيرات الضرورية للبيئة. أنشئ أو حدث ملف .env باستخدام بيانات اعتماد Foundry الخاصة بك:

  1. قم بإعداد متغيرات البيئة الخاصة بك بناء على نظام التشغيل الخاص بك:

    $env:AZURE_AI_PROJECT_ENDPOINT="https://<your-resource-name>.services.ai.azure.com/api/projects/<your-project-name>"
$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="your-deployment-name"

تحقق من صحة وكيلك المستضاف

عينة الوكيل المستضاف تصادق باستخدام DefaultAzureCredential. قم بتكوين بيئة التطوير الخاصة بك لتوفير بيانات الاعتماد عبر أحد المصادر المدعومة، على سبيل المثال:

  • Azure CLI (az login)
  • تسجيل دخول حساب Visual Studio Code
  • تسجيل دخول حساب Visual Studio
  • متغيرات البيئة لمبدأ الخدمة (AZURE_TENANT_ID، AZURE_CLIENT_ID، AZURE_CLIENT_SECRET)

تأكد من المصادقة محليا بتشغيل أوامر Azure CLI az account show أو az account get-access-token قبل تشغيل العينة.

يمكنك تشغيل الوكيل المستضاف في الوضع التفاعلي أو وضع الحاوية.

شغل وكيلك المستضاف في الوضع التفاعلي

شغل الوكيل المستضاف مباشرة للتطوير والاختبار:

dotnet restore
dotnet build
dotnet run

شغل الوكيل المستضاف في وضع الحاوية

نصيحة

افتح الملعب المحلي قبل بدء وكيل الحاوية للتأكد من أن التصور يعمل بشكل صحيح.

لتشغيل الوكيل في وضع الحاوية:

  1. افتح لوحة أوامر الشيفرة Visual Studio ونفذ أمر Microsoft Foundry: Open Container Agent Playground Locally.
  2. استخدم الأمر التالي لتهيئة الوكيل المستضاف المعبأ في الحاويات. 
    dotnet restore
dotnet build
dotnet run
  3. قدم طلبا إلى الوكيل عبر واجهة الملعب. على سبيل المثال، أدخل طلبا مثل: "أنشئ شعارا لسيارة SUV كهربائية جديدة بأسعار معقولة وممتعة في القيادة."
  4. راجع رد الوكيل في واجهة الملعب.

تصور تنفيذ سير عمل الوكلاء المستضاف

يوفر إضافة Foundry for Visual Studio Code رسما بيانيا لتنفيذ الوقت الحقيقي يوضح كيف يتفاعل الوكلاء في سير عملك ويتعاونون. فعل الملاحظة في project الخاص بك لاستخدام هذا التصور.

قم بتمكين التصور في مهام سير العمل عن طريق إضافة قصاصة البرمجة التالية:

from agent_framework.observability import setup_observability
setup_observability(vs_code_extension_port=4319) # Default port is 4319

أضف المرجع التالي إلى ملف csproj الخاص بك:

<ItemGroup>
    <PackageReference Include="OpenTelemetry" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
    <PackageReference Include="System.Diagnostics.DiagnosticSource" Version="9.0.10" />
</ItemGroup>

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

using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

var otlpEndpoint =
    Environment.GetEnvironmentVariable("OTLP_ENDPOINT") ?? "http://localhost:4319";

var resourceBuilder = OpenTelemetry
    .Resources.ResourceBuilder.CreateDefault()
    .AddService("WorkflowSample");

var s_tracerProvider = OpenTelemetry
    .Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource("Microsoft.Agents.AI.*") // All agent framework sources
    .SetSampler(new AlwaysOnSampler()) // Ensure all traces are sampled
    .AddOtlpExporter(options =>
    {
        options.Endpoint = new Uri(otlpEndpoint);
        options.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.Grpc;
    })
    .Build();

راقب وتصور سير عمل الوكيل المستضاف لديك

لمراقبة وتصور تنفيذ سير عمل الوكيل المستضاف في الوقت الحقيقي:

  1. افتح لوحة الأوامر (Ctrl+Shift+P).

  2. قم بتشغيل هذا الأمر: >Microsoft Foundry: Open Visualizer for Hosted Agents.

يتم فتح علامة تبويب جديدة في VS Code لعرض الرسم البياني للتنفيذ. يتم تحديث التصور نفسه تلقائيا مع تقدم سير العمل، لإظهار التدفق بين الوكلاء وتفاعلاتهم.

صراعات الموانئ

بالنسبة لتعارضات المنافذ، يمكنك تغيير منفذ التصور عن طريق تعيينه في إعدادات إضافة Foundry. To do ذلك، اتبع هذه الخطوات:

  1. في الشريط الجانبي الأيسر من VS Code، اختر أيقونة المعدات لفتح قائمة الإعدادات.
  2. اختر Extensions>Microsoft Foundry Configuration.
  3. حدد الإعداد Hosted Agent Visualization Port وغير الرقم إلى رقم منفذ متاح.
  4. إعادة التشغيل مقابل كود لتطبيق التغييرات.

تغيير المنفذ في الكود

غير منفذ التصور عن طريق تعيين FOUNDRY_OTLP_PORT متغير البيئة. قم بتحديث منفذ قابلية الملاحظة في workflow.py الملف وفقا لذلك.

على سبيل المثال، لتغيير المنفذ إلى 4318، استخدم هذا الأمر:

  export FOUNDRY_OTLP_PORT=4318

في workflow.py، قم بتحديث رقم المنفذ في تكوين إمكانية الملاحظة:

  setup_observability(vs_code_extension_port=4318)

نصيحة

لتمكين المزيد من معلومات التصحيح، أضف المعامل enable_sensitive_data=True إلى الدالة setup_observability .

بالنسبة لأي تعارض في المنافذ، غير منفذ التصور عن طريق تعيين FOUNDRY_OTLP_PORT متغير البيئة. قم بتحديث نقطة نهاية OTLP في برنامجك وفقا لذلك.

على سبيل المثال، لتغيير المنفذ إلى 4318، استخدم هذا الأمر:

  $env:FOUNDRY_OTLP_PORT="4318"

في برنامجك، قم بتحديث نقطة نهاية OTLP لاستخدام رقم المنفذ الجديد:

var otlpEndpoint =
    Environment.GetEnvironmentVariable("OTLP_ENDPOINT") ?? "http://localhost:4318";

نشر الوكيل المستضاف

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

مهم

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

  1. افتح لوحة أوامر الشيفرة Visual Studio وشغل أمر Microsoft Foundry: Deploy Hosted Agent.
  2. قم بتكوين إعدادات النشر باختيار مساحة العمل المستهدفة، وتحديد ملف وكيل الحاوية (container.py)، وتحديد أي معلمات نشر أخرى حسب الحاجة.
  3. عند النشر الناجح، يظهر الوكيل المستضاف في Hosted Agents (Preview) قسم عرض شجرة التوسعات في مايكروسوفت فاوندري.
  4. اختر الوكيل المنشور ل access المعلومات التفصيلية ووظائف الاختبار باستخدام واجهة الملعب المدمجة.
  1. افتح لوحة أوامر الشيفرة Visual Studio وشغل أمر Microsoft Foundry: Deploy Hosted Agent.
  2. قم بتكوين إعدادات النشر باختيار مساحة العمل المستهدفة، وتحديد ملف وكيل الحاوية (<your-project-name>.csproj)، وتحديد أي معلمات نشر أخرى حسب الحاجة.
  3. عند النشر الناجح، يظهر الوكيل المستضاف في Hosted Agents (Preview) قسم عرض شجرة التوسعات في مايكروسوفت فاوندري.
  4. اختر الوكيل المنشور ل access المعلومات التفصيلية ووظائف الاختبار باستخدام واجهة الملعب المدمجة.

المحتوى ذو الصلة

  • Last updated on