Integração com Jira

Visão Geral

Permita que seus agentes gerenciem problemas, projetos e fluxos de trabalho pelo Jira. Crie e atualize issues, acompanhe o progresso de projetos, gerencie atribuições e otimize sua gestão de projetos com automação potencializada por IA.

Pré-requisitos

Antes de usar a integração com o Jira, certifique-se de ter:

Uma conta CrewAI AMP com assinatura ativa
Uma conta Jira com permissões adequadas para o projeto
Sua conta Jira conectada pela Página de Integrações

Configurando a Integração com o Jira

1. Conectar Sua Conta Jira

Acesse Integrações CrewAI AMP
Encontre Jira na seção de Integrações de Autenticação
Clique em Conectar e complete o fluxo do OAuth
Conceda as permissões necessárias para gestão de issues e projetos
Copie seu Token Enterprise em Configurações de Integração

2. Instalar o Pacote Necessário

uv add crewai-tools

Ações Disponíveis

jira/create_issue

Descrição: Cria uma issue no Jira.

Parâmetros:

summary (string, obrigatório): Resumo - Um breve resumo da issue. (exemplo: “A impressora parou de funcionar”).
project (string, opcional): Projeto - Projeto ao qual a issue pertence. Padrão para o primeiro projeto do usuário se não informado. Use as Configurações de Workflow do Portal de Conexão para permitir a seleção de Projeto.
issueType (string, opcional): Tipo de issue - Padrão para Task se não informado.
jiraIssueStatus (string, opcional): Status - Padrão para o primeiro status do projeto se não informado.
assignee (string, opcional): Responsável - Padrão para o usuário autenticado se não informado.
descriptionType (string, opcional): Tipo de Descrição - Selecione o Tipo de Descrição.
- Opções: description, descriptionJSON
description (string, opcional): Descrição - Uma descrição detalhada da issue. Este campo aparece apenas se ‘descriptionType’ = ‘description’.
additionalFields (string, opcional): Campos Adicionais - Especifique outros campos em formato JSON. Use as Configurações de Workflow do Portal de Conexão para permitir ao usuário selecionar quais campos atualizar.
```
{
  "customfield_10001": "value"
}
```

jira/update_issue

Descrição: Atualiza uma issue no Jira.

Parâmetros:

issueKey (string, obrigatório): Chave da Issue (exemplo: “TEST-1234”).
summary (string, opcional): Resumo - Breve resumo da issue. (exemplo: “A impressora parou de funcionar”).
issueType (string, opcional): Tipo de issue - Use as Configurações de Workflow do Portal de Conexão para permitir a seleção.
jiraIssueStatus (string, opcional): Status - Use as Configurações de Workflow do Portal de Conexão para permitir a seleção.
assignee (string, opcional): Responsável - Use as Configurações de Workflow do Portal de Conexão para permitir a seleção.
descriptionType (string, opcional): Tipo de Descrição - Selecione o Tipo de Descrição.
- Opções: description, descriptionJSON
description (string, opcional): Descrição - Descrição detalhada da issue. Este campo aparece apenas se ‘descriptionType’ = ‘description’.
additionalFields (string, opcional): Campos Adicionais - Especifique outros campos em formato JSON.

jira/get_issue_by_key

Descrição: Obtém uma issue pelo identificador no Jira.

Parâmetros:

issueKey (string, obrigatório): Chave da Issue (exemplo: “TEST-1234”).

jira/filter_issues

Descrição: Busca issues no Jira usando filtros.

Parâmetros:

jqlQuery (object, opcional): Filtro em forma normal disjuntiva - OU de grupos E de condições simples.

{
  "operator": "OR",
  "conditions": [
    {
      "operator": "AND",
      "conditions": [
        {
          "field": "status",
          "operator": "$stringExactlyMatches",
          "value": "Open"
        }
      ]
    }
  ]
}

Operadores disponíveis: $stringExactlyMatches, $stringDoesNotExactlyMatch, $stringIsIn, $stringIsNotIn, $stringContains, $stringDoesNotContain, $stringGreaterThan, $stringLessThan

limit (string, opcional): Limitar resultados - Limite máximo de issues retornados. Padrão para 10 se estiver em branco.

jira/search_by_jql

Descrição: Busca issues no Jira utilizando JQL.

Parâmetros:

jqlQuery (string, obrigatório): Query JQL (exemplo: “project = PROJECT”).
paginationParameters (object, opcional): Parâmetros de paginação para resultados paginados.
```
{
  "pageCursor": "cursor_string"
}
```

jira/update_issue_any

Descrição: Atualiza qualquer issue no Jira. Use DESCRIBE_ACTION_SCHEMA para obter o schema de propriedades dessa função.

Parâmetros: Nenhum parâmetro específico - use JIRA_DESCRIBE_ACTION_SCHEMA primeiro para obter o schema esperado.

jira/describe_action_schema

Descrição: Obtém o schema esperado para um tipo de issue. Use esta função caso nenhuma outra função atenda ao tipo de issue que deseja operar.

Parâmetros:

issueTypeId (string, obrigatório): ID do Tipo de Issue.
projectKey (string, obrigatório): Chave do projeto.
operation (string, obrigatório): Tipo de Operação, por exemplo CREATE_ISSUE ou UPDATE_ISSUE.

jira/get_projects

Descrição: Obtém os projetos no Jira.

Parâmetros:

paginationParameters (object, opcional): Parâmetros de Paginação.
```
{
  "pageCursor": "cursor_string"
}
```

jira/get_issue_types_by_project

Descrição: Obtém os tipos de issues por projeto no Jira.

Parâmetros:

project (string, obrigatório): Chave do projeto.

jira/get_issue_types

Descrição: Obtém todos os tipos de issues no Jira.

Parâmetros: Nenhum obrigatório.

jira/get_issue_status_by_project

Descrição: Obtém os status das issues de um projeto específico.

Parâmetros:

project (string, obrigatório): Chave do projeto.

jira/get_all_assignees_by_project

Descrição: Obtém os responsáveis por um projeto específico.

Parâmetros:

project (string, obrigatório): Chave do projeto.

Exemplos de Uso

Configuração Básica de um Agente Jira

from crewai import Agent, Task, Crew

# Obtenha as ferramentas enterprise (incluirá ferramentas do Jira)

# Criação de um agente com capacidades Jira
jira_agent = Agent(
    role="Issue Manager",
    goal="Gerenciar issues do Jira e acompanhar o progresso do projeto de forma eficiente",
    backstory="Um assistente de IA especializado em rastreamento de issues e gestão de projetos.",
    apps=['jira']
)

# Tarefa para criar um relatório de bug
create_bug_task = Task(
    description="Criar um relatório de bug para a funcionalidade de login com alta prioridade e designar para o time de desenvolvimento",
    agent=jira_agent,
    expected_output="Bug report creado com sucesso e chave da issue"
)

# Executar a tarefa
crew = Crew(
    agents=[jira_agent],
    tasks=[create_bug_task]
)

crew.kickoff()

Filtrando Ferramentas Jira Específicas

# Obtenha apenas ferramentas Jira específicas
    actions_list=["jira/create_issue", "jira/update_issue", "jira/search_by_jql"]
)

issue_coordinator = Agent(
    role="Issue Coordinator",
    goal="Criar e gerenciar issues Jira de forma eficiente",
    backstory="Um assistente de IA focado na criação e gestão de issues.",
    apps=['jira']
)

# Tarefa para gerenciar workflow de issues
issue_workflow = Task(
    description="Criar uma issue de solicitação de feature e atualizar o status de issues relacionadas",
    agent=issue_coordinator,
    expected_output="Feature request criada e issues relacionadas atualizadas"
)

crew = Crew(
    agents=[issue_coordinator],
    tasks=[issue_workflow]
)

crew.kickoff()

Análise e Relatórios de Projeto

from crewai import Agent, Task, Crew

project_analyst = Agent(
    role="Project Analyst",
    goal="Analisar dados de projetos e gerar insights a partir do Jira",
    backstory="Um analista de projetos experiente que extrai insights de dados de gestão de projetos.",
    apps=['jira']
)

# Tarefa para analisar status do projeto
analysis_task = Task(
    description="""
    1. Obtenha todos os projetos e seus tipos de issues
    2. Busque todas as issues abertas entre projetos
    3. Analise distribuição de issues por status e responsável
    4. Crie uma issue de relatório de resumo com os achados
    """,
    agent=project_analyst,
    expected_output="Análise do projeto completa com relatório de resumo criado"
)

crew = Crew(
    agents=[project_analyst],
    tasks=[analysis_task]
)

crew.kickoff()

Gestão Automatizada de Issues

from crewai import Agent, Task, Crew

automation_manager = Agent(
    role="Automation Manager",
    goal="Automatizar gestão de issues e processos de workflow",
    backstory="Um assistente de IA que automatiza tarefas repetitivas de gestão de issues.",
    apps=['jira']
)

# Tarefa para automatizar gestão de issues
automation_task = Task(
    description="""
    1. Buscar todas as issues não atribuídas usando JQL
    2. Obter responsáveis disponíveis de cada projeto
    3. Atribuir issues automaticamente com base na carga de trabalho e especialidade
    4. Atualizar prioridades das issues baseando-se na idade e tipo
    5. Criar issues semanais de planejamento de sprint
    """,
    agent=automation_manager,
    expected_output="Issues atribuídas automaticamente e issues de planejamento de sprint criadas"
)

crew = Crew(
    agents=[automation_manager],
    tasks=[automation_task]
)

crew.kickoff()

Operações Avançadas Baseadas em Schema

from crewai import Agent, Task, Crew

schema_specialist = Agent(
    role="Schema Specialist",
    goal="Executar operações complexas no Jira usando schemas dinâmicos",
    backstory="Um assistente de IA que manipula schemas dinâmicos e tipos de issues customizadas do Jira.",
    apps=['jira']
)

# Tarefa usando operações baseadas em schema
schema_task = Task(
    description="""
    1. Obtenha todos os projetos e seus tipos personalizados de issues
    2. Para cada tipo personalizado, descreva o schema de ação
    3. Crie issues usando schema dinâmico para campos complexos customizados
    4. Atualize issues com valores de campos personalizados a partir de regras de negócio
    """,
    agent=schema_specialist,
    expected_output="Issues customizadas criadas e atualizadas utilizando schemas dinâmicos"
)

crew = Crew(
    agents=[schema_specialist],
    tasks=[schema_task]
)

crew.kickoff()

Solução de Problemas

Problemas Comuns

Erros de Permissão

Certifique-se de que sua conta Jira tem as permissões necessárias nos projetos alvo
Verifique se a conexão OAuth inclui os escopos necessários da API Jira
Confira se você possui permissões de criar/editar issues nos projetos especificados

Chaves de Projeto ou Issue Inválidas

Confira o formato das chaves dos projetos e issues (ex: “PROJ-123”)
Verifique se os projetos existem e são acessíveis pela sua conta
Certifique-se de que chaves de issues referenciam issues existentes

Problemas de Tipo ou Status de Issue

Use JIRA_GET_ISSUE_TYPES_BY_PROJECT para obter tipos válidos de issue para um projeto
Use JIRA_GET_ISSUE_STATUS_BY_PROJECT para obter status válidos
Certifique-se de que tipos e status de issue estão disponíveis no projeto alvo

Problemas com Queries JQL

Teste as queries JQL na busca de issues do Jira antes de utilizar em chamadas de API
Certifique-se de que os nomes dos campos em JQL estejam corretos e existam em sua instância do Jira
Use a sintaxe correta de JQL para queries complexas

Problemas com Campos Customizados e Schemas

Use JIRA_DESCRIBE_ACTION_SCHEMA para obter o schema correto para tipos de issues complexas
Certifique-se de que os IDs dos campos customizados estão corretos (ex: “customfield_10001”)
Verifique se esses campos estão disponíveis no projeto e tipo de issue alvo

Problemas de Fórmulas de Filtro

Garanta que as fórmulas de filtro sigam a estrutura JSON correta para forma normal disjuntiva
Use apenas campos válidos conforme configuração do seu Jira
Teste filtros simples antes de construir queries complexas com múltiplas condições

Obtenha Ajuda

Precisa de Ajuda?

Entre em contato com nosso time de suporte para obter assistência na configuração ou solução de problemas da integração Jira.