Skip to main content
10 min read

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.

Available for roles: Admin Workspace Admin

Scope: Workspace

Which Jira setup do you need?​

Aiden uses Jira in two different ways. Pick the one that matches your goal:

GoalSetupGuide
Pull Jira tickets into the Aiden DevOps Requests Inbox for triage and approved workflowsConnect Jira from Aiden DevOps -> IntegrationsConnect your ticketing system
Chat with an agent that searches, summarizes, creates, or comments on Jira issuesConnect Jira under Workspace Settings and attach it to a persona agentThis page

You can do both.

Before you begin​

  • You are an Admin or Workspace Admin.
  • You have Jira credentials:
Jira typeCredentials
Jira CloudYour Atlassian account email and an API token
Jira Server / Data CenterA 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.
tip

Start with a sandbox project or a read-only Jira account. Widen access after you trust the agent's behavior.

Step 1: Connect Jira​

  1. Open Workspace Settings -> Connections -> Integrations.
  2. Click Add integration and choose Jira.
  3. Fill in the form:
FieldExampleNotes
Namejira-prodUnique name for this connection
DescriptionJira 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 URLhttps://your-org.atlassian.netFor Server / Data Center, use the full base URL, including any context path such as /jira
Atlassian account emailyou@example.comCloud: 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 toLeave emptyOptional. See below
  1. 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​

  1. Open Workspace Settings -> Agents and automation -> Agents.
  2. Click New Agent.
  3. Fill the dialog using one of the two options below.
  4. 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​

  1. Click jira-assistant to open it.
  2. Select the Integrations tab.
  3. Under Attach an integration, choose jira-prod.
  4. 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:

ToolWhat it doesSuggested setting
jira-prod_jira_getRead from the Jira REST API: issues, searches, projectsAuto-approve
jira-prod_jira_postCreate things: issues, comments, and status transitionsRequire approval
jira-prod_jira_putUpdate or replace data on an issueRequire approval
jira-prod_jira_patchPartially update dataRequire approval
jira-prod_jira_deleteDelete thingsRequire 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.

  1. Select the Tools tab.
  2. Click Manage auto-approved tools.
  3. Search for jira_get and select jira-prod_jira_get.
  4. 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​

  1. Click Talk to Agent.
  2. 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.

  1. 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.

warning

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​

SymptomLikely causeFix
Agent says it has no Jira toolsJira is not attached to this agent, or the integration is disabledCheck the agent's Integrations tab. Attach jira-prod and confirm it is enabled
Attach to on the Jira form lists no agentsNo persona agents exist yetLeave it empty, create the agent, then attach from the agent's Integrations tab
Attach an integration is missing on the agentEvery enabled integration is already attached, or none is connectedConnect Jira under Integrations, or check that it is enabled
Every lookup asks for approvaljira-prod_jira_get is not auto-approvedComplete Step 4
The agent changed Jira during a scheduled or webhook run without askingUnattended runs approve every toolAssign a policy that denies the Jira write tools, or use a read-only Jira account. See Run it on a schedule
Jira returns 401Wrong email, token, or auth typeCloud needs email plus API token. Server / Data Center with a PAT needs the email field empty
Jira returns 403 or empty resultsThe Jira account cannot see the projectGrant project access in Jira, or use an account that has it
Connection fails with a URL errorThe site URL is not https://, or includes a query string or credentialsUse a plain base URL such as https://your-org.atlassian.net
Connection times outAiden cannot reach the Jira site, for example because it is only reachable inside your networkThe Jira integration cannot run on a remote runner. Make the site reachable over HTTPS, or contact support@stackgen.com
Agent searches the wrong projectThe prompt does not set a default projectEdit the Persona tab and set the default project key