Skip to main content
from praisonaiagents import Agent
from praisonaiagents.tools import jira_search, jira_create_task

agent = Agent(
    name="Jira Assistant",
    instructions="Search and create Jira issues from natural language.",
    tools=[jira_search, jira_create_task],
)
agent.start("Find open bugs in PROJ and create a task for the login timeout")
The user describes backlog work; the agent searches Jira and creates or updates issues.
Prerequisites
  • Python 3.10 or higher
  • pip install praisonaiagents jira
  • Jira Cloud API token (generate here)

​
Quick Start

1

Set Environment Variables

export JIRA_URL="https://your-domain.atlassian.net"
export JIRA_EMAIL="your-email@example.com"
export JIRA_API_TOKEN="your-api-token"
2

Create a Jira Agent

from praisonaiagents import Agent
from praisonai_tools import (
    jira_create_task,
    jira_search,
    jira_list_boards,
    jira_get_board_issues,
    jira_get_transitions,
    jira_move_issue,
)

agent = Agent(
    name="JiraManager",
    role="Jira Project Manager",
    goal="Manage Jira Kanban board and track tasks through workflow stages",
    instructions="You manage a Jira project. The project key is 'PROJ' and the board ID is 1.",
    tools=[
        jira_create_task,
        jira_search,
        jira_list_boards,
        jira_get_board_issues,
        jira_get_transitions,
        jira_move_issue,
    ],
)

agent.start("List all boards, then create a task called 'Setup CI pipeline' and move it to In Progress")

​
How It Works

​
Available Tools

FunctionDescription
jira_search(jql)Search issues with JQL queries
jira_create_task(project, summary, ...)Create a new task
jira_list_boards(board_type)List all Kanban/Scrum boards
jira_get_board_issues(board_id, jql)Get issues on a board
jira_get_transitions(issue_key)Get available status transitions
jira_move_issue(issue_key, status)Move issue to a status (e.g., “In Progress”, “Done”)

​
Common Patterns

​
Kanban Workflow Agent

An agent that manages the full Kanban lifecycle — creates tasks, moves them through stages, and verifies completion. 
from praisonaiagents import Agent
from praisonai_tools import (
    jira_create_task,
    jira_search,
    jira_list_boards,
    jira_get_board_issues,
    jira_get_transitions,
    jira_move_issue,
)

agent = Agent(
    name="KanbanManager",
    role="Kanban Board Manager",
    goal="Manage tasks through the Kanban workflow",
    instructions="""You manage a Jira Kanban board.
    
The project key is 'KAN' and the board ID is 2.

Follow these steps:
1. List boards to confirm the board exists
2. Get current board issues to see what's there
3. Create a new task
4. Get transitions for the new issue
5. Move it to 'In Progress'
6. Move it to 'Done'
7. Search to confirm final status""",
    tools=[
        jira_create_task,
        jira_search,
        jira_list_boards,
        jira_get_board_issues,
        jira_get_transitions,
        jira_move_issue,
    ],
    llm="gpt-4o-mini",
)

result = agent.start(
    "Create a task 'Setup CI pipeline' in KAN project, "
    "move it through In Progress to Done, and verify the final status."
)
print(result)

​
Issue Search and Reporting

from praisonaiagents import Agent
from praisonai_tools import jira_search

agent = Agent(
    name="JiraReporter",
    role="Jira Reporter",
    goal="Search and report on Jira issues",
    tools=[jira_search],
)

agent.start("Find all open bugs in project KAN and summarize them")

​
Multi-Agent Project Management

from praisonaiagents import Agent, Task, PraisonAIAgents
from praisonai_tools import (
    jira_create_task,
    jira_search,
    jira_get_transitions,
    jira_move_issue,
)

# Planner creates tasks
planner = Agent(
    name="Planner",
    role="Sprint Planner",
    goal="Plan and create sprint tasks",
    tools=[jira_create_task, jira_search],
)

# Tracker moves tasks through workflow
tracker = Agent(
    name="Tracker",
    role="Progress Tracker",
    goal="Track and update task statuses",
    tools=[jira_get_transitions, jira_move_issue, jira_search],
)

plan_task = Task(
    description="Create 3 tasks for a 'User Auth' feature in project KAN: Login page, Session management, Password reset",
    agent=planner,
    name="plan_sprint"
)

track_task = Task(
    description="Move all newly created auth tasks to 'In Progress'",
    agent=tracker,
    name="track_progress"
)

agents = PraisonAIAgents(
    agents=[planner, tracker],
    tasks=[plan_task, track_task],
    process="sequential"
)
agents.start()

​
Configuration

​
Environment Variables

VariableRequiredDescription
JIRA_URL✅Jira instance URL (e.g., https://your-domain.atlassian.net)
JIRA_EMAIL✅Email associated with your Jira account
JIRA_API_TOKEN✅API token from Atlassian API tokens

​
Create Task Parameters

ParameterTypeRequiredDescription
projectstr✅Project key (e.g., "KAN")
summarystr✅Task title
descriptionstr❌Task description
issue_typestr❌Issue type (default: "Task")
prioritystr❌Priority level
assigneestr❌Assignee username

​
Best Practices

Include the project key and board ID directly in the agent’s instructions so it doesn’t need to guess:
instructions="The project key is 'KAN' and the board ID is 2."
JQL gives exact control over search results:
jira_search("project = KAN AND status = 'In Progress' ORDER BY created DESC")
Always let the agent call jira_get_transitions before jira_move_issue so it knows what transitions are available for the current status.
Jira operations are straightforward tool calls. gpt-4o-mini handles them well at lower cost.

​
Watch & Monitor

Monitor issues and projects for changes over time. These tools live in praisonaiagents.tools (not praisonai_tools board tools above). 
from praisonaiagents import Agent
from praisonaiagents.tools import jira_tools

agent = Agent(
    name="JIRA Watcher",
    instructions="Monitor JIRA issues and report changes. Always include the JIRA URL.",
    tools=jira_tools(),
)

agent.start("Get info on issue PROJ-123 at https://mycompany.atlassian.net")

​
Watch tools

ToolDescription
jira_watch_issueCurrent issue state, or field/comment diff since since_timestamp
jira_watch_projectRecent project activity, or new/updated issues since since_timestamp
jira_get_issue_infoStatus, priority, assignee, description, recent comments
jira_search_issuesJQL search with human-readable summary (max_results default 20)
jira_tools()Returns all four tools as a list
Every call requires url (e.g. https://yourcompany.atlassian.net).

​
Auth

ModeCredentialsEnv vars
Cloud (Atlassian.net)email + tokenJIRA_EMAIL, JIRA_API_TOKEN
Self-hosted Serverusername + tokenJIRA_USERNAME, JIRA_API_TOKEN

​
Examples

from praisonaiagents import Agent
from praisonaiagents.tools import jira_watch_issue, jira_watch_project, schedule_add

# Diff since a timestamp
Agent(
    name="Issue Watcher",
    tools=[jira_watch_issue],
).start(
    "Check PROJ-123 at https://mycompany.atlassian.net "
    "for changes since 2026-06-21T00:00:00Z"
)

# Recurring project monitor
Agent(
    name="Project Monitor",
    tools=jira_tools() + [schedule_add],
).start("Schedule a check of project PROJ every 30 minutes")
All watch tools require url. Include it in user prompts or hard-code it in agent instructions.
Without since_timestamp, watch tools return current state only — no change detection.
Watch tools are one-shot polls. Pair with schedule_add for interval monitoring.
jira_watch_project accepts keys matching ^[A-Z][A-Z0-9_]*$ to prevent JQL injection.

Custom Tools

Create your own tools

Schedule Tools

Interval polling for JIRA watch agents

GitHub Tools

Branch, commit, and PR tools