Tìm phiếu Jira bằng Action tùy chỉnh

Jira không phải tích hợp có sẵn của Quickchat AI. Trang này minh họa cách tạo API Action tùy chỉnh sử dụng REST API của bên thứ ba; cách làm tương tự áp dụng cho các API khác.

Trong bài này, tôi sẽ hướng dẫn kết nối AI Agent với Jira. Chúng ta sẽ dùng:

• một tài khoản Jira (miễn phí)
• một AI Agent của Quickchat (đăng ký tại đây và sử dụng miễn phí)

Nhờ đó, Quickchat AI Agent có thể:

• tìm kiếm trong các phiếu Jira của bạn, và
• trả lời câu hỏi dựa trên chúng một cách thông minh

Chúng ta sẽ dùng AI Actions của Quickchat (các Action HTTP tùy chỉnh) để Agent gọi endpoint Enhanced search for issues của API Jira (Atlassian).

Tạo AI Agent có khả năng diễn giải linh hoạt nội dung người dùng nhập

Kiểm tra ví dụ tùy chọn

• Xem trước yêu cầu API Action. Điền các giá trị mẫu giả lập vào mẫu yêu cầu được cung cấp mà không gửi yêu cầu. Bỏ các header chứa thông tin xác thực.

• Xem trước kết quả khớp JSONPath. Kiểm tra đường dẫn gốc, trường, chỉ số mảng và ký tự đại diện trên JSON được cung cấp. Công cụ không chạy Action hay lưu bộ nhớ cuộc trò chuyện.

Trong trình duyệt tương thích, các kiểm tra này cũng có sẵn dưới dạng công cụ của website. Các liên kết mở biểu mẫu tiêu chuẩn.

Xem video

Play

Cách hoạt động

AI Agent sẽ hoạt động trong cuộc trò chuyện như sau:

1. Người dùng đặt câu hỏi như “các phiếu liên quan đến mercury thế nào rồi?”
2. AI Agent lấy thông tin liên quan từ Jira API bằng truy vấn như “mercury”
3. AI Agent trả lời người dùng dựa trên thông tin lấy từ API

Hãy làm theo các bước bên dưới. Toàn bộ thiết lập không nên mất quá 10 phút!

Bước 0: Tạo tài khoản và dự án Jira

1. Truy cập id.atlassian.com/signup, tạo và xác minh tài khoản.
2. Thêm Jira vào các ứng dụng Atlassian (gói miễn phí đủ để bắt đầu).
3. Thiết lập dự án đầu tiên và tạo phiếu như ví dụ bên dưới.

Bảng ví dụ với các phiếu Jira

Bước 1: Token xác thực Jira API

Truy cập id.atlassian.com/manage-profile/security/api-tokens rồi tạo token API, có dạng như sau:

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

Để dùng token API Atlassian trong Quickchat AI Actions, bạn cần mã hóa base64 token cùng địa chỉ email:

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

Hãy nhập đúng địa chỉ email đã dùng để tạo tài khoản Atlassian

Bạn có thể dùng công cụ trực tuyến đơn giản như base64encode.org.

Hãy dùng Live mode để bảo đảm toàn bộ quá trình mã hóa diễn ra trong trình duyệt của bạn.

Bạn có thể dùng công cụ trực tuyến miễn phí để mã hóa token API

Hoặc bạn có thể thực hiện trên máy của mình bằng script Python đơn giản:

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

Script trên cung cấp header dùng được ngay với token đã mã hóa, có dạng như sau:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Bước 2: Tạo Quickchat AI Action

Trong ứng dụng Quickchat AI, đi đến Actions và MCPs rồi thêm Action:

Trang AI Action

Đặt tên phù hợp cho AI Action:

Tên: Search Jira issues

Nhập tên AI Action

Bước 3: Đặt tham số đầu vào

Nhiệm vụ chính của AI Agent là chuyển câu hỏi người dùng thành truy vấn chính xác để tìm phiếu Jira. Jira gần đây đã chuyển hoàn toàn sang JQL (Jira Query Language) khi tìm kiếm phiếu, hỗ trợ các truy vấn phức tạp hơn. Điều này mở rộng đáng kể khả năng của AI Agent. Thiết lập tham số đầu vào như sau:

Định dạng	Tên	Mô tả	Giá trị mặc định	Bắt buộc
Text	jql	(xem bên dưới)	-	✅

Để AI Agent hoạt động hiệu quả, mô tả được viết kỹ có vai trò rất quan trọng:

Mô tả:

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"`.

Mô tả tham số được viết kỹ là chìa khóa giúp AI Agent hoạt động hiệu quả

Lưu ý về trạng thái Jira

Jira tách tên trạng thái khỏi nhóm trạng thái, và JQL xử lý chúng khác nhau:

• Tên trạng thái là nội dung hiển thị trên bảng. Một dự án dùng To Do / In Progress / Done, dự án khác dùng Open / In Review / Closed.
• Nhóm trạng thái là một trong ba nhóm cố định mà mọi trạng thái được ánh xạ vào: To Do, In Progress, Done.

status = "To Do" lọc theo tên, nên không trả về kết quả trên bảng có cột đầu tiên mang tên Open. Đây là lý do phổ biến khiến Agent tự tin báo “không có phiếu cần làm” dù bảng có rất nhiều phiếu. Với các câu hỏi “việc gì chưa bắt đầu”, “việc gì đang thực hiện” và “việc gì đã xong”, hãy lọc theo nhóm:

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

Chỉ dùng status = "..." khi người dùng nêu tên trạng thái cụ thể mà bạn biết tồn tại trên bảng. Bạn cũng có thể liệt kê tên trạng thái thực tế của bảng trong mô tả Action (Bước 7), để Agent ánh xạ yêu cầu như “sẵn sàng cho QA” vào đúng trạng thái.

Bước 4: Đặt URL endpoint API

1. Chọn GET làm phương thức yêu cầu API
2. Đặt URL endpoint thành endpoint Jira /rest/api/3/search/jql

Đặt URL endpoint API

Hãy dùng tên miền Atlassian của bạn. Bạn có thể tìm thấy nó trong URL bảng Jira.

Tên miền Atlassian của bạn

Bước 5: Đặt header yêu cầu API

Định nghĩa Headers của yêu cầu API như sau:

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

Đặc biệt chú ý định dạng đúng header Authorization: Basic <base64-encoded email:api token>

Đặt header yêu cầu API

Bước 6: Đặt tham số truy vấn yêu cầu API

Đặt hai tham số truy vấn cho yêu cầu AI:

• jql nhận giá trị động đã định nghĩa trong phần Thông tin cần hỏi người dùng trước. AI Agent có nhiệm vụ điền giá trị tham số này dựa trên nội dung người dùng đã nói trong cuộc trò chuyện.
• fields nhận giá trị cố định. Với mỗi phiếu Jira, chúng ta chỉ quan tâm đến summary, description và status.

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

Đặt tham số truy vấn yêu cầu API

Bảo đảm tham số jql tham chiếu đúng giá trị đã định nghĩa trước đó. Bạn có thể chọn nó từ menu thả xuống Thêm dữ liệu AI.

Chọn tham số động jql từ menu thả xuống

Bước 7: Đặt mô tả API Action

Thành phần quan trọng cuối cùng của AI Action được thiết lập tốt là mô tả. Dù AI Agent có thể hiểu khá rõ endpoint API chỉ từ URL và tham số, bạn vẫn cần tối ưu cách hoạt động cho trường hợp sử dụng của mình.

Ba khía cạnh quan trọng nhất trong prompt là:

• khi nào gọi Action: liệt kê mọi cách diễn đạt người dùng có thể chọn (tìm / tìm kiếm / tìm giúp, cũng như giải thích / cho tôi biết về / mô tả / là gì / trạng thái thế nào) để Agent không bỏ qua lệnh gọi khi người dùng không nói “tìm kiếm”
• gợi ý cách dùng cú pháp JQL nâng cao khi tìm phiếu Jira
• cách xử lý kết quả trống: Agent phải nói rõ điều này thay vì báo không có quyền truy cập

Đây là Mô tả API Action hoàn chỉnh:

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.

Bước 8: Kiểm thử API Action

Trước khi kiểm thử AI Action trong cuộc trò chuyện, chúng ta có thể kiểm tra cách gọi API trong thẻ Kiểm thử phản hồi. Hãy thử truy vấn sau trước; nó sẽ trả về mọi phiếu trong dự án: project = "Solar System"

Tìm mọi phiếu trong dự án Solar System

Bên dưới là phản hồi kiểm thử nhận được. Đúng như dự kiến, nó liệt kê các trường summary, description và status của cả 6 phiếu trên bảng Jira.

Phản hồi liệt kê mọi phiếu trong dự án Solar System

Hãy thử thêm một truy vấn. Lần này tìm mọi phiếu nhắc đến “mercury”: text ~ "mercury"

Tìm các phiếu nhắc đến mercury

Chúng ta đã xác nhận AI Action gọi đúng endpoint API. Giờ có thể kiểm thử toàn bộ cuộc trò chuyện với AI Agent!

Bước 9: Kiểm thử AI Agent trong cuộc trò chuyện

Trở lại ứng dụng Quickchat AI và kiểm thử AI Agent trong bản xem trước cuộc trò chuyện.

Cuộc trò chuyện số 1

AI Agent tóm tắt mọi phiếu trong dự án

Trong cuộc trò chuyện đơn giản này, AI Agent trình bày tổng quan mọi phiếu trong dự án. Kiểm tra bên trong cho thấy truy vấn chính xác đã chạy tại endpoint API là: project = "Solar System"

Cuộc trò chuyện số 2

AI Agent trả lời câu hỏi về các phiếu và trạng thái cụ thể

Trong trường hợp này, AI Agent được hỏi về hai nội dung riêng: một phiếu cụ thể và các phiếu đang thực hiện nói chung. Kiểm tra bên trong cho thấy Agent quyết định gọi Jira API theo hai bước:

1. Kiểm tra pluto có đang thực hiện không:

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

2. Kiểm tra còn việc gì đang thực hiện:

status = "In Progress"

Cuộc trò chuyện số 3

AI Agent trả lời truy vấn cần diễn giải linh hoạt 😉

Ở đây, tôi muốn thử thách AI Agent bằng câu hỏi cần một chút sáng tạo để hiểu đúng. Câu hỏi được chuyển thành truy vấn JQL như sau:

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

Thử các cách diễn đạt sau

Để bảo đảm AI Action chạy bất kể người dùng cuối diễn đạt yêu cầu thế nào, hãy thử từng prompt bên dưới với kịch bản kiểm thử của bạn. Agent phải truy vấn Jira trong mọi trường hợp, không chỉ với câu hỏi có dạng tìm kiếm:

• “tìm tất cả phiếu đang mở về tỷ số trực tiếp”
• “tìm phiếu có mercury”
• “giải thích dự án Solar System”
• “cho tôi biết về các phiếu đang mở trong sprint này”
• “mô tả những việc đang thực hiện”
• “pluto hiện có trạng thái gì?”

Nếu cách diễn đạt nào không gọi AI Action, hãy kiểm tra lại mô tả API Action (Bước 7) có liệt kê rõ những động từ đó không.

Kết quả mong đợi khi Jira không có phiếu phù hợp

Khi Jira trả về không có kết quả, AI Agent cần nói rõ, chẳng hạn “Tôi đã kiểm tra Jira và không tìm thấy phiếu phù hợp với truy vấn của bạn. Hãy thử diễn đạt rộng hơn hoặc bỏ bộ lọc trạng thái.”

Nếu Agent lại trả lời “Tôi không có quyền truy cập trực tiếp vào Jira của bạn”, AI Action chưa hề chạy. Kiểm tra lại mô tả ở Bước 7 và xác nhận nó liệt kê rõ các động từ không mang nghĩa tìm kiếm (explain, tell me about, describe, what is).

Tổng kết

Bài này minh họa cách thiết lập AI Agent sử dụng một endpoint API cụ thể một cách linh hoạt trong cuộc trò chuyện. Cấu hình phù hợp không có sẵn ngay từ đầu; bạn cần cung cấp thêm thông tin chi tiết về trường hợp sử dụng mong muốn. Bạn có thể dùng lại các prompt và mô tả trong bài để tạo AI Agent tương tự!

Bạn thích hướng dẫn dài có phần diễn giải hơn? Cách thiết lập này cũng được trình bày trong bài viết trên quickchat.ai. Trang tài liệu này là nguồn tham chiếu chính thức, được cập nhật liên tục.

Tìm hiểu thêm

Action Jira không nhất thiết chỉ có một yêu cầu cố định. Bạn có thể chèn biến cuộc trò chuyện có sẵn và metadata đã lưu (như ngôn ngữ khách truy cập hoặc giá trị thu thập trước đó) vào bất kỳ trường nào, đồng thời thêm nhiều Action để Agent chọn đúng Action cho từng câu hỏi. Xem tài liệu Actions để biết toàn bộ tùy chọn.

🎁  PHẦN THÊM

Bài viết trên do một con người (chính tôi) viết, nhưng AI cũng có thể viết được. Ví dụ, hãy dán một prompt như sau vào 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)

Trong tương lai, có thể thay vì tìm phiếu Jira, bạn muốn:

• gửi tin nhắn đến kênh Slack?
• lấy thông tin từ trang Notion?
• thực hiện Action qua Zapier?

Hãy nêu điều đó trong câu đầu rồi chạy lại prompt! Bạn sẽ nhận được hướng dẫn hữu ích để thêm đúng AI Action mình cần!