Jira

Dans cet article, je vais vous montrer comment connecter votre AI Agent à Jira. Nous utiliserons :

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

Cela permettra à votre AI Agent Quickchat :

• de pouvoir rechercher dans vos tickets Jira, et
• d’être malin pour répondre aux questions en s’appuyant dessus

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).

Concevez un AI Agent créatif dans l’interprétation des saisies utilisateur

Regarder la vidéo

Play

Comment ça marche

Voici comment votre AI Agent fonctionnera pendant les conversations :

1. L’utilisateur pose une question du type « quoi de neuf avec les issues liées à mercure ? »
2. L’AI Agent récupère des informations pertinentes auprès de l’API Jira à l’aide d’une requête comme « mercury »
3. L’AI Agent répond à l’utilisateur en se basant sur les informations récupérées depuis l’API

Veuillez suivre les étapes ci-dessous. L’ensemble de la configuration ne devrait pas prendre plus de 10 minutes !

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

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

Tableau d’exemple avec des issues Jira

Étape 1 – jeton d’authentification de l’API Jira

Allez sur id.atlassian.com/manage-profile/security/api-tokens et créez votre jeton d’API, qui ressemblera à ceci :

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

Pour pouvoir utiliser votre jeton d’API Atlassian dans les AI Actions de Quickchat, vous devez l’encoder en base64 en même temps que votre adresse e‑mail :

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

Veillez à indiquer exactement l’adresse e‑mail utilisée pour créer votre compte Atlassian.

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

Assurez-vous d’utiliser le Live mode, qui garantit que l’encodage se fait entièrement dans votre navigateur.

Vous pouvez utiliser un outil en ligne gratuit pour encoder votre jeton d’API

Sinon, voici comment le faire sur votre machine dans 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 en-tête prêt à l’emploi avec le jeton encodé, qui ressemble à ceci :

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Étape 2 – créer une AI Action Quickchat

Dans l’application Quickchat AI, allez dans Actions & MCPs et ajoutez une action :

Page AI Action

Donnez un nom approprié à votre AI Action :

Name : Search Jira issues

Indiquez le nom de l’AI Action

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

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

Format	Nom	Description	Valeur par défaut	Requis
Text	jql	(voir ci-dessous)	-	✅

Pour obtenir d’excellentes performances avec votre AI Agent, une description bien rédigée est très importante :

Description :

A single valid JQL (Jira Query Language) string built per the description. Favor recall: prefer `(text ~ "term1" OR text ~ "term2")` over chaining with AND, add `status = "..."` only if requested, avoid custom fields, and use parentheses for grouping. Examples: `status = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`, `(text ~ "planet*" OR text ~ "integration")`, `project = "Solar System" AND (text ~ "api" OR text ~ "integration")`.

Une description bien pensée est la clé des performances de l’AI Agent

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

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

Définissez l’URL de l’endpoint API

Assurez-vous d’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 en-têtes (headers) de la requête API

Définissez vos en-têtes de requête API comme suit :

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

Faites particulièrement attention au formatage correct de votre en-tête Authorization : Basic <base64-encoded email:api token>

Définissez les en-têtes de la requête API

Étape 6 – définir les paramètres de requête (query params)

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

• jql prend une valeur dynamique définie plus tôt dans la section What to ask the user first. C’est le travail de l’AI Agent de remplir 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 issue Jira, nous ne sommes intéressés que par son summary, description et status.

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

Définissez les paramètres de requête de la requête API

Assurez-vous que le paramètre jql pointe correctement vers la valeur définie plus tôt. Vous pouvez le sélectionner dans le menu déroulant Add AI Data.

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

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

L’ingrédient final crucial d’une AI Action bien configurée est sa description. Bien que l’AI Agent comprenne déjà bien 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 explicitement chaque formulation que l’utilisateur pourrait choisir (find / search / look for, mais aussi explain / tell me about / describe / what is / how is the status of) afin que l’agent n’ignore pas l’appel quand l’utilisateur ne dit pas « search »
• des suggestions sur la façon d’utiliser la syntaxe JQL avancée lors de la recherche d’issues Jira
• comment gérer les résultats vides — l’agent doit le dire explicitement plutôt que de refuser l’accès

Voici la description d’API Action résultante :

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, add `status = "..."` only if the user asked for a specific status, avoid custom fields, and use parentheses for grouping.

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

Étape 8 – tester l’API Action

Avant de tester l’AI Action dans une conversation, nous pouvons tester comment l’API est appelée dans l’onglet Test Response. Faisons un premier test avec la requête suivante, qui devrait renvoyer toutes les issues du projet : project = "Solar System"

Recherche de toutes les issues dans le projet Solar System

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

La réponse liste toutes les issues du projet Solar System

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

Recherche des issues qui mentionnent mercury

Nous avons maintenant validé que l’AI Action appelle correctement notre endpoint API. Nous pouvons passer aux tests de conversations complètes avec l’AI Agent !

Étape 9 – tester l’AI Agent en conversation

Retournez sur l’application Quickchat AI et testez votre AI Agent dans l’aperçu de conversation.

Conversation #1

L’AI Agent donne un résumé de toutes les issues du projet

Dans cette conversation simple, l’AI Agent donne un aperçu de toutes les issues du projet. En coulisses, la requête exacte qu’il a exécutée contre l’endpoint API était : project = "Solar System"

Conversation #2

L’AI Agent répond à des questions sur des issues et des statuts spécifiques

Dans ce cas, on a demandé à l’AI Agent deux choses : une issue spécifique et les issues en cours de manière générale. En coulisses, 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 encore en cours :

status = "In Progress"

Conversation #3

L’AI Agent répond à une requête créative 😉

Dans ce cas, je voulais mettre l’AI Agent à l’épreuve et lui ai posé une question qui demande un peu de créativité pour être correctement interprétée. 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 vous assurer que l’AI Action se déclenche peu importe la façon dont vos utilisateurs finaux formulent leur requête, testez chacun des prompts ci-dessous sur votre scénario de test. L’agent doit interroger Jira sur chacun d’eux, pas uniquement ceux avec des verbes de recherche :

• « 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? »

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

Que faire quand Jira ne trouve aucune issue correspondante

Quand Jira renvoie zéro résultat, votre AI Agent doit le dire explicitement — par exemple : « J’ai vérifié Jira et n’ai trouvé aucune issue correspondant à votre requête — essayez une formulation plus large ou supprimez le filtre de statut. »

Si l’agent répond à la place « Je n’ai pas accès direct à votre Jira », l’AI Action ne s’est pas déclenchée du tout. Vérifiez à nouveau la description de l’Étape 7 et assurez-vous qu’elle liste explicitement les verbes hors recherche (explain, tell me about, describe, what is).

Récapitulatif

Dans cet article, nous avons montré comment configurer un AI Agent pour utiliser un endpoint API spécifique de manière créative dans les conversations. La configuration correcte n’est pas livrée « prête à l’emploi » – elle nécessite de fournir des informations supplémentaires détaillées sur le cas d’usage spécifique visé. N’hésitez pas à réutiliser les prompts et descriptions présentés dans cet article pour créer vos propres AI Agents similaires !

Vous préférez un guide long et narratif ? La même configuration est également couverte dans un billet de blog sur quickchat.ai. Cette page de documentation est la référence canonique et continuellement mise à jour.

🎁  BONUS

L’article ci-dessus a été écrit par un humain (votre serviteur), mais aurait tout aussi bien pu être écrit par une IA. Par exemple, en collant un prompt comme celui-ci dans 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)

À l’avenir, peut‑être qu’au lieu de rechercher dans des tickets Jira, vous souhaiteriez :

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

Dites‑le dans la première phrase et relancez le prompt ! Vous obtiendrez d’excellentes instructions pour ajouter précisément l’AI Action dont vous avez besoin !