AI Agent mit Jira-Tickets verbinden

Einführung

In diesem Blogbeitrag zeige ich dir, wie du deinen AI Agent mit Jira verbindest. Wir verwenden:

• ein Jira-Konto (kostenlos)
• einen AI Agent von Quickchat (hier registrieren und kostenlos nutzen)

Suchst du die kanonische, laufend aktualisierte Referenz? Dieselbe Anleitung findest du in unserer Dokumentation unter docs.quickchat.ai/channels/jira. Dieser Beitrag ist die ausführliche, kommentierte Version.

Damit kann dein Quickchat AI Agent:

• deine Jira-Tickets durchsuchen und
• Fragen auf ihrer Grundlage intelligent beantworten

Wir verwenden Quickchats AI Actions (benutzerdefinierte HTTP-Aktionen), damit dein Agent den Endpunkt Enhanced search for issues der Jira-API (Atlassian) aufrufen kann.

Erstelle einen AI Agent, der Benutzereingaben kreativ interpretiert

Video ansehen

Funktionsweise

So arbeitet dein AI Agent während Konversationen:

1. Der Benutzer stellt eine Frage wie “what’s up with issues to do with mercury?”
2. Der AI Agent ruft relevante Informationen aus der Jira API mit einer Abfrage wie “mercury” ab
3. Der AI Agent antwortet dem Benutzer auf Grundlage der Informationen, die aus der API abgerufen wurden

Bitte befolge die folgenden Schritte. Die gesamte Einrichtung sollte nicht länger als 10 Minuten dauern.

Schritt 0: Jira-Konto und Projekt erstellen

1. Gehe zu id.atlassian.com/signup, erstelle dein Konto und bestätige es.
2. Füge Jira zu deinen Atlassian-Apps hinzu (der kostenlose Plan reicht für den Einstieg).
3. Richte dein erstes Projekt ein und erstelle Tickets wie im folgenden Beispiel.

Beispiel-Board mit Jira-Issues

Schritt 1: Authentifizierungstoken für die Jira-API

Gehe zu id.atlassian.com/manage-profile/security/api-tokens und erstelle dein API token, das ungefähr so aussieht:

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

Damit du dein Atlassian-API-Token in Quickchat AI Actions verwenden kannst, musst du es zusammen mit deiner E-Mail-Adresse base64-kodieren:

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

Achte darauf, genau die E-Mail-Adresse einzuschließen, mit der du dein Atlassian-Konto eingerichtet hast

Du kannst ein einfaches Online-Tool wie base64encode.org verwenden.

Achte darauf, den Live mode zu verwenden. Er garantiert, dass die Kodierung vollständig in deinem Browser erfolgt.

Du kannst ein kostenloses Online-Tool verwenden, um dein API-Token zu kodieren

Alternativ kannst du das auf deinem Rechner mit einem einfachen Python-Skript erledigen:

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

Das obige Skript gibt dir einen sofort verwendbaren Header mit dem kodierten Token aus, der ungefähr so aussieht:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Schritt 2: Quickchat AI Action erstellen

Gehe in der Quickchat AI app zu Actions & MCPs und füge eine Action hinzu:

Seite der AI Action

Gib deiner AI Action einen passenden Namen:

Name: Search Jira issues

Name der AI Action einfügen

Schritt 3: Eingabeparameter festlegen

Die Hauptaufgabe deines AI Agent besteht darin, das Anliegen des Benutzers in eine exakte Abfrage zu übersetzen, mit der Jira-Issues durchsucht werden. Für die Suche nach Issues ist Jira kürzlich vollständig auf JQL (Jira Query Language) migriert, um komplexere Suchvorgänge zu ermöglichen. Dadurch kann dein AI Agent deutlich leistungsfähiger arbeiten. Lege deine Eingabeparameter wie folgt fest:

Um mit deinem AI Agent eine hohe Leistung zu erzielen, ist eine gut formulierte Beschreibung sehr wichtig:

Beschreibung:

Ein einzelner gültiger JQL-String (Jira Query Language), der gemäß der Beschreibung erstellt wird. Bevorzuge Recall: Verwende lieber `(text ~ "term1" OR text ~ "term2")` statt einer Verkettung mit AND, und verwende Klammern zur Gruppierung. Filtere bei Fragen zu "not started / in progress / done" nach `statusCategory` ("To Do", "In Progress", "Done"), da diese projektübergreifend stabil ist. Verwende `status = "..."` nur, wenn der Benutzer einen bestimmten Status nennt, der auf dem Board existiert. Vermeide benutzerdefinierte Felder. Beispiele: `statusCategory = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`, `(text ~ "planet*" OR text ~ "integration")`, `project = "Solar System" AND statusCategory = "To Do"`.

Eine gut formulierte Parameterbeschreibung ist entscheidend für die Leistung des AI Agent

Hinweis zu Jira-Status

Jira trennt den Namen eines Status von seiner Kategorie, und JQL behandelt beide unterschiedlich:

• Der Statusname ist das, was das Board anzeigt. Ein Projekt verwendet To Do / In Progress / Done, ein anderes verwendet Open / In Review / Closed.
• Die Statuskategorie ist einer von drei festen Buckets, denen jeder Status zugeordnet wird: To Do, In Progress, Done.

status = "To Do" filtert nach Namen. Auf einem Board, dessen erste Spalte Open heißt, liefert diese Abfrage daher nichts zurück. Das ist ein häufiger Grund dafür, dass ein Agent überzeugt meldet, es gebe “no tickets to do”, obwohl das Board voll davon ist. Filtere bei Fragen wie “what has not started”, “what is in progress” und “what is done” stattdessen nach der Kategorie:

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

Behalte status = "..." für Fälle bei, in denen der Benutzer einen bestimmten Status nennt, von dem du weißt, dass er auf dem Board existiert. Du kannst außerdem die tatsächlichen Statusnamen deines Boards in der Action-Beschreibung (Schritt 7) auflisten, damit der Agent eine Anfrage wie “ready for QA” dem richtigen Status zuordnet.

Schritt 4: URL des API-Endpunkts festlegen

1. Wähle GET als Action Type aus
2. Lege als Endpunkt-URL den Jira-Endpunkt /rest/api/3/search/jql fest

URL deines API-Endpunkts festlegen

Achte darauf, deinen Atlassian-Domainnamen zu verwenden. Du findest ihn in der URL deines Jira-Boards.

Dein Atlassian-Domainname

Schritt 5: API-Request-Header festlegen

Definiere deine Header für den API-Request wie folgt:

Achte besonders darauf, deinen Authorization-Header korrekt zu formatieren: Basic <base64-encoded email:api token>

API-Request-Header festlegen

Schritt 6: Query-Parameter für API-Request festlegen

Lege zwei Query-Parameter für deinen AI-Request fest:

• jql nimmt einen dynamischen Wert an, der zuvor im Abschnitt What to ask the user first definiert wurde. Es ist die Aufgabe des AI Agent, den Wert dieses Parameters auf Grundlage dessen auszufüllen, was der Benutzer in der Konversation gesagt hat.
• fields nimmt einen festen Wert an. Für jedes Jira-Issue interessieren uns nur Zusammenfassung, Beschreibung und Status.

Query-Parameter für API-Request festlegen

Achte darauf, dass der Parameter jql korrekt auf den zuvor definierten Wert verweist. Du kannst ihn im Dropdown-Menü Add AI Data auswählen.

Dynamischen Parameter jql im Dropdown-Menü auswählen

Schritt 7: Beschreibung der API Action festlegen

Die letzte entscheidende Zutat einer gut eingerichteten AI Action ist ihre Beschreibung. Der AI Agent versteht deinen API-Endpunkt bereits anhand seiner URL und Parameter recht gut. Trotzdem ist es wichtig, sein Verhalten für deinen Anwendungsfall zu optimieren.

Die drei wichtigsten Aspekte im Prompt sind:

• wann die Action aufgerufen werden soll: jede Formulierung auflisten, die der Benutzer verwenden könnte (find / search / look for sowie explain / tell me about / describe / what is / how is the status of), damit der Agent den Aufruf nicht überspringt, wenn der Benutzer nicht “search” sagt
• Hinweise zur Verwendung der erweiterten JQL-Syntax bei der Suche nach Jira-Issues
• Umgang mit leeren Ergebnissen: Der Agent muss dies ausdrücklich sagen, statt den Zugriff abzulehnen

Hier ist die resultierende API Action Description:

Verwende diese Action immer dann, wenn der Benutzer etwas fragt, das durch Daten in Jira beantwortet werden könnte: Projekte, Issues, Status, Sprints, Testzyklen, Beschreibungen, Verantwortliche, Kommentare. Dies gilt unabhängig davon, wie die Anfrage formuliert ist (find / search / look for / explain / tell me about / describe / what is / how is the status of usw.). Zugriff nicht ablehnen, zuerst Jira abfragen.

Erstelle eine JQL-Abfrage, die Recall gegenüber Präzision priorisiert: Verwende lieber `(text ~ "term1" OR text ~ "term2")` statt einer Verkettung mit AND, und verwende Klammern zur Gruppierung. Filtere bei Lebenszyklusfragen (not started, in progress, done) nach `statusCategory` ("To Do" / "In Progress" / "Done") statt nach `status`, da Statusnamen je nach Board variieren. Verwende `status = "..."` nur, wenn der Benutzer einen bestimmten Status nennt. Vermeide benutzerdefinierte Felder.

Wenn Jira keine Treffer zurückgibt, sage das dem Benutzer ausdrücklich und schlage eine verfeinerte Abfrage vor.

Schritt 8: API Action testen

Bevor wir die AI Action in einer Konversation testen, können wir im Tab Test Response prüfen, wie die API selbst aufgerufen wird. Führen wir einen ersten Test mit der folgenden Abfrage aus, die alle Issues im Projekt zurückgeben sollte: project = "Solar System"

Suche nach allen Issues im Projekt Solar System

Unten siehst du die Testantwort. Wie erwartet listet sie die Felder Summary, Description und Status für alle 6 Issues auf unserem Jira-Board auf.

Antwort listet alle Issues im Projekt Solar System auf

Versuchen wir eine weitere Abfrage. Diesmal suchen wir nach allen Issues, die “mercury” erwähnen: text ~ "mercury"

Suche nach Issues, die mercury erwähnen

Wir haben jetzt validiert, dass die AI Action unseren API-Endpunkt korrekt aufruft. Nun können wir vollständige Konversationen mit dem AI Agent testen.

Schritt 9: AI Agent in Konversationen testen

Gehe zurück zur Quickchat AI app und teste deinen AI Agent in der Konversationsvorschau.

Konversation #1

AI Agent gibt eine Zusammenfassung aller Issues im Projekt

In dieser einfachen Konversation gibt der AI Agent einen Überblick über alle Issues im Projekt. Ein Blick hinter die Kulissen zeigt, dass die exakte Abfrage, die er gegen den API-Endpunkt ausgeführt hat, folgende war: project = "Solar System"

Konversation #2

AI Agent beantwortet Fragen zu bestimmten Issues und Status

In diesem Fall wurde der AI Agent nach zwei getrennten Aspekten gefragt: einem bestimmten Issue und allgemein nach laufenden Issues. Ein Blick hinter die Kulissen zeigt, dass er entschieden hat, die Jira-API in einem zweistufigen Prozess zu verwenden:

1. Prüfen, ob pluto laufend ist:

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

2. Prüfen, was sonst noch laufend ist:

status = "In Progress"

Konversation #3

AI Agent beantwortet eine kreative Abfrage 😉

In diesem Fall wollte ich dem AI Agent eine ungewöhnliche Aufgabe geben und stellte ihm eine Frage, deren korrekte Interpretation etwas Kreativität erfordert. So wurde sie in eine JQL-Abfrage übersetzt:

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

Diese Formulierungen ausprobieren

Um sicherzugehen, dass die AI Action unabhängig von der Formulierung deiner Endbenutzer ausgelöst wird, führe jeden der folgenden Prompts in deinem Testszenario aus. Der Agent sollte bei jedem davon Jira abfragen, nicht nur bei den suchähnlichen Formulierungen:

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

Wenn eine dieser Formulierungen die AI Action nicht auslöst, prüfe erneut, ob deine API Action-Beschreibung (Schritt 7) diese Verben ausdrücklich auflistet.

Was du erwarten solltest, wenn Jira keine passenden Issues hat. Wenn Jira null Ergebnisse zurückgibt, sollte dein AI Agent dies ausdrücklich sagen, zum Beispiel: “I checked Jira and found no matching issues for your query, try a broader phrasing or remove the status filter.” Wenn der Agent stattdessen mit “I don’t have direct access to your Jira” antwortet, wurde die AI Action überhaupt nicht ausgelöst. Prüfe die Beschreibung aus Schritt 7 erneut und bestätige, dass sie ausdrücklich Nicht-Suchverben auflistet (explain, tell me about, describe, what is).

Zusammenfassung

In diesem Blogbeitrag haben wir gezeigt, wie ein AI Agent so eingerichtet werden kann, dass er einen bestimmten API-Endpunkt in Konversationen kreativ verwendet. Die korrekte Einrichtung funktioniert nicht direkt ohne zusätzliche Angaben. Sie erfordert detaillierte Zusatzinformationen zum konkreten Anwendungsfall, den wir im Blick haben. Du kannst die in diesem Blogbeitrag gezeigten Prompts und Beschreibungen gerne wiederverwenden, um ähnliche eigene AI Agents zu erstellen. Ein weiteres vollständig ausgearbeitetes Beispiel im gleichen Schritt-für-Schritt-Stil findest du unter AI Agent mit Google Sheets verbinden, um Leads, unbeantwortete Fragen und Demo-Anfragen in einer Tabelle zu protokollieren.

Möchtest du diese Anleitung als Lesezeichen speichern? Die kanonische, laufend aktualisierte Version dieser Anleitung findest du in unserer Dokumentation unter docs.quickchat.ai/channels/jira. Dort kannst du die neueste API Action-Beschreibung kopieren und Aktualisierungen des Rezepts verfolgen.

Weiterführende Möglichkeiten

Eine Jira-Action muss keine einzelne feste Anfrage sein. Du kannst integrierte Konversationsvariablen und gespeicherte Metadaten (zum Beispiel die Sprache des Besuchers oder zuvor in der Konversation erfasste Werte) in jedes Feld einfügen. Du kannst außerdem mehrere Actions hinzufügen, damit der Agent je nach Frage die richtige auswählt. Die AI Actions-Referenz beschreibt alle verfügbaren Optionen.

Verwandte Anleitungen

Derselbe AI Action-Mechanismus verbindet einen Agent mit jeder HTTP-API. Weitere Anleitungen, die ihn verwenden:

• AI Discord-Moderationsbot mit benutzerdefinierten AI Actions erstellen
• AI Agent mit der Telegram Bot API verbinden
• AI Agent mit Google Sheets verbinden
• AI Agent mit HubSpot verbinden, um Kontakte, Deals und Tickets zu protokollieren
• Slack-Benachrichtigungen mit AI Actions senden
• Cal.com in 5 Minuten mit deinem AI Agent verbinden
• So erstellst du einen AI Support Agent aus deiner Dokumentation
• AI Agent für SaaS-Kundensupport

BONUS

Der obige Blogbeitrag wurde von einem Menschen geschrieben (von mir), hätte aber genauso gut von einer KI geschrieben werden können. Zum Beispiel, indem du einen Prompt wie diesen in ChatGPT einfügst:

Ich brauche einen API-Endpunkt, mit dem ich meine Jira-Tickets durchsuchen kann.

Führe mich Schritt für Schritt durch den Prozess, sodass er für eine Person mit moderaten technischen Kenntnissen verständlich ist:
- Stelle Links zur Dokumentation bereit, die den Endpunkt beschreibt
- Beschreibe alle notwendigen Schritte zur Kontoerstellung und Ersteinrichtung
- Wenn ein kostenpflichtiges Konto benötigt wird, gib das klar an
- Wenn eine Authentifizierung wie API-Tokens benötigt wird, führe mich durch den Prozess ihrer Erstellung und zeige mir genau jeden Schritt, der erforderlich ist, um sie als HTTP-Request-Header verwenden zu können. Wenn zum Beispiel base64-Kodierung erforderlich ist, zeige ein Skript oder eine andere Möglichkeit dafür.
- Zeige mir genau, welche Header-Schlüssel und -Werte ich für den HTTP-Request brauche (zeige Header-Schlüssel und -Werte in einer Tabelle)
- Zeige mir genau, welche Payload-Parameter ich für den HTTP-Request brauche (zeige Payload-Parameternamen und Beispielwerte in einer Tabelle)

In Zukunft möchtest du vielleicht nicht Jira-Tickets durchsuchen, sondern:

• Nachrichten an einen Slack-Channel senden?
• Informationen von einer Notion-Seite abrufen?
• eine Aktion über Zapier ausführen?

Sag das im ersten Satz und führe den Prompt erneut aus. Du erhältst brauchbare Anweisungen, um genau die AI Action hinzuzufügen, die du brauchst.