동적 Workflow

:::실험적

이 기능은 베타 버전입니다. API가 안정될 때까지 주요 버전 변경 없이 주요 변경 사항이 발생할 수 있습니다.

:::

동적 Workflow는 코드 대신 데이터로 표현되는 Workflow 정의입니다. 정의는 Workflow의 스키마와 단계 그래프를 설명하는 JSON 문서입니다. Mastra는 정의의 유효성을 검사하고 이를 실행 가능한 Workflow로 등록한 다음 프로세스를 다시 시작해도 유지되도록 스토리지에 유지합니다.

정의에는 JavaScript 클로저가 포함되어 있지 않으므로 JSON을 생성할 수 있는 모든 것(HTTP 클라이언트, LLM, 시각적 편집기 또는 자체 Tool)으로 Workflow를 작성할 수 있습니다. 일단 등록되면 동적 Workflow는 코드 정의 Workflow와 동일한 실행 API를 통해 실행됩니다.

동적 Workflow를 사용해야 하는 경우

사용자, Agent, 시각적 편집기 또는 외부 시스템이 애플리케이션 코드를 변경하거나 다시 배포하지 않고 Workflow를 생성해야 하는 경우 동적 Workflow를 사용합니다.

Workflow가 애플리케이션 소스에 속하거나 사용자 정의 단계 함수가 필요하면 계속해서 createWorkflow()으로 Workflow를 정의하세요. 동적 Workflow는 Mastra 인스턴스에 이미 등록된 Agent, Tool, Workflow를 호출할 수 있습니다.

빠른 시작

다음 예제에서는 Tool을 등록하고 동적 Workflow에서 호출합니다. 그런 다음 LibSQLStore가 정의를 mastra.db에 영속화한 상태로 Workflow를 실행하므로, Mastra는 재시작 후에도 이를 복원할 수 있습니다.

src/dynamic-workflow.ts

import { Mastra } from '@mastra/core/mastra'
import { createTool } from '@mastra/core/tools'
import { LibSQLStore } from '@mastra/libsql'
import { z } from 'zod'

const greetingTool = createTool({
  id: 'create-greeting',
  description: 'Create a greeting for a name',
  inputSchema: z.object({
    name: z.string(),
  }),
  outputSchema: z.object({
    message: z.string(),
  }),
  execute: async ({ name }) => ({
    message: `Hello, ${name}!`,
  }),
})

const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  tools: { 'create-greeting': greetingTool },
})

await mastra.addDynamicWorkflow({
  id: 'greeting-workflow',
  description: 'Create a greeting for the supplied name',
  inputSchema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
    },
    required: ['name'],
  },
  outputSchema: {
    type: 'object',
    properties: {
      message: { type: 'string' },
    },
    required: ['message'],
  },
  graph: [
    {
      type: 'tool',
      id: 'greet',
      toolId: 'create-greeting',
    },
  ],
})

const workflow = mastra.getWorkflow('greeting-workflow')
const run = await workflow.createRun()
const result = await run.start({
  inputData: { name: 'Ada' },
})

if (result.status === 'success') {
  console.log(result.result.message)
}

Workflow는 Hello, Ada!를 출력합니다. addDynamicWorkflow()를 호출하면 스토리지나 라이브 Workflow 레지스트리를 변경하기 전에 정의를 검증합니다. 정의는 JSON 왕복 변환 후에도 유지되어야 하므로 JSON 스키마를 사용합니다. graph는 호출할 등록 구성 요소와 구성 요소 간 데이터 이동 방식을 설명합니다. 모든 필드와 그래프 항목은 동적 Workflow 정의 레퍼런스를 참조하세요.

정의 빌드 및 업데이트

정의는 JSON을 생성하는 모든 소스에서 나올 수 있습니다. 예를 들어 API 경로는 시각적 편집기에서 생성된 정의를 수락하고 이를 직접 등록할 수 있습니다.

const definition = await request.json()
await mastra.addDynamicWorkflow(definition)

종속성을 먼저 등록하세요.

동적 Workflow를 추가하기 전에 참조되는 구성 요소를 동일한 Mastra 인스턴스에 등록하세요. Agent 및 중첩 Workflow 항목은 자체 ID를 사용합니다. Tool 항목은 Mastra의 tools 객체에 있는 키를 사용하므로, 빠른 시작에서는 toolId로 해당 키를 참조하기 전에 Tool을 create-greeting 키로 등록합니다. 한 단계의 출력이 다음 단계의 입력과 일치하지 않으면 mapping 항목을 사용하세요. 매핑 항목은 Workflow 입력과 이전 단계 결과뿐 아니라 Workflow 상태와 요청 컨텍스트에서도 데이터를 읽을 수 있습니다. 지원되는 매핑 설명자는 정의 레퍼런스에 나와 있습니다.

Workflow 바꾸기

영속화된 정의와 라이브 등록을 교체하려면 동일한 id를 사용해 새 정의를 추가하세요.

await mastra.addDynamicWorkflow(updatedDefinition)

새로운 실행에서는 업데이트된 그래프를 사용합니다. 이미 시작된 실행은 원래 그래프로 계속됩니다.

중첩된 Workflow를 함께 추가

루트 Workflow가 아직 등록되지 않은 도우미 Workflow를 참조하는 경우 다음을 사용하여 전체 세트를 추가하세요.addDynamicWorkflows():

await mastra.addDynamicWorkflows([rootDefinition, helperDefinition])

Mastra는 번들을 하나의 단위로 검증하고 종속성에서 등록 순서를 결정합니다. 유효성 검증이 실패하면 어떤 정의도 등록되지 않습니다.

HTTP를 통해 정의 관리

애플리케이션에서 동적 Workflow를 관리하기 위해 Mastra 인스턴스에 직접 접근할 필요는 없습니다. 다음 인터페이스 중 하나를 사용하세요.

• 클라이언트 SDK Workflow API: JavaScript 또는 TypeScript 클라이언트에서 upsertDynamicWorkflow()를 호출합니다.
• 서버 경로: 정의를 POST /api/stored/workflows로 전송합니다. 인증된 서버에서 동적 Workflow를 관리하려면 stored-workflows:read 및 stored-workflows:write 권한이 필요합니다. 등록된 Workflow를 실행하려면 workflows:execute가 필요합니다.

지속 정의

저장된 정의는 workflowDefinitions 스토리지 도메인을 사용합니다. 시작할 때 Mastra는 활성 정의를 스토리지에서 불러와 종속성 순서대로 등록합니다. 스토리지 어댑터가 이 도메인을 지원하지 않더라도 addDynamicWorkflow()는 Workflow를 메모리에 등록하지만, 프로세스를 재시작하면 정의가 손실됩니다. 어댑터 지원 여부는 스토리지 레퍼런스를 참조하세요.

관련된

• 동적 Workflow 정의
• Mastra.addDynamicWorkflow()
• Mastra.addDynamicWorkflows()
• 클라이언트 SDK Workflow API
• 서버 경로