Cercare ticket Jira con un'azione personalizzata

Jira non è un’integrazione predefinita di Quickchat AI. Questa pagina è un esempio pratico di creazione di un’azione API personalizzata per un’API REST di terze parti. Lo stesso schema funziona con qualsiasi altra API.

In questo articolo ti mostrerò come collegare il tuo agente AI a Jira. Useremo:

• un account Jira (gratuito)
• un agente AI di Quickchat (registrati qui e usalo gratuitamente)

Il tuo agente Quickchat AI potrà:

• cercare nei tuoi ticket Jira e
• rispondere in modo intelligente alle domande basandosi su di essi

Useremo le azioni AI di Quickchat (azioni HTTP personalizzate) per consentire all’agente di chiamare l’endpoint Enhanced search for issues dell’API di Jira (Atlassian).

Crea un agente AI capace di interpretare con creatività gli input degli utenti

Verifiche di esempio facoltative

• Visualizza un’anteprima di una richiesta di azione API. Compila un modello di richiesta fornito usando valori di esempio sintetici senza inviarlo. Ometti gli header con credenziali.

• Visualizza un’anteprima delle corrispondenze JSONPath. Verifica percorsi radice, campi, indici di array e caratteri jolly su JSON fornito. Questo strumento non esegue un’azione e non salva la memoria della conversazione.

In un browser compatibile queste verifiche sono disponibili anche come strumenti del sito. I link aprono i moduli standard.

Guarda il video

Play

Come funziona

Ecco come opererà il tuo agente AI durante le conversazioni:

1. L’utente pone una domanda come “come vanno le issue che riguardano mercury?”
2. L’agente AI recupera informazioni pertinenti dall’API di Jira usando una query come “mercury”
3. L’agente AI risponde all’utente in base alle informazioni recuperate dall’API

Segui i passaggi riportati di seguito. L’intera configurazione non dovrebbe richiedere più di 10 minuti!

Passaggio 0 - Creare un account e un progetto Jira

1. Vai su id.atlassian.com/signup, crea il tuo account e verificalo.
2. Aggiungi Jira alle tue app Atlassian (il piano gratuito è sufficiente per iniziare).
3. Configura il tuo primo progetto e crea ticket come nell’esempio seguente.

Bacheca di esempio con issue Jira

Passaggio 1 - Token di autenticazione dell’API di Jira

Vai su id.atlassian.com/manage-profile/security/api-tokens e crea il tuo token API, che avrà un aspetto simile a questo:

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

Per usare il token API Atlassian nelle azioni AI di Quickchat, devi codificarlo in base64 insieme al tuo indirizzo email:

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

Assicurati di includere l’indirizzo email esatto usato per creare il tuo account Atlassian

Puoi usare un semplice strumento online come base64encode.org.

Assicurati di usare Live mode, che garantisce che la codifica avvenga interamente nel browser.

Puoi usare uno strumento online gratuito per codificare il tuo token API

In alternativa, ecco come farlo sul tuo computer con un semplice 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}")

Lo script precedente fornisce un header pronto all’uso con il token codificato, simile a questo:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Passaggio 2 - Creare un’azione Quickchat AI

Nell’app Quickchat AI, vai in Azioni e MCP e aggiungi un’azione:

Pagina dell’azione AI

Assegna un nome adeguato alla tua azione AI:

Nome: Search Jira issues

Inserisci il nome dell’azione AI

Passaggio 3 - Impostare i parametri di ingresso

Il compito principale del tuo agente AI sarà tradurre la domanda dell’utente in una query precisa da usare per cercare nelle issue Jira. Per la ricerca di issue, Jira è recentemente passato completamente a JQL (Jira Query Language), che permette ricerche più complesse. Questo rende il tuo agente AI molto più potente. Configura i parametri di ingresso come segue:

Formato	Nome	Descrizione	Valore predefinito	Obbligatorio
Text	jql	(vedi sotto)	-	✅

Per ottenere ottime prestazioni dal tuo agente AI, una descrizione ben formulata è fondamentale:

Descrizione:

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"`.

Una descrizione ben formulata del parametro è essenziale per le prestazioni dell’agente AI

Una nota sugli stati di Jira

Jira distingue il nome di uno stato dalla sua categoria e JQL li tratta diversamente:

• Il nome dello stato è quello visualizzato nella bacheca. Un progetto usa To Do / In Progress / Done, un altro Open / In Review / Closed.
• La categoria dello stato è una delle tre categorie fisse a cui corrisponde ogni stato: To Do, In Progress, Done.

status = "To Do" filtra per nome, quindi non restituisce nulla in una bacheca la cui prima colonna si chiama Open. Questo è un motivo comune per cui un agente afferma con sicurezza che “non ci sono ticket da svolgere” mentre la bacheca ne è piena. Per domande come “cosa non è ancora iniziato”, “cosa è in corso” e “cosa è completato”, filtra invece per categoria:

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

Mantieni status = "..." quando l’utente indica uno stato specifico che sai essere presente nella bacheca. Puoi anche elencare i nomi effettivi degli stati della bacheca nella descrizione dell’azione (passaggio 7), così l’agente associa una richiesta come “pronto per il controllo qualità” allo stato corretto.

Passaggio 4 - Impostare l’URL dell’endpoint API

1. Seleziona GET come metodo della richiesta API
2. Imposta l’URL dell’endpoint sull’endpoint Jira /rest/api/3/search/jql

Imposta l’URL del tuo endpoint API

Assicurati di usare il nome del tuo dominio Atlassian. Lo trovi nell’URL della tua bacheca Jira.

Il nome del tuo dominio Atlassian

Passaggio 5 - Impostare gli header della richiesta API

Definisci gli header della richiesta API come segue:

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

Presta particolare attenzione al formato dell’header Authorization: Basic <base64-encoded email:api token>

Imposta gli header della richiesta API

Passaggio 6 - Impostare i parametri di query della richiesta API

Imposta due parametri di query per la richiesta AI:

• jql riceve un valore dinamico definito in precedenza nella sezione Cosa chiedere prima all’utente. È compito dell’agente AI compilare il valore di questo parametro in base a ciò che l’utente ha detto nella conversazione.
• fields riceve un valore fisso. Per ogni issue Jira ci interessano soltanto summary, description e status.

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

Imposta i parametri di query della richiesta API

Assicurati che il parametro jql punti correttamente al valore definito in precedenza. Puoi selezionarlo dal menu a discesa Aggiungi dati AI.

Seleziona il parametro dinamico jql dal menu a discesa

Passaggio 7 - Impostare la descrizione dell’azione API

L’ultimo ingrediente essenziale di un’azione AI ben configurata è la sua descrizione. Anche se l’agente AI comprende bene il tuo endpoint API già dall’URL e dai parametri, è fondamentale ottimizzare il suo comportamento per il tuo caso d’uso.

I tre aspetti più importanti inclusi nel prompt sono:

• quando richiamare l’azione: elencare tutte le formulazioni che l’utente potrebbe scegliere (trova / cerca / ricerca, ma anche spiega / parlami di / descrivi / cos’è / qual è lo stato di), così l’agente non salta la chiamata quando l’utente non dice “cerca”
• suggerimenti su come usare la sintassi JQL avanzata per cercare issue Jira
• come gestire i risultati vuoti: l’agente deve comunicarlo esplicitamente anziché negare di avere accesso

Ecco la descrizione dell’azione API risultante:

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.

Passaggio 8 - Provare l’azione API

Prima di provare l’azione AI in una conversazione, possiamo verificare come viene chiamata l’API nella scheda Testa risposta. Facciamo una prima prova con la seguente query, che dovrebbe restituire tutte le issue del progetto: project = "Solar System"

Ricerca di tutte le issue del progetto Solar System

Di seguito trovi la risposta al test. Come previsto, elenca i campi summary, description e status per tutte e 6 le issue della nostra bacheca Jira.

La risposta elenca tutte le issue del progetto Solar System

Proviamo un’altra query. Questa volta cerchiamo tutte le issue che menzionano “mercury”: text ~ "mercury"

Ricerca di issue che menzionano mercury

Abbiamo verificato che l’azione AI chiama correttamente il nostro endpoint API. Ora possiamo provare conversazioni complete con l’agente AI!

Passaggio 9 - Provare l’agente AI nelle conversazioni

Torna nell’app Quickchat AI e prova il tuo agente AI nell’anteprima della conversazione.

Conversazione n. 1

L’agente AI fornisce un riepilogo di tutte le issue del progetto

In questa semplice conversazione, l’agente AI offre una panoramica di tutte le issue del progetto. Esaminando ciò che accade dietro le quinte, vediamo che la query esatta eseguita sull’endpoint API era: project = "Solar System"

Conversazione n. 2

L’agente AI risponde a domande su issue e stati specifici

In questo caso, all’agente AI sono stati chiesti due aspetti distinti: una issue specifica e le issue in corso in generale. Esaminando ciò che accade dietro le quinte, vediamo che ha deciso di usare l’API di Jira in due passaggi:

1. Verificare se pluto è in corso:

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

2. Verificare cos’altro è in corso:

status = "In Progress"

Conversazione n. 3

L’agente AI risponde a una richiesta creativa 😉

In questo caso volevo mettere alla prova l’agente AI e gli ho posto una domanda che richiede una certa creatività per essere interpretata correttamente. Ecco come l’ha tradotta in una query JQL:

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

Prova queste formulazioni

Per verificare che l’azione AI venga richiamata indipendentemente da come gli utenti formulano la richiesta, prova ciascuno dei prompt seguenti nel tuo scenario di test. L’agente dovrebbe interrogare Jira per tutti, non soltanto per quelli formulati come una ricerca:

• “trova tutte le issue aperte sui risultati in tempo reale”
• “cerca issue con mercury”
• “spiega il progetto Solar System”
• “parlami delle issue aperte in questo sprint”
• “descrivi cosa è attualmente in corso”
• “qual è lo stato di pluto?”

Se una di queste formulazioni non richiama l’azione AI, controlla che la descrizione dell’azione API (passaggio 7) elenchi esplicitamente quei verbi.

Cosa aspettarsi quando Jira non trova issue corrispondenti

Quando Jira restituisce zero risultati, il tuo agente AI dovrebbe comunicarlo esplicitamente, ad esempio: “Ho controllato Jira e non ho trovato issue corrispondenti alla tua query. Prova una formulazione più ampia o rimuovi il filtro sullo stato.”

Se invece l’agente risponde “Non ho accesso diretto al tuo Jira”, l’azione AI non è stata richiamata. Ricontrolla la descrizione del passaggio 7 e verifica che elenchi esplicitamente i verbi che non indicano una ricerca (explain, tell me about, describe, what is).

Riepilogo

In questo articolo abbiamo mostrato come configurare un agente AI per usare uno specifico endpoint API in modo creativo nelle conversazioni. La configurazione corretta non è già pronta: richiede informazioni aggiuntive dettagliate sul caso d’uso che abbiamo in mente. Puoi riutilizzare i prompt e le descrizioni di questo articolo per creare agenti AI simili!

Preferisci una guida narrata più estesa? La stessa configurazione è descritta anche in un articolo del blog su quickchat.ai. Questa pagina della documentazione è il riferimento ufficiale, aggiornato costantemente.

Per approfondire

Un’azione Jira non deve limitarsi a un’unica richiesta fissa. Puoi inserire variabili di conversazione predefinite e metadati salvati (come la lingua del visitatore o valori acquisiti in precedenza nella conversazione) in qualsiasi campo e aggiungere più azioni affinché l’agente scelga quella adatta a ogni domanda. Consulta il riferimento delle azioni per tutte le opzioni.

🎁  BONUS

Questo articolo è stato scritto da un essere umano (il sottoscritto), ma avrebbe potuto essere scritto altrettanto bene dall’AI. Ad esempio, incollando in ChatGPT un prompt come questo:

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)

In futuro, invece di cercare nei ticket Jira, potresti voler:

• inviare messaggi a un canale Slack?
• recuperare informazioni da una pagina Notion?
• eseguire un’azione tramite Zapier?

Indicalo nella prima frase ed esegui di nuovo il prompt! Otterrai istruzioni valide per aggiungere esattamente l’azione AI di cui hai bisogno!