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

# Jira

> Search, create, and update Jira issues from your agent.

# Jira

Search, create, update issues, and add comments in Jira using the Jira REST API v3.

***

## Quick Start

```typescript theme={null}
import { Agent, openai, JiraToolkit } from "@agentium/core";

const jira = new JiraToolkit({
  baseUrl: "https://yourcompany.atlassian.net",
  // Uses JIRA_EMAIL and JIRA_API_TOKEN env vars
});

const agent = new Agent({
  name: "project-manager",
  model: openai("gpt-4o"),
  instructions: "Help manage Jira issues and sprints.",
  tools: [...jira.getTools()],
});

const result = await agent.run("Find all open bugs in the PROJ project");
```

***

## Config

<ParamField body="baseUrl" type="string" required>
  Jira instance base URL (e.g. `"https://yourcompany.atlassian.net"`).
</ParamField>

<ParamField body="email" type="string">
  Atlassian account email. Falls back to `JIRA_EMAIL` env var.
</ParamField>

<ParamField body="apiToken" type="string">
  Jira API token. Falls back to `JIRA_API_TOKEN` env var.
</ParamField>

***

## Tools

| Tool                 | Description                                                   |
| -------------------- | ------------------------------------------------------------- |
| `jira_search_issues` | Search issues using JQL (Jira Query Language).                |
| `jira_get_issue`     | Get full details of an issue by key (e.g. `PROJ-123`).        |
| `jira_create_issue`  | Create a new issue with project, summary, type, and priority. |
| `jira_update_issue`  | Update fields or transition status on an existing issue.      |
| `jira_add_comment`   | Add a comment to an issue.                                    |

***

## Environment Variables

```bash theme={null}
export JIRA_EMAIL="you@company.com"
export JIRA_API_TOKEN="ATATT..."
```

Create an API token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).

***

## Tool Usage Examples

### Search Issues with JQL

```typescript theme={null}
const result = await agent.run("Find all high-priority bugs assigned to me in the PROJ project");

// The agent calls jira_search_issues with:
// { jql: "project = PROJ AND type = Bug AND priority = High AND assignee = currentUser() ORDER BY created DESC" }
//
// Returns:
// PROJ-142 — Login timeout on slow networks (High, In Progress)
// PROJ-138 — Dashboard charts not rendering (High, Open)
```

### Create Issue

```typescript theme={null}
const result = await agent.run(
  "Create a story in PROJ: 'Add dark mode support' with high priority. " +
  "Description: Implement dark mode toggle in user settings."
);

// The agent calls jira_create_issue with:
// {
//   project: "PROJ",
//   summary: "Add dark mode support",
//   issueType: "Story",
//   priority: "High",
//   description: "Implement dark mode toggle in user settings."
// }
```

### Transition Issue

```typescript theme={null}
const result = await agent.run("Move PROJ-142 to 'In Review'");

// The agent calls jira_update_issue with:
// { issueKey: "PROJ-142", transition: "In Review" }
```

### Add Comment

```typescript theme={null}
const result = await agent.run(
  "Add a comment to PROJ-138: 'Root cause identified — missing polyfill for Chart.js. Fix in PR #245.'"
);

// The agent calls jira_add_comment with:
// {
//   issueKey: "PROJ-138",
//   body: "Root cause identified — missing polyfill for Chart.js. Fix in PR #245."
// }
```