Поиск задач Jira с помощью пользовательского действия

Jira не является встроенной интеграцией Quickchat AI. На этой странице приведён подробный пример создания пользовательского действия API для стороннего REST API. Такой же подход подходит и для других API.

В этой статье я покажу, как подключить AI-агента к Jira. Мы будем использовать:

• аккаунт Jira (бесплатно)
• AI-агента Quickchat (зарегистрируйтесь здесь и используйте бесплатно)

После настройки AI-агент Quickchat сможет:

• искать задачи Jira и
• разумно отвечать на вопросы на основе найденных задач

Мы используем AI-действия Quickchat (пользовательские HTTP-действия), чтобы агент мог вызывать конечную точку расширенного поиска задач 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

Чтобы использовать API-токен Atlassian в AI-действиях Quickchat, закодируйте его в base64 вместе со своим адресом электронной почты:

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

Обязательно укажите именно тот адрес электронной почты, который использовали для создания аккаунта 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. Создайте AI-действие Quickchat

В приложении Quickchat AI перейдите в Действия и MCP и добавьте действие:

Страница AI-действия

Задайте AI-действию подходящее название:

Название: Search Jira issues

Введите название AI-действия

Шаг 3. Настройте входные параметры

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

Формат	Название	Описание	Значение по умолчанию	Обязательный
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 в качестве метода запроса API
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

Задайте два параметра строки запроса для AI:

• jql получает динамическое значение, определённое ранее в разделе Что сначала спросить у пользователя. AI-агент должен заполнить значение этого параметра на основе слов пользователя в разговоре.
• fields получает фиксированное значение. Для каждой задачи Jira нам нужны только поля summary, description и status.

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

Задайте параметры строки запроса API

Убедитесь, что параметр jql правильно ссылается на ранее определённое значение. Его можно выбрать в раскрывающемся меню «Добавить данные AI».

Выберите динамический параметр jql в раскрывающемся меню

Шаг 7. Задайте описание действия API

Последняя важная составляющая правильно настроенного AI-действия состоит в его описании. Хотя AI-агент хорошо понимает конечную точку API по её 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

Прежде чем тестировать AI-действие в разговоре, можно проверить сам вызов API на вкладке Проверка ответа. Выполним первую проверку со следующим запросом, который должен вернуть все задачи проекта: project = "Solar System"

Поиск всех задач проекта Solar System

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

В ответе перечислены все задачи проекта Solar System

Попробуем ещё один запрос. Теперь найдём все задачи, в которых упоминается «mercury»: text ~ "mercury"

Поиск задач, в которых упоминается mercury

Мы убедились, что AI-действие правильно вызывает конечную точку API. Теперь можно перейти к проверке полноценных разговоров с AI-агентом!

Шаг 9. Проверьте AI-агента в разговорах

Вернитесь в приложение Quickchat AI и проверьте 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-агент отвечает на творчески сформулированный вопрос 😉

В этом случае я решил усложнить задачу AI-агенту и задал вопрос, для правильного понимания которого нужна некоторая изобретательность. Вот как он был преобразован в запрос JQL:

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

Попробуйте эти формулировки

Чтобы убедиться, что AI-действие вызывается независимо от формулировки запроса конечного пользователя, проверьте каждый из промптов ниже в своём тестовом сценарии. Агент должен обращаться к Jira для каждого из них, а не только для явных поисковых запросов:

• «найди все открытые задачи о результатах матчей в реальном времени»
• «поищи задачи с mercury»
• «объясни проект Solar System»
• «расскажи об открытых задачах этого спринта»
• «опиши, что сейчас в работе»
• «каков статус pluto?»

Если какая-либо формулировка не вызывает AI-действие, проверьте, что в описании действия 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-действия, которое вам нужно!