Tutorial · Jira agent

Jira AI agent: triage, summarize and route

A useful Jira agent reads the issue, finds related work, proposes a category, priority and owner, and then stops. The write is a separate, approved step.

Short answer. Register a signed Jira webhook, enqueue the event, fetch the full issue, classify it with a structured-output prompt, search for duplicates with JQL and embeddings, and write nothing until a human approves the proposed assignee, priority or transition. Log every decision with the webhook identifier so retries are idempotent.

1. Put a write boundary around the agent

Jira is a system of record, and a wrong transition can hide work from the team that needs it. Separate the agent into a read phase and a write phase. The read phase can run automatically. The write phase should require an approval, or at minimum a policy that names which actions are safe to auto-apply.

ActionAuto-apply?Approval needed
Add a triage label or commentYes, if policy allowsNone, but log it.
Set priority or componentNo by defaultIssue owner or triage lead.
Assign to a personNoTeam lead, because workload is not in the issue.
Transition statusNoProject admin or workflow owner.
Merge or close as duplicateNoIssue owner; show the candidate links.

This boundary is also a security control. The model never holds a token that can write; a separate policy service holds the token and applies only the actions that are allowlisted or approved.

2. Register and verify the webhook

Create an admin webhook for jira:issue_created and jira:issue_updated, scoped with JQL to the projects you triage. Add a secret so Jira signs the body with HMAC. The signature arrives in X-Hub-Signature as method=signature, for example sha256=....

import hmac, hashlib

def verify(secret: str, body: bytes, header: str) -> bool:
    method, _, signature = header.partition("=")
    if method != "sha256":
        return False
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Respond with 200 quickly and enqueue the payload; do not run the model inside the webhook request. Jira retries failed deliveries up to five times with a randomized backoff, and the same X-Atlassian-Webhook-Identifier is reused across retries. Store that identifier and drop duplicates before you process the event.

3. Read the issue and find context

The webhook includes the issue, but fields can be truncated or stale. Fetch the full issue with GET /rest/api/3/issue/{issueIdOrKey}, then search for related work. The issue schema is large, so request only the fields the task needs. Use the enhanced JQL endpoint, POST /rest/api/3/search/jql. The legacy /rest/api/3/search endpoint has been removed and returns 410 Gone.

POST /rest/api/3/search/jql
{
  "jql": "project = OPS AND text ~ \"checkout timeout\" ORDER BY created DESC",
  "fields": ["key", "summary", "status", "assignee", "labels", "created"],
  "maxResults": 50
}

Always pass fields; the enhanced endpoint defaults to IDs only. Paginate with nextPageToken, not startAt, and do not expect a total count. If you need a count for a dashboard, use /rest/api/3/search/approximate-count.

4. Classify and detect duplicates

Ask for a JSON object with a fixed schema: summary, category, priority, suggested_team, duplicate_candidates, confidence and reason. Validate the response against the schema before you use it. If the model returns an unknown category or a confidence below your threshold, route the issue to a human queue instead of guessing.

{
  "summary": "Checkout callback times out after payment; three reports since 09:00.",
  "category": "bug",
  "priority": "high",
  "suggested_team": "checkout",
  "duplicate_candidates": ["OPS-1842", "OPS-1799"],
  "confidence": 0.82,
  "reason": "Timeout on payment callback; same stack trace as OPS-1842."
}

The summary is for humans, so keep it to two factual sentences and ground it in fields the issue actually contains. Do not let the model invent customer impact, revenue or root cause. Post the summary as a comment only after approval, and label it as an agent-generated draft so readers know where it came from.

For duplicates, combine retrieval methods. A JQL text search finds lexical matches; plugsky-embed over summaries finds semantic matches; the model adjudicates the top few candidates. Never auto-merge. Show the candidate keys, summaries and links, and let the owner decide.

5. Approve, then write

Fetch the available transitions before proposing one. The API needs a transition ID, not a status name, and the IDs differ between workflows.

GET  /rest/api/3/issue/OPS-2001/transitions
POST /rest/api/3/issue/OPS-2001/transitions
{ "transition": { "id": "31" } }

PUT  /rest/api/3/issue/OPS-2001/assignee
{ "accountId": "5b10ac8d82e05b22cc7d4ef5" }

Comments and descriptions use the Atlassian Document Format, not raw HTML. Build a small ADF helper and validate it before sending. After the write, store the approval ID, the actor, the before and after values, the model version and the prompt version. That record is what lets you answer "why did this issue move?" three weeks later.

6. Cost and failure modes

FailureSymptomControl
Duplicate deliveryTwo comments or two transitionsIdempotency key from the webhook identifier.
Stale issueAgent acts on an old statusRe-fetch the issue before the write.
Unknown transition400 from the transitions endpointFetch transitions and validate the ID.
Permission denied403 on assign or transitionUse a dedicated integration account and test its project roles.
Cost spikeEvery edit triggers a full searchFilter on changed fields and cache duplicate candidates.

Cost is roughly one classification call plus one adjudication call per new issue, plus embedding calls for duplicate candidates. On Plugsky, paid plans start at $8/month; Builder and Scale have no monthly token cap under fair-use concurrency and RPM limits. See pricing for the current plan details.

For the broader operating model, see build an AI operations agent and the agent tool permissions guide.

FAQ

Can Jira webhooks trigger an AI agent?

Yes. Register a signed admin webhook for issue events, verify the X-Hub-Signature HMAC, enqueue the payload, and process it asynchronously so the webhook returns quickly.

How do I prevent duplicate processing?

Store X-Atlassian-Webhook-Identifier and ignore repeats. Jira retries failed deliveries and reuses the identifier across retries.

Can the agent assign issues automatically?

It can propose an assignee, but assignment should require approval because the issue does not contain workload or on-call context. Keep the write behind an approval service.

Which Jira search endpoint should I use?

Use POST /rest/api/3/search/jql with explicit fields and nextPageToken. The legacy /rest/api/3/search endpoint has been removed and returns 410 Gone.

How much does a Jira triage agent cost?

Budget one classification call and one duplicate-adjudication call per new issue, plus embeddings. Plugsky paid plans start at $8/month; Builder and Scale have no monthly token cap under fair-use limits.

Sources checked 20 November 2026: Jira Cloud webhooks; Jira issue search API; Atlassian Document Format. Product behavior, endpoint support and plan limits can change; re-check the primary documentation before production rollout.