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 deux aspects les plus importants inclus dans le prompt sont :

• des suggestions sur la façon d’utiliser la syntaxe JQL avancée lors de la recherche d’issues Jira
• la nécessité d’effectuer des recherches larges pour éviter de revenir à l’utilisateur avec des résultats vides

Voici la description d’API Action résultante :

Infer the user’s intent and construct a single valid JQL that prioritizes recall over precision. Use `text ~ "..."` for contains (case-insensitive) domain / content terms (features, services, tasks, components, etc.). If multiple candidate terms exist, prefer OR and wrap in parentheses. Include `status = "..."` only when the user states a status. Never invent custom fields; only use standard fields like `text`, `status`, and `project` if explicitly mentioned. Keep queries short to avoid zero results. Use parentheses to make precedence explicit (AND binds tighter than OR). Example: `status = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`.

La description doit indiquer précisément comment utiliser la requête API

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

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 !

🎁  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 !