Jira

Neste artigo, vou mostrar como conectar seu AI Agent ao Jira. Usaremos:

• uma conta Jira (gratuita)
• um AI Agent da Quickchat (cadastre-se aqui e use gratuitamente)

Isso permitirá que seu AI Agent da Quickchat:

• pesquise nos seus tickets do Jira, e
• seja inteligente ao responder perguntas com base neles

Usaremos as AI Actions da Quickchat (ações HTTP personalizadas) para permitir que seu Agente chame o endpoint Enhanced search for issues da API do Jira (Atlassian).

Crie um AI Agent criativo ao interpretar entradas do usuário

Assista ao vídeo

Play

Como funciona

Veja como seu AI Agent operará durante as conversas:

1. O usuário faz uma pergunta como “o que há com os issues sobre mercúrio?”
2. O AI Agent busca informações relevantes na API do Jira usando uma consulta como “mercury”
3. O AI Agent responde ao usuário com base nas informações obtidas da API

Siga os passos abaixo. Toda a configuração não deve levar mais do que 10 minutos!

Passo 0 - criar uma conta e um projeto no Jira

1. Acesse id.atlassian.com/signup, crie e verifique sua conta.
2. Adicione o Jira aos seus apps Atlassian (o plano gratuito é suficiente para começar).
3. Configure seu primeiro projeto e crie tickets como no exemplo abaixo.

Quadro de exemplo com issues do Jira

Passo 1 - token de autenticação da API do Jira

Acesse id.atlassian.com/manage-profile/security/api-tokens e crie seu token de API, que será algo assim:

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

Para poder usar seu token de API Atlassian nas AI Actions da Quickchat, você precisa codificá-lo em base64 junto com seu e‑mail:

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

Certifique-se de incluir o mesmo endereço de e‑mail usado para criar sua conta Atlassian.

Você pode usar uma ferramenta online simples como base64encode.org.

Use o Live mode, que garante que a codificação aconteça inteiramente no seu navegador.

Ferramenta online gratuita para codificar seu token de API

Como alternativa, veja como fazer isso localmente com um script Python simples:

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

O script acima retornará um header pronto para uso com o token codificado, parecido com isto:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Passo 2 - criar uma AI Action da Quickchat

No aplicativo Quickchat AI, vá em Actions & MCPs e adicione uma ação:

Página da AI Action

Dê um nome apropriado à sua AI Action:

Name: Search Jira issues

Insira o nome da AI Action

Passo 3 - definir os parâmetros de entrada

A principal tarefa do seu AI Agent será traduzir o que o usuário está pedindo em uma consulta exata para pesquisar issues no Jira. Para pesquisa de issues, o Jira migrou totalmente para JQL (Jira Query Language), permitindo pesquisas mais complexas. Isso torna seu AI Agent muito mais poderoso. Defina os parâmetros de entrada assim:

Formato	Nome	Descrição	Valor padrão	Obrigatório
Text	jql	(ver abaixo)	-	✅

Para obter um ótimo desempenho do seu AI Agent, uma descrição bem elaborada é fundamental:

Descrição:

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

Uma descrição bem feita é a chave para o desempenho do AI Agent

Passo 4 - definir a URL do endpoint da API

1. Selecione GET como o tipo da ação
2. Defina a URL do endpoint para /rest/api/3/search/jql do Jira

Defina a URL do endpoint da API

Certifique-se de usar seu domínio Atlassian. Você o encontrará na URL do seu quadro do Jira.

Seu domínio Atlassian

Passo 5 - definir os headers da requisição API

Defina os headers da sua requisição API da seguinte forma:

Accept	Autorization
application/json	Basic cGlvdHJAcXVpY2tjaGF0LmFpOkFUQVRUM3hGZkdGMGlQOVNacEhVZ1o5YUJfWGhmQjZJWjJId3MyaHlsMzEtTlNpYW90Z2tZVzRxQXEwQ3R4UVY1OXFTZkpWWVZNcXlxem42MWRkR0VobmJWNzdzaWtrb19ZWkhtLUgwazFOZGh4WlpQMnltYmZ1SzhBRmlFMnJEUmdqd182N1hkSFFUelFQY2I2U1lrNUFPRlRuVnZvaGxkZUd3djVpM2VrcEFyMVJ4QnJWRncyYz04MEZGQTcyMA==

Preste muita atenção ao formato correto do header Authorization: Basic <base64-encoded email:api token>

Defina os headers da requisição API

Passo 6 - definir os parâmetros de consulta (query params)

Defina dois parâmetros de consulta para sua requisição de IA:

• jql recebe um valor dinâmico definido anteriormente na seção What to ask the user first. É tarefa do AI Agent preencher o valor deste parâmetro com base no que o usuário disse.
• fields recebe um valor fixo. Para cada issue do Jira, nos interessam apenas summary, description e status.

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

Defina os parâmetros de consulta da requisição API

Garanta que o parâmetro jql aponte corretamente para o valor definido anteriormente. Você pode selecioná-lo no menu suspenso Add AI Data.

Selecione o parâmetro dinâmico jql no menu

Passo 7 - definir a descrição da API Action

O ingrediente final crucial de uma AI Action bem configurada é sua descrição. Embora o AI Agent já compreenda bem seu endpoint de API a partir da URL e dos parâmetros, é fundamental otimizar seu comportamento para o seu caso de uso.

Os dois aspectos mais importantes incluídos no prompt são:

• sugestões de como usar a sintaxe avançada do JQL ao pesquisar issues do Jira
• a necessidade de fazer buscas amplas para evitar retornar resultados vazios ao usuário

Aqui está a descrição da 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")`.

A descrição deve especificar com precisão como usar a requisição API

Passo 8 - testar a API Action

Antes de testarmos a AI Action em conversa, podemos testar como a API é chamada na aba Test Response. Vamos fazer um primeiro teste com a consulta a seguir, que deve retornar todos os issues do projeto: project = "Solar System"

Buscando todos os issues do projeto Solar System

Abaixo está a resposta do teste. Como esperado, lista os campos summary, description e status para todos os 6 issues do nosso quadro do Jira.

A resposta lista todos os issues do projeto Solar System

Vamos tentar outra consulta. Desta vez, pesquise todos os issues que mencionam “mercury”: text ~ "mercury"

Pesquisando issues que mencionam mercury

Agora validamos que a AI Action chama corretamente nosso endpoint de API. Podemos seguir para testar conversas completas com o AI Agent!

Passo 9 - testar o AI Agent em conversas

Volte ao aplicativo Quickchat AI e teste seu AI Agent na prévia de conversa.

Conversa #1

O AI Agent apresenta um resumo de todos os issues do projeto

Nesta conversa simples, o AI Agent fornece uma visão geral de todos os issues do projeto. Por trás dos panos, a consulta exata executada no endpoint da API foi: project = "Solar System"

Conversa #2

O AI Agent responde perguntas sobre issues específicos e status

Neste caso, o AI Agent foi questionado sobre dois aspectos: um issue específico e issues em andamento de modo geral. Por trás dos panos, ele decidiu usar a API do Jira em um processo de duas etapas:

1. Verificar se pluto está em andamento:

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

2. Ver o que mais está em andamento:

status = "In Progress"

Conversa #3

O AI Agent responde a uma consulta criativa 😉

Neste caso, quis desafiar o AI Agent e fiz uma pergunta que exige certa criatividade para ser interpretada corretamente. Veja como foi traduzida para uma consulta JQL:

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

Resumo

Neste artigo, mostramos como configurar um AI Agent para usar de forma criativa um endpoint de API específico em conversas. A configuração correta não vem pronta: exige fornecer informações extras detalhadas do caso de uso específico. Sinta-se à vontade para reutilizar os prompts e descrições mostrados neste artigo ao criar seus próprios AI Agents semelhantes!

🎁  BÔNUS

O artigo acima foi escrito por um humano (este que vos fala), mas poderia ter sido escrito por IA. Por exemplo, colando um prompt como este no 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)

No futuro, talvez em vez de pesquisar tickets do Jira você queira:

• enviar mensagens para um canal do Slack?
• obter informações de uma página do Notion?
• executar uma ação via Zapier?

Diga isso na primeira frase e rode o prompt novamente! Você obterá instruções perfeitas para adicionar exatamente a AI Action de que precisa!