본문으로 바로가기
리옵트 핸드북
리옵트 핸드북
Vercel 엔터프라이즈 AI 플랫폼

플랫폼 기초

플랫폼 아키텍처AI SDK 런타임AI Gateway 제어면

실행 런타임

Workflow 장기 실행Sandbox 실행 격리MCP 데이터 계층Queues & 비동기 작업 관리

프롬프트 & 품질

프롬프트 엔지니어링 & 가드레일RAG & 검색 증강 생성관측성·평가

운영 체계

보안·거버넌스비용·안정성배포 전략 & AI CI/CD

실전 시나리오

고객지원 에이전트 아키텍처내부 리서치 에이전트 아키텍처승인형 백오피스 자동화코딩 오케스트레이션

오케스트레이션 패턴

그래프 중심 오케스트레이션실무 오케스트레이션 플레이북멀티 에이전트 아키텍처

부록

마이그레이션 가이드레퍼런스검증 리포트업데이트 내역
핸드북›Vercel 엔터프라이즈 AI›Workflow 장기 실행
한국어English

Workflow 장기 실행

Workflow를 장기 실행 에이전트의 오케스트레이션 계층으로 사용해 승인, 이벤트 재개, durable replay를 구현하는 방법을 정리합니다.

핵심 요약

  • 장기 실행·외부 이벤트 재개·사람 승인 대기 작업은 timeout을 늘리지 말고 durable execution 모델인 Workflow로 옮깁니다.
  • 2026년 4월 GA된 Vercel Workflows는 "use workflow"가 오케스트레이션을, "use step"이 재시도·영속화 가능한 작업 단위를 담당합니다.
  • step은 작게 유지하고 side effect를 뒤로 밀어 replay 시 중복을 막으며, 외부 write에는 idempotency key를 부여합니다.
  • 승인이 필요한 action은 별도 step으로 분리하고 환불·권한 승격 등 업무별 기본 대기 시간(4~24시간)을 둡니다.
  • 단순 fan-out 비동기는 Queue가 더 단순할 수 있으므로 모든 비동기 작업을 Workflow로 몰지 않습니다.

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

Workflow에 올려야 하는 작업

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

작업 유형Workflow 적합도이유
즉시 채팅 응답낮음request path에 남기는 편이 단순
수분~수시간 배치 분석높음재개 가능성과 상태 추적 필요
사람 승인 대기매우 높음external event와 pause/resume 필요
외부 API 재시도높음step retry와 backoff 관리 필요
cron성 작업중간큐 또는 스케줄 작업과 비교 필요

실행 구조

Workflow와 Queue의 경계

질문WorkflowQueue
상태 재개가 필요한가강점약함
사람 승인/이벤트 대기가 필요한가강점별도 구현 필요
단순 fan-out 비동기 처리인가가능더 단순할 수 있음
실행 경로를 단계별로 감사해야 하는가강점제한적

step 설계 원칙

원칙이유예시
step은 작게 유지재시도 단위 명확화fetch data, run model, persist result
side effect는 뒤로 민다replay 시 중복 방지approval 이후 write 실행
human approval은 별도 단계business gate 명시payment, message send, privilege grant
versioned deployment를 고려장기 실행 중 코드 변경 대비migration-safe payload 사용

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

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)
}

승인이 필요한 업무 예시

업무승인 이유기본 대기 시간
고객에게 금전성 혜택 발송비용/악용 방지4시간
권한 승격보안 리스크24시간
법적 문안 발송규제 리스크8시간
대량 외부 메시지 발송브랜드 리스크2시간

추론

Vercel Workflow가 장기 실행과 이벤트 재개에 강하다고 해서 모든 비동기 작업을 여기로 몰아넣을 필요는 없습니다. 단순 큐잉과 상태 머신은 떼어 두는 편이 비용과 운영 복잡도 양쪽에서 낫습니다.

운영 기준

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

ADR 스타일 결론

Decision

장기 실행, 외부 이벤트 재개, 사람 승인 대기가 있는 작업은 Workflow로 이동합니다. request timeout을 늘려 해결하지 않고, durable state machine으로 모델링합니다.

실무 체크리스트

  • 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

관련 문서

Queues & 비동기 작업 관리

Vercel Queues를 활용해 AI 작업의 fan-out, 배치 처리, 재시도·poison message 운영을 설계하는 방법을 정리합니다.

내부 리서치 에이전트 아키텍처

내부 분석·리서치 에이전트를 Workflow, Sandbox, artifact 중심으로 설계하는 방법을 정리합니다.

Ch13. Observability와 Deployment

엔터프라이즈 Eve 에이전트 개발 · Eve의 OpenTelemetry, Workflow tags, Vercel/self-host 배포, 운영 점검 절차를 정리한다.

Ch1. Eve 멘탈 모델

엔터프라이즈 Eve 에이전트 개발 · Eve를 파일시스템 작성 표면, durable workflow, runtime harness, channel protocol로 나누어 이해한다.

Agentic 운영 체계

Agentic MVP · AI 에이전트를 개발 보조가 아닌 제품·GTM 실험팀으로 운영하는 체계. 역할 분리, 도구 레이어, 30~90분 티켓, 권한 설계로 제품 신호를 더 빨리 만드는 방법을 다룹니다.

AI Gateway 제어면

AI Gateway를 모델 라우팅, 비용, 정책, 자격 증명 관리를 중앙화하는 제어면으로 운영하는 방법을 정리합니다.

Sandbox 실행 격리

Sandbox를 이용해 코드 실행, 파일 접근, 셸 실행, 브라우저 자동화를 격리하는 방법을 정리합니다.

On this page

Workflow에 올려야 하는 작업실행 구조Workflow와 Queue의 경계step 설계 원칙예시: 승인 포함 오케스트레이션승인이 필요한 업무 예시운영 기준ADR 스타일 결론실무 체크리스트관련 문서