Jira

W tym artykule pokażę, jak połączyć Twojego AI Agenta z Jira. Będziemy używać:

• konta Jira (bezpłatne)
• AI Agenta Quickchat (zarejestruj się tutaj i korzystaj za darmo)

To umożliwi Twojemu AI Agentowi Quickchat:

• przeszukiwanie Twoich zgłoszeń w Jira oraz
• inteligentne odpowiadanie na pytania na ich podstawie

Użyjemy AI Actions Quickchat (niestandardowe akcje HTTP), aby Agent mógł wywoływać endpoint Enhanced search for issues interfejsu API Jira (Atlassian).

Zaprojektuj AI Agenta, który kreatywnie interpretuje wpisy użytkownika

Obejrzyj wideo

Play

Jak to działa

Tak będzie działał Twój AI Agent podczas rozmów:

1. Użytkownik zadaje pytanie, np. “co słychać w tematach dotyczących Merkurego?”
2. AI Agent pobiera odpowiednie informacje z API Jira używając zapytania typu “mercury”
3. AI Agent odpowiada użytkownikowi na podstawie informacji pobranych z API

Postępuj zgodnie z poniższymi krokami. Cała konfiguracja nie powinna zająć więcej niż 10 minut!

Krok 0 – utwórz konto i projekt Jira

1. Przejdź do id.atlassian.com/signup, utwórz i zweryfikuj konto.
2. Dodaj Jira do swoich aplikacji Atlassian (na początek wystarczy plan bezpłatny).
3. Skonfiguruj pierwszy projekt i utwórz zgłoszenia jak na poniższym przykładzie.

Przykładowa tablica ze zgłoszeniami Jira

Krok 1 – token uwierzytelniania API Jira

Przejdź do id.atlassian.com/manage-profile/security/api-tokens i utwórz swój token API, który będzie wyglądał mniej więcej tak:

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

Aby móc używać tokena API Atlassian w Quickchat AI Actions, musisz zakodować go w base64 razem z adresem e‑mail:

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

Upewnij się, że podajesz dokładnie ten sam adres e‑mail, którego użyłeś do założenia konta Atlassian.

Możesz skorzystać z prostego narzędzia online, np. base64encode.org.

Użyj Live mode, który gwarantuje, że kodowanie odbywa się całkowicie w przeglądarce.

Darmowe narzędzie online do kodowania tokena API

Alternatywnie, możesz to zrobić lokalnie prostym skryptem Pythona:

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}")

Powyższy skrypt zwróci gotowy nagłówek z zakodowanym tokenem, który wygląda mniej więcej tak:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Krok 2 – utwórz AI Action w Quickchat

W aplikacji Quickchat AI przejdź do Actions & MCPs i dodaj akcję:

Strona AI Action

Nadaj swojej AI Action odpowiednią nazwę:

Name: Search Jira issues

Wprowadź nazwę AI Action

Krok 3 – ustaw parametry wejściowe

Głównym zadaniem Twojego AI Agenta będzie przetłumaczenie tego, o co pyta użytkownik, na dokładne zapytanie do wyszukiwania zgłoszeń w Jira. Jeśli chodzi o wyszukiwanie zgłoszeń, Jira niedawno w pełni przeszła na JQL (Jira Query Language), aby umożliwić bardziej złożone wyszukiwanie. Dzięki temu Twój AI Agent jest znacznie potężniejszy. Skonfiguruj parametry wejściowe w następujący sposób:

Format	Nazwa	Opis	Wartość domyślna	Wymagane
Text	jql	(patrz poniżej)	-	✅

Aby osiągnąć świetną wydajność AI Agenta, dobrze przygotowany opis ma ogromne znaczenie:

Description:

A single valid JQL (Jira Query Language) string built per the description. Favor recall: prefer `(text ~ "term1" OR text ~ "term2")` over chaining with AND, add `status = "..."` only if requested, avoid custom fields, and use parentheses for grouping. Examples: `status = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`, `(text ~ "planet*" OR text ~ "integration")`, `project = "Solar System" AND (text ~ "api" OR text ~ "integration")`.

Dobrze opracowany opis parametru to klucz do wydajności AI Agenta

Krok 4 – ustaw URL endpointu API

1. Wybierz GET jako typ akcji
2. Ustaw URL endpointu na Jira /rest/api/3/search/jql

Ustaw URL endpointu API

Pamiętaj, aby użyć swojej domeny Atlassian. Znajdziesz ją w adresie URL tablicy Jira.

Twoja domena Atlassian

Krok 5 – ustaw nagłówki żądania API

Zdefiniuj nagłówki żądania API w następujący sposób:

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

Zwróć szczególną uwagę na poprawne sformatowanie nagłówka Authorization: Basic <base64-encoded email:api token>

Ustaw nagłówki żądania API

Krok 6 – ustaw parametry zapytania (query params)

Ustaw dwa parametry dla żądania AI:

• jql pobiera wartość dynamiczną zdefiniowaną wcześniej w sekcji What to ask the user first. Zadaniem AI Agenta jest uzupełnienie wartości tego parametru na podstawie wypowiedzi użytkownika w rozmowie.
• fields pobiera wartość stałą. Dla każdego zgłoszenia Jira interesują nas tylko pola summary, description i status.

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

Ustaw parametry zapytania żądania API

Upewnij się, że parametr jql poprawnie wskazuje na wcześniej zdefiniowaną wartość. Możesz wybrać go z menu rozwijanego Add AI Data.

Wybierz dynamiczny parametr jql z menu rozwijanego

Krok 7 – ustaw opis API Action

Ostatnim, kluczowym elementem dobrze skonfigurowanej AI Action jest jej opis. Chociaż AI Agent rozumie Twój endpoint API na podstawie URL i parametrów, kluczowe jest zoptymalizowanie jego zachowania pod Twój przypadek użycia.

Trzy najważniejsze aspekty zawarte w promptcie to:

• kiedy wywołać akcję — wyraźnie wymieniając każdy sposób, w jaki użytkownik może sformułować zapytanie (find / search / look for, jak również explain / tell me about / describe / what is / how is the status of), aby agent nie pominął wywołania, gdy użytkownik nie powie „search”
• wskazówki, jak używać zaawansowanej składni JQL podczas wyszukiwania zgłoszeń Jira
• jak obsługiwać puste wyniki — agent musi to powiedzieć jednoznacznie, zamiast odmawiać dostępu

Oto wynikowy API Action Description:

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, add `status = "..."` only if the user asked for a specific status, avoid custom fields, and use parentheses for grouping.

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

Krok 8 – przetestuj API Action

Zanim przetestujemy AI Action w rozmowie, możemy sprawdzić wywołanie API w zakładce Test Response. Zróbmy pierwszy test z następującym zapytaniem, które powinno zwrócić wszystkie zgłoszenia w projekcie: project = "Solar System"

Wyszukiwanie wszystkich zgłoszeń w projekcie Solar System

Poniżej widzimy odpowiedź testową. Zgodnie z oczekiwaniami, listuje ona pola summary, description i status dla wszystkich 6 zgłoszeń na naszej tablicy Jira.

Odpowiedź listuje wszystkie zgłoszenia w projekcie Solar System

Spróbujmy jeszcze jednego zapytania. Tym razem wyszukajmy wszystkie zgłoszenia, które wspominają „mercury”: text ~ "mercury"

Wyszukiwanie zgłoszeń wspominających mercury

Zweryfikowaliśmy, że AI Action poprawnie wywołuje nasz endpoint API. Możemy przejść do testowania pełnych rozmów z AI Agentem!

Krok 9 – przetestuj AI Agenta w rozmowach

Wróć do aplikacji Quickchat AI i przetestuj swojego AI Agenta w podglądzie rozmowy.

Rozmowa #1

AI Agent przedstawia podsumowanie wszystkich zgłoszeń w projekcie

W tej prostej rozmowie AI Agent przedstawia przegląd wszystkich zgłoszeń w projekcie. Za kulisami dokładne zapytanie do endpointu API brzmiało: project = "Solar System"

Rozmowa #2

AI Agent odpowiada na pytania o konkretne zgłoszenia i statusy

W tym przypadku AI Agent został zapytany o dwa aspekty: konkretne zgłoszenie oraz ogólnie o sprawy w toku. Za kulisami zdecydował się użyć API Jira w dwuetapowym procesie:

1. Sprawdzić, czy pluto jest w toku:

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

2. Sprawdzić, co jeszcze jest w toku:

status = "In Progress"

Rozmowa #3

AI Agent odpowiada na kreatywne pytanie 😉

W tym przypadku chciałem rzucić AI Agentowi wyzwanie i zadałem pytanie wymagające pewnej kreatywności przy poprawnej interpretacji. Oto jak zostało przetłumaczone na zapytanie JQL:

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

Wypróbuj te sformułowania

Aby mieć pewność, że AI Action jest wywoływana niezależnie od tego, jak użytkownicy formułują pytanie, uruchom każde z poniższych zapytań w swoim scenariuszu testowym. Agent powinien odpytać Jirę przy każdym z nich, nie tylko przy tych w stylu wyszukiwania:

• „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?”

Jeżeli któreś z tych sformułowań nie wywoła AI Action, sprawdź ponownie, czy opis Twojej API Action (Krok 7) wyraźnie wymienia te czasowniki.

Czego oczekiwać, gdy w Jirze nie ma pasujących zgłoszeń

Gdy Jira zwraca zero wyników, AI Agent powinien powiedzieć to wprost — na przykład: „Sprawdziłem Jirę i nie znalazłem zgłoszeń pasujących do Twojego zapytania — spróbuj szerszego sformułowania lub usuń filtr statusu.”

Jeśli zamiast tego widzisz odpowiedź „Nie mam bezpośredniego dostępu do Twojej Jiry”, AI Action w ogóle się nie wywołała. Sprawdź ponownie opis z Kroku 7 i upewnij się, że wyraźnie wymienia czasowniki spoza zakresu wyszukiwania (explain, tell me about, describe, what is).

Podsumowanie

W tym artykule pokazaliśmy, jak skonfigurować AI Agenta tak, aby kreatywnie wykorzystywał konkretny endpoint API w rozmowach. Poprawna konfiguracja nie jest „z pudełka” – wymaga dostarczenia szczegółowych informacji o konkretnym przypadku użycia. Śmiało korzystaj ponownie z promptów i opisów pokazanych w tym artykule, tworząc własnych, podobnych AI Agentów!

Wolisz dłuższy, narracyjny przewodnik? Ta sama konfiguracja jest też omówiona w poście na blogu quickchat.ai. Ta strona dokumentacji jest kanonicznym, na bieżąco aktualizowanym źródłem.

🎁  BONUS

Powyższy artykuł został napisany przez człowieka (niżej podpisanego), ale równie dobrze mógłby zostać napisany przez AI. Na przykład, wklejając taki prompt do 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)

Być może w przyszłości zamiast przeszukiwać zgłoszenia Jira będziesz chciał:

• wysyłać wiadomości na kanał Slack?
• pobierać informacje ze strony Notion?
• wykonywać akcję przez Zapier?

Napisz to w pierwszym zdaniu i uruchom prompt ponownie! Otrzymasz świetne instrukcje, jak dodać dokładnie taką AI Action, jakiej potrzebujesz!