Example: Build a Jira Agent
Example: Build a Jira Agent
This walkthrough builds jira-assistant, a persona agent that searches and summarizes Jira issues, drafts new tickets, and adds comments. In chat, read-only lookups run on their own, and anything that creates or changes an issue waits for your approval. Scheduled and webhook runs work differently: see Run it on a schedule.
Allow about 15 minutes.
Which Jira setup do you need?
Aiden uses Jira in two different ways. Pick the one that matches your goal:
| Goal | Setup | Guide |
|---|---|---|
| Pull Jira tickets into the Aiden DevOps Requests Inbox for triage and approved workflows | Connect Jira from Aiden DevOps -> Integrations | Connect your ticketing system |
| Chat with an agent that searches, summarizes, creates, or comments on Jira issues | Connect Jira under Workspace Settings and attach it to a persona agent | This page |
You can do both.
Before you begin
- You are an Admin or Workspace Admin.
- You have Jira credentials:
| Jira type | Credentials |
|---|---|
| Jira Cloud | Your Atlassian account email and an API token |
| Jira Server / Data Center | A username and password, or a personal access token (PAT) |
- The account can read the projects the agent should see. Add create and comment permissions only if you want the agent to write.
- Your Jira site URL uses
https://, and Aiden can reach it. The Jira integration cannot run on a remote runner, so a Jira site that is only reachable inside your private network will not connect.
Start with a sandbox project or a read-only Jira account. Widen access after you trust the agent's behavior.
Step 1: Connect Jira
- Open Workspace Settings -> Connections -> Integrations.
- Click Add integration and choose Jira.
- Fill in the form:
| Field | Example | Notes |
|---|---|---|
| Name | jira-prod | Unique name for this connection |
| Description | Jira Cloud for the platform team. Used to search, summarize, and update issues in project PLAT. | Required. Type a short sentence, then click Enhance if you want Aiden to expand it |
| Jira site URL | https://your-org.atlassian.net | For Server / Data Center, use the full base URL, including any context path such as /jira |
| Atlassian account email | you@example.com | Cloud: your Atlassian email. Server / Data Center: your username. Leave empty only when you use a Server / Data Center PAT |
| API token | (your token) | Cloud: Atlassian API token. Server / Data Center: password or PAT |
| Attach to | Leave empty | Optional. See below |
- Click Add integration.
What about Attach to? You do not need an agent before you connect Jira. Leave Attach to empty here and attach Jira to the agent in Step 3. If you also want the Aiden DevOps app to use this connection, pick Aiden DevOps under Apps. See Attach to.
Expected result: jira-prod appears in the Integrations list.
Step 2: Create the agent
- Open Workspace Settings -> Agents and automation -> Agents.
- Click New Agent.
- Fill the dialog using one of the two options below.
- Click Create Agent.
Option A: Use Assist me
Paste this into Assist me, change PLAT to your project key, then click Generate:
Create a Jira assistant for our platform team. It searches and summarizes
Jira issues in project PLAT, drafts new tickets from a description, and adds
comments. It always uses bounded searches with a result limit. It must show
the exact change and wait for confirmation before creating, updating, or
transitioning any issue, and it never deletes issues.
Review the generated Name and Personality (System Prompt). Compare it with Option B and add anything it missed.
Option B: Paste the fields
Name
jira-assistant
Personality (System Prompt)
Replace PLAT and the team name with your own values:
You are jira-assistant, a Jira helper for the platform team.
Your job:
- Find, search, and summarize Jira issues.
- Draft new issues from a user's description.
- Add comments to existing issues.
Scope:
- Default to project PLAT unless the user names another project.
- Only work with Jira. If a request needs another system, say so.
How to work:
- At the start of a conversation, check whether the site is Jira Cloud or
Jira Server / Data Center (read /rest/api/2/serverInfo) and use the
matching API paths. Cloud uses /rest/api/3, Server / Data Center uses
/rest/api/2. On Cloud API v3, descriptions and comments use Atlassian
Document Format.
- If the user gives an issue key such as PLAT-123, fetch that issue
directly.
- Every search must use JQL with a project or time bound and a result
limit of 25 or fewer. Example:
project = PLAT AND updated >= -7d ORDER BY updated DESC
- Base every answer on Jira results. If a search returns nothing, or Jira
returns 401 or 403, say which one happened. Never invent issues.
Creating or changing issues:
- Before you create, update, transition, or comment, show the project,
issue type, summary, description, and any fields you will set. Wait for
the user to confirm.
- Never delete issues.
- Never print API tokens or other credentials.
Output:
- For one issue: key, summary, status, assignee, priority, labels, last
updated, and a link.
- For several issues: a table with key, summary, status, assignee, and
updated, newest first.
- Start with a one-line summary of what you found.
Expected result: jira-assistant appears in the Agents list.
Step 3: Attach Jira to the agent
- Click
jira-assistantto open it. - Select the Integrations tab.
- Under Attach an integration, choose
jira-prod. - Click Attach.
Alternatively, edit jira-prod on the Integrations page and pick jira-assistant under Attach to > Agents.
Expected result: a jira-prod card appears with a tool count. Click the count to see the Jira tools. Each name starts with the integration's name, so with an integration named jira-prod you see:
| Tool | What it does | Suggested setting |
|---|---|---|
jira-prod_jira_get | Read from the Jira REST API: issues, searches, projects | Auto-approve |
jira-prod_jira_post | Create things: issues, comments, and status transitions | Require approval |
jira-prod_jira_put | Update or replace data on an issue | Require approval |
jira-prod_jira_patch | Partially update data | Require approval |
jira-prod_jira_delete | Delete things | Require approval, and consider a policy that denies it |
If you named the integration something else, the prefix changes to match.
If the card shows a count but no tool names, open jira-prod's More actions menu on the Integrations page and click Refresh.
Step 4: Auto-approve read-only lookups
Without this step, every Jira lookup in chat pauses for approval.
- Select the Tools tab.
- Click Manage auto-approved tools.
- Search for
jira_getand selectjira-prod_jira_get. - Click Save.
Expected result: jira-prod_jira_get is listed under Auto-Approved. The other Jira tools still require approval in chat.
Note that jira-prod_jira_post creates issues, adds comments, and moves issues between statuses. Keep it on approval unless you are comfortable with the agent doing all three without asking.
Step 5: Test the agent
- Click Talk to Agent.
- Try a read-only request first:
Summarize PLAT issues updated in the last 7 days.
What is the status of PLAT-123, and who is working on it?
List open bugs in PLAT with priority High or Highest.
Expected result: the agent answers from real Jira data without asking for approval.
- Then try a write request:
Create a task in PLAT: "Rotate staging database credentials". Description:
Rotate the staging DB password and update the secret in Vault. Priority Medium.
Expected result: the agent shows what it will create. When it calls jira-prod_jira_post, an approval card with Approve and Reject appears in the conversation. The request also appears in Approvals. After you approve, the agent replies with the new issue key.
Your team can now reach the agent from Aiden Chat by typing @jira-assistant.
Variations
Read-only agent
Replace the "Creating or changing issues" section of the prompt with:
Read-only:
- You never create, update, transition, comment on, or delete issues.
- If the user asks for a change, describe what they should do in Jira.
Then auto-approve only jira-prod_jira_get. The prompt alone is not a guarantee. For a hard limit, connect Jira with a read-only account, or assign a policy that denies the other Jira tools.
Ticket drafter
Add a template to the prompt so new issues follow your format:
When drafting an issue, use this description format:
Background: <why this is needed>
Acceptance criteria: <bullet list>
Links: <related issues or docs>
Default issue type: Task. Default labels: platform.
Run it on a schedule
Create an automation that targets jira-assistant with a prompt such as Summarize PLAT issues that changed since yesterday and sends the result to a notification channel.
Scheduled and webhook runs have no one to approve tool calls, so every tool runs without approval, including jira-prod_jira_post and jira-prod_jira_delete. A prompt, or text inside an issue the agent reads, could lead it to create, change, or delete issues with no approval card. Before you schedule this agent, assign a policy that denies the Jira write tools for it, or connect Jira with a read-only account. See Runs with no one watching.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Agent says it has no Jira tools | Jira is not attached to this agent, or the integration is disabled | Check the agent's Integrations tab. Attach jira-prod and confirm it is enabled |
| Attach to on the Jira form lists no agents | No persona agents exist yet | Leave it empty, create the agent, then attach from the agent's Integrations tab |
| Attach an integration is missing on the agent | Every enabled integration is already attached, or none is connected | Connect Jira under Integrations, or check that it is enabled |
| Every lookup asks for approval | jira-prod_jira_get is not auto-approved | Complete Step 4 |
| The agent changed Jira during a scheduled or webhook run without asking | Unattended runs approve every tool | Assign a policy that denies the Jira write tools, or use a read-only Jira account. See Run it on a schedule |
| Jira returns 401 | Wrong email, token, or auth type | Cloud needs email plus API token. Server / Data Center with a PAT needs the email field empty |
| Jira returns 403 or empty results | The Jira account cannot see the project | Grant project access in Jira, or use an account that has it |
| Connection fails with a URL error | The site URL is not https://, or includes a query string or credentials | Use a plain base URL such as https://your-org.atlassian.net |
| Connection times out | Aiden cannot reach the Jira site, for example because it is only reachable inside your network | The Jira integration cannot run on a remote runner. Make the site reachable over HTTPS, or contact support@stackgen.com |
| Agent searches the wrong project | The prompt does not set a default project | Edit the Persona tab and set the default project key |