> ## Documentation Index
> Fetch the complete documentation index at: https://amd-gaia.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira Agent

> Search, create, and update Jira issues with plain-English commands via the Atlassian REST API.

<Info>
  **Source Code:** [`hub/agents/python/jira/gaia_agent_jira/agent.py`](https://github.com/amd/gaia/blob/main/hub/agents/python/jira/gaia_agent_jira/agent.py) · [`src/gaia/apps/jira/app.py`](https://github.com/amd/gaia/blob/main/src/gaia/apps/jira/app.py)
</Info>

## 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](/docs/setup) guide first to install GAIA and its dependencies.
>
> **Desktop WebUI**: GAIA also ships a JIRA WebUI Electron app. See [WebUI Configuration](#webui-configuration) below.

## Quick Start

### Prerequisites

1. **GAIA Installation** — Follow the [Setup](/docs/setup) guide. The base install includes everything the Jira agent needs.

2. **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](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.

3. **Set Jira credentials**:

   ```bash theme={null}
   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](#getting-your-jira-api-token) for token setup.

### Verify Installation

```bash theme={null}
gaia --version
gaia jira "show all projects"   # auto-discovers your instance
```

### Basic Usage

<CodeGroup>
  ```bash Interactive theme={null}
  gaia jira --interactive
  ```

  ```bash Direct Query theme={null}
  gaia jira "show my open issues"
  ```

  ```bash Search theme={null}
  gaia jira "find critical bugs from last week"
  ```

  ```bash Create theme={null}
  gaia jira "create a task: Update documentation"
  ```

  ```bash Update theme={null}
  gaia jira "set MDP-6 priority to high"
  ```
</CodeGroup>

<Note>
  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.
</Note>

## 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.

```mermaid theme={null}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#E2A33E', 'primaryTextColor':'#1a1a1a', 'primaryBorderColor':'#A87B2D', 'lineColor':'#A87B2D', 'edgeLabelBackground':'#ffffff', 'fontFamily':'system-ui, -apple-system, sans-serif'}}}%%
graph LR
    User(["User Query"]) --> Agent(["JiraAgent"])
    Agent --> Discover(["Auto-Discovery"])
    Discover --> Config(["Jira Config"])
    Config --> LLM(["LLM Processing"])
    LLM --> Tools(["Tool Execution"])
    Tools --> API(["Jira REST API"])
    API --> Result(["Formatted Result"])

    style User fill:#f8f9fa,stroke:#dee2e6,stroke-width:2px,color:#495057
    style Agent fill:#E2A33E,stroke:#A87B2D,stroke-width:2px,color:#1a1a1a
    style Discover fill:#EFC480,stroke:#E2A33E,stroke-width:2px,color:#1a1a1a
    style Config fill:#A87B2D,stroke:#A87B2D,stroke-width:2px,color:#fff
    style LLM fill:#2d2d2d,stroke:#1a1a1a,stroke-width:2px,color:#fff
    style Tools fill:#EFC480,stroke:#E2A33E,stroke-width:2px,color:#1a1a1a
    style API fill:#A87B2D,stroke:#A87B2D,stroke-width:2px,color:#fff
    style Result fill:#28a745,stroke:#1e7e34,stroke-width:2px,color:#fff

    linkStyle 0,1,2,3,4,5,6 stroke:#E2A33E,stroke-width:2px
```

1. **Automatic discovery** — on first use it queries your Jira instance for projects, issue types, statuses, and priorities.
2. **Dynamic prompting** — that discovered config teaches the LLM about your specific setup.
3. **Query translation** — the LLM converts natural language into structured tool calls (and JQL).
4. **Tool execution** — calls the Jira REST API.
5. **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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
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:

```python theme={null}
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:

```bash theme={null}
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`.

<CodeGroup>
  ```bash cURL theme={null}
  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" }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  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");
  ```
</CodeGroup>

For workflow integrations, see the [MCP Documentation](/docs/integrations/mcp) and [n8n Integration Guide](/docs/integrations/n8n).

## 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

1. Log into your Atlassian account.
2. Go to [Account Settings > Security > API tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
3. Click **Create API token**, name it (e.g. "GAIA Integration"), and copy it somewhere safe.

### Setting Environment Variables

<Tabs>
  <Tab title="Linux/Mac">
    ```bash theme={null}
    export ATLASSIAN_SITE_URL=https://your-domain.atlassian.net
    export ATLASSIAN_API_KEY=your-api-token
    export ATLASSIAN_USER_EMAIL=your-email@example.com
    ```
  </Tab>

  <Tab title="Windows">
    ```cmd theme={null}
    set ATLASSIAN_SITE_URL=https://your-domain.atlassian.net
    set ATLASSIAN_API_KEY=your-api-token
    set ATLASSIAN_USER_EMAIL=your-email@example.com
    ```
  </Tab>

  <Tab title=".env file">
    ```bash theme={null}
    ATLASSIAN_SITE_URL=https://your-domain.atlassian.net
    ATLASSIAN_API_KEY=your-api-token
    ATLASSIAN_USER_EMAIL=your-email@example.com
    ```
  </Tab>
</Tabs>

### Custom Model Selection

Override the default model when constructing the agent:

```python theme={null}
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:

```bash theme={null}
echo $ATLASSIAN_SITE_URL $ATLASSIAN_API_KEY $ATLASSIAN_USER_EMAIL

curl -u your-email@example.com: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:

```bash theme={null}
gaia jira --debug "your query"
gaia jira "show all projects"
```

#### "Invalid issue type" errors

Discover the issue types your instance actually uses:

```python theme={null}
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

```bash theme={null}
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.

## See Also

* [GAIA CLI Documentation](/docs/reference/cli) - Full command line interface guide
* [MCP Server Documentation](/docs/integrations/mcp) - External integration details
* [Agent Development Guide](/docs/reference/dev) - Build your own agents
* [Features Overview](/docs/reference/features) - Complete GAIA capabilities

***

<small style="color: #666;">
  **License**

  Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.

  SPDX-License-Identifier: MIT
</small>