사용자 지정 Action으로 Jira 티켓 검색

Jira는 Quickchat AI의 기본 제공 연동이 아닙니다. 이 페이지는 타사 REST API에 연결하는 사용자 지정 API Action을 만드는 예시이며, 같은 방식을 다른 모든 API에도 적용할 수 있습니다.

이 글에서는 AI 에이전트를 Jira에 연결하는 방법을 설명합니다. 다음을 사용합니다.

• Jira 계정(무료)
• Quickchat AI 에이전트(여기에서 가입하여 무료로 사용하세요)

연결하면 Quickchat AI 에이전트가 다음을 수행할 수 있습니다.

• Jira 티켓을 검색하고,
• 티켓 내용을 바탕으로 질문에 지능적으로 답변합니다.

Quickchat의 AI Actions(사용자 지정 HTTP Actions)를 사용하여 에이전트가 Jira(Atlassian) API의 Enhanced search for issues 엔드포인트를 호출하도록 합니다.

사용자 입력을 창의적으로 해석하는 AI 에이전트를 만드세요

선택적으로 사용할 예시 검사

• API Action 요청 미리 보기. 제공한 요청 템플릿을 가상의 예시 값으로 렌더링하며 실제로 전송하지 않습니다. 인증 정보가 담긴 헤더는 제외하세요.

• JSONPath 일치 항목 미리 보기. 제공한 JSON에 대해 루트, 필드, 배열 인덱스 및 와일드카드 경로를 확인하세요. Action을 실행하거나 대화 메모리를 저장하지 않습니다.

호환되는 브라우저에서는 이 검사를 사이트 도구로도 사용할 수 있습니다. 링크를 열면 일반 양식이 표시됩니다.

동영상 보기

Play

작동 방식

대화 중 AI 에이전트는 다음과 같이 작동합니다.

1. 사용자가 “mercury 관련 이슈는 어떻게 되고 있나요?” 같은 질문을 합니다.
2. AI 에이전트가 “mercury” 같은 쿼리로 Jira API에서 관련 정보를 가져옵니다.
3. AI 에이전트가 API에서 가져온 정보를 바탕으로 사용자에게 답변합니다.

아래 단계를 따라 하세요. 전체 설정에는 10분 정도면 충분합니다!

0단계 - Jira 계정과 프로젝트 만들기

1. id.atlassian.com/signup에서 계정을 만들고 인증하세요.
2. Atlassian 앱에 Jira를 추가하세요. 시작할 때는 무료 플랜으로 충분합니다.
3. 첫 프로젝트를 설정하고 아래 예시처럼 티켓을 만드세요.

Jira 이슈가 있는 예시 보드

1단계 - Jira API 인증 토큰

id.atlassian.com/manage-profile/security/api-tokens에서 API 토큰을 만드세요. 다음과 같은 형식입니다.

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

Atlassian API 토큰을 Quickchat AI Actions에서 사용하려면 이메일 주소와 함께 base64로 인코딩해야 합니다.

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

Atlassian 계정을 만들 때 사용한 정확한 이메일 주소를 포함하세요.

base64encode.org 같은 간단한 온라인 도구를 사용할 수 있습니다.

인코딩이 브라우저 안에서만 이루어지도록 Live mode를 사용하세요.

무료 온라인 도구로 API 토큰을 인코딩할 수 있습니다

또는 컴퓨터에서 다음과 같은 간단한 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}")

위 스크립트는 인코딩된 토큰이 포함된 바로 사용할 수 있는 헤더를 출력합니다. 다음과 같은 형식입니다.

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

2단계 - Quickchat AI Action 만들기

Quickchat AI 앱에서 Actions 및 MCPs로 이동하여 Action을 추가하세요.

AI Action 페이지

AI Action에 적절한 이름을 지정하세요.

이름: Search Jira issues

AI Action 이름 입력

3단계 - 입력 매개변수 설정

AI 에이전트의 주요 작업은 사용자의 질문을 Jira 이슈 검색에 사용할 정확한 쿼리로 바꾸는 것입니다. Jira는 더 복잡한 검색을 지원하기 위해 최근 이슈 검색을 JQL(Jira Query Language)로 완전히 전환했습니다. 이를 통해 AI 에이전트의 기능을 훨씬 확장할 수 있습니다. 입력 매개변수를 다음과 같이 설정하세요.

형식	이름	설명	기본값	필수
Text	jql	아래 참고	-	✅

AI 에이전트의 성능을 높이려면 잘 작성된 설명이 매우 중요합니다.

설명:

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 에이전트 성능의 핵심입니다

Jira 상태에 대한 참고 사항

Jira는 상태 이름과 범주를 구분하며 JQL도 이를 다르게 처리합니다.

• 상태 이름은 보드에 표시되는 이름입니다. 어떤 프로젝트는 To Do / In Progress / Done을 사용하고, 다른 프로젝트는 Open / In Review / Closed를 사용합니다.
• 상태 범주는 모든 상태가 속하는 세 가지 고정 범주인 To Do, In Progress, Done 중 하나입니다.

status = "To Do"는 이름으로 필터링하므로 첫 열의 이름이 Open인 보드에서는 결과가 없습니다. 보드에 미처리 티켓이 많아도 에이전트가 자신 있게 “할 일이 없습니다”라고 답하는 흔한 원인입니다. “아직 시작하지 않은 일”, “진행 중인 일”, “완료된 일”에 대한 질문에는 대신 범주로 필터링하세요.

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

status = "..."는 사용자가 보드에 실제로 있는 특정 상태 이름을 말할 때 사용하세요. Action 설명(7단계)에 보드의 실제 상태 이름을 나열하면 에이전트가 “QA 준비 완료” 같은 요청을 올바른 상태에 대응시킬 수 있습니다.

4단계 - API 엔드포인트 URL 설정

1. API 요청 메서드로 GET을 선택하세요.
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 에이전트는 대화에서 사용자가 말한 내용에 따라 이 매개변수 값을 채웁니다.
• fields는 고정 값을 사용합니다. 각 Jira 이슈에서 필요한 항목은 요약, 설명, _상태_뿐입니다.

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

API 요청 쿼리 매개변수 설정

jql 매개변수가 앞서 정의한 값을 올바르게 가리키는지 확인하세요. AI 데이터 추가 드롭다운 메뉴에서 선택할 수 있습니다.

드롭다운 메뉴에서 동적 jql 매개변수 선택

7단계 - API Action 설명 설정

AI Action을 제대로 설정하는 마지막 핵심 요소는 설명입니다. AI 에이전트는 URL과 매개변수만으로도 API 엔드포인트를 잘 이해하지만, 사용 목적에 맞게 동작을 최적화하는 것이 중요합니다.

프롬프트에 포함되는 가장 중요한 세 가지 요소는 다음과 같습니다.

• Action을 언제 호출할지: 사용자가 “검색”이라고 말하지 않아도 호출을 생략하지 않도록 찾기 / 검색하기 / 찾아보기뿐 아니라 설명하기 / 알려 주기 / 묘사하기 / 무엇인지 / 상태가 어떤지 등 가능한 표현을 모두 나열합니다.
• Jira 이슈를 검색할 때 고급 JQL 구문을 사용하는 방법에 대한 제안.
• 결과가 없을 때의 처리: 에이전트는 접근을 거부하지 말고 결과가 없다는 사실을 명시적으로 알려야 합니다.

이 내용을 반영한 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 에이전트와의 전체 대화를 테스트할 수 있습니다!

9단계 - 대화에서 AI 에이전트 테스트

Quickchat AI 앱으로 돌아가 대화 미리 보기에서 AI 에이전트를 테스트하세요.

대화 #1

AI 에이전트가 프로젝트의 모든 이슈를 요약합니다

이 간단한 대화에서 AI 에이전트는 프로젝트에 있는 모든 이슈의 개요를 제공합니다. 내부 동작을 확인하면 API 엔드포인트에 실행한 정확한 쿼리가 project = "Solar System"임을 알 수 있습니다.

대화 #2

AI 에이전트가 특정 이슈와 상태에 관한 질문에 답변합니다

이 경우에는 특정 이슈와 전반적으로 진행 중인 이슈라는 두 가지를 물었습니다. 내부 동작을 보면 에이전트가 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 에이전트가 창의적인 질문에 답변합니다 😉

이 경우에는 AI 에이전트에 조금 까다로운 질문을 던져 보았습니다. 올바르게 해석하려면 창의력이 필요한 질문이었습니다. 다음과 같은 JQL 쿼리로 변환되었습니다.

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

다음 표현으로 시도해 보세요

최종 사용자가 어떤 표현으로 요청하더라도 AI Action이 실행되는지 확인하려면 아래 프롬프트를 테스트 시나리오에서 각각 실행하세요. 에이전트는 검색 형태의 요청뿐 아니라 모든 요청에서 Jira를 조회해야 합니다.

• “실시간 점수에 관한 모든 열린 이슈를 찾아 주세요”
• “mercury가 포함된 이슈를 검색해 주세요”
• “Solar System 프로젝트를 설명해 주세요”
• “이번 스프린트의 열린 이슈를 알려 주세요”
• “현재 진행 중인 내용을 설명해 주세요”
• “pluto의 상태는 어떤가요?”

이 표현 중 하나라도 AI Action을 호출하지 않으면 API Action 설명(7단계)에 해당 동사가 명시적으로 나열되어 있는지 다시 확인하세요.

Jira에 일치하는 이슈가 없을 때의 예상 동작

Jira가 결과를 반환하지 않으면 AI 에이전트는 이를 명시적으로 알려야 합니다. 예를 들어 _“Jira를 확인했지만 쿼리와 일치하는 이슈를 찾지 못했습니다. 더 넓은 표현을 사용하거나 상태 필터를 제거해 보세요.”_라고 답해야 합니다.

대신 _“저는 Jira에 직접 접근할 수 없습니다”_라고 답한다면 AI Action이 아예 실행되지 않은 것입니다. 7단계의 설명을 다시 확인하고 검색 외의 동사(explain, tell me about, describe, what is)가 명시적으로 나열되어 있는지 확인하세요.

요약

이 글에서는 AI 에이전트가 대화에서 특정 API 엔드포인트를 창의적으로 활용하도록 설정하는 방법을 살펴보았습니다. 올바른 설정이 자동으로 갖춰지는 것은 아닙니다. 원하는 사용 목적에 관한 자세한 추가 정보를 제공해야 합니다. 이 글의 프롬프트와 설명을 활용하여 비슷한 AI 에이전트를 직접 만들어 보세요!

설명을 곁들인 긴 안내를 선호하시나요? 같은 설정 과정을 quickchat.ai의 블로그 글에서도 다룹니다. 이 문서 페이지가 지속적으로 갱신되는 공식 참조입니다.

추가 활용

Jira Action을 고정된 단일 요청으로만 사용할 필요는 없습니다. 방문자의 언어나 앞선 대화에서 수집한 값 같은 기본 제공 대화 변수와 저장된 메타데이터를 모든 필드에 삽입할 수 있습니다. 여러 Actions를 추가하여 에이전트가 질문마다 적절한 것을 선택하도록 할 수도 있습니다. 전체 옵션은 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을 추가하는 데 유용한 지침을 얻을 수 있습니다.