> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 임시 작업 흐름

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

> **경고:** `@mastra/temporal`은 실험적 기능이며 아직 프로덕션에서 사용할 준비가 되지 않았습니다. 릴리스 간에 API가 변경될 수 있습니다. 현재 상태는 [패키지 README](https://github.com/mastra-ai/mastra/tree/main/workflows/temporal)를 참조하세요.

## 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**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

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

## 임시 지원 Workflow 구축

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

### 임시 초기화

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

```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 문서](https://docs.temporal.io/develop/typescript/temporal-clients)를 참조하세요.

### 단계 만들기

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

```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`는 정적 문자열 리터럴이어야 합니다.

```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를 등록합니다. 실행은 임시 작업자에 의해 주도됩니다.

```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 진입점 파일을 가리키도록 설정하세요.

```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:

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

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

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

   ```bash
   npx tsx src/mastra/worker.ts
   ```

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

   ```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](https://temporal.io/cloud) 또는 자체 호스팅 Temporal 클러스터를 사용하세요. `@temporalio/envconfig`가 읽는 환경 변수를 통해 클라이언트 및 worker 연결을 구성합니다.

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

mTLS 및 API 키 옵션은 [Temporal Cloud 연결 문서](https://docs.temporal.io/cloud/get-started)를 참조하세요.

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

## 구성 옵션

### `taskQueue`

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

### `startToCloseTimeout`

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

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

## 제약 조건 및 참고 사항

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

## 관련된

- [Workflow 실행자](https://mastra.zisheng.pro/ko/docs/deployment/workflow-runners)
- [Workflow 개요](https://mastra.zisheng.pro/ko/docs/workflows/overview)
- [임시 문서화](https://docs.temporal.io/)