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(''); };
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.
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 68import { 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();
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.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.
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 48import { 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' ); };
map() needs its list of items when
the run starts.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.Summarise many Confluence pages in parallel, then combine the summaries into one overview.
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 30import { 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.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.
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 60import 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();
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.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.
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 58import { 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();
escalate runs in its own invocation, so drafting the update doesn't share the page step's
time limit.escalate fails, the .pipe() step that called it fails with the same error. Add a .catch() after
it to handle the failure.escalate for many issues at once, use issueKeys.map(escalate).collect().Give the primary model 60 seconds. If it times out or fails, retry once with a fallback model.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23import { 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..catch() step can use prompt because it's a parameter of draftReply. Parameters are saved when the run
starts.Rate this page: