Workflow SDK 5, 프로덕션 환경을 위해 새롭게 태어나다

Workflow SDK를 처음 선보였을 때 목표는 단순했습니다. 평범한 비동기 JavaScript를 작성하면, 크래시나 배포, 긴 대기 시간이 있어도 SDK가 실행을 끊김 없이 이어 주는 것이었습니다.

import { sleep } from "workflow";

export async function welcomeUser(email) {
  "use workflow";

  const user = await createUser(email);
  await sendWelcomeEmail(user);

  // Survives crashes and deployments
  // while it waits
  await sleep("3d");
  await sendCheckInEmail(user);
}

지난해 Vercel은 특유의 뛰어난 개발자 경험을 갖춘 바로 그 SDK를 출시했습니다. 그리고 고객들이 이 SDK로 무엇을 만들어 내는지 지켜봤습니다.

지금까지 40억 개가 넘는 스텝과 7억 건의 실행이 쌓였고, 여기서 두 가지 뚜렷한 패턴이 드러났습니다.

• 첫 번째는 자동화입니다. 데이터를 옮기고, 주문을 처리하고, 백그라운드 작업을 조율하고, 구독을 관리하고, ETL과 데이터 파이프라인을 돌리는 전통적인 워크플로가 여기에 속합니다.

• 두 번째는 에이전트와 하니스입니다. 에이전트는 비용이 많이 들고 오래 실행되기 때문에 내구성이 자연스럽게 필요합니다.

이런 워크로드가 성숙해지면서 Workflow도 함께 성장했습니다. 우리가 늘 최우선으로 둔 가치는 보안, 안정성, 성능입니다.

Workflow SDK 5가 이 세 가지를 어떻게 달성했는지 소개합니다.

더 안전해진 워크플로

Workflow의 이벤트 로그에는 스텝의 인자와 반환값이 저장되어, 크래시나 배포 이후에도 실행을 복구할 수 있습니다. 이 데이터에는 고객의 민감한 정보, 모델 컨텍스트, 자격 증명, 도구 호출 결과가 포함될 수 있으므로 저장 시 강력한 보호가 필요합니다.

Workflow SDK는 코드를 떠나기 전에 모든 페이로드를 종단간 암호화합니다. 워크플로와 스텝의 입출력, 훅 페이로드, 스트림 데이터는 실행마다 고유한 키를 사용해 AES-256-GCM으로 암호화됩니다. 암호화를 켜면 Vercel을 포함한 어떤 Workflow SDK 백엔드도 암호문만 보고 저장합니다. 평문은 사용자의 배포 환경이나 권한이 있는 관측 도구에서만 복호화됩니다.

Vercel에서는 설정 없이 암호화

Vercel에서는 별도 설정이나 코드 변경 없이 암호화가 적용됩니다. 각 실행의 키는 해당 실행을 만든 배포 범위의 키에서 파생되므로, 실행은 자신의 데이터만 복호화할 수 있습니다. 워크플로 코드는 그대로입니다.

export async function onboardCustomer(
  customer: Customer,
) {
  "use workflow";

  // The customer record is stored
  // encrypted in the event log
  const account = await createAccount(customer);
  await sendWelcomeEmail(account.email);
  return account.id;
}

async function createAccount(
  customer: Customer,
) {
  "use step";

  // ...and arrives here decrypted,
  // inside your deployment
  return db.accounts.create(customer);
}

기본적으로 Vercel이 키를 관리하므로 관측 기능도 그대로 동작합니다. 이름, 소요 시간, 상태는 항상 확인할 수 있고, 페이로드를 봐야 할 때는 대시보드나 CLI에서 복호화하면 됩니다. 복호화는 사용자의 브라우저나 터미널에서 이루어지고, 프로젝트 환경 변수와 같은 권한 체계를 따르며, 모든 요청이 팀의 감사 로그에 기록됩니다.

# Payloads show as 🔒 Encrypted
npx workflow inspect run <run-id>

# Decrypts locally, if you have access
npx workflow inspect run <run-id> --decrypt

자체 호스팅 World에서의 암호화

암호화는 SDK 단에서 구현되므로, 자체 호스팅 World에서도 페이로드가 스토리지, 큐, 스트림에 도달하기 전에 보호할 수 있습니다.

커스텀 World에서 암호화를 사용하려면 자체 키 관리 체계를 연결해 getEncryptionKeyForRun()를 구현하세요. SDK가 새 페이로드를 암호화하고 재생(replay) 중에 복호화할 수 있도록, 호출할 때마다 같은 실행에는 항상 같은 32바이트 키를 반환해야 합니다.

import type { World } from "@workflow/world";

type RunKeyProvider =
  World["getEncryptionKeyForRun"];

export const getEncryptionKeyForRun:
  RunKeyProvider = async (run) => {
    const runId =
      typeof run === "string" ? run : run.runId;

    // Return the same 32 bytes for a run
    // every time, so replays can decrypt
    return keyStore.getRunKey(runId);
  };

v5의 추가 보안 개선

다른 실행에 대한 쓰기도 봉인됩니다. 코드가 다른 실행의 훅을 재개하거나, 다른 배포에서 실행을 시작하거나, 다른 실행에서 전달된 스트림에 쓸 때 페이로드는 대상 실행의 공개 키로 암호화됩니다. 쓰는 쪽은 대상 실행의 기존 페이로드를 읽지 않고도 암호화할 수 있습니다.

민감한 데이터의 보관 기간을 제한할 수도 있습니다. 페이로드 보존(payload retention)을 experimental_retention: 0로 설정하면 실행이 완료되거나 실패하는 즉시 입력, 출력, 스트림 내용이 삭제됩니다. 실행의 메타데이터는 관측 화면에 그대로 남습니다.

새롭게 디자인한 트레이스 뷰어

새로 디자인한 트레이스 뷰어는 스팬 검색, 확대/축소, 미니맵, 개발 중 로컬 검사 기능을 갖춰 실행을 훨씬 쉽게 탐색할 수 있습니다.

실행 속성(run attributes)은 v5에서 새로 추가됐습니다. 주문 ID 같은 검색 가능한 컨텍스트를 실행에 붙여 두고, 이를 기준으로 실행을 찾을 수 있습니다. 속성은 평문으로 저장되므로 비밀 값을 넣어서는 안 됩니다.

모든 리전에서 실행되는 워크플로

Workflow SDK 4에서는 모든 실행이 iad1에 있었습니다. 프로젝트를 여러 리전에 배포해도 각 실행의 이벤트 로그, 큐, 스트림은 한 리전에만 저장되었기 때문에, 다른 리전에서 실행되는 스텝은 진행 상황을 기록하려고 리전 간 요청을 보내야 했습니다.

v5에서는 Vercel Function이 지원하는 모든 리전에 Workflow 인프라를 배포했습니다. 이제 각 실행에는 홈 리전이 있어서, 상태, 큐 디스패치, 스트림이 실행을 시작한 리전에서 처리되고 핵심 경로에서 리전 간 왕복이 발생하지 않습니다.

기본적으로 실행은 이를 시작한 함수가 있는 리전에서 시작됩니다. 여러 리전에 배포하면 설정 없이도 각 실행이 이를 호출한 사용자와 가까운 곳에 머뭅니다.

import { start } from "workflow/api";
import { processOrder } from "@/workflows/process-order";

export async function POST(request: Request) {
  const order = await request.json();

  // Runs in the region that served this request
  const run = await start(
    processOrder,
    [order],
  );
  return Response.json({ runId: run.runId });
}

실행을 다른 곳에 두고 싶다면 start()에 리전을 전달하세요. 그러면 워크플로를 데이터를 읽고 쓰는 데이터베이스 옆에서 실행하거나, 고객 데이터를 반드시 있어야 하는 리전에 보관할 수 있습니다.

// Keep this customer’s run data in Frankfurt
const run = await start(
  processOrder,
  [order],
  { region: "fra1" },
);

region 옵션은 실행의 데이터가 저장되는 위치를 결정합니다. 스텝은 앱이 배포된 곳에서 실행되므로, 스텝도 해당 리전에서 실행하려면 앱 역시 그 리전에 배포해야 합니다. 기존 v4 실행은 계속 iad1에 남습니다.

인프라 안정성

리전을 격리하면 안정성도 높아집니다. 한 리전에 장애가 생겨도 정상 리전의 새 실행까지 멈출 필요는 없습니다. Vercel Function 페일오버를 설정한 프로젝트라면 스텝은 대체 리전에서 실행하면서도 상태는 계속 실행의 원래 홈 리전에서 관리할 수 있습니다. 상태는 페일오버 중에도 홈 리전에 고정되며 다른 곳으로 이전되지 않습니다.

익명화된 텔레메트리와 여러 고객과의 긴밀한 협업 덕분에 Workflow 런타임의 드문 버그와 경쟁 상태(race condition)를 수십 건 찾아 수정했습니다. 또한 Workflow SDK는 더 다양한 유형의 일시적 네트워크 오류에서 스스로 복구합니다.

그 결과 Workflow SDK 5에서는 플랫폼이나 런타임 버그 때문에 실패하거나 멈춘 실행을 거의 볼 수 없었습니다.

에이전트 시대에 맞는 성능

Workflow SDK 4에서는 스텝을 호출할 때마다 스텝을 시작하는 큐 홉(queue hop)과 워크플로를 이어 가는 큐 홉이 한 번씩 필요했습니다. 느린 백그라운드 자동화에는 문제없는 수준이지만, 오늘날 개발자들이 만드는 AI 워크로드에는 지연 시간을 더하게 됩니다.

에이전트 루프와 하니스에는 수천 개의 순차 이벤트, 처리량이 높은 토큰 스트림, 도구 체인, 동적 서브에이전트가 들어갈 수 있습니다. 이 정도 규모에서는 스텝마다 따라붙는 네트워크 작업과 CPU 작업이 한계로 작용했습니다.

Workflow SDK 5에서는 엔진의 상당 부분을 다시 작성해 불필요한 큐 홉, 네트워킹, CPU 작업을 최소화했습니다. 측정한 워크로드 전반에서 지연 시간과 오버헤드가 1.6배에서 25배까지 개선되었고, 개발자 경험은 그대로 유지하면서 큰 호환성 파괴 변경도 없습니다.

아래 벤치마크는 Vercel에서 v5.2.0과 v4.8.12를 비교한 결과입니다. 측정 항목을 선택해 v5와 v4를 비교해 보고, 설명 영상을 재생하거나 탐색하면서 각 벤치마크가 정확히 무엇을 측정하는지 확인해 보세요.

이를 위해 Workflow SDK 5에는 수백 건의 성능 개선이 담겨 있습니다. 이 수치를 만든 주요 변경 사항은 다음과 같습니다.

줄어든 큐 홉

v4에서는 스텝마다 실행 권한이 큐를 거쳐 다시 넘어갔습니다. v5에서는 한 번의 호출 안에서 병렬 스텝을 포함한 여러 스텝을 인라인으로 실행하다가, 대기나 훅, 타임아웃 임박 시점에 비로소 실행을 넘깁니다.

런타임은 불필요한 영속화 왕복도 피하고, 스텝 생성을 실행 과정에 통합했습니다. 큐와 네트워크 요청이 줄면 CPU 작업이 줄고 런타임 오버헤드도 낮아집니다. 5단계 스텝 벤치마크에서 스텝 간 오버헤드(p75)는 618ms에서 109ms로 줄었습니다.

증분 재생(Incremental replay)

1,020단계 벤치마크에서 v4의 p75 오버헤드는 이벤트 로그가 커질수록 함께 늘어났습니다. 전체 이벤트 기록을 재생하는 데 걸리는 시간이 기록 크기에 비례했기 때문입니다. 마지막 샘플 구간에서는 오버헤드가 1,748ms에 달했지만, v5.2.0에서는 70ms였습니다. 1,020개 스텝을 모두 끝내는 데 걸린 중앙값도 21.0분에서 3.0분으로 줄었습니다.

WebSocket 스트리밍

내구성을 확보한다고 해서 스트리밍 응답이 생성 속도를 따라가지 못해서는 안 됩니다. Vercel World에서 v5.2.0은 기본적으로 WebSocket으로 스트림을 기록합니다. 52.4초짜리 에이전트 응답을 재생하는 벤치마크에서 전달 시간의 중앙값은 226.1초에서 53.5초로 줄었습니다.

페이로드 압축도 저장 및 전송되는 데이터량을 줄여 줍니다. AI 토큰 스트림은 압축 후 평균 약 80% 작아집니다.

이 측정값은 하나의 워크로드를 한 리전에서 Vercel World를 대상으로 측정한 결과입니다. 런타임 오버헤드를 파악하는 데는 유용하지만 모든 애플리케이션의 성능을 예측하는 값은 아닙니다.

벤치마크 결과와 측정 방법

2026년 10월 8일 Vercel 프로덕션 환경의 iad1에서 관리형 Vercel World를 대상으로 측정했습니다. 버전마다 동일한 앱을 별도의 배포로 구성했으며, 스텝은 1KB의 JSON을 입력받아 같은 크기로 출력합니다.

주요 결과 · v4.8.12와 v5.2.0 비교

테일 지연 시간을 포함한 전체 결과는 성능 문서에서 확인할 수 있습니다.

World: 모두가 공유하는 내구성 기반

Workflow SDK의 내구성 함수는 World 위에서 동작합니다. World는 진행 상황 저장, 작업 디스패치, 스트림 전달을 위한 인터페이스입니다. 이제 이 기반은 fx와 durable-harness도 지원하며, durable-harness는 기존 에이전트 하니스에 내구성을 더해 줍니다.

공유 스토리지, 큐, 스트리밍 인프라를 개선하면 World를 사용하는 모든 쪽이 혜택을 볼 수 있습니다. 반면 Workflow 재생 런타임 내부의 최적화는 Workflow SDK에만 적용되며, 모든 하니스에 자동으로 적용되지는 않습니다.

만들고 싶은 방식에 맞춰 통합 방법을 고르세요.

• Workflow SDK: use workflow와 use step로 내구성 있는 애플리케이션 로직을 작성합니다.

• WorkflowAgent: 워크플로 안에서 AI SDK 에이전트 루프를 쓰려면 @ai-sdk/workflow를 사용합니다.

• fx: libfx로 네이티브 코딩 에이전트를 내장하고 확장합니다.

• durable-harness: 지원되는 기존 하니스를 그대로 쓰면서 그 아래에 내구성을 추가합니다.

  • Pi와 OpenCode를 지원하며, Vercel Sandbox에서는 Claude Code와 Codex에 대한 실험적 통합도 제공합니다.

• eve: Workflow SDK와 World를 기반으로 한 내구성 세션으로 에이전트를 만듭니다.

World 기반의 내구성을 갖춘 SDK와 프레임워크 라인업은 앞으로 더 늘려 갈 예정입니다.

Workflow SDK 5로 시작하기

위에서 소개한 개선 사항 외에도 Workflow SDK 5에는 다음 기능이 추가되었습니다.

• AbortController를 이용한 실행 중 취소

• 검색 가능한 실행 속성

• 더 많은 프레임워크 통합

• 그 밖의 개선 사항

변경된 내용은 v5 업그레이드 문서에 정리되어 있습니다. 새 워크플로를 만들려면 먼저 SDK를 설치하세요.

pnpm add workflow@latest

Workflow SDK는 현재 베타인 Python SDK도 제공하며, 내구성 워크플로, 스텝, 슬립, 훅을 동일하게 사용할 수 있습니다.

기여자