워크플로우(Workflows) 개요

워크플로우(Workflows)를 사용하면 데이터 흐름으로 연결된 타입이 **지정된 스텝(steps)**으로 복잡한 작업 시퀀스를 정의하고 오케스트레이션할 수 있습니다. 각 스텝은 Zod 스키마로 검증되는 명확하게 정의된 입출력을 가집니다.

워크플로우는 실행 순서, 의존성, 분기, 병렬성 및 오류 처리를 관리하여 견고하고 재사용 가능한 프로세스를 구축할 수 있게 해줍니다. 스텝은 중첩되거나 복제되어 더 큰 워크플로우를 구성할 수 있습니다.

워크플로우는 다음과 같이 생성합니다:

createStep으로 **스텝(steps)**을 정의하여 입출력 스키마와 비즈니스 로직을 지정합니다.
createWorkflow로 **스텝(steps)**을 구성하여 실행 흐름을 정의합니다.
**워크플로우(workflows)**를 실행하여 전체 시퀀스를 수행하며, 일시정지, 재개 및 스트리밍 결과에 대한 내장 지원을 받습니다.

이 구조는 완전한 타입 안전성과 런타임 검증을 제공하여 전체 워크플로우에서 데이터 무결성을 보장합니다.

시작하기

워크플로우를 사용하려면 먼저 워크플로우 모듈에서 필요한 함수들을 가져옵니다:

src/mastra/workflows/test-workflow.ts:

import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

스텝(Step) 생성

스텝은 워크플로우의 구성 요소입니다. createStep을 사용하여 스텝을 생성합니다:

src/mastra/workflows/test-workflow.ts:

const step1 = createStep({...});

자세한 정보는 createStep을 참조하세요.

워크플로우(Workflow) 생성

createWorkflow를 사용하여 워크플로우를 생성하고 .commit()으로 완료합니다.

src/mastra/workflows/test-workflow.ts:

import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";
 
const step1 = createStep({...});
 
export const testWorkflow = createWorkflow({
  id: "test-workflow",
  description: 'Test workflow',
  inputSchema: z.object({
    input: z.string()
  }),
  outputSchema: z.object({
    output: z.string()
  })
})
  .then(step1)
  .commit();

자세한 정보는 workflow를 참조하세요.

스텝 구성

워크플로우 스텝은 .then()을 사용하여 구성되고 순차적으로 실행될 수 있습니다.

src/mastra/workflows/test-workflow.ts:

import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";
 
const step1 = createStep({...});
const step2 = createStep({...});
 
export const testWorkflow = createWorkflow({
  id: "test-workflow",
  description: 'Test workflow',
  inputSchema: z.object({
    input: z.string()
  }),
  outputSchema: z.object({
    output: z.string()
  })
})
  .then(step1)
  .then(step2)
  .commit();

스텝은 여러 다양한 방법으로 구성할 수 있습니다. 자세한 정보는 Control Flow를 참조하세요.

스텝 복제

워크플로우 스텝은 cloneStep()을 사용하여 복제할 수 있으며, 모든 워크플로우 메소드와 함께 사용할 수 있습니다.

src/mastra/workflows/test-workflow.ts:

import { createWorkflow, createStep, cloneStep } from "@mastra/core/workflows";
import { z } from "zod";
 
const step1 = createStep({...});
const clonedStep = cloneStep(step1, { id: "cloned-step" });
const step2 = createStep({...});
 
export const testWorkflow = createWorkflow({
  id: "test-workflow",  
  description: 'Test workflow',
  inputSchema: z.object({
    input: z.string()
  }),
  outputSchema: z.object({
    output: z.string()
  })
})
  .then(step1)
  .then(clonedStep)
  .then(step2)
  .commit();

워크플로우 등록

메인 Mastra 인스턴스에서 workflows를 사용하여 워크플로우를 등록합니다:

src/mastra/index.ts:

import { Mastra } from "@mastra/core/mastra";
import { PinoLogger } from "@mastra/loggers";
import { LibSQLStore } from "@mastra/libsql";
 
import { testWorkflow } from "./workflows/test-workflow";
 
export const mastra = new Mastra({
  workflows: { testWorkflow },
  storage: new LibSQLStore({
    // 텔레메트리, 평가 등을 메모리 저장소에 저장, 지속성이 필요하면 file:../mastra.db로 변경
    url: ":memory:"
  }),
  logger: new PinoLogger({
    name: "Mastra",
    level: "info"
  })
});

워크플로우 실행

워크플로우를 실행하고 테스트하는 방법은 두 가지가 있습니다.

Mastra 플레이그라운드

Mastra 개발 서버가 실행 중일 때 브라우저에서 http://localhost:4111/workflows를 방문하여 Mastra 플레이그라운드에서 워크플로우를 실행할 수 있습니다.

커맨드 라인

createRunAsync와 start를 사용하여 모든 Mastra 워크플로우의 실행 인스턴스를 생성합니다:

src/test-workflow.ts:

import { mastra } from "./mastra";
 
const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
const result = await run.start({
  inputData: {
    city: "London"
  }
});
 
// 완전한 워크플로우 결과 출력 (상태, 스텝 및 결과 포함)
console.log(JSON.stringify(result, null, 2));
 
// 워크플로우 출력 값 가져오기
if (result.status === 'success') {
  console.log(`output value: ${result.result.output}`);
}

자세한 정보는 createRunAsync와 start를 참조하세요.

이 워크플로우를 트리거하려면 다음을 실행하세요:

npx tsx src/test-workflow.ts

워크플로우 실행 결과

start() 또는 resume()을 사용하여 워크플로우를 실행한 결과는 결과에 따라 다음 중 하나처럼 보입니다.

성공 상태(Status succes)

{
  "status": "success",
  "steps": {
    // ...
    "step-1": {
      // ...
      "status": "success",
    }
  },
  "result": {
    "output": "London + step-1"
  }
}

status: 워크플로우 실행의 최종 상태를 보여줍니다. success, suspended, 또는 error 중 하나
steps: 워크플로우의 각 스텝을 나열하며, 입출력을 포함합니다
status: 각 개별 스텝의 결과를 보여줍니다
result: outputSchema에 따라 타입이 지정된 워크플로우의 최종 출력을 포함합니다

유보 상태(Status suspended)

{
  "status": "suspended",
  "steps": {
    // ...
    "step-1": {
      // ...
      "status": "suspended",
    }
  },
  "suspended": [
    [
      "step-1"
    ]
  ]
}

suspended: 계속 진행하기 전에 현재 입력을 기다리고 있는 스텝을 나열하는 선택적 배열

실패 상태(Status failed)

{
  "status": "failed",
  "steps": {
    // ...
    "step-1": {
      // ...
      "status": "failed",
      "error": "Test error",
    }
  },
  "error": "Test error"
}

error: 워크플로우가 실패할 경우 오류 메시지를 포함하는 선택적 필드

워크플로우 스트림

위에서 보여준 run 메소드와 유사하게, 워크플로우를 스트리밍할 수도 있습니다:

src/test-workflow.ts:

import { mastra } from "./mastra";
 
const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
const result = await run.stream({
  inputData: {
    city: "London"
  }
});
 
for await (const chunk of result.stream) {
  console.log(chunk);
}

자세한 정보는 stream과 messages를 참조하세요.

워크플로우 감시

워크플로우를 감시하여 방출되는 각 이벤트를 검사할 수도 있습니다.

src/test-workflow.ts:

import { mastra } from "./mastra";
 
const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
run.watch((event) => {
  console.log(event);
});
 
const result = await run.start({
  inputData: {
    city: "London"
  }
});

자세한 정보는 watch를 참조하세요.

추가 리소스

워크플로우 (레거시)

레거시 워크플로우 문서는 워크플로우 (레거시)를 참조하세요.

2025년 7월 26일 기준 번역
by dongne.lab@gmail.com

Updated on July 31, 2025, 10:21 AM UTC

의미적 회상