ربط وكيل AI بتذاكر Jira

المقدمة

في هذه المقالة، سأوضح لك كيفية ربط وكيل AI الخاص بك بـ Jira. سنستخدم:

• حساب Jira (مجاني)
• وكيل AI من Quickchat (سجل هنا واستخدمه مجانا)

تبحث عن المرجع الأساسي المحدث باستمرار؟ الإرشاد نفسه موجود في وثائقنا على docs.quickchat.ai/channels/jira. هذه المقالة هي النسخة المطولة والمشروحة.

سيمكن ذلك وكيل Quickchat AI الخاص بك من:

• البحث في تذاكر Jira الخاصة بك، و
• التعامل بذكاء مع الإجابة عن الأسئلة بناء عليها

سنستخدم AI Actions من Quickchat (إجراءات HTTP مخصصة) للسماح لوكيلك باستدعاء نقطة نهاية Enhanced search for issues في واجهة Jira (Atlassian) API.

صمم وكيل AI مبدعا في تفسير مدخلات المستخدم

شاهد الفيديو

كيف يعمل

هذه هي طريقة عمل وكيل AI أثناء المحادثات:

1. يطرح المستخدم سؤالا مثل “ما الجديد في المشكلات المتعلقة بعطارد؟”
2. يجلب وكيل AI المعلومات ذات الصلة من Jira API باستخدام استعلام مثل “mercury”
3. يرد وكيل AI على المستخدم بناء على المعلومات المجلوبة من API

اتبع الخطوات أدناه. يفترض ألا يستغرق الإعداد بالكامل أكثر من 10 دقائق.

الخطوة 0، إنشاء حساب ومشروع في Jira

1. انتقل إلى id.atlassian.com/signup، وأنشئ حسابك وتحقق منه.
2. أضف Jira إلى تطبيقات Atlassian لديك (ستكون الخطة المجانية كافية للبدء).
3. أعد مشروعك الأول وأنشئ تذاكر كما في المثال أدناه.

مثال على لوحة تحتوي على مشكلات Jira

الخطوة 1، رمز مصادقة Jira API

انتقل إلى id.atlassian.com/manage-profile/security/api-tokens وأنشئ API token الخاص بك، وسيبدو شبيها بهذا:

ATATT3xFfGF01sKUl0HEW2-_-u9umfLSz7jeblmeLzEHZ1DLcdLbKeVF137iTHGkKhPuNMSKX8mkbwLpHXT4-qXEn-xNEnfiK8_XDVW6XXvGd_SBV3HD4kJInGNjfg2_yEoJFN6uwy4NRqeuhV2tjmyzxozLBRn35OhXkDA6QGfLFvf2_PKuNtA=8DA704E4

لكي تتمكن من استخدام Atlassian API token في Quickchat AI Actions، تحتاج إلى ترميزه بصيغة base64 مع عنوان بريدك الإلكتروني:

your_email@example.com:ATATT3xFfGF01sKUl0HEW2-_-u9umfLSz7jeblmeLzEHZ1DLcdLbKeVF137iTHGkKhPuNMSKX8mkbwLpHXT4-qXEn-xNEnfiK8_XDVW6XXvGd_SBV3HD4kJInGNjfg2_yEoJFN6uwy4NRqeuhV2tjmyzxozLBRn35OhXkDA6QGfLFvf2_PKuNtA=8DA704E4

تأكد من تضمين عنوان البريد الإلكتروني نفسه الذي استخدمته لإعداد حساب Atlassian

يمكنك استخدام أداة بسيطة على الإنترنت مثل base64encode.org.

تأكد من استخدام Live mode الذي يضمن أن الترميز يحدث بالكامل داخل متصفحك.

يمكنك استخدام أداة مجانية على الإنترنت لترميز API token الخاص بك

بدلا من ذلك، إليك كيفية تنفيذ ذلك على جهازك باستخدام سكريبت python بسيط:

import base64

email = "your_email@example.com"
api_token = "ATATT3xFfGF01sKUl0HEW2-_-u9umfLSz7jeblmeLzEHZ1DLcdLbKeVF137iTHGkKhPuNMSKX8mkbwLpHXT4-qXEn-xNEnfiK8_XDVW6XXvGd_SBV3HD4kJInGNjfg2_yEoJFN6uwy4NRqeuhV2tjmyzxozLBRn35OhXkDA6QGfLFvf2_PKuNtA=8DA704E4"

credentials = f"{email}:{api_token}"
b64_credentials = base64.b64encode(credentials.encode("utf-8")).decode("utf-8")

print(f"Basic {b64_credentials}")

سيعطيك السكريبت أعلاه ترويسة جاهزة للاستخدام تحتوي على الرمز المرمز، وستبدو شبيهة بهذا:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

الخطوة 2، إنشاء Quickchat AI Action

في تطبيق Quickchat AI، انتقل إلى Actions & MCPs وأضف إجراء:

صفحة AI Action

امنح AI Action الخاص بك اسما مناسبا:

Name: Search Jira issues

إدراج اسم AI Action

الخطوة 3، تعيين معلمات الإدخال

ستكون المهمة الأساسية لوكيل AI الخاص بك هي ترجمة ما يسأل عنه المستخدم إلى استعلام دقيق لاستخدامه في البحث داخل مشكلات Jira. بالنسبة إلى البحث عن المشكلات، انتقلت Jira مؤخرا بالكامل إلى JQL (Jira Query Language) للسماح بتنفيذ عمليات بحث أكثر تعقيدا. هذا يجعل وكيل AI الخاص بك أكثر قدرة. أعد معلمات الإدخال كما يلي:

لتحقيق أداء جيد مع وكيل AI الخاص بك، يكون الوصف المصاغ بعناية مهما جدا:

Description:

سلسلة JQL (Jira Query Language) واحدة صالحة مبنية وفق الوصف. أعط الأولوية للاستدعاء الواسع: فضل `(text ~ "term1" OR text ~ "term2")` على الربط باستخدام AND، واستخدم الأقواس للتجميع. في أسئلة "not started / in progress / done"، رشح باستخدام `statusCategory` ("To Do", "In Progress", "Done")، فهي ثابتة عبر المشاريع، واستخدم `status = "..."` فقط عندما يذكر المستخدم حالة محددة موجودة على اللوحة. تجنب الحقول المخصصة. أمثلة: `statusCategory = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`, `(text ~ "planet*" OR text ~ "integration")`, `project = "Solar System" AND statusCategory = "To Do"`.

الوصف المصاغ بعناية للمعلمة عامل أساسي في أداء وكيل AI

ملاحظة حول حالات Jira

تفصل Jira بين اسم الحالة وفئتها، وتتعامل JQL معهما بشكل مختلف:

• اسم الحالة هو ما تعرضه اللوحة. يستخدم مشروع To Do / In Progress / Done، ويستخدم آخر Open / In Review / Closed.
• فئة الحالة هي واحدة من ثلاث مجموعات ثابتة ترتبط بها كل حالة: To Do, In Progress, Done.

يرشح status = "To Do" حسب الاسم، لذلك لا يعيد أي نتيجة على لوحة اسم عمودها الأول Open. هذا سبب شائع يجعل الوكيل يقرر بثقة أنه “لا توجد تذاكر مطلوب تنفيذها” بينما اللوحة ممتلئة بها. في أسئلة “ما الذي لم يبدأ”، و”ما الذي قيد التنفيذ”، و”ما الذي اكتمل”، رشح حسب الفئة بدلا من ذلك:

statusCategory = "To Do"
statusCategory = "In Progress"
statusCategory = "Done"

احتفظ بـ status = "..." للحالات التي يذكر فيها المستخدم حالة محددة تعرف أنها موجودة على اللوحة. يمكنك أيضا إدراج أسماء الحالات الفعلية في لوحتك ضمن وصف Action (الخطوة 7) حتى يربط الوكيل طلبا مثل “جاهز لـ QA” بالحالة الصحيحة.

الخطوة 4، تعيين عنوان URL لنقطة نهاية API

1. حدد GET باعتباره Action Type
2. عيّن عنوان URL لنقطة النهاية إلى نقطة نهاية Jira /rest/api/3/search/jql

تعيين عنوان URL لنقطة نهاية API

تأكد من استخدام اسم نطاق Atlassian الخاص بك. ستجده في عنوان URL للوحة Jira لديك.

اسم نطاق Atlassian الخاص بك

الخطوة 5، تعيين ترويسات طلب API

عرّف ترويسات طلب API كما يلي:

انتبه بشكل خاص إلى تنسيق ترويسة Authorization بشكل صحيح: Basic <base64-encoded email:api token>

تعيين ترويسات طلب API

الخطوة 6، تعيين معلمات استعلام طلب API

عيّن معلمتي استعلام لطلب AI الخاص بك:

• يأخذ jql قيمة ديناميكية عرفت سابقا في قسم What to ask the user first. تتمثل مهمة وكيل AI في ملء قيمة هذه المعلمة بناء على ما قاله المستخدم في المحادثة.
• يأخذ fields قيمة ثابتة. لكل مشكلات Jira، نهتم فقط بـ الملخص و_الوصف_ و_الحالة_.

تعيين معلمات استعلام طلب API

تأكد من أن المعلمة jql تشير بشكل صحيح إلى القيمة المعرفة سابقا. يمكنك تحديدها من القائمة المنسدلة Add AI Data.

حدد معلمة jql الديناميكية من القائمة المنسدلة

الخطوة 7، تعيين وصف API Action

العنصر الحاسم الأخير في إعداد AI Action بشكل جيد هو وصفه. رغم أن وكيل AI لديه فهم جيد لنقطة نهاية API من عنوان URL والمعلمات، فمن المهم تحسين سلوكه لحالة الاستخدام الخاصة بك.

أهم ثلاثة جوانب مضمنة في البرومبت هي:

• متى يجب استدعاء الإجراء، مع إدراج كل صياغة قد يختارها المستخدم (find / search / look for، وكذلك explain / tell me about / describe / what is / how is the status of) حتى لا يتخطى الوكيل الاستدعاء عندما لا يقول المستخدم “search”
• اقتراحات حول كيفية استخدام صياغة JQL المتقدمة عند البحث عن مشكلات Jira
• كيفية التعامل مع النتائج الفارغة، يجب أن يصرح الوكيل بذلك بدلا من رفض الوصول

إليك API Action Description الناتج:

استخدم هذا الإجراء كلما سأل المستخدم عن أي شيء يمكن الإجابة عنه ببيانات في Jira لديه، مثل المشاريع أو المشكلات أو الحالات أو السبرنتات أو دورات الاختبار أو الأوصاف أو المالكين أو التعليقات، بغض النظر عن صياغة الطلب (find / search / look for / explain / tell me about / describe / what is / how is the status of، وما إلى ذلك). لا ترفض الوصول، استعلم من Jira أولا.

أنشئ JQL يعطي الأولوية للاستدعاء الواسع على الدقة: فضل `(text ~ "term1" OR text ~ "term2")` على الربط باستخدام AND، واستخدم الأقواس للتجميع. بالنسبة إلى أسئلة دورة الحياة (not started, in progress, done)، رشح باستخدام `statusCategory` ("To Do" / "In Progress" / "Done") بدلا من `status`، لأن أسماء الحالات تختلف حسب اللوحة، واستخدم `status = "..."` فقط عندما يذكر المستخدم حالة محددة. تجنب الحقول المخصصة.

إذا لم ترجع Jira أي نتائج مطابقة، فأخبر المستخدم بذلك صراحة واقترح استعلاما أكثر تحديدا.

الخطوة 8، اختبار API Action

قبل اختبار AI Action في محادثة، يمكننا اختبار كيفية استدعاء API نفسه في تبويب Test Response. لنجر اختبارا أوليا بالاستعلام التالي الذي يفترض أن يعيد كل المشكلات في المشروع: project = "Solar System"

البحث عن كل المشكلات في مشروع Solar System

فيما يلي استجابة الاختبار التي نحصل عليها. كما هو متوقع، تسرد حقول الملخص والوصف والحالة لكل المشكلات الـ 6 على لوحة Jira لدينا.

تعرض الاستجابة كل المشكلات في مشروع Solar System

لنجرب استعلاما آخر. هذه المرة سنبحث عن كل المشكلات التي تذكر “mercury”: text ~ "mercury"

البحث عن المشكلات التي تذكر mercury

لقد تحققنا الآن من أن AI Action يستدعي نقطة نهاية API الخاصة بنا بشكل صحيح. يمكننا الآن الانتقال إلى اختبار محادثات كاملة مع وكيل AI.

الخطوة 9، اختبار وكيل AI في المحادثات

ارجع إلى تطبيق Quickchat AI واختبر وكيل AI الخاص بك في معاينة المحادثة.

المحادثة #1

يعطي وكيل AI ملخصا لكل المشكلات داخل المشروع

في هذه المحادثة البسيطة، يقدم وكيل AI نظرة عامة على كل المشكلات داخل المشروع. تخبرنا نظرة خلف الكواليس أن الاستعلام الدقيق الذي شغله على نقطة نهاية API كان: project = "Solar System"

المحادثة #2

يرد وكيل AI على أسئلة حول مشكلات وحالات محددة

في هذه الحالة، سئل وكيل AI عن جانبين منفصلين: مشكلة محددة ومشكلات جارية بوجه عام. تخبرنا نظرة خلف الكواليس أنه قرر استخدام Jira API في عملية من خطوتين:

1. التحقق مما إذا كان pluto جاريا:

status = "In Progress" AND (text ~ "pluto" OR text ~ "ongoing" OR text ~ "current" OR text ~ "active" OR text ~ "progress")

2. التحقق مما هو جار أيضا:

status = "In Progress"

المحادثة #3

يرد وكيل AI على استعلام إبداعي 😉

في هذه الحالة أردت طرح سؤال غير مباشر على وكيل AI يتطلب بعض الإبداع لتفسيره بشكل صحيح. إليك كيف ترجم إلى استعلام JQL:

(text ~ "planet" OR text ~ "upstream" OR text ~ "mercury" OR text ~ "venus")

جرب هذه الصياغات

للتأكد من أن AI Action يعمل بصرف النظر عن صياغة المستخدمين النهائيين لطلبهم، شغل كل البرومبتات أدناه على سيناريو الاختبار لديك. يجب أن يستعلم الوكيل من Jira في كل واحدة منها، وليس فقط الصياغات المشابهة للبحث:

• “اعثر على كل المشكلات المفتوحة المتعلقة بالنتائج المباشرة”
• “ابحث عن مشكلات تحتوي على mercury”
• “اشرح مشروع Solar System”
• “أخبرني عن المشكلات المفتوحة في هذا السبرنت”
• “صف ما هو قيد التنفيذ حاليا”
• “ما حالة pluto؟”

إذا لم تستدع أي من هذه الصياغات AI Action، فتحقق مرة أخرى من أن وصف API Action (الخطوة 7) يذكر هذه الأفعال صراحة.

ما الذي تتوقعه عندما لا تجد Jira مشكلات مطابقة. عندما ترجع Jira صفر نتائج، يجب أن يقول وكيل AI ذلك صراحة، على سبيل المثال: “تحققت من Jira ولم أجد مشكلات مطابقة لاستعلامك، جرب صياغة أوسع أو أزل مرشح الحالة.” إذا رأيت بدلا من ذلك أن الوكيل يرد بـ “ليست لدي إمكانية وصول مباشرة إلى Jira لديك”، فهذا يعني أن AI Action لم يعمل على الإطلاق. أعد فحص الوصف من الخطوة 7 وتأكد من أنه يذكر صراحة الأفعال غير البحثية (explain, tell me about, describe, what is).

الملخص

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

تريد الاحتفاظ بهذا الدليل في مفضلاتك؟ النسخة الأساسية والمحدثة باستمرار من هذا الإرشاد موجودة في وثائقنا على docs.quickchat.ai/channels/jira، انتقل إليها لنسخ أحدث وصف لـ API Action ومتابعة تحديثات الوصفة.

خطوات إضافية

لا يجب أن يكون إجراء Jira طلبا ثابتا واحدا. يمكنك حقن متغيرات المحادثة المضمنة والبيانات الوصفية المحفوظة (مثل لغة الزائر أو القيم الملتقطة سابقا في المحادثة) في أي حقل، ويمكنك إضافة عدة إجراءات حتى يختار الوكيل الإجراء الصحيح لكل سؤال. يغطي مرجع AI Actions مجموعة الخيارات الكاملة.

أدلة ذات صلة

آلية AI Action نفسها تربط الوكيل بأي HTTP API. إرشادات أخرى تستخدمها:

• إنشاء بوت إشراف AI على Discord باستخدام AI Actions مخصصة
• ربط وكيل AI الخاص بك بـ Telegram Bot API
• ربط وكيل AI الخاص بك بـ Google Sheets
• ربط وكيل AI الخاص بك بـ HubSpot لتسجيل جهات الاتصال والصفقات والتذاكر
• إرسال إشعارات Slack باستخدام AI Actions
• ربط Cal.com بوكيل AI الخاص بك في 5 دقائق
• كيفية إنشاء وكيل دعم AI من وثائقك
• وكيل AI لدعم عملاء SaaS

إضافة

كتب مقالة المدونة أعلاه إنسان (أنا)، ولكن كان من الممكن أن يكتبها AI كذلك. على سبيل المثال، عن طريق لصق برومبت مثل هذا في ChatGPT:

أحتاج إلى نقطة نهاية API تتيح لي البحث في تذاكر Jira الخاصة بي.

أرشدني خلال العملية خطوة بخطوة بحيث تكون مفهومة لشخص لديه معرفة تقنية متوسطة:
- قدم روابط إلى الوثائق التي تصف نقطة النهاية
- أي إنشاء حساب وإعداد أولي مطلوب
- إذا كان هناك حاجة إلى أي حساب مدفوع، فاذكر ذلك بوضوح
- إذا كانت هناك حاجة إلى أي مصادقة مثل API tokens، فأرشدني خلال عملية إنشائها وأرني بدقة كل خطوة مطلوبة حتى أتمكن من استخدامها كترويسة طلب HTTP. على سبيل المثال، إذا كان ترميز base64 مطلوبا، فأظهر سكريبت أو طريقة أخرى لتحقيق ذلك.
- أرني بدقة مفاتيح الترويسات والقيم التي أحتاجها لطلب HTTP (أظهر مفاتيح الترويسات وقيمها في جدول)
- أرني بدقة معلمات الحمولة التي أحتاجها لطلب HTTP (أظهر اسم معلمة الحمولة وقيم أمثلة في جدول)

في المستقبل، ربما بدلا من البحث في تذاكر Jira قد ترغب في:

• إرسال رسائل إلى قناة Slack؟
• جلب معلومات من صفحة Notion؟
• تنفيذ إجراء عبر Zapier؟

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