חיבור AI Agent לכרטיסי Jira

מבוא

בפוסט הזה אראה כיצד לחבר את ה-AI Agent שלכם ל-Jira. נשתמש ב:

• חשבון Jira (חינמי)
• AI Agent של Quickchat (הירשמו כאן והשתמשו בחינם)

מחפשים את ההפניה הקנונית, שמתעדכנת ברציפות? אותו מדריך נמצא בתיעוד שלנו ב-docs.quickchat.ai/channels/jira. הפוסט הזה הוא הגרסה הארוכה והמסופרת.

החיבור יאפשר ל-Quickchat AI Agent שלכם:

• להיות מסוגל לחפש בכרטיסי Jira שלכם, וגם
• להיות חכם במענה על שאלות על בסיסם

נשתמש ב-AI Actions של Quickchat (פעולות HTTP מותאמות אישית) כדי לאפשר ל-Agent שלכם לקרוא ל-endpoint‏ Enhanced search for issues של Jira (Atlassian) API.

צרו AI Agent יצירתי בפירוש קלטי משתמש

צפייה בסרטון

איך זה עובד

כך ה-AI Agent שלכם יפעל במהלך שיחות:

1. המשתמש שואל שאלה כמו “what’s up with issues to do with mercury?”
2. ה-AI Agent שולף מידע רלוונטי מה-Jira API באמצעות שאילתה כמו “mercury”
3. ה-AI Agent עונה למשתמש על בסיס המידע שנשלף מה-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 שלכם ב-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}")

הסקריפט שלמעלה ייתן לכם header מוכן לשימוש עם הטוקן המקודד, שנראה בערך כך:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

שלב 2 - יצירת Quickchat AI Action

ב-Quickchat AI app, עברו אל Actions & MCPs והוסיפו פעולה:

עמוד AI Action

תנו ל-AI Action שלכם שם מתאים:

Name: Search Jira issues

הזנת שם AI Action

שלב 3 - הגדרת פרמטרי קלט

המשימה העיקרית של ה-AI Agent שלכם תהיה לתרגם את מה שהמשתמש שואל עליו לשאילתה מדויקת לחיפוש בבעיות Jira. כשמדובר בחיפוש בעיות, Jira עברה לאחרונה במלואה ל-JQL (Jira Query Language) כדי לאפשר ביצוע חיפושים מורכבים יותר. הדבר מאפשר ל-AI Agent שלכם להיות חזק הרבה יותר. הגדירו את פרמטרי הקלט כך:

כדי להגיע לביצועים טובים עם ה-AI Agent שלכם, תיאור מנוסח היטב חשוב מאוד:

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 Agent

הערה על סטטוסים ב-Jira

Jira מפרידה בין שם הסטטוס לבין ה-קטגוריה שלו, ו-JQL מתייחסת אליהם באופן שונה:

• שם הסטטוס הוא מה שמוצג בלוח. פרויקט אחד משתמש ב-To Do / In Progress / Done, ופרויקט אחר משתמש ב-Open / In Review / Closed.
• קטגוריית הסטטוס היא אחת משלוש קבוצות קבועות שכל סטטוס ממופה אליהן: To Do, In Progress, Done.

status = "To Do" מסנן לפי שם, ולכן הוא לא מחזיר דבר בלוח שבו העמודה הראשונה נקראת Open. זו סיבה נפוצה לכך ש-agent מדווח בביטחון “אין כרטיסים לביצוע” בזמן שהלוח מלא בהם. עבור שאלות כמו “מה עדיין לא התחיל”, “מה בתהליך” ו”מה הושלם”, סננו לפי הקטגוריה במקום זאת:

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

שמרו את status = "..." למקרים שבהם המשתמש מציין שם של סטטוס ספציפי שאתם יודעים שקיים בלוח. אפשר גם לרשום את שמות הסטטוסים האמיתיים של הלוח שלכם בתיאור ה-Action (שלב 7), כדי שה-agent ימפה בקשה כמו “ready for QA” לסטטוס הנכון.

שלב 4 - הגדרת URL של API endpoint

1. בחרו GET בתור Action Type
2. הגדירו את URL ה-endpoint ל-endpoint‏ /rest/api/3/search/jql של Jira

הגדירו את URL ה-API endpoint שלכם

ודאו שאתם משתמשים ב-שם הדומיין של Atlassian שלכם. תמצאו אותו ב-URL של לוח Jira שלכם.

שם הדומיין של Atlassian שלכם

שלב 5 - הגדרת API request headers

הגדירו את headers של בקשת ה-API כך:

שימו לב במיוחד לעיצוב נכון של ה-Authorization header: Basic <base64-encoded email:api token>

הגדירו את API request headers שלכם

שלב 6 - הגדרת פרמטרי שאילתה של בקשת API

הגדירו שני פרמטרי שאילתה עבור בקשת ה-AI שלכם:

• jql מקבל ערך דינמי שהוגדר קודם לכן בסעיף What to ask the user first. תפקידו של ה-AI Agent הוא למלא את ערך הפרמטר הזה על בסיס מה שהמשתמש אמר בשיחה.
• fields מקבל ערך קבוע. עבור כל בעיית Jira, אנחנו מתעניינים רק ב-summary, description וב-status שלה.

הגדירו את פרמטרי השאילתה של בקשת ה-API שלכם

ודאו שהפרמטר jql מצביע נכון לערך שהוגדר קודם לכן. אפשר לבחור אותו מתפריט Add AI Data.

בחרו את פרמטר jql הדינמי מהתפריט הנפתח

שלב 7 - הגדרת תיאור API Action

המרכיב הקריטי האחרון של AI Action שמוגדר היטב הוא התיאור שלו. אמנם ל-AI Agent יש הבנה טובה של ה-API endpoint שלכם רק מתוך ה-URL והפרמטרים שלו, אבל חשוב להתאים את ההתנהגות שלו למקרה השימוש שלכם.

שלושת ההיבטים החשובים ביותר שנכללים בפרומפט הם:

• מתי להפעיל את הפעולה, רשימת כל ניסוח שהמשתמש עשוי לבחור (find / search / look for, וכן explain / tell me about / describe / what is / how is the status of), כדי שה-agent לא ידלג על הקריאה כאשר המשתמש לא אומר “search”
• הצעות לשימוש בתחביר JQL מתקדם בעת חיפוש בעיות Jira
• כיצד לטפל בתוצאות ריקות, ה-agent חייב לומר זאת במפורש במקום לסרב לגישה

זהו ה-API Action Description שנוצר:

השתמשו בפעולה זו בכל פעם שהמשתמש שואל כל דבר שניתן לענות עליו באמצעות נתונים ב-Jira שלו, כולל פרויקטים, בעיות, סטטוסים, sprints, מחזורי בדיקה, תיאורים, בעלים, תגובות, ללא קשר לאופן ניסוח הבקשה (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

להלן תגובת הבדיקה שקיבלנו. כצפוי, היא מציגה את שדות summary, description ו-status עבור כל 6 הבעיות בלוח Jira שלנו.

התגובה מציגה את כל הבעיות בפרויקט Solar System

ננסה שאילתה נוספת. הפעם נחפש את כל הבעיות שמזכירות “mercury”: text ~ "mercury"

חיפוש בעיות שמזכירות mercury

כעת אימתנו שה-AI Action קוראת נכון ל-API endpoint שלנו. אפשר לעבור לבדיקת שיחות מלאות עם ה-AI Agent!

שלב 9 - בדיקת ה-AI Agent בשיחות

חזרו אל Quickchat AI app ובדקו את ה-AI Agent שלכם בתצוגה מקדימה של שיחה.

שיחה #1

ה-AI Agent נותן סיכום של כל הבעיות בפרויקט

בשיחה פשוטה זו ה-AI Agent נותן סקירה של כל הבעיות בפרויקט. מבט מאחורי הקלעים אומר לנו שהשאילתה המדויקת שהוא הריץ מול ה-API endpoint הייתה: project = "Solar System"

שיחה #2

ה-AI Agent עונה לשאלות על בעיות וסטטוסים ספציפיים

במקרה הזה, ה-AI Agent נשאל על שני היבטים נפרדים: בעיה ספציפית ובעיות שנמצאות בתהליך באופן כללי. מבט מאחורי הקלעים אומר לנו שהוא החליט להשתמש ב-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 Agent עונה לשאילתה יצירתית 😉

במקרה הזה רציתי להקשות על ה-AI Agent ושאלתי אותו שאלה שדורשת מעט יצירתיות כדי לפרש אותה נכון. כך היא תורגמה לשאילתת JQL:

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

נסו את הניסוחים האלה

כדי לוודא שה-AI Action מופעלת ללא תלות באופן שבו משתמשי הקצה מנסחים את הבקשה שלהם, הריצו כל אחד מהפרומפטים הבאים מול תרחיש הבדיקה שלכם. ה-agent צריך לבצע שאילתה ל-Jira בכל אחד מהם, ולא רק באלה שמנוסחים כסגנון חיפוש:

• “find all open issues about live scores”
• “search for issues with mercury”
• “explain the Solar System project”
• “tell me about the open issues in this sprint”
• “describe what’s currently in progress”
• “what is the status of pluto?”

אם אחד מהניסוחים האלה לא מפעיל את ה-AI Action, בדקו שוב שתיאור ה-API Action שלכם (שלב 7) מפרט את הפעלים האלה במפורש.

למה לצפות כאשר אין ב-Jira בעיות תואמות. כאשר Jira מחזירה אפס תוצאות, ה-AI Agent שלכם צריך לומר זאת במפורש, לדוגמה, “בדקתי ב-Jira ולא מצאתי בעיות תואמות לשאילתה שלך. נסו ניסוח רחב יותר או הסירו את מסנן הסטטוס.” אם במקום זאת אתם רואים שה-agent עונה “אין לי גישה ישירה ל-Jira שלך”, ה-AI Action לא הופעלה כלל. בדקו שוב את התיאור משלב 7 ואשרו שהוא מפרט במפורש פעלים שאינם חיפוש (explain, tell me about, describe, what is).

סיכום

בפוסט הזה הראינו כיצד ניתן להגדיר AI Agent לשימוש ב-API endpoint ספציפי באופן יצירתי בתוך שיחות. הגדרה נכונה לא מגיעה מוכנה מראש, היא דורשת לספק מידע נוסף ומפורט על מקרה השימוש הספציפי שאנחנו רוצים. אתם מוזמנים להשתמש מחדש בפרומפטים ובתיאורים שמופיעים בפוסט הזה כדי ליצור AI Agents דומים משלכם. לדוגמה מלאה נוספת באותו סגנון שלב אחר שלב, ראו כיצד לחבר את ה-AI Agent שלכם ל-Google Sheets ולתעד לידים, שאלות שלא נענו ובקשות דמו בגיליון אלקטרוני.

רוצים לשמור את המדריך הזה בסימניות? הגרסה הקנונית, שמתעדכנת ברציפות, של המדריך הזה נמצאת בתיעוד שלנו ב-docs.quickchat.ai/channels/jira. עברו לשם כדי להעתיק ולהדביק את תיאור ה-API Action העדכני ביותר וכדי לעקוב אחר עדכונים למתכון.

המשך העמקה

פעולת Jira אינה חייבת להיות בקשה קבועה אחת. אפשר להזריק משתני שיחה מובנים ומטא-דאטה שמור (כגון שפת המבקר או ערכים שנלכדו מוקדם יותר בשיחה) לכל שדה, ואפשר להוסיף כמה פעולות כך שה-agent יבחר את המתאימה לפי השאלה. הפניית AI Actions מכסה את סט האפשרויות המלא.

מדריכים קשורים

אותו מנגנון AI Action מחבר agent לכל HTTP API. מדריכים נוספים שמשתמשים בו:

• בניית בוט AI למודרציה ב-Discord עם AI Actions מותאמות אישית
• חיבור ה-AI Agent שלכם ל-Telegram Bot API
• חיבור ה-AI Agent שלכם ל-Google Sheets
• חיבור ה-AI Agent שלכם ל-HubSpot לתיעוד אנשי קשר, עסקאות וכרטיסים
• שליחת התראות Slack עם AI Actions
• חיבור Cal.com ל-AI Agent שלכם בתוך 5 דקות
• איך ליצור AI Support Agent מהתיעוד שלכם
• AI Agent לתמיכת לקוחות ב-SaaS

בונוס

הפוסט שלמעלה נכתב על ידי אדם (באמת אני), אבל באותה מידה הוא יכול היה להיכתב על ידי AI. לדוגמה, באמצעות הדבקת פרומפט כזה ב-ChatGPT:

אני צריך API endpoint שמאפשר לי לחפש בכרטיסי Jira שלי.

הנחה אותי בתהליך שלב אחר שלב כך שיהיה נגיש לאדם בעל ידע טכני בינוני:
- ספק קישורים לתיעוד שמתאר את ה-endpoint
- כל יצירת חשבון והגדרה ראשונית שנדרשות
- אם נדרש חשבון בתשלום, ציין זאת בבירור
- אם נדרש אימות כלשהו, כגון API tokens, הנחה אותי בתהליך יצירתם והראה לי בדיוק כל שלב שנדרש כדי שאוכל להשתמש בהם כ-HTTP request header. לדוגמה, אם נדרש קידוד base64, הראה סקריפט או דרך אחרת לבצע זאת.
- הראה לי בדיוק אילו header keys ו-values נדרשים עבור בקשת ה-HTTP (הצג header keys ו-values בטבלה)
- הראה לי בדיוק אילו payload parameters נדרשים עבור בקשת ה-HTTP (הצג שם payload parameter וערכי דוגמה בטבלה)

בעתיד, אולי במקום לחפש בכרטיסי Jira תרצו:

• לשלוח הודעות לערוץ Slack?
• לשלוף מידע מדף Notion?
• לבצע פעולה דרך Zapier?

כתבו זאת במשפט הראשון והריצו את הפרומפט שוב. תקבלו הוראות טובות לחלוטין להוספת ה-AI Action המדויקת שאתם צריכים!