Run.startAsync()

.startAsync() 方法會啟動 Workflow run，而不會等待執行完成。它會立即傳回 runId，讓 Workflow 在背景執行。這適合需長時間執行的 Workflow 或排程任務，亦可避免因等待 Workflow 完成而阻塞。

使用範例

const run = await workflow.createRun()

// Fire-and-forget - returns immediately
const { runId } = await run.startAsync({
  inputData: {
    value: 'initial data',
  },
})

// Optionally poll for completion later
const result = await workflow.getWorkflowRunExecutionResult(runId)

參數

inputData?:

z.infer<TInput>

符合 Workflow 輸入 schema 的輸入資料

requestContext?:

RequestContext

執行 Workflow 期間使用的 Request Context 資料

initialState?:

z.infer<TState>

執行 Workflow 時使用的初始狀態

tracingOptions?:

TracingOptions

Tracing 設定選項。

metadata?:

Record<string, any>

要加入 root trace span 的 metadata。適合加入使用者 ID、session ID 或 feature flag 等自訂屬性。

traceId?:

string

這次執行使用的 Trace ID（1 至 32 個十六進位字元）。如有提供，這個 trace 將成為指定 trace 的一部分。

outputOptions?:

OutputOptions

輸出設定選項。

includeState?:

boolean

是否在結果中包含 Workflow run 狀態。

傳回值

runId:

string

這次 Workflow run 的唯一識別碼。可用於稍後檢查狀態或擷取結果。

何時使用 startAsync()

在以下情況，請使用 startAsync() 而非 start()：

• 需長時間執行的 Workflow：Workflow 可能需數分鐘或數小時才能完成
• 排程／cron 觸發器：你想觸發 Workflow，而不阻塞排程器
• 避免輪詢失敗：對於 Inngest Workflow，start() 會輪詢執行結果，過程可能失敗並觸發重試。startAsync() 可避免此問題
• 背景處理：你想將工作加入佇列，並以非同步方式處理結果

檢查 Workflow 狀態

呼叫 startAsync() 後，你可以使用以下方式檢查 Workflow 狀態：

// Get the execution result (including step outputs)
const result = await workflow.getWorkflowRunExecutionResult(runId)

if (result?.status === 'success') {
  console.log('Workflow completed:', result.steps)
} else if (result?.status === 'failed') {
  console.log('Workflow failed:', result.error)
} else if (result?.status === 'running') {
  console.log('Workflow still running...')
}

相關內容

• Run.start()：啟動 Workflow 並等待執行完成
• Workflows 概覽
• Workflow.createRun()