임시 작업 흐름

일시적인장기간 실행되는 내결함성 Workflow를 조정하기 위한 내구성 있는 실행 플랫폼입니다. 그만큼@mastra/temporal패키지를 사용하면 표준 Mastra API로 Workflow를 작성하고 임시 클러스터에서 실행할 수 있습니다.

경고

@mastra/temporal은 실험적 기능이며 아직 프로덕션에서 사용할 준비가 되지 않았습니다. 릴리스 간에 API가 변경될 수 있습니다. 현재 상태는 패키지 README를 참조하세요.

Temporal이 Mastra와 작동하는 방식

createWorkflow() 및 createStep()으로 작성한 Mastra Workflow는 Temporal의 Workflow 및 Activity Model에 매핑됩니다. Temporal 작업자용 MastraPlugin은 번들 생성 시 Mastra 진입점 파일을 컴파일합니다.

• 각 createStep() 핸들러는 Temporal Activity로 추출됩니다.
• 각 createWorkflow()는 해당 Activity를 호출하는 Temporal Workflow로 다시 작성됩니다.
• 플러그인은 생성된 Activity와 Workflow를 작업자에 자동으로 등록합니다. 실행이 mastra.getWorkflow(...).createRun().start(...)로 시작되면 Mastra 클라이언트가 Temporal에 제어권을 넘깁니다. 그러면 Temporal이 worker에서 내구성 있는 실행, 재시도, 상태 유지를 처리합니다.

설정

필수 패키지를 설치합니다:

npm

npm install @mastra/temporal@latest @temporalio/client @temporalio/worker @temporalio/envconfig

pnpm

pnpm add @mastra/temporal@latest @temporalio/client @temporalio/worker @temporalio/envconfig

Yarn

yarn add @mastra/temporal@latest @temporalio/client @temporalio/worker @temporalio/envconfig

Bun

bun add @mastra/temporal@latest @temporalio/client @temporalio/worker @temporalio/envconfig

임시 클러스터에도 액세스해야 합니다. 로컬 개발의 경우 Docker를 사용하여 실행할 수 있습니다(참조Running locally).

임시 지원 Workflow 구축

이 가이드에서는 Temporal 및 Mastra를 사용하여 Workflow를 생성하는 과정을 안내하고 값을 증가시키는 카운터 애플리케이션을 보여줍니다.

임시 초기화

Mastra 호환 Workflow 도우미를 사용하려면 Temporal 통합을 초기화하세요. createWorkflow() 및 createStep() 함수가 Temporal 클라이언트와 task queue에 바인딩됩니다.

src/mastra/temporal/index.ts

import { init } from '@mastra/temporal'
import { Client, Connection } from '@temporalio/client'
import { loadClientConnectConfig } from '@temporalio/envconfig'

const config = loadClientConnectConfig()
const connection = await Connection.connect(config.connectionOptions)
const client = new Client({ connection })

export const { createWorkflow, createStep } = init({
  client,
  taskQueue: 'mastra',
})

loadClientConnectConfig()는 TEMPORAL_ADDRESS, TEMPORAL_NAMESPACE, mTLS 설정과 같은 표준 Temporal 환경 변수를 읽습니다. 전체 목록은 Temporal envconfig 문서를 참조하세요.

단계 만들기

Workflow를 구성할 개별 단계를 정의하십시오. 각 단계는 임시 활동이 됩니다.

src/mastra/workflows/index.ts

import { z } from 'zod'
import { createWorkflow, createStep } from '../temporal'

const incrementStep = createStep({
  id: 'increment',
  inputSchema: z.object({
    value: z.number(),
  }),
  outputSchema: z.object({
    value: z.number(),
  }),
  execute: async ({ inputData }) => {
    return { value: inputData.value + 1 }
  },
})

Workflow 만들기

단계를 Workflow로 구성합니다. 빌드 시 변환기가 Temporal 내보내기 이름을 파생할 수 있도록 Workflow id는 정적 문자열 리터럴이어야 합니다.

src/mastra/workflows/index.ts

const workflow = createWorkflow({
  id: 'increment-workflow',
  steps: [incrementStep],
  inputSchema: z.object({
    value: z.number(),
  }),
  outputSchema: z.object({
    value: z.number(),
  }),
}).then(incrementStep)

workflow.commit()

export { workflow as incrementWorkflow }

Mastra 인스턴스 구성

Mastra에 Workflow를 등록합니다. 실행은 임시 작업자에 의해 주도됩니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'
import { incrementWorkflow } from './workflows'

export const mastra = new Mastra({
  workflows: { incrementWorkflow },
  logger: new PinoLogger({ name: 'Mastra', level: 'info' }),
})

작업자 실행

worker는 Temporal task queue를 폴링하는 장기 실행 Node.js 프로세스입니다. MastraPlugin을 설치하고 src 옵션이 Workflow를 등록하는 Mastra 진입점 파일을 가리키도록 설정하세요.

src/mastra/worker.ts

import { MastraPlugin } from '@mastra/temporal/worker'
import { NativeConnection, Worker } from '@temporalio/worker'

const connection = await NativeConnection.connect({
  address: 'localhost:7233',
})

const mastraPlugin = new MastraPlugin()

await mastraPlugin.prebuild({
  entryFile: import.meta.resolve('./index.ts'),
})

const worker = await Worker.create({
  connection,
  namespace: 'default',
  taskQueue: 'mastra',
  plugins: [mastraPlugin],
})

await worker.run()

MastraPlugin은 진입점 파일을 Workflow 전용 번들로 다시 작성하고 단계 핸들러를 Temporal Activity로 연결합니다. activities 또는 workflowsPath를 Worker.create()에 직접 전달할 필요가 없습니다.

Workflow 실행

로컬에서 실행

1. 로컬 임시 서버를 시작합니다. 가장 간단한 옵션은temporalio/auto-setup Docker image:

   docker run --rm -p 7233:7233 -p 8080:8080 temporalio/auto-setup:latest

2. http://localhost:8080에서 Temporal UI를 열어 namespace, Workflow, Activity를 살펴봅니다.

3. 새 터미널에서 다음을 실행하여 작업자를 시작합니다.

   npx tsx src/mastra/worker.ts

4. Mastra 인스턴스를 가져오는 스크립트 또는 프로세스에서 Workflow 실행을 트리거합니다.

   scripts/run.ts

   import { mastra } from '../src/mastra'
   
   const run = await mastra.getWorkflow('incrementWorkflow').createRun()
   const result = await run.start({ inputData: { value: 5 } })
   
   console.log(result)

5. Temporal UI의 Workflows에서 실행을 모니터링하여 단계별 Activity 진행 상황과 재시도 기록을 확인합니다.

프로덕션에서 실행 중

프로덕션 환경에서는 Temporal Cloud 또는 자체 호스팅 Temporal 클러스터를 사용하세요. @temporalio/envconfig가 읽는 환경 변수를 통해 클라이언트 및 worker 연결을 구성합니다.

.env

TEMPORAL_ADDRESS=your-namespace.tmprl.cloud:7233
TEMPORAL_NAMESPACE=your-namespace
TEMPORAL_API_KEY=your-api-key

mTLS 및 API 키 옵션은 Temporal Cloud 연결 문서를 참조하세요.

경고

임시 작업자는 수명이 긴 프로세스로 실행되어야 합니다. AWS Lambda 또는 Vercel 기능과 같이 실행 제한이 짧은 서버리스 플랫폼에 배포하지 마십시오. 컨테이너, VM 또는 Fly.io, Railway, Kubernetes와 같은 작업자 친화적인 플랫폼을 사용하세요.

구성 옵션

taskQueue

필수입니다. worker가 폴링하는 Temporal task queue를 식별합니다. init()(클라이언트가 실행을 시작할 때 사용)과 Worker.create()(worker가 실행을 수신할 때 사용)에 같은 값을 전달해야 합니다.

startToCloseTimeout

선택 과목. Temporal이 이를 취소하고 재시도 정책을 적용하기 전에 단일 활동(단계)을 실행할 수 있는 최대 시간을 설정합니다. 기본값은1 minute.

src/mastra/temporal/index.ts

export const { createWorkflow, createStep } = init({
  client,
  taskQueue: 'mastra',
  startToCloseTimeout: '5 minutes',
})

제약 조건 및 참고 사항

• Workflow ID는 정적 문자열 리터럴이어야 합니다. 빌드 시 변환기가 리터럴 값을 읽어 Temporal Workflow 내보내기 이름을 파생합니다.
• Activity는 createStep() 핸들러에서 자동으로 생성됩니다. Worker.create({ activities })에 전달하지 마세요.

관련된

• Workflow 실행자
• Workflow 개요
• 임시 문서화