Workflow 장기 실행

Workflow 5 전환 점검

2026-10-23 npm latest는 workflow@5.2.3입니다. "use workflow"·"use step" 경계를 유지하되 다음 호환성을 함께 검토합니다.

• runStep은 제거됐으므로 step 함수를 직접 호출합니다.
• getWorld()·getWorldHandlers()·createWorld()는 비동기입니다. self-hosted worker bootstrap에서 await 누락을 확인합니다.
• getHookByToken()·resumeHook()으로 얻은 hook의 metadata는 Promise이므로 읽을 때 await합니다.
• experimental_setAttributes는 제거됐으며 setAttributes를 사용합니다.
• 중복 step·workflow ID는 build 오류로 처리됩니다. 번들·자체 route를 직접 연결한 앱은 v5 migration 항목도 검토합니다.

AbortSignal을 step에 전달해 실행 중인 요청을 취소할 수 있지만 signal을 무시하는 작업은 계속 실행될 수 있습니다. 취소는 이미 완료한 결제·메일을 되돌리는 동작이 아니므로 side effect의 idempotency key를 보존합니다. hook token retention·force takeover는 승인을 생략하는 기능으로 쓰지 않습니다.

Workflow 5 changes.

에이전트가 실제 업무를 다루기 시작하면 요청-응답 구조만으로는 부족합니다.
승인 대기, 외부 웹훅 재개, 긴 분석 작업, 밤새 돌아가는 배치가 끼어들기 때문입니다. 이럴 때 필요한 건 "더 긴 timeout"이 아니라 durable execution 모델입니다.

Workflow에 올려야 하는 작업

2026년 4월 GA 이후 Vercel Workflows는 "use workflow"와 "use step" directive를 두 축으로 삼습니다. workflow 함수가 오케스트레이션을 맡고, step 함수가 재시도·영속화·관측이 가능한 작업 단위를 맡습니다.

실행 구조

Workflow와 Queue의 경계

step 설계 원칙

예시: 승인 포함 오케스트레이션

import { defineHook, sleep } from 'workflow'

const approvalHook = defineHook<{ approved: boolean; operatorId: string }>()

export async function customerEscalation(ticketId: string) {
  'use workflow'

  const summary = await summarizeTicket(ticketId)
  const approval = approvalHook.create({ token: `ticket:${ticketId}` })
  await sendApprovalRequest({ ticketId, summary, token: approval.token })

  const result = await Promise.race([
    approval,
    sleep('24h').then(() => ({ approved: false, operatorId: 'timeout' })),
  ])

  if (!result.approved) {
    return { status: 'rejected' }
  }

  return executeEscalation(summary)
}

async function summarizeTicket(ticketId: string) {
  'use step'
  return loadAndSummarizeTicket(ticketId)
}

async function executeEscalation(summary: TicketSummary) {
  'use step'
  return dispatchEscalation(summary)
}

승인이 필요한 업무 예시

운영 기준

1. 사용자가 기다리는 요청과 사람이 나중에 확인할 작업을 분리합니다.
2. 승인 전 단계는 읽기 중심으로 설계하고, 쓰기는 승인 뒤에 배치합니다.
3. step payload는 버전 호환성을 고려해 최소 필드만 유지합니다.
4. replay 가능한 설계를 위해 외부 side effect idempotency key를 사용합니다.

ADR 스타일 결론

실무 체크리스트

• 30초 이상 걸리는 작업이 request path에 남아 있지 않은가
• approval 전에 irreversible side effect가 실행되지 않는가
• step payload가 버전 안전한 최소 구조로 유지되는가
• 외부 write가 idempotency key를 갖는가

관련 문서

• Workflow Docs
• Queues Docs
• Anyone can build agents, but it takes a platform to run them
• Keeping community human while scaling with agents