Hubungkan AI Agent ke tiket Jira

Pendahuluan

Dalam posting blog ini, saya akan menunjukkan cara menghubungkan AI Agent Anda ke Jira. Kita akan menggunakan:

• akun Jira (gratis)
• AI Agent Quickchat (daftar di sini dan gunakan secara gratis)

Mencari referensi kanonis yang terus diperbarui? Panduan yang sama tersedia di dokumentasi kami di docs.quickchat.ai/channels/jira. Posting ini adalah versi panjang dengan penjelasan naratif.

Ini akan memungkinkan Quickchat AI Agent Anda untuk:

• dapat mencari di seluruh tiket Jira Anda, dan
• cerdas dalam menjawab pertanyaan berdasarkan tiket tersebut

Kita akan menggunakan AI Actions Quickchat (custom HTTP actions) agar Agent Anda dapat memanggil endpoint Enhanced search for issues dari API Jira (Atlassian).

Buat AI Agent yang kreatif dalam menafsirkan input pengguna

Tonton Video

Cara kerjanya

Berikut cara AI Agent Anda akan beroperasi selama percakapan:

1. Pengguna mengajukan pertanyaan seperti “apa kabar issue yang terkait dengan mercury?”
2. AI Agent mengambil informasi relevan dari Jira API menggunakan kueri seperti “mercury”
3. AI Agent membalas pengguna berdasarkan informasi yang diambil dari API

Ikuti langkah-langkah di bawah ini. Seluruh pengaturan seharusnya tidak memakan waktu lebih dari 10 menit!

Langkah 0 - buat akun dan proyek Jira

1. Buka id.atlassian.com/signup, buat dan verifikasi akun Anda.
2. Tambahkan Jira ke aplikasi Atlassian Anda (paket gratis cukup untuk memulai).
3. Siapkan proyek pertama Anda dan buat tiket seperti pada contoh di bawah ini.

Contoh board dengan issue Jira

Langkah 1 - token autentikasi Jira API

Buka id.atlassian.com/manage-profile/security/api-tokens dan buat API token Anda yang akan terlihat kira-kira seperti ini:

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

Agar dapat menggunakan Atlassian API token Anda di Quickchat AI Actions, Anda perlu mengenkodenya dengan base64 bersama alamat email Anda:

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

Pastikan untuk menyertakan alamat email persis yang Anda gunakan untuk menyiapkan akun Atlassian Anda

Anda dapat menggunakan alat online sederhana seperti base64encode.org.

Pastikan untuk menggunakan Live mode yang menjamin proses encoding terjadi sepenuhnya di browser Anda.

Anda dapat menggunakan alat online gratis untuk mengenkode API token Anda

Sebagai alternatif, berikut cara melakukannya di mesin Anda dengan skrip python sederhana:

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

Skrip di atas akan memberi Anda header siap pakai dengan token yang sudah dienkode, yang terlihat kira-kira seperti ini:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Langkah 2 - buat Quickchat AI Action

Di aplikasi Quickchat AI, buka Actions & MCPs dan tambahkan action:

Halaman AI Action

Beri AI Action Anda nama yang sesuai:

Name: Search Jira issues

Masukkan nama AI Action

Langkah 3 - atur parameter input

Tugas utama AI Agent Anda adalah menerjemahkan apa yang ditanyakan pengguna menjadi kueri yang tepat untuk mencari issue Jira. Untuk pencarian issue, Jira baru-baru ini sepenuhnya bermigrasi ke JQL (Jira Query Language) agar dapat melakukan pencarian yang lebih kompleks. Ini membuat AI Agent Anda jauh lebih kuat. Atur parameter input Anda sebagai berikut:

Agar AI Agent Anda berkinerja baik, deskripsi yang disusun dengan baik sangat penting:

Description:

Satu string JQL (Jira Query Language) valid yang dibuat berdasarkan deskripsi. Utamakan cakupan hasil: pilih `(text ~ "term1" OR text ~ "term2")` daripada merangkai dengan AND, dan gunakan tanda kurung untuk pengelompokan. Untuk pertanyaan "not started / in progress / done", filter berdasarkan `statusCategory` ("To Do", "In Progress", "Done"), yang stabil di seluruh proyek; gunakan `status = "..."` hanya ketika pengguna menyebutkan status tertentu yang ada di board. Hindari custom fields. Contoh: `statusCategory = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`, `(text ~ "planet*" OR text ~ "integration")`, `project = "Solar System" AND statusCategory = "To Do"`.

Deskripsi parameter yang disusun dengan baik adalah kunci performa AI Agent

Catatan tentang status Jira

Jira memisahkan nama status dari kategori status, dan JQL memperlakukannya secara berbeda:

• Nama status adalah apa pun yang ditampilkan board. Satu proyek menggunakan To Do / In Progress / Done, proyek lain menggunakan Open / In Review / Closed.
• Kategori status adalah salah satu dari tiga kelompok tetap yang dipetakan dari setiap status: To Do, In Progress, Done.

status = "To Do" memfilter berdasarkan nama, sehingga tidak mengembalikan apa pun pada board yang kolom pertamanya bernama Open. Ini adalah alasan umum agent dengan yakin melaporkan “tidak ada tiket yang perlu dikerjakan” padahal board penuh dengan tiket tersebut. Untuk pertanyaan “apa yang belum dimulai”, “apa yang sedang berjalan”, dan “apa yang sudah selesai”, filter berdasarkan kategori sebagai gantinya:

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

Pertahankan status = "..." untuk saat pengguna menyebutkan status tertentu yang Anda tahu ada di board. Anda juga dapat mencantumkan nama status asli board Anda dalam deskripsi Action (Langkah 7) agar agent memetakan permintaan seperti “ready for QA” ke status yang tepat.

Langkah 4 - atur URL endpoint API

1. Pilih GET sebagai Action Type
2. Atur URL endpoint ke endpoint Jira /rest/api/3/search/jql

Atur URL endpoint API Anda

Pastikan untuk menggunakan nama domain Atlassian Anda. Anda akan menemukannya di URL board Jira Anda.

Nama domain Atlassian Anda

Langkah 5 - atur header request API

Definisikan headers request API Anda sebagai berikut:

Perhatikan dengan cermat pemformatan header Authorization Anda: Basic <base64-encoded email:api token>

Atur header request API Anda

Langkah 6 - atur parameter kueri request API

Atur dua parameter kueri untuk request AI Anda:

• jql mengambil nilai dinamis yang didefinisikan sebelumnya di bagian What to ask the user first. Tugas AI Agent adalah mengisi nilai parameter ini berdasarkan apa yang dikatakan pengguna dalam percakapan.
• fields mengambil nilai tetap. Untuk setiap issue Jira, kita hanya tertarik pada summary, description, dan status.

Atur parameter kueri request API Anda

Pastikan parameter jql dengan benar mengarah ke nilai yang didefinisikan sebelumnya. Anda dapat memilihnya dari menu dropdown Add AI Data.

Pilih parameter dinamis jql dari menu dropdown

Langkah 7 - atur deskripsi API Action

Bahan akhir yang sangat penting dari AI Action yang disiapkan dengan baik adalah deskripsinya. Meskipun AI Agent memiliki pemahaman yang baik tentang endpoint API Anda hanya dari URL dan parameternya, penting untuk mengoptimalkan perilakunya untuk kasus penggunaan Anda.

Tiga aspek paling penting yang disertakan dalam prompt adalah:

• kapan memanggil action, dengan mencantumkan setiap frasa yang mungkin dipilih pengguna (find / search / look for, serta explain / tell me about / describe / what is / how is the status of) agar agent tidak melewatkan panggilan ketika pengguna tidak mengatakan “search”
• saran tentang cara menggunakan sintaks JQL lanjutan saat mencari issue Jira
• cara menangani hasil kosong, agent harus mengatakannya secara eksplisit, bukan menolak akses

Berikut API Action Description yang dihasilkan:

Gunakan action ini setiap kali pengguna menanyakan apa pun yang dapat dijawab oleh data di Jira mereka, proyek, issue, status, sprint, siklus pengujian, deskripsi, pemilik, komentar, terlepas dari cara mereka merumuskan permintaan (find / search / look for / explain / tell me about / describe / what is / how is the status of, dll.). Jangan menolak akses; kueri Jira terlebih dahulu.

Buat JQL yang memprioritaskan cakupan hasil daripada presisi: pilih `(text ~ "term1" OR text ~ "term2")` daripada merangkai dengan AND, dan gunakan tanda kurung untuk pengelompokan. Untuk pertanyaan siklus hidup (not started, in progress, done), filter berdasarkan `statusCategory` ("To Do" / "In Progress" / "Done") alih-alih `status`, karena nama status berbeda-beda menurut board; gunakan `status = "..."` hanya ketika pengguna menyebutkan status tertentu. Hindari custom fields.

Jika Jira tidak mengembalikan kecocokan, sampaikan hal tersebut secara eksplisit kepada pengguna dan sarankan kueri yang diperbaiki.

Langkah 8 - uji API Action

Sebelum menguji AI Action dalam percakapan, kita dapat menguji bagaimana API itu sendiri dipanggil di tab Test Response. Mari lakukan pengujian pertama dengan kueri berikut yang seharusnya mengembalikan semua issue dalam proyek: project = "Solar System"

Mencari semua issue dalam proyek Solar System

Di bawah ini adalah respons pengujian yang kita dapatkan. Seperti yang diharapkan, respons ini mencantumkan field summary, description, dan status untuk semua 6 issue di board Jira kita.

Respons mencantumkan semua issue dalam proyek Solar System

Mari coba satu kueri lagi. Kali ini mari mencari semua issue yang menyebut “mercury”: text ~ "mercury"

Mencari issue yang menyebut mercury

Sekarang kita telah memvalidasi bahwa AI Action memanggil endpoint API kita dengan benar. Sekarang kita dapat melanjutkan ke pengujian percakapan penuh dengan AI Agent!

Langkah 9 - uji AI Agent dalam percakapan

Kembali ke aplikasi Quickchat AI dan uji AI Agent Anda dalam pratinjau percakapan.

Percakapan #1

AI Agent memberikan ringkasan semua issue dalam proyek

Dalam percakapan sederhana ini, AI Agent memberikan gambaran umum tentang semua issue dalam proyek. Melihat proses di balik layar menunjukkan bahwa kueri persis yang dijalankannya terhadap endpoint API adalah: project = "Solar System"

Percakapan #2

AI Agent merespons pertanyaan tentang issue dan status tertentu

Dalam kasus ini, AI Agent ditanya tentang dua aspek terpisah: satu issue tertentu dan issue yang sedang berjalan secara umum. Melihat proses di balik layar menunjukkan bahwa agent memutuskan untuk menggunakan Jira API dalam proses dua langkah:

1. Periksa apakah pluto sedang berjalan:

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

2. Periksa apa lagi yang sedang berjalan:

status = "In Progress"

Percakapan #3

AI Agent merespons kueri kreatif 😉

Dalam kasus ini, saya ingin memberikan pertanyaan yang tidak biasa kepada AI Agent dan menanyakan pertanyaan yang memerlukan sedikit kreativitas untuk ditafsirkan dengan benar. Berikut cara pertanyaan tersebut diterjemahkan menjadi kueri JQL:

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

Coba frasa ini

Untuk memastikan AI Action dipicu terlepas dari bagaimana pengguna akhir Anda merumuskan permintaan mereka, jalankan setiap prompt di bawah ini terhadap skenario pengujian Anda. Agent harus mengueri Jira untuk semuanya, bukan hanya yang bergaya pencarian:

• “temukan semua issue terbuka tentang live scores”
• “cari issue dengan mercury”
• “jelaskan proyek Solar System”
• “beri tahu saya tentang issue terbuka dalam sprint ini”
• “deskripsikan apa yang saat ini sedang berjalan”
• “apa status pluto?”

Jika salah satu frasa ini tidak memanggil AI Action, periksa kembali bahwa deskripsi API Action Anda (Langkah 7) mencantumkan verba tersebut secara eksplisit.

Apa yang diharapkan saat Jira tidak memiliki issue yang cocok. Saat Jira mengembalikan nol hasil, AI Agent Anda harus mengatakannya secara eksplisit, misalnya, “Saya memeriksa Jira dan tidak menemukan issue yang cocok untuk kueri Anda, coba frasa yang lebih luas atau hapus filter status.” Jika sebaliknya Anda melihat agent membalas dengan “Saya tidak memiliki akses langsung ke Jira Anda”, AI Action sama sekali tidak dipicu. Periksa kembali deskripsi dari Langkah 7 dan pastikan deskripsi tersebut secara eksplisit mencantumkan verba non-pencarian (explain, tell me about, describe, what is).

Ringkasan

Dalam posting blog ini, kami menunjukkan bagaimana AI Agent dapat disiapkan untuk menggunakan endpoint API tertentu secara kreatif dalam percakapan. Pengaturan yang benar tidak tersedia secara otomatis, ini memerlukan penyediaan informasi tambahan yang detail tentang kasus penggunaan spesifik yang kita inginkan. Silakan gunakan kembali prompt dan deskripsi yang ditampilkan dalam posting blog ini untuk membuat AI Agent serupa milik Anda sendiri. Untuk contoh lain yang dikerjakan lengkap dengan gaya langkah demi langkah yang sama, lihat cara menghubungkan AI Agent Anda ke Google Sheets dan mencatat lead, pertanyaan yang tidak terjawab, serta permintaan demo ke spreadsheet.

Ingin menyimpan panduan ini sebagai bookmark? Versi kanonis yang terus diperbarui dari panduan ini tersedia di dokumentasi kami di docs.quickchat.ai/channels/jira, buka halaman tersebut untuk menyalin dan menempel API Action description terbaru serta mengikuti pembaruan resepnya.

Lebih lanjut

Action Jira tidak harus berupa satu request tetap. Anda dapat menyisipkan built-in conversation variables and saved metadata (seperti bahasa pengunjung atau nilai yang diambil sebelumnya dalam percakapan) ke field mana pun, dan Anda dapat menambahkan beberapa action agar agent memilih yang tepat untuk setiap pertanyaan. Referensi AI Actions membahas kumpulan opsi lengkap.

Panduan terkait

Mekanisme AI Action yang sama menghubungkan agent ke HTTP API apa pun. Panduan lain yang menggunakannya:

• Buat bot moderasi AI Discord dengan custom AI Actions
• Hubungkan AI Agent Anda ke Telegram Bot API
• Hubungkan AI Agent Anda ke Google Sheets
• Hubungkan AI Agent Anda ke HubSpot untuk mencatat kontak, deal, dan tiket
• Kirim notifikasi Slack dengan AI Actions
• Hubungkan Cal.com ke AI Agent Anda dalam 5 Menit
• Cara membuat AI Support Agent dari dokumentasi Anda
• AI Agent untuk Dukungan Pelanggan SaaS

BONUS

Posting blog di atas ditulis oleh seorang manusia (saya sendiri), tetapi bisa saja ditulis oleh AI. Misalnya, dengan menempelkan prompt seperti ini ke ChatGPT:

Saya memerlukan endpoint API yang memungkinkan saya mencari di seluruh tiket Jira saya.

Pandulah saya melalui prosesnya langkah demi langkah agar dapat diikuti oleh orang dengan kemampuan teknis tingkat menengah:
- Berikan tautan ke dokumentasi yang mendeskripsikan endpoint
- Pembuatan akun dan pengaturan awal apa pun yang diperlukan
- Jika akun berbayar diperlukan, tunjukkan dengan jelas
- Jika autentikasi seperti API token diperlukan, pandu saya melalui proses pembuatannya dan tunjukkan kepada saya setiap langkah yang diperlukan secara tepat agar dapat menggunakannya sebagai header request HTTP. Misalnya, jika encoding base64 diperlukan, tunjukkan skrip atau cara lain untuk melakukannya.
- Tunjukkan kepada saya secara tepat key dan value header apa yang saya perlukan untuk request HTTP (tunjukkan key dan value header dalam tabel)
- Tunjukkan kepada saya secara tepat parameter payload apa yang saya perlukan untuk request HTTP (tunjukkan nama parameter payload dan contoh value dalam tabel)

Di masa depan, mungkin alih-alih mencari di seluruh tiket Jira, Anda ingin:

• mengirim pesan ke channel Slack?
• mengambil informasi dari halaman Notion?
• melakukan action melalui Zapier?

Katakan itu di kalimat pertama dan jalankan prompt lagi. Anda akan memperoleh instruksi yang sangat baik untuk menambahkan AI Action persis yang Anda perlukan!