Conecta un Agente de IA a tickets de Jira

Introducción

En esta publicación de blog, te mostraré cómo conectar tu Agente de IA a Jira. Usaremos:

• una cuenta de Jira (gratis)
• un Agente de IA de Quickchat (regístrate aquí y úsalo gratis)

Buscas la referencia canónica y actualizada continuamente. El mismo recorrido está en nuestra documentación en docs.quickchat.ai/channels/jira. Esta publicación es la versión extensa y narrada.

Permitirá que tu Agente de IA de Quickchat:

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

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

Crea un Agente de IA creativo para interpretar entradas de usuario

Mira el video

Cómo funciona

Así operará tu Agente de IA durante las conversaciones:

1. El usuario hace una pregunta como “qué pasa con los issues relacionados con mercurio?”
2. El Agente de IA obtiene información relevante de la API de Jira usando una consulta como “mercurio”
3. El Agente de IA 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 tardar más de 10 minutos.

Paso 0 - crea una cuenta y un proyecto de Jira

1. Ve a id.atlassian.com/signup, crea y verifica tu cuenta.
2. Agrega Jira a tus apps de Atlassian (el plan gratuito será 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 API token, que se verá más o menos 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 dirección de correo electrónico exacta que usaste para configurar tu cuenta de Atlassian

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

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

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

Como alternativa, así puedes hacerlo en tu máquina con un script de python sencillo:

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 encabezado listo para usar con el token codificado, que se verá más o menos así:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Paso 2 - crea una Quickchat AI Action

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

Página de AI Action

Dale a tu AI Action un nombre adecuado:

Name: Search Jira issues

Inserta el nombre de la AI Action

Paso 3 - configura los parámetros de entrada

La tarea principal de tu Agente de IA será traducir lo que pregunta el usuario a una consulta exacta para buscar en los issues de Jira. En cuanto a la búsqueda de issues, Jira migró recientemente por completo a JQL (Jira Query Language) para permitir búsquedas más complejas. Esto permite que tu Agente de IA sea mucho más potente. Configura tus parámetros de entrada de la siguiente manera:

Para lograr un gran rendimiento con tu Agente de IA, 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, 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 descripción de parámetro bien elaborada es clave para el rendimiento del Agente de IA

Nota sobre los estados de Jira

Jira separa el nombre de un estado de su categoría, y JQL los trata de forma diferente:

• El nombre del estado es lo que muestra el tablero. Un proyecto usa To Do / In Progress / Done, otro usa Open / In Review / Closed.
• La categoría del estado es uno de tres grupos fijos a los que se asigna cada estado: To Do, In Progress, Done.

status = "To Do" filtra por nombre, por lo que no devuelve nada en un tablero cuya primera columna se llama Open. Esta es una razón común por la que un agente informa con seguridad que “no hay tickets por hacer” mientras el tablero está lleno de ellos. Para preguntas sobre “qué no ha empezado”, “qué está en curso” y “qué está hecho”, filtra por la categoría en su lugar:

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

Mantén status = "..." para cuando el usuario mencione un estado específico que sabes que existe en el tablero. También puedes listar los nombres reales de estados de tu tablero en la descripción de la Action (Paso 7) para que el agente asigne una solicitud como “listo para QA” al estado correcto.

Paso 4 - configura la URL del endpoint de la API

1. Selecciona GET como Action Type
2. Configura la URL del endpoint como el endpoint /rest/api/3/search/jql de Jira

Configura la URL de tu endpoint de la API

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

Tu nombre de dominio de Atlassian

Paso 5 - configura los encabezados de la solicitud de la API

Define los headers de tu solicitud de la API de la siguiente manera:

Presta especial atención a dar el formato correcto a tu encabezado Authorization: Basic <base64-encoded email:api token>

Configura los encabezados de tu solicitud de la API

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

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

• jql toma un valor dinámico definido anteriormente en la sección What to ask the user first. Es tarea del Agente de IA completar el valor de este parámetro basándose en lo que el usuario ha dicho en la conversación.
• fields toma un valor fijo. Para cada issue de Jira, solo nos interesan su resumen, descripción y estado.

Configura los parámetros de consulta de tu solicitud de la API

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

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

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

El ingrediente final y crucial de una AI Action bien configurada es su descripción. Aunque el Agente de IA entiende bien tu endpoint de API solo a partir de su URL y parámetros, es clave optimizar su comportamiento para tu caso de uso.

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

• cuándo invocar la acción: listar cada formulación que el usuario podría elegir (buscar / encontrar / revisar, así como explicar / háblame de / describir / qué es / cuál es el estado de) para que el agente no omita la llamada cuando el usuario no diga “buscar”
• sugerencias sobre cómo usar la sintaxis avanzada de JQL al buscar issues de Jira
• cómo gestionar resultados vacíos: el agente debe decirlo explícitamente en lugar de rechazar el acceso

Esta es la API Action Description resultante:

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.

Paso 8 - prueba la API Action

Antes de probar la AI Action en una conversación, podemos probar cómo se llama 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"

Búsqueda de todos los issues del proyecto Solar System

Abajo está la respuesta de prueba que obtenemos. Como era de esperar, lista los campos de resumen, descripción y estado para los 6 issues de nuestro tablero de Jira.

La respuesta lista todos los issues del proyecto Solar System

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

Búsqueda de 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 Agente de IA.

Paso 9 - prueba el Agente de IA en conversaciones

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

Conversación #1

El Agente de IA da un resumen de todos los issues dentro del proyecto

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

Conversación #2

El Agente de IA responde preguntas sobre issues y estados específicos

En este caso, se le preguntó al Agente de IA sobre dos aspectos separados: un issue específico e issues en curso en general. Al mirar detrás de escena, vemos que decidió usar la API de Jira en un proceso de dos pasos:

1. Comprobar si pluto está en curso:

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

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

status = "In Progress"

Conversación #3

El Agente de IA responde a una consulta creativa 😉

En este caso quise plantearle un reto al Agente de IA y le hice una pregunta que requiere algo de creatividad para interpretarse correctamente. Así fue como se tradujo a una consulta JQL:

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

Prueba estas formulaciones

Para asegurarte de que la AI Action se activa sin importar cómo formulen su solicitud tus usuarios finales, ejecuta cada uno de los prompts siguientes en tu escenario de prueba. El agente debería consultar Jira en todos ellos, no solo en los que tienen estilo de búsqueda:

• “encuentra todos los issues abiertos sobre resultados en vivo”
• “busca issues con mercury”
• “explica el proyecto Solar System”
• “háblame de los issues abiertos en este sprint”
• “describe qué está actualmente en curso”
• “cuál es el estado de pluto?”

Si alguna de estas formulaciones no invoca la AI Action, verifica de nuevo que la descripción de tu API Action (Paso 7) liste esos verbos explícitamente.

Qué esperar cuando Jira no tiene issues coincidentes. Cuando Jira devuelve cero resultados, tu Agente de IA debería decirlo explícitamente, por ejemplo, “Revisé Jira y no encontré issues coincidentes para tu consulta, prueba una formulación más amplia o elimina el filtro de estado.” Si en cambio ves que el agente responde “No tengo acceso directo a tu Jira”, la AI Action no se activó en absoluto. Revisa de nuevo la descripción del Paso 7 y confirma que liste explícitamente verbos que no son de búsqueda (explain, tell me about, describe, what is).

Resumen

En esta publicación de blog, mostramos cómo se puede configurar un Agente de IA para usar un endpoint de API específico de forma creativa en conversaciones. La configuración correcta no viene lista para usar: requiere proporcionar información adicional detallada del caso de uso específico que tenemos en mente. Puedes reutilizar los prompts y las descripciones mostrados en esta publicación para crear tus propios Agentes de IA similares. Para ver otro ejemplo completo con el mismo estilo paso a paso, consulta cómo conectar tu Agente de IA a Google Sheets y registrar leads, preguntas sin responder y solicitudes de demo en una hoja de cálculo.

Quieres guardar esta guía en marcadores. La versión canónica y actualizada continuamente de este recorrido está en nuestra documentación en docs.quickchat.ai/channels/jira. Ve allí para copiar y pegar la descripción más reciente de la API Action y seguir las actualizaciones de la receta.

Ir más allá

Una acción de Jira no tiene que ser una única solicitud fija. Puedes inyectar variables de conversación integradas y metadatos guardados (como el idioma del visitante o valores capturados antes en la conversación) en cualquier campo, y puedes agregar varias acciones para que el agente elija la correcta según la pregunta. La referencia de AI Actions cubre el conjunto completo de opciones.

Guías relacionadas

El mismo mecanismo de AI Action conecta un agente a cualquier API HTTP. Otros recorridos que lo usan:

• Crea un bot de moderación de Discord con IA usando AI Actions personalizadas
• Conecta tu Agente de IA a la API de Telegram Bot
• Conecta tu Agente de IA a Google Sheets
• Conecta tu Agente de IA a HubSpot para registrar contactos, negocios y tickets
• Envía notificaciones de Slack con AI Actions
• Conecta Cal.com a tu Agente de IA en 5 minutos
• Cómo crear un Agente de Soporte de IA a partir de tu documentación
• Agente de IA para soporte al cliente SaaS

BONUS

La publicación de blog anterior fue escrita por un humano (quien escribe), pero también podría haber sido escrita 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 quieras:

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

Indícalo en la primera oración y ejecuta el prompt de nuevo. Obtendrás instrucciones adecuadas para agregar la AI Action exacta que necesitas.