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.

Dwa najważniejsze aspekty zawarte w promptcie to:

• wskazówki, jak używać zaawansowanej składni JQL podczas wyszukiwania zgłoszeń Jira
• potrzeba prowadzenia szerokich wyszukiwań, aby uniknąć zwracania pustych rezultatów

Oto wynikowy API Action Description:

Infer the user’s intent and construct a single valid JQL that prioritizes recall over precision. Use `text ~ "..."` for contains (case-insensitive) domain / content terms (features, services, tasks, components, etc.). If multiple candidate terms exist, prefer OR and wrap in parentheses. Include `status = "..."` only when the user states a status. Never invent custom fields; only use standard fields like `text`, `status`, and `project` if explicitly mentioned. Keep queries short to avoid zero results. Use parentheses to make precedence explicit (AND binds tighter than OR). Example: `status = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`.

Opis musi dokładnie określać, jak należy używać żądania API

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

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!

🎁  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!