Jira

En este artículo, te mostraré cómo conectar tu AI Agent con Jira. Usaremos:

• una cuenta de Jira (gratuita)
• un AI Agent de Quickchat (regístrate aquí y úsalo gratis)

Esto permitirá que tu AI Agent de Quickchat:

• pueda buscar en tus tickets de Jira, y
• sea inteligente al responder preguntas basadas en ellos

Usaremos las AI Actions de Quickchat (acciones HTTP personalizadas) para que tu Agente llame al endpoint Enhanced search for issues de la API de Jira (Atlassian).

Crea un AI Agent creativo interpretando las entradas del usuario

Ver el video

Play

Cómo funciona

Así funcionará tu AI Agent durante las conversaciones:

1. El usuario hace una pregunta como “¿qué pasa con los issues sobre mercurio?”
2. El AI Agent recupera información relevante de la API de Jira usando una consulta como “mercury”
3. El AI Agent responde al usuario basándose en la información obtenida de la API

Sigue los pasos a continuación. ¡Toda la configuración no debería tomar más de 10 minutos!

Paso 0 - crear una cuenta y proyecto en Jira

1. Ve a id.atlassian.com/signup, crea y verifica tu cuenta.
2. Añade Jira a tus aplicaciones de Atlassian (el plan gratuito es suficiente para empezar).
3. Configura tu primer proyecto y crea tickets como en el ejemplo siguiente.

Tablero de ejemplo con issues de Jira

Paso 1 - token de autenticación de la API de Jira

Ve a id.atlassian.com/manage-profile/security/api-tokens y crea tu token de API, que se verá así:

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

Para poder usar tu token de API de Atlassian en Quickchat AI Actions, debes codificarlo en base64 junto con tu dirección de correo electrónico:

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

Asegúrate de incluir la misma dirección de correo que usaste para crear tu cuenta de Atlassian.

Puedes usar una herramienta en línea como base64encode.org.

Asegúrate de usar el Live mode, que garantiza que la codificación se realiza completamente en tu navegador.

Puedes usar una herramienta gratuita en línea para codificar tu token de API

Alternativamente, así puedes hacerlo en tu máquina con un sencillo script de 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}")

El script anterior te dará un header listo para usar con el token codificado, que se ve así:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Paso 2 - crear una AI Action de Quickchat

En la app de Quickchat AI, ve a Actions & MCPs y agrega una acción:

Página de AI Action

Ponle a tu AI Action un nombre apropiado:

Nombre: Search Jira issues

Inserta el nombre de la AI Action

Paso 3 - configurar parámetros de entrada

La tarea principal de tu AI Agent será traducir lo que el usuario pregunta en una consulta exacta para buscar en los issues de Jira. Para la búsqueda de issues, Jira ha migrado completamente a JQL (Jira Query Language) para permitir búsquedas más complejas. Esto hace que tu AI Agent sea mucho más potente. Configura tus parámetros de entrada así:

Formato	Nombre	Descripción	Valor por defecto	Requerido
Text	jql	(ver abajo)	-	✅

Para lograr un gran rendimiento con tu AI Agent, una descripción bien elaborada es muy importante:

Descripción:

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

Una descripción bien redactada es clave para el rendimiento del AI Agent

Paso 4 - configurar la URL del endpoint de la API

1. Selecciona GET como tipo de acción
2. Establece la URL del endpoint al de Jira /rest/api/3/search/jql

Configura la URL del endpoint de la API

Asegúrate de usar tu dominio de Atlassian. Lo encontrarás en la URL de tu tablero de Jira.

Tu dominio de Atlassian

Paso 5 - configurar los headers de la solicitud API

Define tus headers de la solicitud API así:

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

Presta especial atención a formatear correctamente tu header Authorization: Basic <base64-encoded email:api token>

Configura los headers de la solicitud API

Paso 6 - configurar los parámetros de consulta de la solicitud API

Configura dos parámetros de consulta para tu solicitud de IA:

• jql toma un valor dinámico definido antes en la sección What to ask the user first. Es trabajo del AI Agent completar el valor de este parámetro basándose en lo que dijo el usuario en la conversación.
• fields toma un valor fijo. Para cada issue de Jira, solo nos interesan su summary, description y status.

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

Configura los parámetros de consulta de la solicitud API

Asegúrate de que el parámetro jql apunte correctamente al valor definido antes. Puedes seleccionarlo desde el menú desplegable Add AI Data.

Selecciona el parámetro dinámico jql del menú desplegable

Paso 7 - configurar la descripción de la API Action

El ingrediente final crucial de una AI Action bien configurada es su descripción. Aunque el AI Agent comprende bien tu endpoint de API por su URL y parámetros, es clave optimizar su comportamiento para tu caso de uso.

Los dos aspectos más importantes incluidos en el prompt son:

• sugerencias sobre cómo usar la sintaxis avanzada de JQL al buscar issues de Jira
• la necesidad de realizar búsquedas amplias para evitar volver al usuario con resultados vacíos

Aquí está la descripción de la API Action resultante:

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 descripción debe indicar con precisión cómo se debe usar la solicitud de API

Paso 8 - probar la API Action

Antes de probar la AI Action en conversación, podemos probar cómo se llama a la API en la pestaña Test Response. Hagamos una primera prueba con la siguiente consulta, que debería devolver todos los issues del proyecto: project = "Solar System"

Buscando todos los issues en el proyecto Solar System

A continuación se muestra la respuesta de la prueba. Como era de esperar, enumera los campos summary, description y status de los 6 issues en nuestro tablero de Jira.

La respuesta enumera todos los issues del proyecto Solar System

Probemos una consulta más. Esta vez busquemos todos los issues que mencionan “mercury”: text ~ "mercury"

Buscando issues que mencionan mercury

Ya validamos que la AI Action llama correctamente a nuestro endpoint de API. ¡Ahora podemos pasar a probar conversaciones completas con el AI Agent!

Paso 9 - probar el AI Agent en conversaciones

Vuelve a la app de Quickchat AI y prueba tu AI Agent en la vista previa de conversación.

Conversación #1

El AI Agent da un resumen de todos los issues dentro del proyecto

En esta conversación simple, el AI Agent da una visión general de todos los issues del proyecto. Mirando detrás de escena, la consulta exacta que ejecutó contra el endpoint de la API fue: project = "Solar System"

Conversación #2

El AI Agent responde preguntas sobre issues específicos y estados

En este caso, se le preguntó al AI Agent sobre dos aspectos: un issue específico y los issues en curso en general. Mirando detrás de escena, decidió usar la API de Jira en un proceso de dos pasos:

1. Verificar si pluto está en curso:

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

2. Ver qué más está en curso:

status = "In Progress"

Conversación #3

El AI Agent responde a una consulta creativa 😉

En este caso, quise poner a prueba al AI Agent y le hice una pregunta que requiere algo de creatividad para interpretarse correctamente. Así se tradujo en una consulta JQL:

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

Resumen

En este artículo, mostramos cómo se puede configurar un AI Agent para usar un endpoint de API específico de forma creativa en conversaciones. La configuración correcta no viene de fábrica: requiere proporcionar información adicional detallada del caso de uso específico que tenemos en mente. ¡No dudes en reutilizar los prompts y descripciones mostrados en este artículo para crear tus propios AI Agents similares!

🎁  BONUS

El artículo anterior fue escrito por un humano (un servidor), pero podría haber sido escrito por IA. Por ejemplo, pegando un prompt como este en 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)

En el futuro, quizá en lugar de buscar en tickets de Jira te gustaría:

• ¿enviar mensajes a un canal de Slack?
• ¿obtener información de una página de Notion?
• ¿realizar una acción a través de Zapier?

¡Dilo en la primera frase y vuelve a ejecutar el prompt! ¡Obtendrás instrucciones perfectas para agregar exactamente la AI Action que necesitas!