Jira Integration

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• agent-packages/packages/assetpanda/README.md
• agent-packages/packages/github/src/schema.ts
• agent-packages/packages/jira/package.json
• agent-packages/packages/jira/src/JiraClient.ts
• agent-packages/packages/jira/src/tools.ts
• agent-packages/packages/jira/src/types/index.ts
• agent-packages/packages/kandji/package.json
• src/lib/constants.ts
• src/llm/agent-evals/jira-agent/index.spec.ts
• src/llm/agent-evals/jira-agent/mock.ts
• src/llm/agent-evals/jira-agent/test-data.ts
• src/llm/agent-evals/slack-agent/test-data.ts
• src/slack/slack-events-handler.service.ts
• src/slack/views/app_home.ts

The Jira integration for Quix provides an AI-powered interface to interact with Jira for project and issue tracking directly from Slack. Users can perform actions such as creating, viewing, searching, and updating Jira issues using natural language commands. This functionality is exposed to the AI agent through a set of defined tools.

The integration is part of the agent-packages monorepo structure and is identified as a supported integration within the main application. It allows for seamless connection to Jira instances, enabling users to manage their workflows without leaving their Slack workspace.

Sources: README.md:3-4, src/lib/constants.ts:38-49, agent-packages/packages/jira/package.json:2

Architecture

The Jira integration is built upon a layered architecture that abstracts the Jira API and exposes specific functionalities as tools for the AI agent.

This diagram shows the flow from a user's Slack message to the Jira API call.

1. Jira Tools (tools.ts): A collection of functions (Tool objects) that define the specific actions the agent can perform, such as find_jira_ticket or create_jira_issue. These tools are created by the createJiraTools function.
2. JiraService (index.ts): A service class that encapsulates the business logic for each tool. It uses JiraClient to interact with the Jira API.
3. JiraClient (JiraClient.ts): A low-level client responsible for making authenticated HTTP requests to the Jira REST API. It handles different authentication strategies.
4. Schemas (schema.ts): Zod schemas that define the input validation for each tool, ensuring that the data passed to the Jira API is correctly structured.

Sources: agent-packages/packages/jira/src/tools.ts:28, agent-packages/packages/jira/src/JiraClient.ts:11

Configuration and Authentication

The integration requires a JiraConfig object for initialization. This configuration is stored in the database and linked to a SlackWorkspace.

Sources: src/slack/views/app_home.ts:13, agent-packages/packages/jira/src/types/index.ts:6

Authentication Methods

The JiraClient supports multiple authentication methods for connecting to the Jira API:

1. Basic Authentication: Uses a username and API token, encoded in Base64.
2. Bearer Token: Uses an OAuth or personal access token.
3. JWT (Atlassian Connect): For Atlassian Connect apps, it generates a JWT for each request using a shared secret and app key.

The client automatically selects the authentication method based on the provided JiraAuth configuration.

Sources: agent-packages/packages/jira/src/JiraClient.ts:16-21, 31-45

Configuration Model

The JiraConfig contains the necessary details to connect to a Jira instance.

Field	Type	Description
host	string	The base URL of the Jira instance.
auth	JiraAuth	The authentication credentials.
defaultConfig	object (optional)	Default values, e.g., projectKey.

Sources: agent-packages/packages/jira/src/types/index.ts:6, src/llm/agent-evals/jira-agent/index.spec.ts:28-33

Available Tools

The integration exposes a set of tools to the LLM agent, allowing it to perform various actions in Jira. Each tool is defined with a name, description, schema for arguments, and the function to execute.

Sources: agent-packages/packages/jira/src/tools.ts:28-106

Tool Name	Description	Operations
find_jira_ticket	Search for Jira issues using a JQL query.	READ
get_jira_issue	Retrieve detailed information about a specific Jira issue by its key or ID.	READ
get_jira_issue_types	Retrieve all available issue types for a Jira project.	READ
create_jira_issue	Create a new Jira issue.	CREATE
assign_jira_issue	Assign a Jira issue to a user.	UPDATE
add_jira_comment	Add a comment to a Jira issue.	CREATE
get_jira_comments	Get comments for a specific Jira issue.	READ
update_jira_issue	Update an existing Jira issue.	UPDATE
search_jira_users	Search for Jira users by name or email.	READ

Tool Interaction Flow

Many user requests require a sequence of tool calls. For instance, creating and assigning a new ticket involves multiple steps that the agent plans and executes.

The following sequence diagram illustrates the flow for creating a new bug and assigning it to a user.

This flow is derived from test cases that define expected agent behavior for complex commands.

Sources: src/llm/agent-evals/jira-agent/test-data.ts:413-441

JiraClient

The JiraClient class is the core component for all communication with the Jira REST API. It is instantiated with the JiraClientConfig and provides methods that map directly to Jira API endpoints.

Sources: agent-packages/packages/jira/src/JiraClient.ts:11-29

This diagram shows the key methods within the JiraClient class.

The makeApiCall method is a generic request handler that also manages authentication, including the generation of JWTs for Atlassian Connect apps.

Sources: agent-packages/packages/jira/src/JiraClient.ts:31-57

Data Models and Schemas

The integration relies on a set of TypeScript types and Zod schemas to ensure data consistency and validation.

Key Data Types

The types defined in agent-packages/packages/jira/src/types/index.ts model the responses from the Jira API.

• JiraIssueResponse: Represents a full Jira issue object.
• JiraUserResponse: Represents a Jira user account.
• JiraCommentResponse: Represents a comment on an issue.
• JiraProjectResponse: Represents a Jira project, including its issue types.

Sources: agent-packages/packages/jira/src/types/index.ts

Input Validation Schemas

Zod schemas are used to validate the arguments passed to each tool before execution. This prevents invalid data from being sent to the Jira API. For example, the schema for creating an issue defines all required and optional fields.

// Example from agent-packages/packages/jira/src/schema.ts
export const createJiraIssueSchema = z.object({
  projectKey: z.string().describe('The key of the Jira project (e.g., "PROJ")'),
  summary: z.string().describe('A brief, descriptive title for the issue'),
  issueTypeId: z.string().describe('The ID of the issue type (e.g., "10001" for Bug)'),
  // ... other fields
});

Sources: agent-packages/packages/jira/src/schema.ts:31-44

Testing

The Jira agent's functionality is validated through a suite of tests that use a real LLM against a set of mocked tools. This approach ensures that the agent can correctly interpret user requests, plan the necessary steps, and call the right tools with the correct arguments.

• Test Cases (test-data.ts): A comprehensive list of TestCase objects defines various user invocations, chat histories, expected tool calls, and mock responses from the tools.
• Mocking (mock.ts): The createJiraMockedTools function generates mock versions of the Jira tools that return predefined data based on the test case, simulating API responses without making actual network calls.
• Evaluation (index.spec.ts): The createTrajectoryMatchEvaluator from the agentevals library is used to compare the agent's actual tool calls (the "trajectory") against the reference_tool_calls defined in the test case. This provides a score indicating whether the agent behaved as expected.

Sources: src/llm/agent-evals/jira-agent/test-data.ts:4, src/llm/agent-evals/jira-agent/mock.ts:246, src/llm/agent-evals/jira-agent/index.spec.ts:10, 37-47