jira-agent 0.1.2

Jira automation agent with Streamlit dashboard and API

Jira Automation Agent

A comprehensive AI-powered agent for automating Jira project management tasks including ticket creation, assignment, status management, epic organization, and more.

Features

🎯 Core Capabilities

• Ticket Management: Create, edit, assign, and change status of tickets
• Project Management: List projects and users
• Epic Management: Create and organize epics
• Search & Discovery: Advanced ticket searching with JQL
• URL Generation: Direct links to tickets and epics
• Status Management: Workflow transitions and status updates
• Assignment: Assign tickets to team members
• Priority Management: Set and update ticket priorities

🚀 Supported Operations

Ticket Operations

• Create tickets (Task, Bug, Story, etc.)
• Edit ticket details (summary, description, priority)
• Assign tickets to users
• Change ticket status through workflow
• Search tickets using JQL
• Get ticket details and URLs

Project Operations

• List all projects
• List users (system-wide or project-specific)
• Get project information

Epic Operations

• Create epics
• List epics (system-wide or project-specific)
• Link tickets to epics
• Get epic URLs

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Set up environment variables: Copy .env.example to .env and fill in values:

JIRA_URL=
JIRA_EMAIL=
JIRA_API_TOKEN=
JIRA_DEFAULT_EMAIL_DOMAIN=

azure_openai_api_version=2024-02-15-preview
azure_openai_model_name_4o_mini=
azure_openai_4o_mini_key=
azure_openai_4o_mini_url=
azure_embedding_key_3=
azure_embedding_version=2023-05-15
azure_embedding_model_3=text-embedding-3-large

3. Get Jira API Token:
   • Go to Atlassian Account Settings
   • Create a new API token
   • Use your email and this token for authentication

Usage

Basic Usage

from phi_jira_agent_final import get_phi_jira_agent

# Create the agent
agent = get_phi_jira_agent()

# Use the agent
response = agent.run("List all projects")
print(response)

Interactive Mode

python example_usage.py interactive

Streamlit Dashboard

streamlit run dashboard_app.py

After packaging, you can run:

jir-agent-dashboard

API Server

uvicorn main:app --reload

After packaging, you can run:

jir-agent-api

Microsoft Teams Bot via API

1. Configure environment variables

Set these in your shell or .env:

MICROSOFT_APP_ID=<bot app id>
MICROSOFT_APP_PASSWORD=<bot client secret>
MICROSOFT_APP_TENANT_ID=<tenant id or 'common'>

2. Run the API locally

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

3. Expose a public URL (for local testing)

• Use a tunneling tool (e.g., ngrok): ngrok http http://localhost:8000
• Note the public HTTPS URL.

4. Configure the Bot in Azure

• In Azure Bot registration, set the Messaging endpoint to: https://<your-public-host>/api/messages
• Ensure Microsoft App ID/Password match your environment variables.

5. Test from Teams

• Add your bot to a Team or personal scope.
• Send a message (e.g., "List projects"). The bot relays to main.py → agent and replies via Bot Framework.

Health check:

curl http://localhost:8000/health
# {"status":"ok","agent":"Phi Jira Agent ready"}

Notes:

• The agent uses the same tools as the dashboard (ticket creation, status changes, search, epics, analytics queries).
• Make sure Jira/Azure env vars are set in .env before starting.

### Example Commands

#### Project Management
```python
# List all projects
agent.run("List all projects")

# List users
agent.run("List all users")
agent.run("List users in project PROJ")

Ticket Management

# Create a ticket
agent.run("Create a new task in project PROJ titled 'Implement login' with description 'Add user authentication' and priority High")

# Assign a ticket
agent.run("Assign ticket PROJ-123 to user with account ID 5d8b8c8e-1234-5678-9abc-123456789abc")

# Change ticket status
agent.run("Change ticket PROJ-123 status to 'In Progress'")

# Edit ticket
agent.run("Edit ticket PROJ-123 to update summary to 'Updated: Implement login' and priority to Critical")

# Get ticket details
agent.run("Get details for ticket PROJ-123")

# Get ticket URL
agent.run("Get the URL for ticket PROJ-123")

Epic Management

# Create an epic
agent.run("Create a new epic in project PROJ titled 'User Management System' with description 'Complete user management functionality'")

# List epics
agent.run("List all epics")
agent.run("List epics in project PROJ")

Search Operations

# Search with JQL
agent.run("Search for tickets with JQL: project = PROJ AND status = 'In Progress'")
agent.run("Search for tickets with JQL: assignee = currentUser() AND status != Done")
agent.run("Search for tickets with JQL: created >= -7d")

# Simple searches
agent.run("Search for all open tickets in project PROJ")
agent.run("Search for tickets assigned to me")

Advanced Features

JQL (Jira Query Language) Support

The agent supports complex JQL queries for advanced ticket searching:

# Find tickets created in the last week
agent.run("Search for tickets with JQL: created >= -7d")

# Find tickets assigned to current user
agent.run("Search for tickets with JQL: assignee = currentUser()")

# Find tickets in specific project with specific status
agent.run("Search for tickets with JQL: project = PROJ AND status = 'In Progress'")

# Find tickets with specific priority
agent.run("Search for tickets with JQL: priority = High AND status != Done")

Workflow Integration

The agent can handle Jira workflow transitions:

# Change ticket status (follows Jira workflow)
agent.run("Change ticket PROJ-123 status to 'In Progress'")
agent.run("Change ticket PROJ-123 status to 'Done'")
agent.run("Change ticket PROJ-123 status to 'To Do'")

File Structure

jir_agent/
├── config.py              # Configuration settings
├── jira_client.py         # Jira API client
├── llm_client.py          # LLM client for Azure OpenAI
├── jira_tools.py          # Tool definitions for the agent
├── jira_agent.py          # Main agent implementation
├── example_usage.py       # Usage examples
├── requirements.txt       # Python dependencies
└── README.md             # This file

Configuration

Jira Setup

1. Ensure you have access to a Jira instance
2. Create an API token in your Atlassian account
3. Update the configuration in config.py or .env file

Azure OpenAI Setup

1. Create an Azure OpenAI resource
2. Deploy a GPT-4o-mini model
3. Get your API key and endpoint
4. Update the configuration

Error Handling

The agent includes comprehensive error handling:

• Connection validation
• Input validation
• Graceful error messages
• Retry mechanisms for API calls

Security

• API tokens are stored securely in environment variables
• No hardcoded credentials in the code
• Proper authentication for all Jira operations

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License.

Support

For issues and questions:

1. Check the error messages for specific guidance
2. Verify your Jira and Azure OpenAI configuration
3. Ensure you have proper permissions in Jira
4. Check the Jira API documentation for advanced features

Examples

See example_usage.py for comprehensive usage examples including:

• Basic operations
• Interactive mode
• Error handling
• Advanced JQL queries