Połącz Agenta AI z ticketami Jira

Wprowadzenie

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

• konta Jira (darmowego)
• Agenta AI od Quickchat (zarejestruj się tutaj i korzystaj za darmo)

Szukasz kanonicznej, stale aktualizowanej wersji? Ten sam przewodnik znajduje się w naszej dokumentacji pod adresem docs.quickchat.ai/channels/jira. Ten wpis to dłuższa wersja z opisem kontekstu.

Umożliwi to twojemu Agentowi Quickchat AI:

• przeszukiwanie ticketów Jira, oraz
• inteligentne odpowiadanie na pytania na ich podstawie

Użyjemy AI Actions (niestandardowych akcji HTTP) w Quickchat, aby twój Agent mógł wywoływać endpoint Enhanced search for issues w API Jira (Atlassian).

Skonfiguruj Agenta AI tak, aby kreatywnie interpretował dane wejściowe użytkownika

Obejrzyj wideo

Jak to działa

Oto jak twój Agent AI będzie działać podczas rozmów:

1. Użytkownik zadaje pytanie, na przykład “what’s up with issues to do with mercury?”
2. Agent AI pobiera odpowiednie informacje z Jira API, używając zapytania takiego jak “mercury”
3. Agent AI odpowiada użytkownikowi na podstawie informacji pobranych z API

Wykonaj poniższe kroki. Cała konfiguracja nie powinna zająć więcej niż 10 minut!

Krok 0 - utwórz konto Jira i projekt

1. Przejdź do id.atlassian.com/signup, utwórz konto i je zweryfikuj.
2. Dodaj Jira do swoich aplikacji Atlassian (na start wystarczy darmowy plan).
3. Skonfiguruj pierwszy projekt i utwórz tickety, jak w przykładzie poniżej.

Przykładowa tablica ze zgłoszeniami Jira

Krok 1 - token uwierzytelniający Jira API

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

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

Aby móc użyć tokenu Atlassian API w Quickchat AI Actions, musisz zakodować go w base64 razem ze swoim adresem e-mail:

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

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

Możesz użyć prostego narzędzia online, takiego jak base64encode.org.

Upewnij się, że używasz Live mode, który gwarantuje, że kodowanie odbywa się w całości w twojej przeglądarce.

Możesz użyć darmowego narzędzia online do zakodowania tokenu API

Alternatywnie możesz zrobić to na swoim komputerze za pomocą prostego skryptu 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}")

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

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Krok 2 - utwórz Quickchat AI Action

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

Strona AI Action

Nadaj swojej AI Action odpowiednią nazwę:

Nazwa: Search Jira issues

Wprowadź nazwę AI Action

Krok 3 - ustaw parametry wejściowe

Głównym zadaniem twojego Agenta AI będzie przetłumaczenie tego, o co pyta użytkownik, na dokładne zapytanie służące do przeszukiwania zgłoszeń Jira. Jeśli chodzi o wyszukiwanie zgłoszeń, Jira niedawno w pełni przeszła na JQL (Jira Query Language), aby umożliwić wykonywanie bardziej złożonych wyszukiwań. Dzięki temu twój Agent AI może być znacznie skuteczniejszy. Ustaw parametry wejściowe w następujący sposób:

Aby uzyskać wysoką skuteczność Agenta AI, dobrze przygotowany opis ma bardzo duże znaczenie:

Opis:

Pojedynczy poprawny ciąg JQL (Jira Query Language) zbudowany zgodnie z opisem. Preferuj wysokie recall: używaj raczej `(text ~ "term1" OR text ~ "term2")` zamiast łączenia warunków przez AND, i używaj nawiasów do grupowania. W przypadku pytań o "not started / in progress / done" filtruj po `statusCategory` ("To Do", "In Progress", "Done"), które jest stabilne między projektami; używaj `status = "..."` tylko wtedy, gdy użytkownik podaje konkretny status istniejący na tablicy. Unikaj pól niestandardowych. Przykłady: `statusCategory = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`, `(text ~ "planet*" OR text ~ "integration")`, `project = "Solar System" AND statusCategory = "To Do"`.

Dobrze przygotowany opis parametru jest kluczowy dla skuteczności Agenta AI

Uwaga o statusach Jira

Jira oddziela nazwę statusu od jego kategorii, a JQL traktuje je inaczej:

• Nazwa statusu to to, co pokazuje tablica. Jeden projekt używa To Do / In Progress / Done, inny używa Open / In Review / Closed.
• Kategoria statusu to jeden z trzech stałych koszyków, do których mapuje się każdy status: To Do, In Progress, Done.

status = "To Do" filtruje po nazwie, więc nie zwróci nic na tablicy, której pierwsza kolumna nazywa się Open. To częsty powód, dla którego agent z przekonaniem informuje, że nie ma “ticketów do zrobienia”, mimo że tablica jest nimi wypełniona. Dla pytań o to, “co nie zostało rozpoczęte”, “co jest w toku” i “co jest zrobione”, filtruj zamiast tego po kategorii:

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

Zostaw status = "..." na sytuacje, gdy użytkownik podaje konkretny status, o którym wiesz, że istnieje na tablicy. Możesz też wypisać rzeczywiste nazwy statusów z tablicy w opisie Action (Krok 7), aby agent mapował prośbę taką jak “ready for QA” na właściwy status.

Krok 4 - ustaw URL endpointu API

1. Wybierz GET jako Action Type
2. Ustaw URL endpointu na endpoint Jira /rest/api/3/search/jql

Ustaw URL endpointu API

Upewnij się, że używasz nazwy swojej domeny Atlassian. Znajdziesz ją w URL swojej tablicy Jira.

Nazwa twojej domeny Atlassian

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

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

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 żądania API

Ustaw dwa parametry zapytania dla żądania AI:

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

Ustaw parametry zapytania żądania API

Upewnij się, że parametr jql poprawnie wskazuje 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. Agent AI dość dobrze rozumie twój endpoint API już na podstawie jego URL i parametrów, ale ważne jest zoptymalizowanie jego zachowania pod twój przypadek użycia.

Trzy najważniejsze elementy ujęte w prompcie to:

• kiedy wywołać akcję: wypisanie wszystkich sformułowań, których użytkownik może użyć (find / search / look for, a także explain / tell me about / describe / what is / how is the status of), aby agent nie pominął wywołania, gdy użytkownik nie powie “search”
• sugestie dotyczące używania zaawansowanej składni JQL podczas wyszukiwania zgłoszeń Jira
• jak obsługiwać puste wyniki: agent musi powiedzieć to wprost, zamiast odmawiać dostępu

Oto wynikowy API Action Description:

Użyj tej akcji zawsze, gdy użytkownik pyta o cokolwiek, na co można odpowiedzieć danymi z jego Jira: projekty, zgłoszenia, statusy, sprinty, cykle testowe, opisy, właścicieli, komentarze, niezależnie od tego, jak formułuje prośbę (find / search / look for / explain / tell me about / describe / what is / how is the status of, itd.). Nie odmawiaj dostępu; najpierw odpytaj Jira.

Zbuduj JQL, który priorytetowo traktuje recall względem precyzji: używaj raczej `(text ~ "term1" OR text ~ "term2")` zamiast łączenia warunków przez AND, i używaj nawiasów do grupowania. W przypadku pytań o cykl życia (not started, in progress, done) filtruj po `statusCategory` ("To Do" / "In Progress" / "Done"), a nie po `status`, ponieważ nazwy statusów różnią się między tablicami; używaj `status = "..."` tylko wtedy, gdy użytkownik podaje konkretny status. Unikaj pól niestandardowych.

Jeśli Jira nie zwróci dopasowań, powiedz to użytkownikowi wprost i zaproponuj doprecyzowanie zapytania.

Krok 8 - przetestuj API Action

Zanim przetestujemy AI Action w rozmowie, możemy sprawdzić, jak samo API jest wywoływane w zakładce Test Response. Zróbmy pierwszy test z poniższym zapytaniem, które powinno zwrócić wszystkie zgłoszenia w projekcie: project = "Solar System"

Wyszukiwanie wszystkich zgłoszeń w projekcie Solar System

Poniżej znajduje się odpowiedź testowa, którą otrzymujemy. Zgodnie z oczekiwaniami zawiera pola summary, description i status dla wszystkich 6 zgłoszeń na naszej tablicy Jira.

Odpowiedź zawiera wszystkie zgłoszenia w projekcie Solar System

Wypróbujmy jeszcze jedno zapytanie. Tym razem wyszukajmy wszystkie zgłoszenia, które wspominają o “mercury”: text ~ "mercury"

Wyszukiwanie zgłoszeń, które wspominają mercury

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

Krok 9 - przetestuj Agenta AI w rozmowach

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

Rozmowa #1

Agent AI podaje podsumowanie wszystkich zgłoszeń w projekcie

W tej prostej rozmowie Agent AI podaje przegląd wszystkich zgłoszeń w projekcie. Spojrzenie za kulisy mówi nam, że dokładne zapytanie wykonane przez niego wobec endpointu API to: project = "Solar System"

Rozmowa #2

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

W tym przypadku Agent AI został zapytany o dwa osobne aspekty: konkretne zgłoszenie i ogólnie trwające prace. Spojrzenie za kulisy mówi nam, że zdecydował się użyć Jira API w dwuetapowym procesie:

1. Sprawdź, czy pluto jest w toku:

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

2. Sprawdź, co jeszcze jest w toku:

status = "In Progress"

Rozmowa #3

Agent AI odpowiada na kreatywne zapytanie 😉

W tym przypadku chciałem postawić Agenta AI przed nietypowym zadaniem i zadałem mu pytanie, którego poprawna interpretacja wymaga trochę kreatywności. 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 uruchamia się niezależnie od tego, jak użytkownicy końcowi formułują prośbę, uruchom każdy z poniższych promptów w swoim scenariuszu testowym. Agent powinien odpytać Jira dla każdego z nich, nie tylko dla tych przypominających wyszukiwanie:

• “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śli któreś z tych sformułowań nie wywołuje AI Action, sprawdź ponownie, czy opis API Action (Krok 7) wyraźnie wymienia te czasowniki.

Czego oczekiwać, gdy Jira nie ma pasujących zgłoszeń. Gdy Jira zwraca zero wyników, Agent AI powinien powiedzieć to wprost, na przykład: “Sprawdziłem Jira i nie znalazłem pasujących zgłoszeń dla twojego zapytania. Spróbuj szerszego sformułowania albo usuń filtr statusu.” Jeśli zamiast tego widzisz odpowiedź agenta: “Nie mam bezpośredniego dostępu do twojego Jira”, AI Action w ogóle się nie uruchomiła. Sprawdź ponownie opis z Kroku 7 i upewnij się, że wyraźnie wymienia czasowniki niezwiązane z wyszukiwaniem (explain, tell me about, describe, what is).

Podsumowanie

W tym wpisie pokazaliśmy, jak skonfigurować Agenta AI, aby używał konkretnego endpointu API w kreatywny sposób podczas rozmów. Poprawna konfiguracja nie działa od razu po utworzeniu, wymaga podania szczegółowych dodatkowych informacji o konkretnym przypadku użycia, który mamy na myśli. Możesz wykorzystać prompty i opisy pokazane w tym wpisie do tworzenia własnych podobnych Agentów AI. Inny kompletny przykład w tym samym stylu krok po kroku znajdziesz w przewodniku, jak połączyć Agenta AI z Google Sheets i zapisywać leady, pytania bez odpowiedzi oraz prośby o demo w arkuszu kalkulacyjnym.

Chcesz zachować ten przewodnik w zakładkach? Kanoniczna, stale aktualizowana wersja tego przewodnika znajduje się w naszej dokumentacji pod adresem docs.quickchat.ai/channels/jira. Przejdź tam, aby skopiować najnowszy opis API Action i śledzić aktualizacje przepisu.

Co dalej

Akcja Jira nie musi być pojedynczym stałym żądaniem. Możesz wstrzykiwać wbudowane zmienne rozmowy i zapisane metadane (takie jak język odwiedzającego lub wartości zebrane wcześniej w rozmowie) do dowolnego pola, a także dodać kilka akcji, aby agent wybierał właściwą dla danego pytania. Dokumentacja AI Actions opisuje pełny zestaw opcji.

Powiązane przewodniki

Ten sam mechanizm AI Action łączy agenta z dowolnym HTTP API. Inne przewodniki, które go używają:

• Zbuduj bota moderacyjnego AI dla Discorda z niestandardowymi AI Actions
• Połącz Agenta AI z Telegram Bot API
• Połącz Agenta AI z Google Sheets
• Połącz Agenta AI z HubSpot, aby zapisywać kontakty, deale i tickety
• Wysyłaj powiadomienia Slack za pomocą AI Actions
• Połącz Cal.com ze swoim Agentem AI w 5 minut
• Jak utworzyć Agenta AI do obsługi klienta z dokumentacji
• Agent AI do obsługi klienta SaaS

BONUS

Powyższy wpis został napisany przez człowieka (przeze mnie), ale równie dobrze mógłby zostać napisany przez AI. Na przykład przez wklejenie do ChatGPT takiego promptu:

Potrzebuję endpointu API, który pozwala przeszukiwać moje tickety Jira.

Przeprowadź mnie przez ten proces krok po kroku, tak aby był zrozumiały dla osoby średnio technicznej:
- Podaj linki do dokumentacji opisującej endpoint
- Uwzględnij niezbędne utworzenie konta i wstępną konfigurację
- Jeśli potrzebne jest jakiekolwiek płatne konto, wyraźnie to zaznacz
- Jeśli potrzebne jest uwierzytelnianie, na przykład tokeny API, przeprowadź mnie przez proces ich tworzenia i pokaż dokładnie każdy krok potrzebny do użycia ich jako nagłówka żądania HTTP. Na przykład jeśli potrzebne jest kodowanie base64, pokaż skrypt lub inny sposób osiągnięcia tego.
- Pokaż mi dokładnie, jakie klucze i wartości nagłówków są potrzebne dla żądania HTTP (pokaż klucze i wartości nagłówków w tabeli)
- Pokaż mi dokładnie, jakich parametrów payload potrzebuję dla żądania HTTP (pokaż nazwę parametru payload i przykładowe wartości w tabeli)

W przyszłości zamiast przeszukiwać tickety Jira możesz chcieć:

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

Powiedz to w pierwszym zdaniu i uruchom prompt ponownie. Otrzymasz poprawne instrukcje dodania dokładnie takiej AI Action, jakiej potrzebujesz!