노동자

:::실험적

이 기능은 베타 버전입니다. API는 프로덕션 용도로 사용할 만큼 안정적이지만 일부 세부 사항은 변경될 수 있습니다. 현재 알려진 문제는 알려진 제한 사항을 참조하세요. :::

작업자는 요청-응답 주기 외부에서 백그라운드 처리를 처리합니다. Workflow 단계 실행, cron 기반 예약 및 장기 실행 Tool 호출은 모두 작업자에서 실행되어 API 응답성을 유지합니다.

기본적으로 작업자는 API와 동일한 프로세스에서 실행됩니다. 프로덕션 워크로드의 경우 이를 별도의 프로세스나 컨테이너로 분할하고 각각을 독립적으로 확장할 수 있습니다.

워커를 사용해야 하는 경우

다음 중 하나라도 해당되면 근로자가 중요합니다.

• Workflow 단계는 몇 초 이상 걸리며 API 응답을 차단해서는 안 됩니다.
• 진행 중인 작업이 프로세스를 다시 시작해도 지속되도록 하려면 이벤트 내구성이 필요합니다.
• 시스템의 다양한 부분은 독립적으로 확장되어야 합니다(예: 더 많은 API 인스턴스 없이 더 많은 오케스트레이션 용량).
• 백그라운드 Tool 호출은 전용 컴퓨팅에서 실행되어야 합니다.

애플리케이션의 트래픽이 적고 Workflow가 빠르게 완료된다면 기본 인프로세스 설정으로 충분합니다. 필요해질 때까지 작업자 인프라를 구성하지 않아도 됩니다.

작업자 유형

Mastra에는 세 가지 기본 제공 작업자 유형이 있습니다. 각각은 특정 종류의 백그라운드 처리를 처리합니다.

오케스트레이션 작업자

PubSub 버스에서 Workflow 이벤트를 구독하고 Workflow 단계를 실행합니다. 모든 workflow.start, 단계 전환 및 수명 주기 이벤트가 이 작업자를 통과합니다. 분할 배포에서 오케스트레이션 작업자는 분산 PubSub 백엔드에서 이벤트를 가져오고 HTTP를 통해 단계 실행을 API에 다시 위임합니다. 인프로세스 모드에서는 단계를 직접 실행합니다. 오케스트레이션 작업자에는 RedisStreamsPubSub 또는 GoogleCloudPubSub처럼 풀 모드를 지원하는 PubSub 백엔드가 필요합니다.

스케줄러 작업자

예정된 크론 일정을 찾기 위해 스토리지를 폴링하고 workflow.start 이벤트를 게시합니다. 이 작업자는 생산자 역할만 하며, 오케스트레이션 작업자가 처리할 작업을 생성합니다. 스케줄러는 Workflow 정의의 선언적 schedule 필드를 자동으로 읽습니다. 일정 선언 방법은 예약된 Workflow를 참조하세요. 둘 이상의 스케줄러 인스턴스를 실행하지 마십시오.동일한 스토리지를 폴링하는 여러 스케줄러는 동일한 일정에 대해 중복 이벤트를 발생시킵니다.

백그라운드 작업 작업자

background: { enabled: true }로 표시된 Agent Tool 호출을 실행합니다. Agent가 백그라운드 Tool을 호출하면 API는 응답 스트림을 차단하는 대신 이 작업자에게 작업을 전달합니다. 백그라운드 작업 작업자는 PubSub 버스를 통해 동시성 제한, 작업 수명 주기 및 결과 전달을 관리합니다.

노동자들이 일하는 방식

인프로세스 모드(기본값)

구성이 없으면 Mastra는 API 프로세스 내에서 작업자를 생성하고 시작합니다. 이벤트는 Memory 내 PubSub를 통해 흐르며 모든 것이 단일 Node.js 런타임을 공유합니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'

export const mastra = new Mastra({
  // Workers run in-process by default.
  // No pubsub or worker config needed.
})

이 설정에는 스토리지 어댑터 이외의 외부 인프라가 필요하지 않습니다. 프로세스 충돌이 발생해도 살아남지 못하며 개별 구성 요소를 확장할 수 없습니다.

분할 프로세스

별도의 프로세스에서 작업자를 실행하려면 분산 PubSub 백엔드를 구성하고 MASTRA_WORKERS 환경 변수를 사용하여 각 프로세스에서 시작할 작업자를 제어하세요.

Redis Streams + PostgreSQL

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { RedisStreamsPubSub } from '@mastra/redis-streams'
import { PostgresStore } from '@mastra/pg'

export const mastra = new Mastra({
  storage: new PostgresStore({
    connectionString: process.env.DATABASE_URL!,
  }),
  pubsub: new RedisStreamsPubSub({
    url: process.env.REDIS_URL!,
  }),
})

Google Cloud Pub/Sub + LibSQL

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { GoogleCloudPubSub } from '@mastra/google-cloud-pubsub'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    url: process.env.DATABASE_URL!,
  }),
  pubsub: new GoogleCloudPubSub({
    projectId: process.env.GCP_PROJECT_ID!,
  }),
})

어떤 지원되는 스토리지 백엔드든 사용할 수 있습니다. 원하는 데이터베이스의 스토리지 어댑터로 교체하세요. 동일한 빌드 아티팩트를 여러 컨테이너에서 실행하고 각각 다른 MASTRA_WORKERS 값을 지정하여 각 프로세스에서 시작할 작업자를 제어하세요. 분할 배포에는 분산 PubSub 백엔드(RedisStreamsPubSub 또는 GoogleCloudPubSub), 공유 스토리지 백엔드, 그리고 오케스트레이션 작업자와 API 간의 네트워크 연결이 필요합니다. 작업자 배포 가이드에서는 Docker Compose와 Kubernetes 예제를 통해 이 설정 과정을 안내합니다.

네트워크 아키텍처

작업자는 내부 인프라입니다. 최종 사용자에게 노출되지 않으며 자체 하위 도메인, 공개 URL 또는 인바운드 HTTP 경로가 필요하지 않습니다.

분할 배포에서는 다음을 수행합니다.

• API 서버는 외부에 공개되는 유일한 프로세스입니다.: REST 엔드포인트, Agent 상호 작용, Workflow 트리거 및 사용자 지정 경로를 포함한 모든 클라이언트 HTTP 요청을 처리합니다.
• 작업자는 아웃바운드 연결만 사용합니다.: 분산 PubSub 백엔드에서 이벤트를 가져오고 공유 스토리지 데이터베이스를 읽고 씁니다. 클라이언트의 인바운드 트래픽은 허용하지 않습니다.
• 오케스트레이션 작업자는 내부적으로 API를 호출합니다.: MASTRA_STEP_EXECUTION_URL을 사용하여 컨테이너 네트워크를 통해 API에 단계 실행 요청을 보냅니다. 이는 내부 서비스 간 통신이며 공개 엔드포인트가 아닙니다. 세 가지 작업자 유형(오케스트레이션, 스케줄러, 백그라운드 작업)은 모두 프라이빗 네트워크의 API 뒤에 있습니다. PubSub 백엔드 및 스토리지 데이터베이스에 대한 액세스를 공유하지만 클라이언트로부터 직접 트래픽을 수신하지는 않습니다. 작업자 관련 기능에 HTTP 경로(예: 음성 통합을 위한 토큰 생성)가 필요한 경우 해당 경로는 작업자 프로세스가 아닌 API 서버에서 실행됩니다.

알려진 제한사항

• 배달 못한 메시지 대기열 없음: 실패한 이벤트는 확인 거부 후 재시도되지만 모든 재시도가 실패한 이벤트를 위한 DLQ는 없습니다.
• 기본 제공 상태 엔드포인트 없음: 작업자는 HTTP 상태 확인을 노출하지 않습니다. 컨테이너 수준의 활성 상태 프로브나 프로세스 모니터링을 사용하세요.
• 스케줄러는 단일 인스턴스입니다.: 스케줄러 프로세스를 여러 개 실행하면 일정이 중복 실행됩니다.
• API 충돌 후 실행이 "실행 중" 상태로 멈춤: Workflow 단계를 실행하는 동안 API 프로세스가 충돌하면 실행이 자동 재시도 없이 running 상태로 유지됩니다. 내구성 있는 Agent의 경우 Mastra 설정에서 recovery.durableAgents를 'auto'로 설정하여 서버 재시작 시 고아 실행을 자동으로 다시 구동하세요. 자세한 내용은 충돌 복구를 참조하세요.

관련된

• 작업자 배포 가이드: Docker Compose 및 Kubernetes 예제
• 작업자 인증: 작업자와 API 간 통신 보안
• 작업자 레퍼런스: 지원되는 스토리지 백엔드 목록을 비롯한 작업자 환경 변수 및 유형 세부 정보
• CLI 레퍼런스: mastra worker build 및 mastra worker start
• PubSub: 이벤트 전달 백엔드
• 예약된 Workflow: Workflow에 크론 일정 선언