Developer
News and Updates
Get Support
Sign in
Get Support
Sign in
DOCUMENTATION
Cloud
Data Center
Resources
Sign in
Sign in
DOCUMENTATION
Cloud
Data Center
Resources
Sign in
Runtimes
Web triggers
Async events
Workflows
Realtime events
Dynamic Modules
Customer-managed egress and remotes
License API
Installation Details API
Atlassian app REST APIs
Fetch APIs
LLMs API
Last updated Nov 18, 2026

Forge Workflows examples

Forge Workflows (@forge/workflows) is under development and is not yet available. These pages describe the planned API, which may change before release.

For more details, see Forge EAP, Preview, and GA.

These examples show complete workflows for common AI use cases. Each one makes tasks with task(), chains steps onto the future that a task call gives you, and calls .start() to start a run. For an introduction to tasks, futures and chains, see Forge Workflows API.

The examples call the Forge LLMs API (@forge/llm). They call Jira and Confluence through small helpers, such as getIssue and addComment. Those helpers are your own code: for example, addComment might call api.asApp().requestJira(). Steps have no user context, so call Atlassian APIs with asApp().

The examples read the model's reply with this helper, because the reply can be either a string or a list of text parts:

1
2
3
4
5
6
7
8
9
// llm.ts
import type { ChatResponse } from '@forge/llm';

/** The text of the model's reply. */
export const textOf = (response: ChatResponse): string => {
  const { content } = response.choices[0].message;
  return typeof content === 'string' ? content : content.map((part) => part.text).join('');
};

Agent tool-call loop

An agent answers a question about an issue. On each turn, the model either asks to call tools, such as searching Jira or reading an issue, or gives its final answer. Each turn is one iteration of a .loop(), and runs in its own invocation, so a long conversation never runs into the function timeout.

Diagram: the startConversation task passes the conversation to the agentTurn task, which runs once per model turn, in its own invocation, for at most 10 turns. When it returns done(answer), a step posts the answer as a comment. If any step fails, the catch step posts an explanation instead.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
import { chat } from '@forge/llm';
import { textOf } from './llm';
import type { Message, ToolCall, ToolSchema } from '@forge/llm';
import { done, next, task } from '@forge/workflows';
import { addComment, getIssue, searchIssues } from './jira';

const MODEL = 'claude-opus-4-6';

const TOOLS: ToolSchema[] = [
  {
    type: 'function',
    function: {
      name: 'search_issues',
      description: 'Search Jira issues with JQL. Returns issue keys and summaries.',
      parameters: { type: 'object', properties: { jql: { type: 'string' } }, required: ['jql'] }
    }
  },
  {
    type: 'function',
    function: {
      name: 'get_issue',
      description: 'Get the summary, description and status of a Jira issue.',
      parameters: { type: 'object', properties: { key: { type: 'string' } }, required: ['key'] }
    }
  }
];

interface Conversation {
  messages: Message[];
}

const runTool = async (call: ToolCall): Promise<Message> => {
  // Tool arguments can arrive as a JSON string.
  const raw: unknown = call.function.arguments;
  const args = (typeof raw === 'string' ? JSON.parse(raw) : raw) as Record<string, string>;
  const result = call.function.name === 'search_issues' ? await searchIssues(args.jql) : await getIssue(args.key);
  return { role: 'tool', tool_call_id: call.id, name: call.function.name, content: JSON.stringify(result) };
};

// Builds the opening conversation from the issue.
const startConversation = task(async (issueKey: string, question: string): Promise<Conversation> => {
  const issue = await getIssue(issueKey);
  return {
    messages: [
      { role: 'system', content: 'You are a Jira assistant. Use the tools to look things up before answering.' },
      { role: 'user', content: `Issue ${issueKey}: ${issue.summary}\n\n${question}` }
    ]
  };
});

// One model turn. Runs the tools the model asks for, or finishes with its answer.
const agentTurn = task(async (conversation: Conversation) => {
  const response = await chat({ model: MODEL, messages: conversation.messages, tools: TOOLS });
  const message = response.choices[0].message;
  if (!message.tool_calls?.length) {
    return done(textOf(response));
  }
  const toolResults = await Promise.all(message.tool_calls.map(runTool));
  return next({ messages: [...conversation.messages, message, ...toolResults] });
});

export const answerQuestion = (issueKey: string, question: string) =>
  startConversation(issueKey, question)
    .loop(agentTurn, { maxIterations: 10 })
    .pipe((answer) => addComment(issueKey, answer))
    .catch((error) => addComment(issueKey, `I couldn't answer that: ${error.message}`))
    .start();
  • The conversation is the loop's state. It's passed from one iteration to the next, so it must be plain JSON data and stay under the 240 KB value limit.
  • The loop starts after startConversation, because the first message needs the issue. If the first state needs no work, start the chain with loop(agentTurn, initialState) instead.
  • maxIterations limits the number of model turns. If the model is still calling tools after 10 turns, the loop fails with code LOOP_LIMIT, and the .catch() step posts an explanation.
  • The tools run in the same invocation as the model turn that asked for them. If a tool is slow, make it a separate task.

Bulk triage

Classify every open issue in a project with an LLM, and label it. A scheduled trigger finds the issues and starts the workflow. The workflow handles up to 10 issues at once, and posts a summary when every issue is done.

Diagram: the scheduled trigger starts triage, which calls the triageIssue task once for every issue, at most 10 at once. collect() with settle: true passes every result, fulfilled or rejected, to a step that posts a summary comment.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
import { chat } from '@forge/llm';
import { textOf } from './llm';
import { task } from '@forge/workflows';
import { addComment, addLabel, getIssue, searchIssues } from './jira';

const LABELS = ['bug', 'feature-request', 'question', 'support'];

// One issue: classify it and apply the label. Retries cover rate limits from the model or Jira.
const triageIssue = task(
  async (issueKey: string) => {
    const issue = await getIssue(issueKey);
    const response = await chat({
      model: 'claude-opus-4-6',
      messages: [
        { role: 'system', content: `Classify the Jira issue. Reply with exactly one of: ${LABELS.join(', ')}.` },
        { role: 'user', content: `${issue.summary}\n\n${issue.description ?? ''}` }
      ]
    });
    const label = textOf(response)
      .trim()
      .toLowerCase()
      .replace(/[^a-z-]/g, '');
    if (!LABELS.includes(label)) throw new Error(`Unexpected label '${label}'`);
    await addLabel(issueKey, label);
    return label;
  },
  { retry: { attempts: 4, backoffSeconds: 5, retryAll: true } }
);

export const triage = (issueKeys: string[], reportIssueKey: string) =>
  issueKeys
    .map(triageIssue)
    .collect({ concurrency: 10, settle: true }) // one bad issue doesn't stop the rest
    .pipe((results) => {
      const failed = results.filter((result) => result.status === 'rejected').length;
      return addComment(reportIssueKey, `Triaged ${results.length - failed} issues; ${failed} failed.`);
    })
    .start();

// Scheduled trigger: find the issues, then start the workflow.
export const nightlyTriage = async () => {
  const issues = await searchIssues('project = SUP AND labels is EMPTY AND statusCategory != Done');
  await triage(
    issues.map((issue) => issue.key),
    'SUP-1'
  );
};
  • The scheduled trigger finds the issues before it starts the run, because map() needs its list of items when the run starts.
  • With settle: true, each result is { status: 'fulfilled', value } or { status: 'rejected', reason }. The summary can report failed issues, and one failure doesn't fail the whole run.
  • Each issue is classified and labelled in one task call. A step can occasionally run twice, and labelling an issue twice is harmless.

Map-reduce summary

Summarise many Confluence pages in parallel, then combine the summaries into one overview.

Diagram: the summarisePage task runs once for every page, at most 20 at once. collect() passes the summaries to the combine task, which passes the overview to a step that updates the overview page.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import { chat } from '@forge/llm';
import { textOf } from './llm';
import { chunk, task } from '@forge/workflows';
import { getPageText, updatePage } from './confluence';

const ask = async (prompt: string) => {
  const response = await chat({ model: 'claude-opus-4-6', messages: [{ role: 'user', content: prompt }] });
  return textOf(response);
};

const summarisePage = task(async (pageId: string) =>
  ask(`Summarise in 3 sentences:\n\n${await getPageText(pageId)}`)
);

// Combine in batches of 20, so no single prompt gets too long, then combine the batches.
const combine = task(async (summaries: string[]) => {
  const batches = await Promise.all(
    chunk(summaries, 20).map((batch) => ask(`Combine these summaries into one paragraph:\n\n${batch.join('\n\n')}`))
  );
  return batches.length === 1 ? batches[0] : ask(`Combine into one overview:\n\n${batches.join('\n\n')}`);
});

export const summariseSpace = (pageIds: string[], overviewPageId: string) =>
  pageIds
    .map(summarisePage)
    .collect({ concurrency: 20 })
    .pipe(combine)
    .pipe((overview) => updatePage(overviewPageId, overview))
    .start();
  • collect() passes every page summary to combine as one value, so together they must fit within the 240 KB value limit.
  • chunk() splits the summaries into batches of 20, and combine sends each batch to the model in the same invocation.

Human approval

Draft release notes with an LLM, wait up to 3 days for someone to approve them, then publish them. A UI Kit panel shows the draft, and calls a resolver that sends the approval signal.

Diagram: the draftNotes task saves a draft, then the run waits in waitForSignal('approval') for up to 3 days until the decide resolver calls runs.signal. If approved, a step publishes the notes; otherwise the result is 'discarded'. If any step fails, the catch step returns 'expired' for a timeout, or throws.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
import Resolver from '@forge/resolver';
import { kvs } from '@forge/kvs';
import { chat } from '@forge/llm';
import { textOf } from './llm';
import { runs, task, waitForSignal } from '@forge/workflows';
import { canApproveReleases } from './auth';
import { publishReleaseNotes } from './confluence';

interface Decision {
  approved: boolean;
  notes: string;
}

const draftNotes = task(async (version: string) => {
  const response = await chat({
    model: 'claude-opus-4-6',
    messages: [{ role: 'user', content: `Draft release notes for version ${version}.` }]
  });
  const draft = textOf(response);
  await kvs.set(`release-draft:${version}`, draft); // the panel shows this
  return draft;
});

export const releaseNotes = (version: string) =>
  draftNotes(version)
    .pipe(() => waitForSignal<Decision>('approval', { timeoutSeconds: 3 * 24 * 60 * 60 }))
    .pipe((decision) => (decision.approved ? publishReleaseNotes(version, decision.notes) : 'discarded'))
    .catch((error) => {
      if (error.code === 'SIGNAL_TIMEOUT') return 'expired';
      throw new Error(error.message);
    })
    .start();

const resolver = new Resolver();

resolver.define('startRelease', async ({ payload }) => {
  const { runId } = await releaseNotes(payload.version);
  await kvs.set(`release-run:${payload.version}`, runId);
  return { runId };
});

// Resolvers return objects, so the frontend gets { draft } rather than a bare string.
resolver.define('draft', async ({ payload }) => ({ draft: await kvs.get<string>(`release-draft:${payload.version}`) }));

resolver.define('decide', async ({ payload, context }) => {
  // Replace this with your app's authorization check.
  if (!(await canApproveReleases(context.accountId))) throw new Error('Not allowed');
  const runId = await kvs.get<string>(`release-run:${payload.version}`);
  if (!runId) return { resolved: false };
  return { resolved: await runs.signal(runId, 'approval', { approved: payload.approved, notes: payload.notes }) };
});

// Look the run up by version rather than accepting a run ID, so the panel can only read this workflow's runs.
resolver.define('status', async ({ payload }) => {
  const runId = await kvs.get<string>(`release-run:${payload.version}`);
  return runId ? runs.get(runId) : undefined;
});

export const handler = resolver.getDefinitions();
  • The panel gets the draft from the draft resolver. The approver can edit it before approving, because the signal carries the final notes.
  • runs.signal returns false if the run isn't waiting any more, for example because it already timed out.
  • canApproveReleases is an app-specific authorization check. Steps run with the app's permissions, so anyone who can send the signal can publish.

Incident response

Classify an issue. If it's an outage, page the on-call team, draft a stakeholder update, and post it. Otherwise, label the issue with its severity. The outage branch takes three steps, so it's a sub-workflow: a named function that returns a chain without .start(). The .pipe() step calls it like a task, and the run continues once all three of its steps have finished.

Diagram: the classifySeverity task passes the severity to a step. For P1 issues, the step calls the escalate sub-workflow, which runs the page, draftUpdate and postUpdate tasks in turn, each in its own invocation. For P2 and P3 issues, it calls the labelSeverity task. The run continues once whichever branch it took has finished.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
import { chat } from '@forge/llm';
import { textOf } from './llm';
import { task } from '@forge/workflows';
import { addComment, addLabel, getIssue, notifyOnCall } from './jira';

const classifySeverity = task(async (issueKey: string) => {
  const issue = await getIssue(issueKey);
  const response = await chat({
    model: 'claude-opus-4-6',
    messages: [
      {
        role: 'system',
        content:
          'Rate the severity of this Jira issue. P1 means an outage for many customers. Reply with P1, P2 or P3 only.'
      },
      { role: 'user', content: `${issue.summary}\n\n${issue.description ?? ''}` }
    ]
  });
  return textOf(response).match(/P[123]/)?.[0] ?? 'P3';
});

const page = task(async (issueKey: string) => notifyOnCall(issueKey));

const draftUpdate = task(async (issueKey: string) => {
  const issue = await getIssue(issueKey);
  const response = await chat({
    model: 'claude-opus-4-6',
    messages: [
      {
        role: 'system',
        content: 'Write a two-sentence incident update for stakeholders: what is affected, and what happens next.'
      },
      { role: 'user', content: `${issue.summary}\n\n${issue.description ?? ''}` }
    ]
  });
  return textOf(response);
});

const postUpdate = task(async (issueKey: string, update: string) => {
  await addLabel(issueKey, 'incident');
  await addComment(issueKey, `Incident update: ${update}`);
});

const labelSeverity = task(async (issueKey: string, severity: string) =>
  addLabel(issueKey, `severity-${severity.toLowerCase()}`)
);

// A sub-workflow: returned without .start(). Each task call in it runs in its own invocation.
const escalate = (issueKey: string) =>
  page(issueKey)
    .pipe(() => draftUpdate(issueKey))
    .pipe((update) => postUpdate(issueKey, update));

export const respondToIncident = (issueKey: string) =>
  classifySeverity(issueKey)
    .pipe((severity) => (severity === 'P1' ? escalate(issueKey) : labelSeverity(issueKey, severity)))
    .start();
  • Each task call in escalate runs in its own invocation, so drafting the update doesn't share the page step's time limit.
  • If a step in escalate fails, the .pipe() step that called it fails with the same error. Add a .catch() after it to handle the failure.
  • To run escalate for many issues at once, use issueKeys.map(escalate).collect().

Model fallback

Give the primary model 60 seconds. If it times out or fails, retry once with a fallback model.

Diagram: the primary task runs with a 60-second timeout and no retries. If it succeeds, a step posts its reply as a comment. If it fails, the catch calls the fallback task, and its reply goes to the same step.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { chat } from '@forge/llm';
import { textOf } from './llm';
import { task } from '@forge/workflows';
import { addComment } from './jira';

const ask = (model: string) =>
  task(
    async (prompt: string) => {
      const response = await chat({ model, messages: [{ role: 'user', content: prompt }] });
      return textOf(response);
    },
    { timeoutSeconds: 60, retry: { attempts: 1 } }
  );

const primary = ask('claude-opus-4-6');
const fallback = ask('claude-sonnet-4-6');

export const draftReply = (issueKey: string, prompt: string) =>
  primary(prompt)
    .catch(() => fallback(prompt))
    .pipe((reply) => addComment(issueKey, reply))
    .start();
  • retry: { attempts: 1 } turns off retries for the primary model, so a timeout goes straight to the fallback.
  • The .catch() step can use prompt because it's a parameter of draftReply. Parameters are saved when the run starts.

Rate this page: