Подключение AI Agent к тикетам Jira

Введение

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

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

Ищете каноническую справочную версию, которая постоянно обновляется? То же пошаговое руководство доступно в нашей документации по адресу docs.quickchat.ai/channels/jira. Эта статья, развернутая версия с пояснениями.

Это позволит вашему Quickchat AI Agent:

• выполнять поиск по вашим тикетам Jira, и
• осмысленно отвечать на вопросы на их основе

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

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 крайне важно хорошо составленное описание:

Описание:

Одна допустимая строка 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. Это частая причина, по которой агент уверенно сообщает “no tickets to do”, хотя доска заполнена такими тикетами. Для вопросов “what has not started”, “what is in progress” и “what is done” фильтруйте по категории:

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

Оставьте status = "..." для случаев, когда пользователь называет конкретный статус, который, как вы знаете, существует на доске. Вы также можете перечислить реальные имена статусов вашей доски в описании Action (Шаг 7), чтобы агент сопоставлял запрос вроде “ready for QA” с правильным статусом.

Шаг 4, задайте URL эндпоинта API

1. Выберите GET как Action Type
2. Укажите URL эндпоинта Jira /rest/api/3/search/jql

Задайте URL эндпоинта API

Убедитесь, что используете ваше доменное имя Atlassian. Вы найдете его в URL вашей доски Jira.

Ваше доменное имя Atlassian

Шаг 5, задайте заголовки API-запроса

Определите headers вашего API-запроса следующим образом:

Обратите особое внимание на правильное форматирование вашего Authorization header: Basic <base64-encoded email:api token>

Задайте заголовки API-запроса

Шаг 6, задайте query parameters API-запроса

Задайте два query parameters для вашего AI-запроса:

• jql принимает динамическое значение, определенное ранее в разделе What to ask the user first. Заполнить значение этого параметра на основе того, что пользователь сказал в беседе, должен AI Agent.
• fields принимает фиксированное значение. Для каждой задачи Jira нас интересуют только summary, description и status.

Задайте query parameters API-запроса

Убедитесь, что параметр jql правильно указывает на значение, определенное ранее. Вы можете выбрать его в выпадающем меню Add AI Data.

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

Шаг 7, задайте описание API Action

Последний важный элемент правильно настроенного AI Action, его описание. Хотя AI Agent хорошо понимает ваш API-эндпоинт уже по его URL и параметрам, важно оптимизировать его поведение под ваш сценарий использования.

Три наиболее важных аспекта, включенных в prompt:

• когда вызывать действие: перечислите все формулировки, которые может выбрать пользователь (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

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

Ответ перечисляет все задачи в проекте Solar System

Попробуем еще один запрос. На этот раз найдем все задачи, где упоминается “mercury”: text ~ "mercury"

Поиск задач, где упоминается mercury

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

Шаг 9, протестируйте AI Agent в беседах

Вернитесь в Quickchat AI app и протестируйте вашего AI Agent в предварительном просмотре беседы.

Беседа #1

AI Agent дает сводку по всем задачам в проекте

В этой простой беседе AI Agent дает обзор всех задач в проекте. Если посмотреть, что происходило за кадром, точный запрос, который он выполнил к API-эндпоинту, был таким: 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 запускается независимо от того, как конечные пользователи формулируют запрос, выполните каждый из prompts ниже в вашем тестовом сценарии. Агент должен запрашивать 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 должен явно сообщить об этом, например: “I checked Jira and found no matching issues for your query, try a broader phrasing or remove the status filter.” Если вместо этого вы видите ответ агента “I don’t have direct access to your Jira”, AI Action вообще не запустился. Перепроверьте описание из Шага 7 и убедитесь, что в нем явно перечислены глаголы, не связанные напрямую с поиском (explain, tell me about, describe, what is).

Итоги

В этой статье мы показали, как настроить AI Agent для использования конкретного API-эндпоинта в беседах гибким способом. Правильная настройка не работает из коробки, она требует подробной дополнительной информации о конкретном сценарии использования. Вы можете повторно использовать prompts и описания, показанные в этой статье, при создании собственных похожих AI Agents. Еще один полный пример в том же пошаговом формате, как подключить ваш AI Agent к Google Sheets и записывать лиды, вопросы без ответа и запросы на демо в электронную таблицу.

Хотите сохранить это руководство в закладки? Каноническая, постоянно обновляемая версия этого пошагового руководства доступна в нашей документации по адресу docs.quickchat.ai/channels/jira, перейдите туда, чтобы скопировать актуальное описание API Action и следить за обновлениями инструкции.

Дальнейшие шаги

Действие Jira не обязано быть одним фиксированным запросом. Вы можете подставлять встроенные переменные беседы и сохраненные метаданные (например, язык посетителя или значения, полученные ранее в беседе) в любое поле, а также добавить несколько действий, чтобы агент выбирал подходящее для конкретного вопроса. Справочник по AI Actions описывает полный набор возможностей.

Связанные руководства

Тот же механизм AI Action подключает агента к любому 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 такой prompt:

Мне нужен API-эндпоинт, который позволит искать мои тикеты Jira.

Проведите меня через процесс шаг за шагом так, чтобы он был понятен человеку с умеренным техническим опытом:
- Дайте ссылки на документацию, описывающую эндпоинт
- Укажите все необходимые шаги по созданию аккаунта и первоначальной настройке
- Если нужен платный аккаунт, явно укажите это
- Если нужна аутентификация, например API-токены, проведите меня через процесс их создания и покажите точно каждый шаг, необходимый для их использования в качестве HTTP request header. Например, если нужно кодирование base64, покажите скрипт или другой способ это сделать.
- Покажите мне точно, какие header keys and values нужны для HTTP-запроса (покажите header keys and values в таблице)
- Покажите мне точно, какие payload parameters нужны для HTTP-запроса (покажите имя payload parameter и примерные значения в таблице)

В будущем, возможно, вместо поиска по тикетам Jira вы захотите:

• отправлять сообщения в Slack channel?
• получать информацию со страницы Notion?
• выполнять действие через Zapier?

Укажите это в первом предложении и запустите prompt снова. Вы получите вполне пригодные инструкции, чтобы добавить именно тот AI Action, который вам нужен!