Workflow

기존 Workflow 기능이 제거되었습니다.

변경됨

getWorkflows에게listWorkflows

mastra.getWorkflows() 메서드의 이름이 mastra.listWorkflows()로 변경되었습니다. 이 변경은 여러 항목을 가져오는 getter 메서드에 list 접두사를 사용하는 API 전반의 명명 규칙과 일치합니다. 마이그레이션하려면 모든 mastra.getWorkflows() 호출을 mastra.listWorkflows()로 바꾸세요.

- const workflows = mastra.getWorkflows();
+ const workflows = mastra.listWorkflows();

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 가져오기를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/mastra-plural-apis .

:::

단계 컨텍스트의 RuntimeContext에서 RequestContext로

Workflow 단계 실행 컨텍스트에서 runtimeContext 매개변수 이름이 requestContext로 변경되었습니다. 이 변경은 명확성을 위한 전역 이름 변경과 일치합니다. 마이그레이션하려면 단계 실행 함수에서 runtimeContext 참조를 requestContext로 변경하세요.

  createStep({
-   execute: async ({ runtimeContext } ) => {
-     const userTier = context.runtimeContext.get('userTier');
+   execute: async ({ requestContext } ) => {
+     const userTier = requestContext.get('userTier');
      return { result: userTier };
    },
  });

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 가져오기를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/runtime-context .

:::

createRunAsync에게createRun

createRunAsync() 메서드의 이름이 createRun()으로 변경되었습니다. 모든 실행 생성이 비동기 방식이므로 불필요한 "Async" 접미사를 제거하여 API를 단순화했습니다. 마이그레이션하려면 메서드 호출의 이름을 createRunAsync에서 createRun으로 변경하세요.

- await workflow.createRunAsync({ input: { ... } });
+ await workflow.createRun({ input: { ... } });

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/workflow-create-run-async .

:::

runCount에게retryCount (deprecated)

Workflow 단계 실행에서 runCount 매개변수 대신 retryCount를 사용하는 것이 권장됩니다. 새 이름은 해당 값이 재시도 횟수임을 명확히 나타냅니다. 이전 runCount도 계속 작동하지만 더 이상 사용하지 말라는 경고가 표시됩니다. 마이그레이션하려면 단계 실행 함수에서 runCount의 이름을 retryCount로 변경하세요.

  createStep({
    execute: async (inputData, context) => {
-     console.log(`Step run ${context.runCount} times`);
+     console.log(`Step retry count: ${context.retryCount}`);
    },
  });

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/workflow-run-count .

:::

getInitData알 수 없는 반환

이제 실행 함수의 getInitData 함수는 any 대신 unknown을 반환합니다. 타입을 직접 지정해야 합니다. 마이그레이션하려면 getInitData()를 getInitData<any>()로 변경하세요.

  createStep({
    execute: async ({ getInitData }) => {
-     const initData = getInitData();
-     if (initData.key === 'value') {}
+     const initData = getInitData<any>();
+     if (initData.key === 'value') {}
    },
  });

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/workflow-get-init-data .

:::

getWorkflowRuns에게listWorkflowRuns

getWorkflowRuns() 메서드의 이름이 listWorkflowRuns()로 변경되었습니다. 이 변경은 컬렉션을 반환하는 메서드에 list*를 사용하는 규칙과 일치합니다. 마이그레이션하려면 메서드 호출의 이름을 getWorkflowRuns에서 listWorkflowRuns로 변경하세요.

- const runs = await workflow.getWorkflowRuns({ fromDate, toDate });
+ const runs = await workflow.listWorkflowRuns({ fromDate, toDate });

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/workflow-list-runs .

:::

입력은 기본적으로 검증됩니다.

이전에는 기본적으로 입력을 검증하지 않았습니다. validateInputs 플래그는 Workflow 입력을 검증할지 여부를 결정합니다. 이 불리언 값의 기본값이 true로 변경되었습니다. 이전 동작을 유지하거나 스키마 검증이 필요하지 않은 Workflow가 있다면 validateInputs: false를 설정하세요.

createWorkflow({
+  options: {
+    validateInputs: false
+  }
})

단계suspendPayload validation

이제 suspendSchema가 정의된 단계에서는 단계의 suspendPayload를 검증합니다. suspendPayload를 검증할지 여부도 validateInputs 플래그를 사용하여 결정합니다.

  createStep({
    id: "suspend-resume-step",
    // ... other step properties
    suspendSchema: z.object({
      reason: z.string(),
      otherReason: z.string()
    }),
    execute: async ({ suspend, resumeData}) => {
      if (!resumeData) {
-       return suspend({ reason: "Suspension reason" }); // Missing otherReason
+       return suspend({ reason: "Suspension reason", otherReason: "Other reason" });
      }
    },
  });

분기 결과 필드는 이제 선택 사항입니다.

이제 .branch() 메서드는 모든 분기 출력 필드가 선택 사항인 스키마를 반환합니다. 각 분기는 조건이 참일 때만 실행되므로 어떤 분기의 출력이든 undefined일 수 있는 런타임 동작을 반영합니다. 마이그레이션하려면 분기 출력을 사용하는 코드를 업데이트하여 선택적 값을 처리하세요.

  const workflow = createWorkflow({...})
    .branch([
      [condition1, stepA],  // outputSchema: { result: z.string() }
      [condition2, stepB],  // outputSchema: { data: z.number() }
    ])
-   // Previously: stepA.result typed as string, stepB.data typed as number
+   // Now: stepA.result typed as string | undefined, stepB.data typed as number | undefined
    .then(nextStep);

코드가 선택 사항이 아닌 유형에 의존하는 경우 런타임 검사를 추가하거나 분기 출력에 액세스할 때 기본값을 제공하세요.

Run.start() 및 Run.timeTravel()의 writableStream에서 outputWriter로

Run.start() 및 Run.timeTravel()의 writableStream 매개변수가 outputWriter로 대체되었습니다. 이제 WritableStream을 전달하는 대신 각 Workflow 이벤트 청크를 직접 받는 비동기 콜백 함수를 전달합니다. 이 변경으로 API가 단순해졌습니다. WritableStream 래퍼 대신 콜백에서 청크를 직접 처리합니다. 예:워크플로 이벤트를 HTTP 응답(SSE)으로 스트리밍:

  const run = await workflow.createRun();

- const stream = new WritableStream({
-   write(chunk) {
-     response.write(`data: ${JSON.stringify(chunk)}\n\n`);
-   }
- });
- await run.start({ inputData, writableStream: stream });

+ await run.start({
+   inputData,
+   outputWriter: async (chunk) => {
+     response.write(`data: ${JSON.stringify(chunk)}\n\n`);
+   },
+ });

노트

단계 execute 함수에 전달되는 writer 매개변수는 이 변경의 영향을 받지 않습니다. 이 매개변수는 계속해서 WritableStream<unknown>을 확장하고 .write() 및 .custom() 메서드를 제공하는 ToolStream입니다.

createStep({
  id: 'my-step',
  execute: async ({ writer }) => {
    // This API is unchanged
    await writer.write({ data: 'some output' })
    await writer.custom({ type: 'custom-event', payload: {} })
  },
})

setState()이제 비동기식이며 전달된 데이터가 검증되었습니다.

이제 setState() 함수는 비동기 함수입니다. 전달된 데이터는 단계에 정의된 stateSchema를 기준으로 검증됩니다. 상태 데이터를 검증할지 여부도 validateInputs 플래그를 사용하여 결정합니다. 또한 이제 setState()를 호출할 때 이전 상태를 펼친 (...state)를 추가하지 않고 업데이트할 상태 데이터만 전달할 수 있습니다. 마이그레이션하려면 setState() 함수를 비동기 함수로 업데이트하세요.

- setState({ ...state, sharedCounter: state.sharedCounter + 1 });
+ await setState({ sharedCounter: state.sharedCounter + 1 });
+ // await setState({ ...state, sharedCounter: state.sharedCounter + 1 }); 
+ // this also works, as the previous state spread remains supported

제거됨

streamVNext, resumeStreamVNext 및 observeStreamVNext 메서드

실험적이었던 streamVNext(), resumeStreamVNext() 및 observeStreamVNext() 메서드가 제거되었습니다. 이제 업데이트된 이벤트 구조와 반환 타입을 갖춘 이 메서드들의 구현이 표준 구현으로 제공됩니다. 마이그레이션하려면 표준 stream(), resumeStream() 및 observeStream() 메서드를 사용하세요. Workflow 접두사가 붙은 이름을 사용하도록 이벤트 타입 검사를 업데이트하고 스트림 속성에 직접 액세스하세요. 자세한 내용은 Run.stream(), Run.resumeStream() 및 Run.observeStream()을 참조하세요. :::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/workflow-stream-vnext .

:::

단계 조건 함수 매개변수에서는 suspend()와 setState()를 사용할 수 없음

단계 조건 함수 매개변수에서는 suspend() 및 setState() 함수를 사용할 수 없습니다. 마이그레이션하려면 단계 실행 함수에서 suspend() 함수를 대신 사용하세요.

.dowhile(step, async ({ suspend, state, setState }) => {
- setState({...state, updatedState: "updated state"})
- await suspend({ reason: "Suspension reason" });
+ // Use the suspend/setState in the step execute function instead
});

dountil 및 branch 조건 함수 매개변수에도 동일하게 적용됩니다.

레거시 Workflow 내보내기

@mastra/core에서 ./workflows/legacy 내보내기 경로가 제거되었습니다. 레거시 Workflow는 더 이상 지원되지 않습니다. 마이그레이션하려면 새로운 Workflow API를 사용하세요. 레거시 Workflow에는 직접 마이그레이션 경로가 없습니다.

- import { LegacyWorkflow } from '@mastra/core/workflows/legacy';
+ // Legacy workflows are no longer supported
+ // Migrate to the new workflow API

WorkflowRunOutput의 pipeThrough 및 pipeTo 메서드

WorkflowRunOutput의 pipeThrough() 및 pipeTo() 메서드는 더 이상 사용하지 않는 것이 권장됩니다. 이 메서드는 계속 작동하지만 콘솔 경고가 표시됩니다. 마이그레이션하려면 실행 출력에서 메서드를 직접 호출하는 대신 fullStream 속성을 사용하세요.

  const run = await workflow.createRun({ input: { ... } });
- await run.pipeTo(writableStream);
- const transformed = run.pipeThrough(transformStream);
+ await run.fullStream.pipeTo(writableStream);
+ const transformed = run.fullStream.pipeThrough(transformStream);

이벤트 API 시청

레거시 감시 이벤트가 제거되고 v2 이벤트 API에 통합되었습니다. watch() 메서드와 관련 감시 엔드포인트는 더 이상 사용할 수 없습니다. 마이그레이션하려면 이벤트 감시 대신 Workflow 이벤트 API 또는 스트리밍을 사용하세요.

- const workflow = mastraClient.getWorkflow('my-workflow');
- const run = await workflow.createRun();
- await run.watch((event) => {
-   console.log('Step completed:', event);
- });

+ const workflow = mastraClient.getWorkflow('my-workflow');
+ const run = await workflow.createRun();
+ const stream = await run.stream({ inputData: { ... } });
+ for await (const chunk of stream) {
+   console.log('Step completed:', chunk);
+ }

waitForEventAPI

Workflow에서 waitForEvent API가 제거되었습니다. 대신 일시 중지/재개 API를 사용하세요. 마이그레이션하려면 Workflow 실행 마일스톤을 기다리는 일시 중지/재개 API를 사용하세요.

- workflow.waitForEvent('step-complete', step1).commit();
+ workflow.then(step1).commit();
+ // Use suspend/resume API instead, in step1 execute function
createStep({
- execute: async (inputData, context) => {
-  // ... execution logic 
- }
+ execute: async (inputData, context) => {
+   if (!context.resumeData) {
+     return context.suspend({})
+   }
+ }
});
+
+ // after workflow is suspended, you can resume it
+ const result = await run.start({ inputData: { ... } });
+ if (result.status === 'suspended') {
+   const resumedResult = await run.resume({
+     resumeData: {
+       event: 'step-complete',
+     },
+     step: 'step1',
+   });
+ }

sendEventAPI

Workflow에서 sendEvent API가 제거되었습니다. 대신 일시 중지/재개 API를 사용하세요.