تثبيت واستخدام واجهة Agent 365 CLI

تُعد Agent 365 CLI أداة سطر أوامر متعددة المنصات لنشر تطبيقات Agent 365 على Azure وإدارتها. يوضح هذا المرجع كيفية تثبيت واجهة سطر الأوامر (CLI) وتحديثها وإلغاء تثبيتها واستخدامها لأغراض الأتمتة واستكشاف الأخطاء وإصلاحها.

لا تحتاج إلى تثبيت واجهة سطر الأوامر (CLI) يدويًا.مهارات Agent 365 تتحقق من وجود واجهة سطر الأوامر (CLI)، وتثبّتها أو تحدّثها تلقائيًا، وتشغّل جميع الأوامر المطلوبة نيابةً عنك. تُعد هذه المقالة مرجعًا للمطورين الذين يحتاجون إلى تثبيت واجهة سطر الأوامر أو استخدامها بشكل مباشر، على سبيل المثال عند إنشاء أتمتة لعمليات CI/CD، أو استكشاف أخطاء خطوة معيّنة وإصلاحها، أو العمل من دون وكيل برمجة بالذكاء الاصطناعي.

ملحوظة

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

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

يتطلب CLI .NET 8.0 أو أحدث. لجميع المتطلبات الأخرى، بما في ذلك اشتراك Azure والأدوار المطلوبة في Entra، انظر Quickstart: ربط وكيل موجود بالوكيل 365.

مصادقة Microsoft Entra

افتراضيا، يستخدم إعداد Agent 365 تطبيق مؤسسي Agent 365 CLI المدار من Microsoft عندما يكون متاحا في المستأجر الخاص بك.

الخاصية	Value
‏‫اسم العرض‬	Agent 365 CLI
معرف التطبيق (العميل)	f54280f4-395e-4ea8-9e48-bf2d4952aa14

للتحقق من التطبيق، اذهب إلى مركز مسؤولي Microsoft Entra، واخترجميع التطبيقات >في تطبيقات المؤسسات، وابحث عن معرف التطبيق. معرف الكائن الخاص بمدير الخدمة فريد من نوعه لمستأجرك. لا تستخدم معرّف الكائن في المواضع التي تطلب فيها واجهة سطر الأوامر أو الوثائق معرّف التطبيق (العميل).

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

إذا لم يكن تطبيق المؤسسة الذي تديره Microsoft متوفرًا، فإن الإعداد من دون تكوين يبحث عن تطبيق مملوك للمستأجر باسم Agent 365 CLI. تظل التكوينات الموجودة التي تحدد التخصيص clientAppId مدعومة. للتعليمات، راجع تسجيل تطبيق العميل المخصص ل Agent 365 CLI.

يستخدم التطبيق المدار من قبل Microsoft هذه الطرق التفاعلية للمصادقة:

البيئة	أسلوب المصادقة
Windows الأصلي	مدير حسابات الويب (WAM)
نظام Windows الفرعي لـ Linux‬ (WSL)، macOS، وLinux	رمز الجهاز

تستخدم التطبيقات المخصصة المملوكة للمستأجرين متصفح النظام عندما لا يكون WAM متاحا.

تثبيت Agent 365 CLI

استخدم الخطوات التالية لتثبيت Agent 365 CLI عالميًا على نظام التشغيل الخاص بك.

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

يجب أن يكون لديك .NET مثبت. (يوصى باستخدام .NET 8.0.)

ويندوز

تثبيت .NET على Windows

ينكس

تثبيت .NET على Linux

تثبيت .NET على macOS

قم بتثبيت أداة dotnet

تثبيت Agent 365 CLI باستخدام الأمر التالي:

dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli

للحصول على أحدث الإرشادات والإصدارات المتاحة، قم بزيارة صفحة NuGet الرسمية: Microsoft.Agents.A365.DevTools.Cli on NuGet.org

التحقق من التثبيت

بعد تثبيت CLI عامل 365، تحقق من تثبيته بشكل صحيح بتشغيل الأمر --help :

a365 -h

يعرض هذا الأمر معلومات المساعدة ويؤكد أن واجهة سطر الأوامر جاهزة للاِسْتِخْدَام.

تحديث واجهة سطر الأوامر لـ Agent 365

تحديث Agent 365 CLI باستخدام أمر تحديث أداة dotnet :

dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli

ملحوظة

لتحديث Agent 365 CLI، تحتاج إلى اتصال إنترنت للوصول إلى أحدث حزمة NuGet: Microsoft.Agents.A365.DevTools.Cli.

قم بإلغاء تثبيت ملف CLI الخاص بالعامل 365

إلغاء تثبيت Agent 365 CLI باستخدام الأمر إلغاء تثبيت أداة dotnet :

dotnet tool uninstall --global Microsoft.Agents.A365.DevTools.Cli

مواقع ملفات Agent 365 CLI

يعتمد الموقع الافتراضي لملف تنفيذ الأداة على نظام التشغيل:

نظام التشغيل	المسار
Linux/macOS	$HOME/.dotnet/tools
Windows	%USERPROFILE%\.dotnet\tools

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

يعد الوصول إلى الأداة خاصًا بالمستخدم، وليس عالميًا على مستوى الجهاز. الأداة العالمية متاحة فقط للمستخدم الذي يقوم بتثبيت الأداة.

أوامر واجهة سطر الأوامر الخاصة بالوكيل 365

للحصول على القائمة الكاملة للأوامر المتاحة، استخدم الأمر --help أو راجع مرجع CLI للعامل 365.

نصيحة

لا تحتاج إلى تشغيل أوامر CLI يدويا. تُؤتمِت مهارات Agent 365 سير العمل بأكمله - تثبيت واجهة سطر الأوامر، والتكوين، وإعداد المخطط، والتوزيع، والنشر - باستخدام وكيل برمجة يعمل بالذكاء الاصطناعي. استخدم مرجع CLI هنا إذا كنت تقوم بإنشاء أتمتة CI/CD، أو استكشاف أخطاء خطوة معينة وإصلاحها، أو العمل دون عامل ترميز الذكاء الاصطناعي.

للحصول على إرشادات كاملة حول كيفية إعداد عامل Agent 365 باستخدام CLI، راجع بدء استخدام تطوير Agent 365.

استكشاف الأخطاء وإصلاحها

يوفر هذا القسم معلومات حول كيفية استكشاف الأخطاء باستخدام Agent 365 CLI.

نصيحة

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

القضايا الخاصة ب CLI التي يغطيها هذا القسم:

• تطبيق سطر الأوامر Agent 365 الذي تديره Microsoft غير متوفر
• تم حظر مصادقة كود الجهاز
• يفشل التحقق مع AADSTS70007
• النطاقات المفوضة المطلوبة مفقودة
• العميل لا يظهر في Teams
• لا يمكن إنشاء نسخة وكيل في Teams

تطبيق سطر الأوامر Agent 365 الذي تديره Microsoft غير متوفر

قم بتحديث واجهة سطر الأوامر وشغّل a365 setup requirements مرة أخرى. للتحقق مما إذا كان الطرح المرحلي قد وصل إلى المستأجر الخاص بك، ابحث عن معرفf54280f4-395e-4ea8-9e48-bf2d4952aa14التطبيقات في تطبيقات المؤسسات في Microsoft Entra.

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

تم حظر مصادقة كود الجهاز

يستخدم التطبيق الذي تديره Microsoft مصادقة كود الجهاز على WSL وmacOS وLinux. يمكن أن تمنع الافتراضيات الأمنية أو سياسة الوصول المشروط هذا التدفق وتعود AADSTS530035.

لا تعطل سياسة الأمان الخاصة بمؤسستك لتجاوز هذا الخطأ. شغل واجهة برمجة الأوامر على نظام Windows الأصلي لاستخدام WAM، أو تعاون مع مسؤول الهوية الخاص بك لاستخدام تطبيق مخصص مملوك للمستأجر وتدفق مصادقة يسمح به وثيقتك.

يفشل التحقق مع AADSTS70007

قد تستخدم إصدارات واجهة سطر الأوامر (CLI) الأقدم وضع استجابة متصفح غير مدعوم مع التطبيق المُدار من Microsoft، وتُرجِع AADSTS70007. تحديث إلى أحدث إصدار من CLI وأعد المحاولة:

dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli

النطاقات المفوَّضة المطلوبة مفقودة

تتحقق واجهة سطر الأوامر من الأذونات المفوَّضة الفعّالة للتطبيق المُدار من Microsoft استنادًا إلى مطالبة scp في رمز الوصول. قم بتحديث قائمة الأوامر وأعد تشغيل a365 setup requirements.

لا تضف وحدات إعادة التوجيه (URIs)، أو المطالبات الاختيارية، أو صلاحيات واجهة برمجة التطبيقات، أو منح الأذونات المحلية المستأجرة إلى التطبيق الذي تديره Microsoft. إذا استمر التحقق في الإبلاغ عن نطاقات مفقودة، فاستخرج معرّفات التتبع والارتباط من رسالة الخطأ واتصل بدعم Microsoft. إذا كنت تستخدم تطبيقا مملوكا للمستأجر، اتبع خطوات التحقق في تسجيل تطبيق العميل المخصص ل Agent 365 CLI.

العميل لا يظهر في Teams

إنشاء حالات الوكيل وحل وإصلاحها: الوكيل لا يظهر في Teams

لا يمكن إنشاء نسخة وكيل في Teams

استكشاف أخطاء إنشاء مثيلات الوكلاء: لا يمكن إنشاء مثيل وكيل في Teams