使用自訂 Action 搜尋 Jira 工單

Jira 並非 Quickchat AI 的內建整合。本頁示範如何針對第三方 REST API 建立自訂 API Action，相同模式也適用於其他 API。

本文將說明如何將 AI Agent 連接到 Jira。我們會使用：

• Jira 帳號（免費）
• Quickchat AI Agent（在此註冊並免費使用）

這將讓 Quickchat AI Agent 能夠：

• 搜尋 Jira 工單，以及
• 智慧地根據工單內容回答問題

我們會使用 Quickchat 的 AI Actions（自訂 HTTP 動作），讓 Agent 呼叫 Jira（Atlassian）API 的 Enhanced search for issues 端點。

建立能靈活解讀使用者輸入的 AI Agent

選用範例檢查

• 預覽 API Action 要求。使用合成範例值呈現提供的要求範本，不會實際傳送。請省略憑證標頭。

• 預覽 JSONPath 比對結果。對提供的 JSON 檢查根、欄位、陣列索引及萬用字元路徑，不會執行 Action 或儲存對話記憶。

在相容瀏覽器中，這些檢查也可作為網站工具使用。連結會開啟一般表單。

觀看影片

Play

運作方式

AI Agent 將在對話中依下列方式運作：

1. 使用者提出問題，例如_「與 mercury 有關的議題目前怎麼樣？」_
2. AI Agent 使用_「mercury」_之類的查詢，從 Jira API 取得相關資訊
3. AI Agent 根據從 API 取得的資訊回覆使用者

請按照以下步驟操作。整個設定應不超過 10 分鐘！

步驟 0：建立 Jira 帳號與專案

1. 前往 id.atlassian.com/signup，建立並驗證帳號。
2. 將 Jira 加入 Atlassian 應用程式（免費方案足以開始）。
3. 設定第一個專案，並依下方範例建立工單。

包含 Jira 議題的看板範例

步驟 1：Jira API 驗證 Token

前往 id.atlassian.com/manage-profile/security/api-tokens，建立 API Token，內容大致如下：

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

若要在 Quickchat AI Actions 中使用 Atlassian API Token，必須將它與電子郵件地址一起進行 base64 編碼：

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

請務必使用建立 Atlassian 帳號時的相同電子郵件地址

您可以使用 base64encode.org 等簡單的線上工具。

請務必使用 Live mode，確保編碼完全在您的瀏覽器內進行。

您可使用免費線上工具為 API Token 編碼

或者，使用簡單的 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}")

上述指令碼會產生含有編碼 Token 的可直接使用標頭，大致如下：

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

步驟 2：建立 Quickchat AI Action

在 Quickchat AI 應用程式中，前往 Actions 與 MCPs 並新增 Action：

AI Action 頁面

為 AI Action 設定適當名稱：

名稱：Search Jira issues

輸入 AI Action 名稱

步驟 3：設定輸入參數

AI Agent 的主要任務是將使用者的問題轉成精確查詢，用來搜尋 Jira 議題。Jira 近期已將議題搜尋全面移轉至 JQL（Jira Query Language），以支援更複雜的搜尋。這讓 AI Agent 能發揮更強的能力。請依下列方式設定輸入參數：

格式	名稱	說明	預設值	必填
Text	jql	（見下方）	-	✅

要讓 AI Agent 有出色表現，精心撰寫的說明非常重要：

說明：

A single valid JQL (Jira Query Language) string built per the description. Favor recall: prefer `(text ~ "term1" OR text ~ "term2")` over chaining with AND, and use parentheses for grouping. For "not started / in progress / done" questions, filter on `statusCategory` ("To Do", "In Progress", "Done"), which is stable across projects; use `status = "..."` only when the user names a specific status that exists on the board. Avoid custom fields. Examples: `statusCategory = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`, `(text ~ "planet*" OR text ~ "integration")`, `project = "Solar System" AND statusCategory = "To Do"`.

精心撰寫參數說明，是 AI Agent 表現的關鍵

關於 Jira 狀態

Jira 將狀態的名稱與類別區分開來，JQL 對兩者的處理也不同：

• 狀態名稱就是看板上顯示的文字。一個專案可能使用 To Do / In Progress / Done，另一個則使用 Open / In Review / Closed。
• 狀態類別是每種狀態所對應的三個固定類別之一：To Do、In Progress、Done。

status = "To Do" 依名稱篩選，因此當看板第一欄名為 Open 時，不會傳回結果。這常導致 Agent 在看板明明有很多待辦工單時，卻自信地回答「沒有待辦工單」。對「哪些尚未開始」、「哪些進行中」與「哪些已完成」這類問題，請改用類別篩選：

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

只有當使用者明確提到您確認存在於看板上的狀態名稱時，才保留 status = "..."。您也可在 Action 說明（步驟 7）中列出看板實際狀態名稱，讓 Agent 將「準備好進行 QA」之類的要求對應到正確狀態。

步驟 4：設定 API 端點 URL

1. 選擇 GET 作為 API 要求方法
2. 將端點 URL 設為 Jira 的 /rest/api/3/search/jql 端點

設定 API 端點 URL

請務必使用您的 Atlassian 網域名稱。可在 Jira 看板 URL 中找到。

您的 Atlassian 網域名稱

步驟 5：設定 API 要求標頭

依下列方式定義 API 要求的標頭：

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

請特別留意 Authorization 標頭格式是否正確：Basic <base64-encoded email:api token>

設定 API 要求標頭

步驟 6：設定 API 要求查詢參數

為 AI 要求設定兩個查詢參數：

• jql 使用前面_先詢問使用者的內容_區段所定義的動態值。AI Agent 會根據使用者在對話中說的內容填入此參數。
• fields 使用固定值。對每個 Jira 議題，我們只需要其_摘要_、說明_與_狀態。

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

設定 API 要求查詢參數

請確認 jql 參數正確指向先前定義的值。您可從「新增 AI 資料」下拉選單選擇。

從下拉選單選擇動態 jql 參數

步驟 7：設定 API Action 說明

完善 AI Action 設定的最後一個關鍵是說明。雖然 AI Agent 可從 URL 與參數充分理解 API 端點，但仍需針對您的使用情境最佳化其行為。

提示詞最重要的三個部分為：

• 何時呼叫 Action：列出使用者可能採用的各種說法（尋找／搜尋／查找，以及解釋／告訴我關於／描述／什麼是／目前狀態如何），避免使用者沒說「搜尋」時 Agent 就略過呼叫
• 搜尋 Jira 議題時如何使用進階 JQL 語法的建議
• 如何處理空結果：Agent 必須明確說明沒有結果，而不是聲稱無法存取

以下是完成後的 API Action 說明：

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, and use parentheses for grouping. For lifecycle questions (not started, in progress, done) filter on `statusCategory` ("To Do" / "In Progress" / "Done") rather than `status`, because status names vary by board; use `status = "..."` only when the user names a specific status. Avoid custom fields.

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

步驟 8：測試 API Action

在對話中測試 AI Action 之前，可先在測試回應分頁測試 API 呼叫本身。先使用以下查詢進行第一次測試，它應傳回專案中所有議題：project = "Solar System"

搜尋 Solar System 專案中的所有議題

下方是取得的測試回應。如預期，列出了 Jira 看板中全部 6 個議題的摘要、說明及狀態欄位。

回應列出 Solar System 專案中的所有議題

再試另一個查詢。這次搜尋所有提到「mercury」的議題：text ~ "mercury"

搜尋提到 mercury 的議題

現在已驗證 AI Action 能正確呼叫 API 端點。接著可以測試與 AI Agent 的完整對話！

步驟 9：在對話中測試 AI Agent

返回 Quickchat AI 應用程式，在對話預覽中測試 AI Agent。

對話 #1

AI Agent 摘要整理專案中的所有議題

在這段簡單對話中，AI Agent 提供專案所有議題的概覽。查看幕後細節可知，它對 API 端點執行的精確查詢是：project = "Solar System"

對話 #2

AI Agent 回答特定議題與狀態的問題

在此案例中，使用者詢問兩個不同面向：一個特定議題，以及整體進行中的議題。查看幕後細節可知，Agent 決定分兩步使用 Jira API：

1. 檢查 pluto 是否進行中：

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

2. 檢查還有哪些議題進行中：

status = "In Progress"

對話 #3

AI Agent 回答需要靈活解讀的查詢 😉

在此案例中，我刻意向 AI Agent 提出較難的問題，需要一些創意才能正確解讀。它將問題轉為以下 JQL 查詢：

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

試試這些說法

為確認終端使用者無論如何措辭都會觸發 AI Action，請在測試情境中逐一執行下列提示詞。Agent 應對每個問題查詢 Jira，而不只是對搜尋式問句如此：

• 「找出所有關於即時比分且尚未關閉的議題」
• 「搜尋包含 mercury 的議題」
• 「解釋 Solar System 專案」
• 「告訴我這次衝刺中尚未關閉的議題」
• 「描述目前有哪些工作進行中」
• 「pluto 的狀態如何？」

若任何說法未觸發 AI Action，請再次確認 API Action 說明（步驟 7）明確列出這些動詞。

Jira 沒有符合議題時的預期行為

當 Jira 傳回零筆結果時，AI Agent 應明確說明，例如：「我已檢查 Jira，找不到符合查詢的議題。請嘗試較廣泛的說法，或移除狀態篩選條件。」

若 Agent 反而回覆_「我無法直接存取您的 Jira」_，表示 AI Action 完全沒有觸發。請重新檢查步驟 7 的說明，確認明確列出非搜尋動詞（explain、tell me about、describe、what is）。

摘要

本文示範如何設定 AI Agent，讓它在對話中靈活使用特定 API 端點。正確設定不是開箱即用，而是需要針對預期使用情境補充詳細資訊。歡迎重複使用文中的提示詞及說明，建立您自己的類似 AI Agent！

想閱讀更完整、敘事式的教學？相同設定也刊載於 quickchat.ai 部落格文章。本文件頁面是持續更新的正式參考來源。

進一步應用

Jira Action 不必局限於單一固定要求。您可將內建對話變數及已儲存中繼資料（例如訪客語言，或先前對話擷取的值）注入任何欄位，也可新增多個 Actions，讓 Agent 依問題選擇合適項目。完整選項請參閱 Actions 參考。

🎁  額外內容

上文由_人類_（也就是我本人）撰寫，不過同樣可以由 AI 完成。例如，在 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)

日後，除了搜尋 Jira 工單，您可能還想：

• 傳送訊息至 Slack 頻道？
• 從 Notion 頁面取得資訊？
• 透過 Zapier 執行動作？

在第一句說明需求，再次執行提示詞！您就能取得實用的操作說明，新增所需的 AI Action！