Conecte um AI Agent aos tickets do Jira

Introdução

Neste post do blog, vou mostrar como conectar seu AI Agent ao Jira. Usaremos:

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

Procurando a referência canônica, atualizada continuamente? O mesmo passo a passo está na nossa documentação em docs.quickchat.ai/channels/jira. Este post é a versão longa e narrada.

Isso permitirá que seu Quickchat AI Agent:

• consiga pesquisar 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 Agent chame o endpoint Enhanced search for issues da API do Jira (Atlassian).

Crie um AI Agent criativo para interpretar entradas de usuários

Assista ao vídeo

Como funciona

Veja como seu AI Agent operará durante as conversas:

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

Siga as etapas abaixo. Toda a configuração não deve levar mais de 10 minutos!

Etapa 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 da Atlassian (o plano gratuito será suficiente para começar).
3. Configure seu primeiro projeto e crie tickets como no exemplo abaixo.

Quadro de exemplo com issues do Jira

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

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

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

Para poder usar seu token de API da Atlassian nas Quickchat AI Actions, você precisa codificá-lo em base64 junto com seu endereço de email:

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

Certifique-se de incluir o endereço de email exato que você usou para configurar sua conta Atlassian

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

Certifique-se de usar o Live mode, que garante que a codificação aconteça inteiramente no seu navegador.

Você pode usar uma ferramenta online gratuita para codificar seu API token

Como alternativa, veja como fazer isso na sua máquina em 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 fornecerá um header pronto para uso com o token codificado, parecido com isto:

Basic eW91cl9lbWFpbEBleGFtcGxlLmNvbTpBVEFUVDN4RmZHRjAxc0tVbDBIRVcyLV8tdTl1bWZMU3o3amVibG1lTHpFSFoxRExjZExiS2VWRjEzN2lUSEdrS2hQdU5NU0tYOG1rYndMcEhYVDQtcVhFbi14TkVuZmlLOF9YRFZXNlhYdkdkX1NCVjNIRDRrSkluR05qZmcyX3lFb0pGTjZ1d3k0TlJxZXVoVjJ0am15enhvekxCUm4zNU9oWGtEQTZRR2ZMRnZmMl9QS3VOdEE9OERBNzA0RTQ=

Etapa 2 - criar uma Quickchat AI Action

No app da Quickchat AI, vá para Actions & MCPs e adicione uma ação:

Página AI Action

Dê à sua AI Action um nome apropriado:

Nome: Search Jira issues

Insira o nome da AI Action

Etapa 3 - definir parâmetros de entrada

A principal tarefa do seu AI Agent será traduzir o que o usuário está perguntando em uma consulta exata a ser usada para pesquisar issues do Jira. Quanto à pesquisa de issues, o Jira migrou recentemente por completo para JQL (Jira Query Language) para permitir pesquisas mais complexas. Isso permite que seu AI Agent seja muito mais poderoso. Configure seus parâmetros de entrada da seguinte forma:

Para obter excelente desempenho com seu AI Agent, uma descrição bem elaborada é extremamente importante:

Descrição:

Uma única string JQL (Jira Query Language) válida criada conforme a descrição. Priorize recall: prefira `(text ~ "term1" OR text ~ "term2")` em vez de encadear com AND, e use parênteses para agrupamento. Para perguntas de "not started / in progress / done", filtre por `statusCategory` ("To Do", "In Progress", "Done"), que é estável entre projetos. Use `status = "..."` apenas quando o usuário mencionar um status específico que exista no quadro. Evite campos personalizados. Exemplos: `statusCategory = "In Progress" AND (text ~ "mercury" OR text ~ "venus")`, `(text ~ "planet*" OR text ~ "integration")`, `project = "Solar System" AND statusCategory = "To Do"`.

Uma descrição de parâmetro bem elaborada é essencial para o desempenho do AI Agent

Uma observação sobre status no Jira

O Jira separa o nome de um status da sua categoria, e a JQL trata esses elementos de forma diferente:

• O nome do status é o que o quadro mostra. Um projeto usa To Do / In Progress / Done, outro usa Open / In Review / Closed.
• A categoria do status é um de três grupos fixos aos quais todo status é mapeado: To Do, In Progress, Done.

status = "To Do" filtra por nome, portanto não retorna nada em um quadro cuja primeira coluna se chama Open. Esse é um motivo comum para um agente informar com confiança “não há tickets a fazer” enquanto o quadro está cheio deles. Para perguntas sobre “o que ainda não começou”, “o que está em andamento” e “o que foi concluído”, filtre pela categoria:

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

Mantenha status = "..." para quando o usuário mencionar um status específico que você sabe que existe no quadro. Você também pode listar os nomes reais dos status do seu quadro na descrição da Action (Etapa 7), para que o agente mapeie uma solicitação como “pronto para QA” para o status correto.

Etapa 4 - definir a URL do endpoint da API

1. Selecione GET como Action Type
2. Defina a URL do endpoint para o endpoint /rest/api/3/search/jql do Jira

Defina a URL do endpoint da API

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

Seu nome de domínio Atlassian

Etapa 5 - definir headers da requisição da API

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

Preste atenção especial à formatação correta do seu header Authorization: Basic <email:api token codificado em base64>

Defina os headers da sua requisição da API

Etapa 6 - definir parâmetros de consulta da requisição da API

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. É trabalho do AI Agent preencher o valor desse parâmetro com base no que o usuário disse na conversa.
• fields recebe um valor fixo. Para cada issue do Jira, estamos interessados apenas em summary, description e status.

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

Certifique-se de 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 suspenso

Etapa 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 tenha uma boa compreensão do seu endpoint de API apenas pela URL e pelos parâmetros, é essencial otimizar seu comportamento para o seu caso de uso.

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

• quando invocar a ação, listando todas as formulações que o usuário pode escolher (encontrar / pesquisar / procurar, bem como explicar / conte-me sobre / descrever / o que é / como está o status de), para que o agente não pule a chamada quando o usuário não disser “pesquisar”
• sugestões sobre como usar a sintaxe JQL avançada ao pesquisar issues do Jira
• como lidar com resultados vazios, o agente deve dizer isso explicitamente em vez de recusar acesso

Aqui está a Descrição da API Action resultante:

Use esta ação sempre que o usuário perguntar qualquer coisa que possa ser respondida por dados no Jira dele: projetos, issues, status, sprints, ciclos de teste, descrições, responsáveis, comentários, independentemente de como ele formule a solicitação (encontrar / pesquisar / procurar / explicar / conte-me sobre / descrever / o que é / como está o status de etc.). Não recuse acesso. Consulte o Jira primeiro.

Construa uma JQL que priorize recall em vez de precisão: prefira `(text ~ "term1" OR text ~ "term2")` em vez de encadear com AND, e use parênteses para agrupamento. Para perguntas de ciclo de vida (não iniciado, em andamento, concluído), filtre por `statusCategory` ("To Do" / "In Progress" / "Done") em vez de `status`, porque os nomes de status variam por quadro. Use `status = "..."` apenas quando o usuário mencionar um status específico. Evite campos personalizados.

Se o Jira não retornar correspondências, diga isso explicitamente ao usuário e sugira uma consulta refinada.

Etapa 8 - testar a API Action

Antes de testarmos a AI Action em uma conversa, podemos testar como a própria API está sendo chamada na aba Test Response. Vamos fazer um primeiro teste com a seguinte consulta, que deve retornar todas as issues do projeto: project = "Solar System"

Pesquisando todas as issues no projeto Solar System

Abaixo está a resposta de teste que recebemos. Como esperado, ela lista os campos de resumo, descrição e status para todas as 6 issues no nosso quadro do Jira.

A resposta lista todas as issues no projeto Solar System

Vamos tentar mais uma consulta. Desta vez, vamos pesquisar todas as issues que mencionam “mercúrio”: text ~ "mercury"

Pesquisando issues que mencionam mercury

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

Etapa 9 - testar o AI Agent em conversas

Volte para o app da Quickchat AI e teste seu AI Agent na prévia de conversa.

Conversa #1

AI Agent fornece um resumo de todas as issues dentro do projeto

Nesta conversa simples, o AI Agent fornece uma visão geral de todas as issues dentro do projeto. Uma análise dos bastidores nos mostra que a consulta exata executada contra o endpoint da API foi: project = "Solar System"

Conversa #2

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

Neste caso, o AI Agent recebeu uma pergunta sobre dois aspectos separados: uma issue específica e issues em andamento em geral. Uma análise dos bastidores nos mostra que 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. Verificar o que mais está em andamento:

status = "In Progress"

Conversa #3

AI Agent responde a uma consulta criativa 😉

Neste caso, eu quis lançar uma pergunta difícil para o AI Agent e fiz uma pergunta que exige alguma criatividade para interpretar corretamente. Veja como ela foi traduzida em uma consulta JQL:

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

Experimente estas formulações

Para ter confiança de que a AI Action dispara independentemente de como seus usuários finais formulem a solicitação, execute cada um dos prompts abaixo no seu cenário de teste. O agente deve consultar o Jira em todos eles, não apenas nos de estilo de pesquisa:

• “encontre todas as issues abertas sobre pontuações ao vivo”
• “pesquise issues com mercury”
• “explique o projeto Solar System”
• “conte-me sobre as issues abertas neste sprint”
• “descreva o que está atualmente em andamento”
• “qual é o status de pluto?”

Se alguma dessas formulações não invocar a AI Action, verifique novamente se a descrição da sua API Action (Etapa 7) lista esses verbos explicitamente.

O que esperar quando o Jira não tiver issues correspondentes. Quando o Jira retorna zero resultados, seu AI Agent deve dizer isso explicitamente, por exemplo, “Verifiquei o Jira e não encontrei issues correspondentes à sua consulta. Tente uma formulação mais ampla ou remova o filtro de status.” Se, em vez disso, você vir o agente responder com “Não tenho acesso direto ao seu Jira”, a AI Action não foi disparada. Verifique novamente a descrição da Etapa 7 e confirme que ela lista explicitamente verbos que não são de pesquisa (explain, tell me about, describe, what is).

Resumo

Neste post do blog, mostramos como um AI Agent pode ser configurado para usar um endpoint de API específico de forma criativa em conversas. A configuração correta não vem pronta, ela exige fornecer informações extras detalhadas sobre o caso de uso específico que temos em mente. Fique à vontade para reutilizar os prompts e descrições mostrados neste post para criar seus próprios AI Agents semelhantes. Para outro exemplo completo no mesmo estilo passo a passo, veja como conectar seu AI Agent ao Google Sheets e registrar leads, perguntas sem resposta e solicitações de demo em uma planilha.

Quer manter este guia salvo nos favoritos? A versão canônica, atualizada continuamente, deste passo a passo está na nossa documentação em docs.quickchat.ai/channels/jira, acesse para copiar e colar a descrição mais recente da API Action e acompanhar atualizações da receita.

Indo além

Uma ação do Jira não precisa ser uma única requisição fixa. Você pode injetar variáveis de conversa integradas e metadados salvos (como o idioma do visitante ou valores capturados anteriormente na conversa) em qualquer campo, e pode adicionar várias ações para que o agente escolha a correta para cada pergunta. A referência de AI Actions cobre o conjunto completo de opções.

Guias relacionados

O mesmo mecanismo de AI Action conecta um agente a qualquer API HTTP. Outros passos a passo que o usam:

• Crie um bot de moderação de Discord com IA usando AI Actions personalizadas
• Conecte seu AI Agent à Telegram Bot API
• Conecte seu AI Agent ao Google Sheets
• Conecte seu AI Agent ao HubSpot para registrar contatos, negócios e tickets
• Envie notificações do Slack com AI Actions
• Conecte o Cal.com ao seu AI Agent em 5 minutos
• Como criar um AI Support Agent a partir da sua documentação
• AI Agent para suporte ao cliente em SaaS

BÔNUS

O post acima foi escrito por um humano (este que vos fala), mas poderia muito bem ter sido escrito por IA. Por exemplo, colando um prompt como este no ChatGPT:

Preciso de um endpoint de API que me permita pesquisar nos meus tickets do Jira.

Oriente-me pelo processo passo a passo para que seja acessível a uma pessoa moderadamente técnica:
- Forneça links para a documentação que descreve o endpoint
- Qualquer criação de conta e configuração inicial necessária
- Se alguma conta paga for necessária, indique isso claramente
- Se alguma autenticação, como API tokens, for necessária, oriente-me pelo processo de criação deles e mostre exatamente cada etapa necessária para poder usá-los como um header de requisição HTTP. Por exemplo, se a codificação em base64 for necessária, mostre um script ou outra forma de fazer isso.
- Mostre exatamente quais chaves e valores de header preciso para a requisição HTTP (mostre chaves e valores de header em uma tabela)
- Mostre exatamente quais parâmetros de payload preciso para a requisição HTTP (mostre o nome do parâmetro de payload e valores de exemplo em uma tabela)

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

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

Diga isso na primeira frase e execute o prompt novamente. Você obterá instruções perfeitamente boas para adicionar a AI Action exata de que precisa!