Skip to main content

Jira Tool

Seamlessly integrate your agents with Atlassian Jira to manage projects, track issues, and automate agile workflows.

This guide will walk you through generating your Atlassian API credentials and configuring the Jira tool for your agents.

💡 Core Concepts​

To configure this tool effectively, you need to understand how the agent interacts with Jira.

1. Operations & Payloads​

The JiraTool is versatile. Your agent acts as a Jira user that can perform specific Operations. The agent determines which operation to perform based on the user's intent:

  • JQL Query: Search for issues using Jira Query Language (e.g., "Find all bugs in the PROJ project").
  • Create Issue: Create new tasks, bugs, or stories by passing a fields dictionary.
  • Get Projects: List all projects accessible to the user.
  • Create confluence page: Create pages directly via the Jira/Confluence API connection.

2. Authentication​

The tool requires three specific pieces of information to connect to your specific Jira instance:

  • Instance URL: The web address of your Jira site.
  • Username: The email address you use to log in.
  • API Key: A security token generated from your Atlassian account (not your password).

⚙️ Configuration Steps​

Follow these steps to set up the Jira integration.

Generate Atlassian API Token​

  1. Log in to your Atlassian Account Settings.
  2. Navigate to Security -> Create and manage API tokens.
  3. Click Create API token.
  4. Give it a label (e.g., "SVAHNAR Agent") and copy the generated token.
warning

Save this token immediately. You will not be able to see it again after you close the window.

Prepare Configuration Details​

Gather the following details for your agent configuration:

  • jira_username: Your email (e.g., jira-user@example.com).
  • jira_api_key: The token you just copied.
  • jira_instance_url: Your full domain (e.g., https://your-domain.atlassian.net).

Configure Tool in YAML​

Add the JiraTool to your agent's tool list. It is recommended to use SVAHNAR Key Vault for sensitive keys.

tools:
  tool_assigned:
    - name: "JiraTool"
      config:
        jira_username: "jira-user@example.com"
        jira_api_key: "${JIRA_API_KEY}"
        jira_instance_url: "[https://your-domain.atlassian.net](https://your-domain.atlassian.net)"

📚 Practical Recipes (Examples)​

Recipe 1: The Issue Manager Agent​

Use Case: An agent dedicated to finding existing tickets and creating new ones based on chat instructions.

create_agent_network:
  agent-1:
    agent_name: "issue_manager"
    LLM_config:
      params:
        model: "gpt-5-mini"
    tools:
      tool_assigned:
        - name: "JiraTool"
          config:
            # Replace with your actual credentials or ENV variables
            jira_username: "jira-user@example.com"
            jira_api_key: "${JIRA_API_KEY}"
            jira_instance_url: "[https://your-domain.atlassian.net](https://your-domain.atlassian.net)"
    agent_function:
      - "You are a project manager."
      - "Use the JiraTool to search for issues using JQL queries."
      - "If a user asks to create a task, form the correct JSON payload with summary and description."
    incoming_edge:
      - Start
    outgoing_edge: []

💡 Tip: Using Key Vault​

For security, never hardcode your API Key in the YAML file if you are sharing your code. Use the ${SECRET_NAME} syntax.

🚑 Troubleshooting​

  • Unauthorized Error

    • Check that jira_username matches the email used to generate the API token.
    • Ensure the jira_api_key was copied correctly without extra spaces.

  • Not Found Error

    • Verify the jira_instance_url includes https:// and ends with .net (no trailing slashes like /jira).

  • Agent fails to find issues

    • The agent might be generating invalid JQL. Try asking the agent to "List projects first" to ensure it knows the valid Project Keys (e.g., MYPROJ) before running a search query.