Connecter un agent IA aux tickets Jira

Introduction

Dans cet article de blog, je vais vous montrer comment connecter votre agent IA à Jira. Nous utiliserons :

• un compte Jira (gratuit)
• un agent IA Quickchat (inscrivez-vous ici et utilisez-le gratuitement)

Vous cherchez la référence canonique, mise à jour en continu ? Le même guide se trouve dans notre documentation à l’adresse docs.quickchat.ai/channels/jira. Cet article est la version longue et commentée.

Cela permettra à votre agent Quickchat AI de :

• pouvoir rechercher dans vos tickets Jira, et
• être pertinent lorsqu’il répond aux questions à partir de ces tickets

Nous utiliserons les AI Actions de Quickchat (actions HTTP personnalisées) pour permettre à votre agent d’appeler l’endpoint Enhanced search for issues de l’API Jira (Atlassian).

Créez un agent IA capable d’interpréter les saisies utilisateur avec souplesse

Regarder la vidéo

Fonctionnement

Voici comment votre agent IA fonctionnera pendant les conversations :

1. L’utilisateur pose une question comme « qu’en est-il des tickets liés à mercury ? »
2. L’agent IA récupère les informations pertinentes depuis l’API Jira avec une requête comme « mercury »
3. L’agent IA répond à l’utilisateur à partir des informations récupérées depuis l’API

Suivez les étapes ci-dessous. La configuration complète ne devrait pas prendre plus de 10 minutes !

Étape 0, créer un compte Jira et un projet

1. Accédez à id.atlassian.com/signup, puis créez et vérifiez votre compte.
2. Ajoutez Jira à vos applications Atlassian (l’offre gratuite suffit pour commencer).
3. Configurez votre premier projet et créez des tickets comme dans l’exemple ci-dessous.

Exemple de tableau avec des tickets Jira

Étape 1, token d’authentification de l’API Jira

Accédez à id.atlassian.com/manage-profile/security/api-tokens et créez votre token API, qui ressemblera à ceci :

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

Pour pouvoir utiliser votre token API Atlassian dans Quickchat AI Actions, vous devez l’encoder en base64 avec votre adresse e-mail :

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

Veillez à inclure l’adresse e-mail exacte que vous avez utilisée pour configurer votre compte Atlassian

Vous pouvez utiliser un outil en ligne simple comme base64encode.org.

Veillez à utiliser le Live mode, qui garantit que l’encodage s’effectue entièrement dans votre navigateur.

Vous pouvez utiliser un outil en ligne gratuit pour encoder votre token API

Vous pouvez aussi le faire sur votre machine avec un simple script 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}")

Le script ci-dessus vous donnera un header prêt à l’emploi avec le token encodé, qui ressemblera à ceci :

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Étape 2, créer une Quickchat AI Action

Dans l’application Quickchat AI, accédez à Actions & MCPs et ajoutez une action :

Page AI Action

Donnez un nom approprié à votre AI Action :

Name : Search Jira issues

Insérer le nom de l’AI Action

Étape 3, définir les paramètres d’entrée

La tâche principale de votre agent IA consistera à traduire la demande de l’utilisateur en requête exacte à utiliser pour rechercher dans les tickets Jira. Pour la recherche de tickets, Jira a récemment entièrement migré vers JQL (Jira Query Language) afin de permettre des recherches plus complexes. Cela rend votre agent IA beaucoup plus puissant. Définissez vos paramètres d’entrée comme suit :

Pour obtenir de bonnes performances avec votre agent IA, une description bien rédigée est très importante :

Description :

Une seule chaîne JQL (Jira Query Language) valide construite selon la description. Privilégier le rappel : préférer `(text ~ "term1" OR text ~ "term2")` plutôt qu’un enchaînement avec AND, et utiliser des parenthèses pour le regroupement. Pour les questions "not started / in progress / done", filtrer sur `statusCategory` ("To Do", "In Progress", "Done"), qui est stable entre les projets ; utiliser `status = "..."` uniquement lorsque l’utilisateur nomme un statut spécifique qui existe sur le tableau. Éviter les champs personnalisés. Exemples : `statusCategory = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`, `(text ~ "planet*" OR text ~ "integration")`, `project = "Solar System" AND statusCategory = "To Do"`.

Une description de paramètre bien rédigée est essentielle aux performances de l’agent IA

Remarque sur les statuts Jira

Jira distingue le nom d’un statut de sa catégorie, et JQL les traite différemment :

• Le nom du statut correspond à ce que le tableau affiche. Un projet utilise To Do / In Progress / Done, un autre utilise Open / In Review / Closed.
• La catégorie de statut correspond à l’une des trois catégories fixes auxquelles chaque statut est associé : To Do, In Progress, Done.

status = "To Do" filtre par nom, il ne renvoie donc rien sur un tableau dont la première colonne s’appelle Open. C’est une raison fréquente pour laquelle un agent indique avec assurance qu’il n’y a « aucun ticket à faire » alors que le tableau en contient beaucoup. Pour les questions de type « ce qui n’a pas commencé », « ce qui est en cours » et « ce qui est terminé », filtrez plutôt sur la catégorie :

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

Conservez status = "..." lorsque l’utilisateur nomme un statut spécifique dont vous savez qu’il existe sur le tableau. Vous pouvez aussi lister les vrais noms de statuts de votre tableau dans la description de l’Action (étape 7), afin que l’agent associe une demande comme « prêt pour QA » au bon statut.

Étape 4, définir l’URL de l’endpoint API

1. Sélectionnez GET comme Action Type
2. Définissez l’URL de l’endpoint sur l’endpoint Jira /rest/api/3/search/jql

Définir l’URL de votre endpoint API

Veillez à utiliser votre nom de domaine Atlassian. Vous le trouverez dans l’URL de votre tableau Jira.

Votre nom de domaine Atlassian

Étape 5, définir les headers de requête API

Définissez les headers de votre requête API comme suit :

Faites particulièrement attention au format correct de votre header Authorization : Basic <base64-encoded email:api token>

Définir les headers de votre requête API

Étape 6, définir les paramètres de requête API

Définissez deux paramètres de requête pour votre requête IA :

• jql prend une valeur dynamique définie précédemment dans la section What to ask the user first. Le rôle de l’agent IA est de renseigner la valeur de ce paramètre en fonction de ce que l’utilisateur a dit dans la conversation.
• fields prend une valeur fixe. Pour chaque ticket Jira, seules les informations summary, description et status nous intéressent.

Définir les paramètres de requête de votre API

Veillez à ce que le paramètre jql pointe correctement vers la valeur définie précédemment. Vous pouvez le sélectionner dans le menu déroulant Add AI Data.

Sélectionner le paramètre dynamique jql dans le menu déroulant

Étape 7, définir la description de l’API Action

Le dernier élément crucial d’une AI Action bien configurée est sa description. Même si l’agent IA comprend déjà correctement votre endpoint API à partir de son URL et de ses paramètres, il est essentiel d’optimiser son comportement pour votre cas d’usage.

Les trois aspects les plus importants inclus dans le prompt sont :

• quand invoquer l’action, en listant toutes les formulations que l’utilisateur pourrait choisir (find / search / look for, ainsi que explain / tell me about / describe / what is / how is the status of), afin que l’agent ne saute pas l’appel lorsque l’utilisateur ne dit pas « search »
• des suggestions sur l’utilisation de la syntaxe JQL avancée lors de la recherche de tickets Jira
• comment gérer les résultats vides, l’agent doit l’indiquer explicitement plutôt que refuser l’accès

Voici la Description de l’API Action obtenue :

Utilisez cette action chaque fois que l’utilisateur demande quelque chose qui pourrait recevoir une réponse à partir des données de son Jira : projets, tickets, statuts, sprints, cycles de test, descriptions, responsables, commentaires, quelle que soit la formulation de la demande (find / search / look for / explain / tell me about / describe / what is / how is the status of, etc.). Ne refusez pas l’accès ; interrogez d’abord Jira.

Construisez une requête JQL qui privilégie le rappel plutôt que la précision : préférez `(text ~ "term1" OR text ~ "term2")` plutôt qu’un enchaînement avec AND, et utilisez des parenthèses pour le regroupement. Pour les questions de cycle de vie (not started, in progress, done), filtrez sur `statusCategory` ("To Do" / "In Progress" / "Done") plutôt que sur `status`, car les noms de statuts varient selon le tableau ; utilisez `status = "..."` uniquement lorsque l’utilisateur nomme un statut spécifique. Évitez les champs personnalisés.

Si Jira ne renvoie aucune correspondance, dites-le explicitement à l’utilisateur et suggérez une requête plus précise.

Étape 8, tester l’API Action

Avant de tester l’AI Action en conversation, nous pouvons tester la façon dont l’API elle-même est appelée dans l’onglet Test Response. Faisons un premier test avec la requête suivante, qui devrait renvoyer tous les tickets du projet : project = "Solar System"

Recherche de tous les tickets du projet Solar System

Voici ci-dessous la réponse de test que nous obtenons. Comme prévu, elle liste les champs summary, description et status pour les 6 tickets de notre tableau Jira.

La réponse liste tous les tickets du projet Solar System

Essayons une autre requête. Cette fois, recherchons tous les tickets qui mentionnent « mercury » : text ~ "mercury"

Recherche de tickets qui mentionnent mercury

Nous avons maintenant validé que l’AI Action appelle correctement notre endpoint API. Nous pouvons passer au test de conversations complètes avec l’agent IA !

Étape 9, tester l’agent IA dans des conversations

Revenez à l’application Quickchat AI et testez votre agent IA dans l’aperçu de conversation.

Conversation #1

L’agent IA donne un résumé de tous les tickets du projet

Dans cette conversation simple, l’agent IA donne une vue d’ensemble de tous les tickets du projet. En arrière-plan, on constate que la requête exacte qu’il a exécutée sur l’endpoint API était : project = "Solar System"

Conversation #2

L’agent IA répond à des questions sur des tickets et des statuts spécifiques

Dans ce cas, l’agent IA a été interrogé sur deux aspects distincts : un ticket précis et les tickets en cours de manière générale. En arrière-plan, on constate qu’il a décidé d’utiliser l’API Jira en deux étapes :

1. Vérifier si pluto est en cours :

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

2. Vérifier ce qui est également en cours :

status = "In Progress"

Conversation #3

L’agent IA répond à une requête créative 😉

Dans ce cas, je voulais mettre l’agent IA à l’épreuve avec une question qui demande une certaine souplesse d’interprétation. Voici comment elle a été traduite en requête JQL :

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

Essayez ces formulations

Pour vérifier que l’AI Action se déclenche quelle que soit la formulation de la demande par vos utilisateurs finaux, exécutez chacun des prompts ci-dessous dans votre scénario de test. L’agent doit interroger Jira pour chacun d’eux, et pas seulement pour ceux qui ressemblent à une recherche :

• « trouve tous les tickets ouverts sur les scores en direct »
• « recherche les tickets avec mercury »
• « explique le projet Solar System »
• « parle-moi des tickets ouverts dans ce sprint »
• « décris ce qui est actuellement en cours »
• « quel est le statut de pluto ? »

Si l’une de ces formulations n’invoque pas l’AI Action, vérifiez que la description de votre API Action (étape 7) liste explicitement ces verbes.

À quoi s’attendre lorsque Jira n’a aucun ticket correspondant. Lorsque Jira renvoie zéro résultat, votre agent IA doit l’indiquer explicitement, par exemple : « J’ai vérifié Jira et je n’ai trouvé aucun ticket correspondant à votre requête. Essayez une formulation plus large ou supprimez le filtre de statut. » Si l’agent répond plutôt « Je n’ai pas d’accès direct à votre Jira », l’AI Action ne s’est pas déclenchée. Vérifiez de nouveau la description de l’étape 7 et confirmez qu’elle liste explicitement les verbes qui ne sont pas des verbes de recherche (explain, tell me about, describe, what is).

Résumé

Dans cet article de blog, nous avons montré comment configurer un agent IA pour utiliser un endpoint API spécifique de manière souple dans des conversations. La bonne configuration n’est pas disponible telle quelle. Elle nécessite de fournir des informations supplémentaires détaillées sur le cas d’usage précis que nous avons en tête. Vous pouvez réutiliser les prompts et descriptions présentés dans cet article pour créer vos propres agents IA similaires. Pour un autre exemple complet dans le même format étape par étape, consultez comment connecter votre agent IA à Google Sheets et enregistrer des leads, des questions sans réponse et des demandes de démo dans une feuille de calcul.

Vous souhaitez garder ce guide en favori ? La version canonique, mise à jour en continu, de ce guide se trouve dans notre documentation à l’adresse docs.quickchat.ai/channels/jira. Consultez-la pour copier-coller la dernière description d’API Action et suivre les mises à jour de la recette.

Aller plus loin

Une action Jira ne doit pas nécessairement être une requête unique et fixe. Vous pouvez injecter des variables de conversation intégrées et des métadonnées enregistrées (comme la langue du visiteur ou des valeurs capturées plus tôt dans la conversation) dans n’importe quel champ, et ajouter plusieurs actions afin que l’agent choisisse la bonne selon la question. La référence AI Actions couvre l’ensemble des options.

Guides associés

Le même mécanisme AI Action connecte un agent à n’importe quelle API HTTP. Autres guides qui l’utilisent :

• Créer un bot de modération Discord IA avec des AI Actions personnalisées
• Connecter votre agent IA à la Telegram Bot API
• Connecter votre agent IA à Google Sheets
• Connecter votre agent IA à HubSpot pour enregistrer des contacts, des deals et des tickets
• Envoyer des notifications Slack avec AI Actions
• Connecter Cal.com à votre agent IA en 5 minutes
• Créer un agent de support IA à partir de votre documentation
• Agent IA pour le support client SaaS

BONUS

L’article de blog ci-dessus a été écrit par un humain (votre serviteur), mais il aurait tout aussi bien pu être écrit par l’IA. Par exemple, en collant un prompt comme celui-ci dans ChatGPT :

J’ai besoin d’un endpoint API qui me permette de rechercher dans mes tickets Jira.

Guidez-moi dans le processus étape par étape, afin qu’il soit accessible à une personne modérément technique :
- Fournissez des liens vers la documentation décrivant l’endpoint
- Toute création de compte et configuration initiale nécessaire
- Si un compte payant est nécessaire, indiquez-le clairement
- Si une authentification, comme des tokens API, est nécessaire, guidez-moi dans le processus de création et montrez-moi exactement chaque étape requise pour pouvoir les utiliser comme header de requête HTTP. Par exemple, si un encodage base64 est nécessaire, montrez un script ou une autre méthode pour y parvenir.
- Montrez-moi exactement les clés et valeurs de headers dont j’ai besoin pour la requête HTTP (montrez les clés et valeurs de headers dans un tableau)
- Montrez-moi exactement les paramètres de payload dont j’ai besoin pour la requête HTTP (montrez le nom du paramètre de payload et des valeurs d’exemple dans un tableau)

À l’avenir, plutôt que de rechercher dans des tickets Jira, vous voudrez peut-être :

• envoyer des messages à un channel Slack ?
• récupérer des informations depuis une page Notion ?
• effectuer une action via Zapier ?

Indiquez-le dans la première phrase et relancez le prompt. Vous obtiendrez des instructions parfaitement correctes pour ajouter exactement l’AI Action dont vous avez besoin !