Пошук звернень Jira через власну дію

Jira не є вбудованою інтеграцією Quickchat AI. Ця сторінка показує створення власної дії API для стороннього REST API; той самий підхід працює з іншими API.

У цьому посібнику ми підключимо AI-агента до Jira. Нам знадобляться:

• обліковий запис Jira (безплатний)
• AI-агент Quickchat (зареєструйтеся й користуйтеся безплатно)

Це дасть AI-агенту Quickchat змогу:

• шукати у ваших зверненнях Jira й
• розумно відповідати на запитання на їхній основі

Ми використаємо дії AI Quickchat (власні HTTP-дії), щоб агент викликав ендпоїнт Enhanced search for issues API Jira (Atlassian).

Створіть AI-агента, який творчо інтерпретує запити користувачів

Необов’язкові перевірки прикладів

• Попередній перегляд запиту дії API. Побудуйте запит із наданого шаблону й синтетичних тестових значень без надсилання. Не додавайте заголовки з обліковими даними.

• Попередній перегляд збігів JSONPath. Перевірте шляхи до кореня, полів, індексів масиву та шляхи з підстановкою за наданим JSON. Дія не виконується, пам’ять розмови не зберігається.

У сумісному браузері ці перевірки також доступні як інструменти сайту. Посилання відкривають звичайні форми.

Перегляньте відео

Play

Як це працює

Під час розмови AI-агент працюватиме так:

1. Користувач запитує, наприклад: «що там із завданнями про Меркурій?»
2. AI-агент отримує потрібні дані з API Jira за запитом на кшталт “mercury”
3. AI-агент відповідає на основі інформації, отриманої з API

Виконайте кроки нижче. Налаштування має зайняти не більше 10 хвилин!

Крок 0: створіть обліковий запис і проєкт Jira

1. Відкрийте id.atlassian.com/signup, створіть і підтвердьте обліковий запис.
2. Додайте Jira до застосунків Atlassian (для початку достатньо безплатного тарифу).
3. Налаштуйте перший проєкт і створіть завдання, як у прикладі нижче.

Приклад дошки із завданнями Jira

Крок 1: токен автентифікації API Jira

Відкрийте id.atlassian.com/manage-profile/security/api-tokens і створіть токен API, який матиме приблизно такий вигляд:

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

Щоб використати токен Atlassian у діях Quickchat AI, закодуйте його в base64 разом з адресою email:

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

Укажіть точну адресу email, яку використали для створення облікового запису Atlassian

Можна скористатися простим онлайн-інструментом, як-от base64encode.org.

Обов’язково ввімкніть Live mode, який виконує кодування повністю у вашому браузері.

Для кодування токена API можна використати безплатний онлайн-інструмент

Або виконайте це на своєму комп’ютері простим скриптом 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

У застосунку Quickchat AI відкрийте Дії та MCP й додайте дію:

Сторінка дії AI

Задайте відповідну назву дії:

Назва: Search Jira issues

Уведіть назву дії AI

Крок 3: задайте вхідні параметри

Основне завдання AI-агента полягатиме в перетворенні запиту користувача на точний пошуковий запит Jira. Пошук Jira повністю перейшов на JQL (Jira Query Language) для складніших запитів, що розширює можливості агента. Налаштуйте вхідні параметри так:

Формат	Назва	Опис	Значення за замовчуванням	Обов’язковий
Text	jql	(див. нижче)	-	✅

Для якісної роботи AI-агента надзвичайно важливий добре продуманий опис:

Опис:

A single valid JQL (Jira Query Language) string built per the description. Favor recall: prefer `(text ~ "term1" OR text ~ "term2")` over chaining with AND, and use parentheses for grouping. For "not started / in progress / done" questions, filter on `statusCategory` ("To Do", "In Progress", "Done"), which is stable across projects; use `status = "..."` only when the user names a specific status that exists on the board. Avoid custom fields. Examples: `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 = "..." для випадків, коли користувач називає конкретний статус, який точно є на дошці. Також можна перелічити справжні назви статусів в описі дії (крок 7), щоб агент правильно зіставляв запити на кшталт «готове до QA».

Крок 4: задайте URL ендпоїнта API

1. Виберіть GET як метод запиту
2. Задайте URL ендпоїнта Jira /rest/api/3/search/jql

Задайте URL ендпоїнта API

Використовуйте власне доменне ім’я Atlassian. Воно є в URL вашої дошки Jira.

Ваше доменне ім’я Atlassian

Крок 5: задайте заголовки запиту API

Визначте заголовки запиту API так:

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

Уважно перевірте формат заголовка Authorization: Basic <base64-encoded email:api token>

Задайте заголовки запиту API

Крок 6: задайте параметри запиту API

Задайте два параметри запиту:

• jql отримує динамічне значення, визначене раніше в розділі Що спочатку запитати в користувача. AI-агент має заповнити його на основі слів користувача в розмові.
• fields має фіксоване значення. Для кожного завдання Jira нас цікавлять лише summary, description і status.

jql	fields
{{jql}}	summary,description,status

Задайте параметри запиту API

Перевірте, що jql правильно посилається на раніше визначене значення. Його можна вибрати зі списку додавання даних AI.

Виберіть динамічний параметр jql зі списку

Крок 7: задайте опис дії API

Останній важливий складник налаштованої дії AI є її опис. Хоча агент розуміє ендпоїнт за URL і параметрами, потрібно оптимізувати поведінку для вашого сценарію.

Три найважливіші аспекти промпту:

• коли викликати дію: перелічіть усі можливі формулювання (знайти / шукати, а також пояснити / розкажи про / описати / що це / який статус), щоб агент не пропускав виклик без слова «пошук»
• підказки щодо використання розширеного синтаксису JQL для пошуку завдань Jira
• обробка порожніх результатів: агент має прямо повідомити про них, а не заявляти про відсутність доступу

Ось отриманий Опис дії API:

Use this action whenever the user asks anything that could be answered by data in their Jira — projects, issues, statuses, sprints, test cycles, descriptions, owners, comments — regardless of how they phrase the request (find / search / look for / explain / tell me about / describe / what is / how is the status of, etc.). Do not refuse access; query Jira first.

Construct a JQL that prioritises recall over precision: prefer `(text ~ "term1" OR text ~ "term2")` over chaining with AND, and use parentheses for grouping. For lifecycle questions (not started, in progress, done) filter on `statusCategory` ("To Do" / "In Progress" / "Done") rather than `status`, because status names vary by board; use `status = "..."` only when the user names a specific status. Avoid custom fields.

If Jira returns no matches, say so explicitly to the user and suggest a refined query.

Крок 8: протестуйте дію API

Перед тестуванням у розмові можна перевірити сам виклик API на вкладці Перевірка відповіді. Почнімо із запиту, який має повернути всі завдання проєкту: project = "Solar System"

Пошук усіх завдань проєкту Solar System

Нижче наведено тестову відповідь. Як і очікувалося, вона містить поля summary, description і status усіх 6 завдань дошки Jira.

Відповідь містить усі завдання проєкту Solar System

Спробуймо ще один запит: усі завдання зі згадкою “mercury”: text ~ "mercury"

Пошук завдань зі згадкою mercury

Ми перевірили, що дія AI правильно викликає ендпоїнт. Тепер можна тестувати повні розмови з AI-агентом!

Крок 9: протестуйте AI-агента в розмовах

Поверніться до застосунку Quickchat AI й протестуйте агента в попередньому перегляді розмови.

Розмова 1

AI-агент підсумовує всі завдання проєкту

У цій простій розмові AI-агент надає огляд усіх завдань проєкту. Якщо подивитися на виконаний запит до API, він був таким: project = "Solar System"

Розмова 2

AI-агент відповідає про конкретні завдання й статуси

Тут AI-агента запитали про два аспекти: конкретне завдання й поточні завдання загалом. Він вирішив звернутися до API Jira у два кроки:

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-агент відповідає на творчий запит 😉

У цьому випадку я поставив агенту незвичне запитання, для правильного розуміння якого потрібен творчий підхід. Ось як він перетворив його на JQL:

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

Спробуйте ці формулювання

Щоб переконатися, що дія запускається незалежно від формулювання користувача, виконайте кожен із запитів нижче в тестовому сценарії. Агент має звертатися до Jira для всіх, а не лише для запитів зі словом «знайти»:

• «знайди всі відкриті завдання про рахунки матчів наживо»
• «знайди завдання з mercury»
• «поясни проєкт Solar System»
• «розкажи про відкриті завдання цього спринту»
• «опиши, що зараз виконується»
• «який статус pluto?»

Якщо будь-яке формулювання не запускає дію, перевірте, що опис дії API (крок 7) явно містить ці дієслова.

Що очікувати, коли Jira не має відповідних завдань

Якщо Jira повертає нуль результатів, AI-агент має прямо сказати про це, наприклад: «Я перевірив Jira й не знайшов відповідних завдань. Спробуйте ширше формулювання або приберіть фільтр статусу».

Якщо натомість агент відповідає «Я не маю прямого доступу до вашої Jira», дія AI взагалі не виконувалася. Перевірте опис із кроку 7 і переконайтеся, що він явно перелічує дієслова без пошукового значення (explain, tell me about, describe, what is).

Підсумок

У цьому посібнику ми налаштували AI-агента для творчого використання конкретного ендпоїнта API в розмовах. Правильна поведінка не виникає автоматично: потрібно надати докладну інформацію про задуманий сценарій. Використовуйте наведені промпти й описи для створення власних подібних AI-агентів!

Бажаєте докладний покроковий виклад? Те саме налаштування описано в блозі quickchat.ai. Ця сторінка документації є основним довідником, що постійно оновлюється.

Подальші можливості

Дія Jira не обов’язково має бути одним фіксованим запитом. Ви можете підставляти вбудовані змінні розмови й збережені метадані, наприклад мову відвідувача або раніше зібрані значення, у будь-яке поле, а також додати кілька дій, щоб агент вибирав потрібну для кожного запитання. Усі можливості наведено в довіднику дій.

🎁  БОНУС

Цей посібник написала людина (ваш покірний слуга), але його цілком міг написати AI. Наприклад, можна вставити такий промпт у ChatGPT:

I need an API endpoint that allows me to search through my Jira tickets.

Guide me through the process step by step so that it is accessible to a moderately technical person:
- Provide links to documentation describing the endpoint
- Any necessary account creation and initial setup
- If any paid account is needed, indicate that clearly
- If any authentication such as API tokens is needed, guide me through the process of creating them and show me exactly every step needed to be able to use them as an HTTP request header. For example, if base64 encoding is needed, show a script or another way of achieving that.
- Show to me exactly what header keys and values I need for the HTTP request (show me header keys and values in a table)
- Show to me exactly what payload parameters I need for the HTTP request (show me payload parameter name and example values in a table)

Можливо, надалі замість пошуку завдань Jira ви захочете:

• надсилати повідомлення в канал Slack?
• отримувати інформацію зі сторінки Notion?
• виконувати дію через Zapier?

Укажіть це в першому реченні й запустіть промпт знову! Ви отримаєте корисні інструкції для додавання потрібної дії AI.