AI AgentをJiraチケットに接続する

はじめに

この記事では、AI AgentをJiraに接続する方法を説明します。使用するものは次のとおりです。

• Jiraアカウント（無料）
• QuickchatのAI Agent（こちらから登録して無料で使用できます）

正式で継続的に更新されるリファレンスを探している場合は、同じ手順をドキュメントのdocs.quickchat.ai/channels/jiraで確認できます。この記事は、説明を加えた詳細版です。

これにより、Quickchat AI Agentは次のことができるようになります。

• Jiraチケットを検索できる
• その内容に基づいて適切に質問へ回答できる

QuickchatのAI Actions（カスタムHTTPアクション）を使用して、AgentがJira（Atlassian）APIのEnhanced search for issuesエンドポイントを呼び出せるようにします。

ユーザー入力の解釈に優れたAI Agentを作成します

動画を見る

仕組み

会話中、AI Agentは次のように動作します。

1. ユーザーが “what’s up with issues to do with mercury?” のような質問をします
2. AI Agentが “mercury” のようなクエリを使用して、Jira APIから関連情報を取得します
3. AI Agentが、APIから取得した情報に基づいてユーザーに返信します

以下の手順に従ってください。全体の設定は10分以内で完了するはずです。

Step 0 - Jiraアカウントとプロジェクトを作成する

1. id.atlassian.com/signupにアクセスし、アカウントを作成して認証します。
2. AtlassianアプリにJiraを追加します（開始には無料プランで十分です）。
3. 最初のプロジェクトを設定し、以下の例のようなチケットを作成します。

Jira課題を含むボードの例

Step 1 - Jira API認証トークン

id.atlassian.com/manage-profile/security/api-tokensにアクセスし、次のようなAPI tokenを作成します。

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=

Step 2 - Quickchat AI Actionを作成する

Quickchat AI appで、Actions & MCPsに移動してアクションを追加します。

AI Actionページ

AI Actionに適切な名前を付けます。

Name: Search Jira issues

AI Action名を入力します

Step 3 - 入力パラメータを設定する

AI Agentの主なタスクは、ユーザーが尋ねている内容を、Jira課題を検索するために使用する正確なクエリへ変換することです。課題の検索について、Jiraは最近、より複雑な検索を実行できるようにJQL（Jira Query Language）へ完全に移行しました。これにより、AI Agentを大幅に強化できます。入力パラメータを次のように設定します。

AI Agentで高い性能を実現するには、よく作られた説明が非常に重要です。

Description:

説明に従って構築された、単一の有効なJQL（Jira Query Language）文字列。再現率を優先します。ANDで連結するよりも`(text ~ "term1" OR text ~ "term2")`を優先し、グループ化には括弧を使用します。「not started / in progress / done」に関する質問では、プロジェクト間で安定している`statusCategory`（"To Do", "In Progress", "Done"）でフィルタします。ユーザーがボード上に存在する特定のステータス名を指定した場合にのみ、`status = "..."`を使用します。カスタムフィールドは避けます。例: `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を使用します。
• ステータスカテゴリは、すべてのステータスが対応する3つの固定バケットのいずれかです: To Do, In Progress, Done。

status = "To Do"は名前でフィルタするため、最初の列の名前がOpenであるボードでは何も返しません。これは、ボードに対象チケットが多数あるにもかかわらず、Agentが「no tickets to do」と自信を持って報告する一般的な原因です。「what has not started」、「what is in progress」、「what is done」のような質問では、代わりにカテゴリでフィルタします。

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

ユーザーが、ボード上に存在することが分かっている特定のステータス名を指定した場合は、status = "..."を使用します。また、Actionの説明（Step 7）にボードの実際のステータス名を列挙しておくと、Agentが「ready for QA」のようなリクエストを適切なステータスに対応付けられます。

Step 4 - APIエンドポイントURLを設定する

1. Action TypeとしてGETを選択します
2. エンドポイントURLをJiraの/rest/api/3/search/jqlエンドポイントに設定します

APIエンドポイントURLを設定します

自分のAtlassianドメイン名を使用してください。これはJiraボードのURLで確認できます。

自分のAtlassianドメイン名

Step 5 - APIリクエストヘッダーを設定する

APIリクエストのheadersを次のように定義します。

Authorizationヘッダーの形式を正しく設定するよう、特に注意してください: Basic <base64-encoded email:api token>

APIリクエストヘッダーを設定します

Step 6 - APIリクエストのクエリパラメータを設定する

AIリクエスト用に2つのクエリパラメータを設定します。

• jqlは、先ほど_What to ask the user first_セクションで定義した動的な値を取ります。このパラメータの値を、会話の中でユーザーが発言した内容に基づいて入力するのはAI Agentの役割です。
• fieldsは固定値を取ります。各Jira課題については、summary、description、_status_のみに関心があります。

APIリクエストのクエリパラメータを設定します

jqlパラメータが、先ほど定義した値を正しく指していることを確認してください。Add AI Dataドロップダウンメニューから選択できます。

ドロップダウンメニューから動的なjqlパラメータを選択します

Step 7 - API Actionの説明を設定する

適切に設定されたAI Actionにおける最後の重要な要素は、その説明です。AI AgentはURLとパラメータだけでもAPIエンドポイントをある程度理解できますが、自分のユースケースに合わせて挙動を最適化することが重要です。

プロンプトに含まれる最も重要な3つの要素は次のとおりです。

• アクションを呼び出すタイミング、ユーザーが選ぶ可能性のあるすべての表現（find / search / look for、および explain / tell me about / describe / what is / how is the status of）を列挙し、ユーザーが「search」と言わない場合でもAgentが呼び出しを省略しないようにします
• Jira課題を検索する際に高度なJQL構文を使用する方法に関する提案
• 空の結果の扱い方、Agentはアクセスを拒否するのではなく、その旨を明示する必要があります

結果として得られるAPI Action Descriptionは次のとおりです。

ユーザーが、Jira内のデータで回答できる可能性がある内容（プロジェクト、課題、ステータス、スプリント、テストサイクル、説明、担当者、コメント）について尋ねた場合は、リクエストの表現（find / search / look for / explain / tell me about / describe / what is / how is the status ofなど）に関係なく、このアクションを使用します。アクセスを拒否しないでください。まずJiraにクエリします。

精度よりも再現率を優先するJQLを構築します。ANDで連結するよりも`(text ~ "term1" OR text ~ "term2")`を優先し、グループ化には括弧を使用します。ライフサイクルに関する質問（not started, in progress, done）では、ボードごとにステータス名が異なるため、`status`ではなく`statusCategory`（"To Do" / "In Progress" / "Done"）でフィルタします。ユーザーが特定のステータス名を指定した場合にのみ、`status = "..."`を使用します。カスタムフィールドは避けます。

Jiraが一致する結果を返さない場合は、その旨をユーザーに明示し、より絞り込んだクエリを提案します。

Step 8 - API Actionをテストする

会話でAI Actionをテストする前に、Test ResponseタブでAPI自体がどのように呼び出されるかをテストできます。プロジェクト内のすべての課題を返すはずの次のクエリで、最初のテストを行います: project = "Solar System"

Solar Systemプロジェクト内のすべての課題を検索しています

以下は取得したテストレスポンスです。想定どおり、Jiraボード上の6件すべての課題について、summary、description、statusフィールドが一覧表示されています。

レスポンスにはSolar Systemプロジェクト内のすべての課題が一覧表示されています

もう1つクエリを試します。今回は「mercury」に言及しているすべての課題を検索します: text ~ "mercury"

mercuryに言及している課題を検索しています

これで、AI ActionがAPIエンドポイントを正しく呼び出すことを確認できました。次に、AI Agentとの完全な会話のテストに進みます。

Step 9 - 会話でAI Agentをテストする

Quickchat AI appに戻り、会話プレビューでAI Agentをテストします。

会話 #1

AI Agentがプロジェクト内のすべての課題の概要を示しています

このシンプルな会話では、AI Agentがプロジェクト内のすべての課題の概要を示しています。裏側を確認すると、APIエンドポイントに対して実行された正確なクエリは project = "Solar System" でした。

会話 #2

AI Agentが特定の課題とステータスに関する質問に回答しています

このケースでは、AI Agentは2つの別々の観点について尋ねられました。特定の課題と、一般的に進行中の課題です。裏側を見ると、Jira APIを2段階のプロセスで使用することを決定したことが分かります。

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にクエリする必要があります。

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

これらの表現のいずれかでAI Actionが呼び出されない場合は、API Actionの説明（Step 7）にそれらの動詞が明示的に記載されていることを再確認してください。

Jiraに一致する課題がない場合に期待される動作。 Jiraが0件の結果を返した場合、AI Agentはその旨を明示する必要があります。たとえば、“I checked Jira and found no matching issues for your query, try a broader phrasing or remove the status filter.” のように返します。代わりにAgentが “I don’t have direct access to your Jira” と返信する場合、AI Actionはまったく実行されていません。Step 7の説明を再確認し、検索以外の動詞（explain, tell me about, describe, what is）が明示的に列挙されていることを確認してください。

まとめ

この記事では、AI Agentが会話の中で特定のAPIエンドポイントを柔軟に使用できるように設定する方法を示しました。正しい設定は標準で自動的に得られるものではありません。想定している具体的なユースケースについて、詳細な追加情報を提供する必要があります。この記事で示したプロンプトと説明は、同様のAI Agentを作成する際に自由に再利用してください。同じステップバイステップ形式の別の完全な例として、AI AgentをGoogle Sheetsに接続する方法を参照してください。リード、未回答の質問、デモリクエストをスプレッドシートに記録できます。

このガイドをブックマークしておきたい場合は、正式で継続的に更新されるこの手順のバージョンがドキュメントのdocs.quickchat.ai/channels/jiraにあります。最新のAPI Action説明をコピー＆ペーストし、レシピの更新を確認するには、そちらにアクセスしてください。

さらに進める

Jiraアクションは、単一の固定リクエストである必要はありません。組み込みの会話変数と保存済みメタデータ（訪問者の言語や会話の前半で取得した値など）を任意のフィールドに挿入できます。また、複数のアクションを追加して、Agentが質問ごとに適切なものを選択できるようにすることもできます。利用可能なすべてのオプションについては、AI Actions referenceを参照してください。

関連ガイド

同じAI Actionの仕組みで、Agentを任意のHTTP APIに接続できます。これを使用する他の手順は次のとおりです。

• カスタムAI ActionsでAI Discordモデレーションbotを構築する
• AI AgentをTelegram Bot APIに接続する
• AI AgentをGoogle Sheetsに接続する
• AI AgentをHubSpotに接続して連絡先、取引、チケットを記録する
• AI ActionsでSlack通知を送信する
• 5分でCal.comをAI Agentに接続する
• ドキュメントからAI Support Agentを作成する方法
• SaaSカスタマーサポート向けAI Agent

BONUS

上記の記事は_人間_（筆者自身）が書いたものですが、AIでも同様に書けたはずです。たとえば、次のようなプロンプトをChatGPTに貼り付けます。

Jiraチケットを検索できるAPIエンドポイントが必要です。

ある程度技術的な知識のある人にも分かるように、プロセスをステップバイステップで案内してください。
- エンドポイントを説明するドキュメントへのリンクを提供してください
- 必要なアカウント作成と初期設定を示してください
- 有料アカウントが必要な場合は、そのことを明確に示してください
- APIトークンなどの認証が必要な場合は、それらを作成するプロセスを案内し、HTTPリクエストヘッダーとして使用できるようにするために必要な各手順を正確に示してください。たとえばbase64エンコードが必要な場合は、それを実現するためのスクリプトまたは別の方法を示してください。
- HTTPリクエストに必要なヘッダーキーと値を正確に示してください（ヘッダーキーと値を表で示してください）
- HTTPリクエストに必要なペイロードパラメータを正確に示してください（ペイロードパラメータ名と値の例を表で示してください）

将来的には、Jiraチケットを検索する代わりに、次のようなことをしたいかもしれません。

• Slackチャンネルにメッセージを送信する
• Notionページから情報を取得する
• Zapier経由でアクションを実行する

それを最初の文に書き、もう一度プロンプトを実行してください。必要な正確なAI Actionを追加するための十分に有用な手順が得られます。