إشعار
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تسجيل الدخول أو تغيير الدلائل.
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تغيير الدلائل.
مهم
العناصر التي تم وضع علامة عليها معاينة في هذه المقالة قيد المعاينة حاليا. يتم توفير هذه المعاينة دون اتفاقية على مستوى الخدمة، ولا توصي Microsoft بأحمال عمل الإنتاج. قد لا تكون بعض الميزات مدعومة أو قد تكون ذات قدرات محدودة. لمزيد من المعلومات، راجع شروط الاستخدام الإضافية لمعاينات Microsoft Azure.
يمنحك Azure Developer CLI (azd) وملحقه azd ai agent سير عمل سطر أوامر واحد للانتقال من الفكرة إلى عامل جاهز للإنتاج على Microsoft Foundry. يمكنك تطوير العوامل المستضافة المستندة إلى التعليمات البرمجية والوكلاء الصوتيين التصريحيين المستندين إلى المطالبة. تشرح هذه المقالة رحلة المطور، والملفات التي تحدد الوكيل، والمفاهيم الأساسية التي تواجهها على طول الطريق.
هذه المقالة موجهة للمطورين الذين يفضلون سير عمل يعتمد على الطرفية أولا وقابل للبرمجة النصية على بوابة Foundry أو مجموعات SDK اللغة.
رحلة المطور
يتبع سير azd ai العمل نفس دورة الحياة سواء بنيت نموذجا أوليا صغيرا أو وكيل إنتاج. تقوم بإنشاء مشروع مرة واحدة، ثم تقوم بمزج ومطابقة الأوامر مع نمو مشروعك.
| مرحلة | ما تفعله | أين يمكنك معرفة المزيد |
|---|---|---|
| Install | التثبيت azd وإضافات Foundry. |
قم بإعداد بيئة المطور الخاصة بك |
| السقالة | تهيئة عامل مستضاف من قالب أو التعليمات البرمجية الموجودة، أو إنشاء عامل صوت يستند إلى المطالبة. | التشغيل السريع: نشر عامل مستضاف أو التشغيل السريع: إنشاء عامل صوت موجه |
| تعريف | تكوين الوكيل، تبعيات نشر النماذج، البروتوكولات، الأدوات، والبيئة في azure.yaml. |
Author azure.yaml for host agents |
| Develop | اكتب منطق العامل، وأضف أدوات باستخدام مربع أدوات، واختبر محليا. | نظرة عامة على مربع الأدوات |
| نشر | توفير البنية التحتية ونشرها في Foundry. | نشر وكيل مستضاف |
| التشغيل | راقب السجلات، وإدارة الإصدارات، وأتمتة التشغيل. | إدارة الوكلاء المستضافين |
| تقييم | قس جودة الوكيل وحسن الطلب. | تشغيل تقييمات الوكيل باستخدام واجهة سطر AZD |
أنواع الوكلاء
azd ai agent يدعم الملحق العوامل المستضافة والمطالبة والصوت.
| النوع | الوصف | وقت الاستخدام |
|---|---|---|
| الوكيل المستضاف | تطبيق تقوم بنشره كتعليق برمجي مصدر أو صورة حاوية. | تحتاج إلى منطق مخصص، أو تكامل مع إطار عمل، أو تحكم كامل في السلوك. |
| وكيل التوجيه | وكيل يعرف بالكامل من خلال التعليمات وتكوينات الأدوات، بدون كود مخصص. | تريد وكيلا سريعا يعتمد على الإعدادات دون كتابة كود تطبيق. |
| عامل صوتي | عامل صوت موجه تعريفي أو برنامج تضمين صوتي يتصل بعامل مستضاف. | تحتاج إلى تجربة صوتية في الوقت الحقيقي من خلال عميل Voice Live. |
الوكلاء المستضافون يمنحونك تحكما كاملا في وقت التشغيل والإطار التكامل مع الأدوات، بينما تتولى Foundry إدارة البنية التحتية والتوسع وإدارة الجلسات.
لا تتطلب العوامل الصوتية المستندة إلى المطالبة حاوية مخصصة. إذا كنت بحاجة إلى تشغيل مسار صوت مخصص لتحويل الكلام إلى كلام أو تدفق صوتي متتالي في الحاوية الخاصة بك، فقم بإنشاء وكيل صوتي مع عامل مستضاف واستخدم invocations_ws البروتوكول.
للحفاظ على منطق المحادثة في عامل نص مستضاف أثناء معالجة Voice Live للصوت، استخدم سير عمل برنامج تضمين الصوت المستضاف. برنامج التضمين والهدف هما خدمات منفصلة في نفس azure.yaml المشروع. لا يحل هذا التدفق محل تدفق تدفق الصوت المخصص invocations_ws الموجود.
قبل استخدام خيارات CLI الصوتية للمعاينة العامة، تحقق من الملحق المثبت كما هو موضح في متطلبات التشغيل السريع لعامل الصوت.
ملفات التكوين
يستخدم مشروع الوكيل المستضاف ملفا واحدا azure.yaml في جذر المشروع للإعلان عن كل من الوكيل ونموذج التوفير والنشر الخاص به. يستخدم الملف نموذج الخدمة المنقسمة، حيث لكل host خدمة مسماة قيمة مثل azure.ai.project، azure.ai.agent، azure.ai.connection، azure.ai.toolbox، azure.ai.skillأو azure.ai.routine.
| File | الغرض | من يحافظ عليه |
|---|---|---|
azure.yaml |
يعلن مشروع Foundry، ونشر النماذج، وخدمة الوكلاء المستضافة، والتبعيات، والبروتوكولات، والأدوات، ومتغيرات البيئة، وموارد الحاويات، وإعدادات النشر. هوية الوكيل، والنموذج، والبروتوكولات، والأدوات، وقيم البيئة موجودة في azure.ai.agent الخدمة. |
التهيئة تولد ذلك. تقوم بتخصيصها حسب الحاجة. |
azure.ai.agent تعرف الخدمة العامل الخاص بك بشكل مضمن أو من خلال جذر $ref صريح لتعريف YAML أو JSON مباشر. استخدم azd ai agent add <service> --file <path> لخدمة مدعومة بالملفات. لا تدعم التهيئة الحالية برامج التضمين ذات AgentManifest المعلمات. تشير قائمة الخدمة uses: إلى تبعيات مثل المشروع والاتصالات وعلب الأدوات.
بالنسبة للعامل الصوتي المستند إلى المطالبة، azure.yaml يخزن تعريف العامل التعريفي، بما في ذلك kind: prompt-voiceالنموذج ونوع النموذج واسم العامل. لا يتضمن وقت تشغيل حاوية عامل مستضاف. لتخصيص الإرشادات والصوت وتحويل الكشف والنسخ والإخراج الصوتي والأدوات والترحيبات، راجع تكوين وكيل صوتي.
بالنسبة إلى برنامج تضمين صوتي مستضاف، conversationEngine.name يشير إلى اسم خدمة الهدف المستضاف. توزيع أوامر تبعية برنامج التضمين uses ، والإعدادات conversationEngine.version الافتراضية للإصدار الذي تم نشره بواسطة البيئة الحالية. راجع مرجع الخدمة الصوتية لحقول التكوين.
الاستبدال بالمتغيرات
استخدم ${VAR_NAME} في azure.yaml القيم التي تختلف حسب azd البيئة. يتم حل البديل المؤقت من .azure/<env>/.env وقت النشر أو التشغيل، لذا يعمل نفس azure.yaml الشيء عبر البيئات مثل التطوير، المرحلة، والإنتاج.
حيث يمر مؤشر القيادة
تعمل الأوامر azd ai داخل وخارج دليل azd المشروع:
- داخل المشروع
azd، تقوم الأوامر بحل نقطة نهاية مشروع Foundry من البيئة النشطةazd. - خارج
azdالمشروع، قم بتعيين السياق النشط مرة واحدة باستخدامazd ai project set <endpoint>، أو مرر--project-endpointأمر مورد فردي (connection،toolbox،skill، أوroutine). كخيار احتياطي،azd aiيقرأFOUNDRY_PROJECT_ENDPOINTمتغير البيئة. - نقطة نهاية غير نشطة تم حلها من البيئة النشطة لها الأسبقية على السياق العمومي. للحصول على shell الاحتياطي والسلوك الخاص بالأوامر، راجع تعيين سياق المشروع.
البروتوكولات
بروتوكول يحدد عقد HTTP بين Foundry وحاوية الوكيل الخاصة بك. وكيلك يستمع إلى المنفذ 8088 ويقدم فحص صحي، بغض النظر عن البروتوكول.
| البروتوكول | نمط API | وقت الاستخدام |
|---|---|---|
responses |
واجهة برمجة تطبيقات OpenAI Responses (POST /responses) |
الخيار القياسي، متوافق مع نظام OpenAI API. |
invocations |
عقد JSON مخصص (POST /invocations) |
عندما تحتاج إلى تحكم كامل في حمولة الطلبات والاستجابة. |
للاطلاع على المواصفات الكاملة، انظر عقد تشغيل الوكيل المستضاف.
تنطبق إعدادات البروتوكول هذه على حاويات العامل المستضاف. لا يقوم العاملون الصوتيون المستندون إلى المطالبة بتكوين بروتوكول عامل مستضاف.
azd ai agent invoke لا ينفذ المحادثات الصوتية للوكلاء الصوتيين المستندين إلى المطالبة أو برامج تضمين الصوت المستضافة. للحصول على سلوك CLI وإرشادات الاختبار، راجع قيود عامل الصوت.
الجلسات والمحادثات
| المفهوم | الوصف |
|---|---|
| جلسة | بيئة تنفيذ معزولة لتفاعل وكيل واحد. كل جلسة تعمل في صندوق رمل خاص بها مع موارد مخصصة. |
| حوار | محفوظات الرسائل لبروتوكول الاستجابات. لا تستمر استدعاءات محفوظات المحادثات تلقائيا. |
يتم تحديد الجلسات بواسطة .session_id يحفظ CLI تحديد جلسة العمل لكل عامل ويعيد استخدامه بشكل افتراضي. استخدمها --new-session للبدء من جديد، أو --session-id <id> لاستهداف جلسة محددة. ذاكرة التخزين المؤقت غير مفتاحية بواسطة المستخدم المفوض؛ الاحتفاظ بتعيين صريح من مستخدم إلى جلسة عمل عند استخدام --user-identity.
موارد حول مشروع مسبك
مشروع Foundry يستضيف أكثر من مجرد وكلاء. كما يحتوي على موارد مشتركة يستشيرها الوكلاء أثناء وقت التشغيل. تدير CLI كل واحدة منها من خلال مجموعة قيادة مخصصة.
| مورد | ما هو عليه | أدار مع |
|---|---|---|
| الاتصال | يربط مشروع Foundry بمورد خارجي، مثل خادم MCP، أو البحث باستخدام الذكاء الاصطناعي في Azure، أو التأريض باستخدام Bing. |
azd ai connection الاوامر |
| صندوق الأدوات | مجموعة مسماة من الأدوات التي يستخدمها الوكلاء أثناء وقت التشغيل. |
azd ai toolbox الاوامر |
| المهاره | إرشادات سلوكية قابلة لإعادة الاستخدام يتم مشاركتها بين الوكلاء في المشروع. |
azd ai skill الاوامر |
| الروتين | محفز زائد فعل يستدعي وكيل. |
azd ai routine الاوامر |
يتم مشاركة هذه الموارد بين المطورين والوكلاء في نفس المشروع. تختلف أوامرها: الاتصالات والروتينات لها update، وتنشر المهارات إصدارا جديدا من خلال update، وتستخدم مربعات الأدوات الاتصال المنتج للإصدار وطفرات المهارات متبوعة ب publish.
تقييم وتحسين وكيل
بعد تشغيل الوكيل، يساعدك سير عمل مرتبطان بقياس وتحسين جودته:
- يستخدم
azd ai agent evalتقييم العامل السريع و محليeval.yaml، بما في ذلك سير عمل المحسن. يستخدم تقييم Project الملحق المثبتazd ai evalبشكل منفصل و،evals/azure.eval.yamlمع مصادر التتبع أو مجموعة البيانات وبوابات جودة CI الصريحة. تنسيقا التكوين غير قابلين للتبديل. - التحسين يعيد كتابة طلب وكيلك لرفع إشارة التقييم بشكل تكراري. يستخدم التقييم كوظيفة هدف وينتج موضوع مرشح تراجعه وتقبله. تدير ذلك باستخدام
azd ai agent optimize.
للتفاصيل، راجع تشغيل تقييمات الوكيل باستخدام تعليمات AZD CLIوOptimize.
مجموعات الأوامر حسب وظيفة المطور
اختر أمرا للنتيجة التي تحتاجها.
--help إلحاق لفحص علاماته وتنسيقات الإخراج المدعومة.
| Job | Commands | Guidance |
|---|---|---|
| تكوين مشروع ونماذج مدارة |
azd ai project add، azd ai project deployment add |
تكوين Project والسياق |
| تحديد سياق نقطة النهاية أو فحصه |
azd ai project set، ، azd ai project show، azd ai project unsetazd ai project context |
اختيار نقطة النهاية العمومية منفصل عن إعلانات البنية الأساسية. يمكن أن يحتوي إخراج السياق على أسرار. |
| استعراض العينات أو تهيئة عامل |
azd ai agent sample list، azd ai agent init، azd ai agent add |
تهيئة العوامل المستضافة والمطالبة والصوتية |
| تحليل المستندات والمحتوى واستخراجها وتصنيفها للوكلاء |
azd ai cu analyze، azd ai cu analyzer |
Azure بدء التشغيل السريع لفهم المحتوى CLI (معاينة) |
| تشغيل وفحص محليا |
azd ai agent run، azd ai inspector launch |
التطوير المحلي |
| استدعاء هوية المستخدم أو تفويضها أو إرسال رؤوس مخصصة | azd ai agent invoke |
خيارات استدعاء |
| فحص العمل أو متابعته أو إلغاؤه |
azd ai agent invocations show، azd ai agent invocations follow، azd ai agent invocations cancel |
استدعاء طويل الأمد |
| فحص نقطة نهاية أو تحديثها |
azd ai agent endpoint show، azd ai agent endpoint update |
تحديثات نقطة النهاية والبطاقة |
| فحص الحالة أو تشخيص المشاكل أو قراءة السجلات |
azd ai agent show، azd ai agent doctor، azd ai agent monitor |
التشخيصوالسجلات |
| إنشاء بيئة الاختبار المعزولة أو سردها أو فحصها أو إيقافها أو حذفها |
azd ai agent sessions create، azd ai agent sessions list، azd ai agent sessions show، ، azd ai agent sessions stopazd ai agent sessions delete |
إدارة الجلسة |
| إنشاء ملفات بيئة الاختبار المعزولة أو استردادها أو صيانتها |
azd ai agent files upload، azd ai agent files download، azd ai agent files list، azd ai agent files mkdir، ، azd ai agent files statazd ai agent files delete |
عمليات ملف جلسة العمل |
| استرداد المصدر المنشور | azd ai agent code download |
تنزيل التعليمات البرمجية أو الرمز البريدي |
| فحص المتاجر الدائمة والحفاظ على العناصر المشتركة |
azd ai agent state-stores list، ، azd ai agent state-stores select، azd ai agent state-stores showazd ai agent state-stores items |
عمليات وحدود مخزن الحالة |
| إضافة تبعيات العامل إلى تكوين النشر |
azd ai agent connection add، azd ai agent toolbox add |
يجب أن تكون كلتا الخدمتين موجودتين بالفعل في azure.yaml؛ تضيف uses هذه الأوامر إدخالات، وليس موارد بعيدة. |
| إدارة بيانات اعتماد الاتصال وبيانات التعريف |
azd ai connection create، azd ai connection list، azd ai connection show، ، azd ai connection updateazd ai connection delete |
مصادقة الاتصال وصيانته |
| تأليف مهارات قابلة لإعادة الاستخدام أو إصدارها أو تنزيلها |
azd ai skill add, azd ai skill create, azd ai skill update, , azd ai skill list, azd ai skill showazd ai skill download, ,azd ai skill delete |
مهام سير عمل المهارات |
| تأليف مربعات الأدوات وإدارتها |
azd ai toolbox add، azd ai toolbox create، azd ai toolbox list، ، azd ai toolbox showazd ai toolbox delete |
تكوين مربع الأدوات |
| تطوير مجموعات الأدوات والترويج لها |
azd ai toolbox connection، ، azd ai toolbox skill، azd ai toolbox versions listazd ai toolbox publish |
فرع الطفرات من أحدث إصدار؛ الترقية صريحة. |
| جدولة الإجراءات الروتينية أو إرسالها أو فحصها |
azd ai routine add، azd ai routine create، azd ai routine list، azd ai routine show، azd ai routine update، azd ai routine enable، azd ai routine disable، azd ai routine dispatch، ، azd ai routine run listazd ai routine delete |
مهام سير العمل الروتينية |
| إنشاء تقييم سريع وتشغيله |
azd ai agent eval generate، azd ai agent eval update، azd ai agent eval run، ، azd ai agent eval listazd ai agent eval show |
التقييم السريع وأصول المحسن |
| تحسين مرشح التحسين ونشره |
azd ai agent optimize، azd ai agent optimize status، azd ai agent optimize list، azd ai agent optimize cancel، ، azd ai agent optimize applyazd ai agent optimize deploy |
سير عمل التحسين |
| حزم عامل نشاط ل Teams أو نشره |
azd ai agent pack، azd ai agent publish |
توزيع الفرق |
| حذف إصدار مستضاف أو عامل | azd ai agent delete |
حذف العامل |
| تقييم مشروع وفرض بوابات الجودة |
azd ai eval init, azd ai eval generate, azd ai eval create, , azd ai eval run, azd ai eval datasetazd ai eval evaluator, ,azd ai eval job |
Project التقييم؛ تثبيت azure.ai.evaluations بشكل منفصل. |
| تسجيل مجموعات البيانات القابلة لإعادة الاستخدام وإصدارها | azd ai dataset |
دورة حياة مجموعة البيانات؛ تثبيت azure.ai.dataset بشكل منفصل. |
| إرسال مهام ضبط دقيقة أو إيقافها مؤقتا أو استئنافها أو إلغائها أو توزيعها |
azd ai finetuning init، azd ai finetuning jobs |
الضبط الدقيق؛ تثبيت azure.ai.finetune بشكل منفصل. |
| تحميل أوزان النموذج المخصص وإدارتها | azd ai models |
استيراد النموذج المخصص وصيانته؛ تثبيت azure.ai.models بشكل منفصل. |
يعرض versionكل ملحق يضيف الأوامر ؛ افحص الحزمة microsoft.foundry باستخدام azd ext list بدلا من ذلك. تعرض context مجموعات الاتصال والروتين والمهارة أيضا لفحص المشروع والبيئة المحليين؛ تعامل مع الإخراج على أنه قد يكون حساسا.
توزيع عامل النشاط
بعد نشر عامل بروتوكول النشاط، azd ai agent pack يتم إنشاء appPackage.zip للتحميل الجانبي. استخدم --output-dirو --display-nameو --app-version لتخصيص الحزمة. التغليف ليس هو نفسه النشر.
azd ai agent publishينشر من خلال Microsoft 365. وكلاء النشاط البسيط افتراضيا للتوزيع shared ما لم يتم تكوين خلاف ذلك؛ --scope tenant يتطلب موافقة المسؤول. يتطلب العاملون الرقميون نطاق المستأجر. استخدم القيم القابلة للتكرار --access-boundary لإزالة --clear-access-boundaries الحدود الموجودة والقيم القابلة للتكرار --optional-permission-scope <resource-app-id>=<scope> للأذونات الاختيارية.
personal ليس نطاق نشر؛ استخدم pack --scope personal الحزمة وقم بتحميلها الجانبي للاختبار لكل مستخدم.
دورة حياة النشر
تتكثف حلقة المطور الكاملة في تسلسل قصير من الأوامر. قم بعمل سقالة مرة واحدة، ثم استخدم الأوامر المباشرة مع نمو مشروعك.
للحصول على مسار عامل الصوت المدار، راجع التشغيل السريع: إنشاء عامل صوت موجه.
# Scaffold a project from a template or your existing code
azd ai agent init
# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"
# Provision infrastructure and deploy the agent
azd up
# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent
# Evaluate quality
azd ai agent eval generate
azd ai agent eval run
# Tear down all Azure resources
azd down