Jira Agent

Source Code: hub/agents/python/jira/gaia_agent_jira/agent.py · src/gaia/apps/jira/app.py

Overview

The GAIA Jira Agent provides a natural language interface to Atlassian Jira. It talks directly to the Atlassian REST API — no intermediary services or MCP bridge required. On first use it auto-discovers your instance configuration (projects, issue types, statuses, priorities) so it adapts to your Jira setup, then lets you search, create, and update issues with plain English.

First time here? Complete the Setup guide first to install GAIA and its dependencies. Desktop WebUI: GAIA also ships a JIRA WebUI Electron app. See WebUI Configuration below.

Quick Start

Prerequisites

GAIA Installation — Follow the Setup guide. The base install includes everything the Jira agent needs.
Download the model — The agent uses Qwen3.5-35B-A3B-GGUF for reliable JSON parsing and JQL generation. Download it via the Lemonade model manager:
1. Start the server: lemonade-server serve
2. Open the model manager (typically http://localhost:13305)
3. Search for and download Qwen3.5-35B-A3B-GGUF
The model is over 17 GB, so download takes a while and is best run on a Strix Halo (or similar high-memory) device. It is selected automatically when you run Jira commands.

Set Jira credentials:

export ATLASSIAN_SITE_URL=https://your-domain.atlassian.net
export ATLASSIAN_API_KEY=your-api-token
export ATLASSIAN_USER_EMAIL=your-email@example.com

Or create a .env file in the project root (see .env.example for a template). See Getting Your Jira API Token for token setup.

Verify Installation

gaia --version
gaia jira "show all projects"   # auto-discovers your instance

Basic Usage

gaia jira --interactive

gaia jira "show my open issues"

gaia jira "find critical bugs from last week"

gaia jira "create a task: Update documentation"

gaia jira "set MDP-6 priority to high"

The agent was developed and tested against a dummy Jira project. Real instances vary in custom fields, workflows, and permissions, so you may hit errors or unexpected results. Auto-discovery adapts to most setups, but highly customized environments may need manual adjustment.

Architecture

The CLI (gaia jira) wraps JiraApp (src/gaia/apps/jira/app.py), which drives the JiraAgent (hub/agents/python/jira/gaia_agent_jira/agent.py):

JiraAgent — processes natural language, auto-discovers your instance configuration, translates queries to JQL, and registers three tools: jira_search, jira_create, jira_update.
JiraApp — high-level wrapper that handles interactive mode and formats output for display.
gaia jira CLI — manages the agent lifecycle; supports direct queries and interactive mode.

Automatic discovery — on first use it queries your Jira instance for projects, issue types, statuses, and priorities.
Dynamic prompting — that discovered config teaches the LLM about your specific setup.
Query translation — the LLM converts natural language into structured tool calls (and JQL).
Tool execution — calls the Jira REST API.
Result formatting — returns a user-friendly response.

Usage Examples

The agent understands a wide range of phrasings — the examples below are representative, not exhaustive.

Search

# Assigned to you
gaia jira "show my issues"
gaia jira "what am I working on"

# By priority and type
gaia jira "find high priority ideas"
gaia jira "show medium priority ideas from this week"

# By project
gaia jira "issues in project MDP"
gaia jira "what's happening in MDP"

# Time-based
gaia jira "issues created today"
gaia jira "bugs fixed last week"
gaia jira "what changed yesterday"

# Sprint queries
gaia jira "current sprint ideas"
gaia jira "unfinished ideas in active sprint"

Create

gaia jira "create idea: Explore VR travel features"
gaia jira "create an idea: Implement AI chatbot, high priority"
gaia jira "new idea: Add user analytics dashboard"
gaia jira "create idea in MDP: Refactor user profile data"   # specify project

Update

# Change priority
gaia jira "update MDP-5 set priority to High"

# Change status
gaia jira "move MDP-6 to Discovery"
gaia jira "move MDP-5 to Parking lot"

# Update multiple fields
gaia jira "update JKL-012 priority High and assign to me"

Interactive Mode

gaia jira --interactive

🚀 GAIA Jira App - Interactive Mode
Type 'help' for commands, 'exit' to quit

jira> show my open issues
[Agent processes your request...]
🎫 Found 2 issues
• MDP-6 - Explore VR travel features
  Status: Parking lot | Priority: Medium | Assignee: You
• MDP-5 - Refactor user profile data
  Status: Parking lot | Priority: Medium | Assignee: You

Integration Methods

1. Python API

Use the JiraAgent directly in your Python applications:

from gaia_agent_jira.agent import JiraAgent

# Initialize and discover Jira configuration (do this once)
agent = JiraAgent(silent_mode=True)   # silent_mode suppresses console output
config = agent.initialize()
print(f"Connected to Jira with {len(config['projects'])} projects")

# Execute natural language queries
result = agent.process_query("show my high priority ideas in MDP")
if result["status"] == "success":
    print(f"Result: {result['result']}")
    print(f"Steps taken: {result['steps_taken']}")

# Create and update issues
agent.process_query("create an idea: Implement AI chatbot with medium priority")
agent.process_query("update MDP-5 set priority to High")

process_query returns a dict with status ("success", "failed", or "incomplete"), result, steps_taken, conversation, and error_history.

2. MCP Server (HTTP/JSON-RPC)

For non-Python applications, expose the agent over HTTP via the MCP bridge:

gaia mcp start --port 8765

Then call it from any language with a JSON-RPC tools/call. The response payload is JSON in result.content[0].text.

curl -X POST http://localhost:8765/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "gaia.jira",
      "arguments": { "query": "show my ideas in Parking lot status" }
    }
  }'

async function queryJira(query) {
  const response = await fetch("http://localhost:8765/", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "tools/call",
      params: { name: "gaia.jira", arguments: { query } },
    }),
  });
  const result = await response.json();
  if (result.result) {
    return JSON.parse(result.result.content[0].text);
  }
  throw new Error(result.error || "Unknown error");
}

const issues = await queryJira("show my open ideas");

For workflow integrations, see the MCP Documentation and n8n Integration Guide.

Key Features

Automatic configuration discovery — learns your projects, issue types, statuses, priorities, and custom fields on first use, with no config files.
Intelligent query translation — maps intent to your instance: "my issues" → assignee = currentUser(), "critical" → your priority values, "this week" → correct date ranges, "in progress" → your real status names.
Robust error handling — validates credentials before calling the API, retries failed operations, suggests corrections for invalid issue types or field names, and preserves conversation context across errors.

Configuration

Getting Your Jira API Token

Log into your Atlassian account.
Go to Account Settings > Security > API tokens.
Click Create API token, name it (e.g. “GAIA Integration”), and copy it somewhere safe.

Setting Environment Variables

Linux/Mac
Windows
.env file

export ATLASSIAN_SITE_URL=https://your-domain.atlassian.net
export ATLASSIAN_API_KEY=your-api-token
export ATLASSIAN_USER_EMAIL=your-email@example.com

set ATLASSIAN_SITE_URL=https://your-domain.atlassian.net
set ATLASSIAN_API_KEY=your-api-token
set ATLASSIAN_USER_EMAIL=your-email@example.com

ATLASSIAN_SITE_URL=https://your-domain.atlassian.net
ATLASSIAN_API_KEY=your-api-token
ATLASSIAN_USER_EMAIL=[email protected]

Custom Model Selection

Override the default model when constructing the agent:

agent = JiraAgent(model_id="gpt-4", debug=True, show_prompts=True)

Troubleshooting

”Missing Jira credentials”

Confirm the environment variables are set, then verify the token works directly:

echo $ATLASSIAN_SITE_URL $ATLASSIAN_API_KEY $ATLASSIAN_USER_EMAIL

curl -u [email protected]:your-api-token \
  https://your-domain.atlassian.net/rest/api/2/myself

“No issues found” when you know they exist

Run with --debug to see the generated JQL, and confirm you can view the project:

gaia jira --debug "your query"
gaia jira "show all projects"

“Invalid issue type” errors

Discover the issue types your instance actually uses:

agent = JiraAgent()
config = agent.initialize()
print("Available issue types:", config["issue_types"])

Note: the dummy project uses “Idea” and “Epic” as issue types, not “Bug”/“Task”/“Story”.

MCP bridge connection issues

gaia mcp status                  # is it running?
gaia mcp stop && gaia mcp start  # restart

Best Practices

Be specific — "show my high priority ideas in project MDP" beats "show issues".
Let discovery run first — call agent.initialize() (or any query) once so the agent knows your projects, statuses, and issue types before you create or update.
Use interactive mode (gaia jira --interactive) for iterative exploration.

To exercise the integration end-to-end, run the smoke test: python scripts/jira_smoke.py (add --interactive, --debug, or --show-prompts as needed).

Limitations

API rate limits — Atlassian enforces rate limits on API calls.
Field permissions — can only access or modify fields you have permission for.
Bulk operations — items are processed sequentially, not in parallel.
Attachments — file attachments are not supported.
Workflow transitions — limited support for complex transitions.

WebUI Configuration

The JIRA WebUI provides an in-app configuration screen for your JIRA server URL, username/email, and API token. Configuration is stored locally and persists between sessions.

Getting Started

C++ Framework

Python Framework

Overview

Quick Start

Prerequisites

Verify Installation

Basic Usage

Architecture

Usage Examples

Search

Create

Update

Interactive Mode

Integration Methods

1. Python API

2. MCP Server (HTTP/JSON-RPC)

Key Features

Configuration

Getting Your Jira API Token

Setting Environment Variables

Custom Model Selection

Troubleshooting

”Missing Jira credentials”

“No issues found” when you know they exist

“Invalid issue type” errors

MCP bridge connection issues

Best Practices

Limitations

WebUI Configuration

See Also

​Overview

​Quick Start

​Prerequisites

​Verify Installation

​Basic Usage

​Architecture

​Usage Examples

​Search

​Create

​Update

​Interactive Mode

​Integration Methods

​1. Python API

​2. MCP Server (HTTP/JSON-RPC)

​Key Features

​Configuration

​Getting Your Jira API Token

​Setting Environment Variables

​Custom Model Selection

​Troubleshooting

​”Missing Jira credentials”

​“No issues found” when you know they exist

​“Invalid issue type” errors

​MCP bridge connection issues

​Best Practices

​Limitations

​WebUI Configuration

​See Also

Overview

Quick Start

Prerequisites

Verify Installation

Basic Usage

Architecture

Usage Examples

Search

Create

Update

Interactive Mode

Integration Methods

1. Python API

2. MCP Server (HTTP/JSON-RPC)

Key Features

Configuration

Getting Your Jira API Token

Setting Environment Variables

Custom Model Selection

Troubleshooting

”Missing Jira credentials”

“No issues found” when you know they exist

“Invalid issue type” errors

MCP bridge connection issues

Best Practices

Limitations

WebUI Configuration

See Also