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

# 마스트라 수업

그만큼`Mastra`클래스는 모든 Mastra 애플리케이션의 중앙 조정자로서 Agent, Workflow, 스토리지, 로깅, Observability 등을 관리합니다. 일반적으로 단일 인스턴스를 생성합니다.`Mastra`귀하의 신청서를 조정합니다.

`Mastra`는 애플리케이션 전체에서 접근해야 하는 Agent, Workflow, Tool 및 기타 구성 요소를 등록하는 최상위 레지스트리라고 생각하면 됩니다.

## 사용예

```typescript
import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'
import { LibSQLStore } from '@mastra/libsql'
import { weatherWorkflow } from './workflows/weather-workflow'
import { weatherAgent } from './agents/weather-agent'

export const mastra = new Mastra({
  workflows: { weatherWorkflow },
  agents: { weatherAgent },
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: ':memory:',
  }),
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
})
```

지연된 알림 기록 및 알림 요약이 Workflow 스케줄러를 통해 자동으로 전달되어야 하는 경우 예약된 알림 발송을 활성화합니다.

```typescript
export const mastra = new Mastra({
  agents: { supportAgent },
  storage,
  notifications: {
    dispatch: {
      enabled: true,
      cron: '*/1 * * * *',
      batchSize: 100,
    },
  },
})
```

`notifications.dispatch.enabled`를 사용하면 내부 디스패처 Workflow가 기본 크론 `*/1 * * * *`에 따라 실행됩니다. 디스패처는 스토리지에서 처리 시점이 된 알림 레코드를 읽고 `agentId`, `resourceId`, `threadId`별로 요약을 그룹화한 다음 Agent 스레드 런타임을 통해 신호를 내보냅니다. 이는 사용자용 진입점이 아닙니다. 디스패치 일정과 이를 지원하는 Workflow 스케줄러는 처음으로 지연 알림이나 요약 알림이 생성될 때 지연 활성화되므로, 알림을 연기하지 않는 앱에서는 스케줄러가 전혀 실행되지 않습니다.

## 생성자 매개변수

사용 가능한 모든 구성 옵션의 자세한 문서는 [구성 레퍼런스](https://mastra.zisheng.pro/ko/reference/configuration)를 참조하세요.

**agents** (`Record<string, Agent>`): 이름을 키로 하여 등록할 Agent 인스턴스 (Default: `{}`)

**tools** (`Record<string, ToolApi>`): 등록할 Tool 인스턴스입니다. 키는 \`getTool()\`에서 사용하는 등록 키이고 값은 Tool 인스턴스입니다. Tool 자체의 ID로 조회하려면 \`getToolById()\`를 사용하고, 레지스트리를 읽으려면 \`listTools()\`를 사용합니다. (Default: `{}`)

**storage** (`MastraCompositeStore`): 데이터를 영구 저장하기 위한 스토리지 엔진 인스턴스

**vectors** (`Record<string, MastraVector>`): 의미론적 검색 및 벡터 기반 Tool에 사용되는 벡터 스토어 인스턴스(예: Pinecone, PgVector 또는 Qdrant)

**logger** (`Logger`): new PinoLogger()로 생성한 로거 인스턴스 (Default: `INFO 수준의 콘솔 로거`)

**idGenerator** (`(context?: IdGeneratorContext) => string`): 사용자 정의 ID 생성기 함수입니다. Agent, Workflow, Memory 및 기타 구성 요소에서 고유 식별자를 생성하는 데 사용됩니다. 컨텍스트 인식 ID 형식을 지원하도록 idType, source, entityId, threadId 등의 선택적 컨텍스트를 받습니다.

**workflows** (`Record<string, Workflow>`): 등록할 Workflow입니다. 키-값 쌍으로 구성되며, 키는 Workflow 이름이고 값은 Workflow 인스턴스입니다. (Default: `{}`)

**tts** (`Record<string, MastraVoice>`): 음성 합성을 위한 텍스트 음성 변환 Provider

**observability** (`ObservabilityEntrypoint`): 추적 및 모니터링을 위한 Observability 구성

**environment** (`string`): 배포 환경 이름(예: production, staging, development)입니다. 설정하면 모든 Observability 신호에 자동으로 연결되므로, 호출할 때마다 tracingOptions.metadata.environment를 전달하지 않아도 환경별로 필터링할 수 있습니다. 설정하지 않으면 process.env.NODE\_ENV를 사용하며, 둘 다 설정되지 않은 경우 undefined로 유지됩니다. 호출별 tracingOptions.metadata.environment가 항상 우선합니다.

**deployer** (`MastraDeployer`): 배포를 관리하기 위한 MastraDeployer 인스턴스입니다.

**server** (`ServerConfig`): 포트, 호스트, 제한 시간, API 경로, 미들웨어, CORS 설정과 Swagger UI, API 요청 로깅 및 OpenAPI 문서를 위한 빌드 옵션을 포함하는 서버 구성입니다.

**mcpServers** (`Record<string, MCPServerBase>`): 키는 레지스트리 키(getMCPServer()에서 사용)이고 값은 MCPServer 인스턴스 또는 MCPServerBase를 확장하는 클래스인 객체입니다. 각 MCPServer에는 id 속성이 있어야 합니다. 서버는 getMCPServer()를 사용하여 레지스트리 키로 가져오거나 getMCPServerById()를 사용하여 서버 자체의 id로 가져올 수 있습니다.

**bundler** (`BundlerConfig`): externals, sourcemap, transpilePackages 및 dynamicPackages 옵션을 포함하는 애셋 번들러 구성입니다. (Default: `{ externals: [], sourcemap: false, transpilePackages: [], dynamicPackages: [] }`)

**scorers** (`Record<string, Scorer>`): Agent 응답과 Workflow 출력을 평가하기 위한 스코어러 (Default: `{}`)

**processors** (`Record<string, Processor>`): Agent 입력과 출력을 변환하기 위한 입출력 프로세서 (Default: `{}`)

**gateways** (`Record<string, MastraModelGateway>`): 대체 Provider 또는 비공개 배포를 통해 AI Model에 접근하도록 등록할 사용자 정의 Model 게이트웨이입니다. 키-값 쌍으로 구성되며, 키는 레지스트리 키(getGateway()에서 사용)이고 값은 게이트웨이 인스턴스입니다. (Default: `{}`)

**memory** (`Record<string, MastraMemory>`): 등록할 Memory 인스턴스입니다. 저장된 Agent에서 이를 참조하고 런타임에 해석할 수 있습니다. 키-값 쌍으로 구성되며, 키는 레지스트리 키이고 값은 Memory 인스턴스입니다. (Default: `{}`)

**notifications** (`object`): 알림 신호 디스패치를 위한 런타임 구성입니다.

**notifications.dispatch** (`NotificationDispatchConfig`): 지연 알림 및 알림 요약을 위한 예약 디스패치 구성입니다. 디스패치는 기본적으로 활성화됩니다.

**notifications.dispatch.enabled** (`boolean`): 자동 예약 알림 디스패치를 사용하지 않으려면 false로 설정합니다.

**notifications.dispatch.cron** (`string`): 내부 알림 디스패처 Workflow에서 사용하는 크론 일정입니다.

**notifications.dispatch.batchSize** (`number`): 디스패치 실행당 처리할 수 있는, 처리 시점이 된 알림 레코드의 최대 수입니다.

**versions** (`VersionOverrides`): 하위 Agent 위임을 위한 전역 버전 재정의입니다. 감독자 Agent가 하위 Agent에 위임하면 이 재정의에 따라 코드에 정의된 기본값 대신 해당 하위 Agent의 어떤 저장 버전을 사용할지 결정됩니다. editor 패키지를 구성해야 합니다. 자세한 내용은 Editor 버전 관리를 참조하세요.

**versions.agents** (`Record<string, VersionSelector>`): Agent ID를 버전 선택기에 매핑한 맵입니다. 각 선택기는 ID 또는 게시 상태를 기준으로 특정 버전을 지정할 수 있습니다.

**versions.agents.versionId** (`string`): 사용할 특정 버전의 ID입니다.

**versions.agents.status** (`'draft' | 'published'`): 이 게시 상태에 해당하는 최신 버전을 선택합니다.

**workers** (`MastraWorker[] | false`): 이 Mastra 인스턴스에서 실행할 워커를 구성합니다. 생략하면 Mastra가 PubSub 및 구성에 따라 기본 워커를 자동 생성합니다. 모든 이벤트 처리를 비활성화하려면 false를 전달합니다(독립 실행형 워커를 별도로 실행할 때 유용함). 사용자 정의 워커를 추가하려면 MastraWorker\[]를 전달합니다. 이 워커들은 자동 생성된 기본 워커와 병합되며, 기본 워커와 name이 같은 사용자 정의 워커가 기본 워커를 대체합니다.

**backgroundTasks** (`BackgroundTaskManagerConfig`): Agent의 백그라운드 작업 실행을 구성합니다. 모든 옵션은 백그라운드 작업 구성 레퍼런스를 참조하세요.

**backgroundTasks.enabled** (`boolean`): 백그라운드 작업 디스패치를 활성화합니다.

**backgroundTasks.globalConcurrency** (`number`): 모든 Agent에 걸쳐 동시에 실행할 수 있는 최대 작업 수입니다.

**backgroundTasks.perAgentConcurrency** (`number`): Agent당 동시에 실행할 수 있는 최대 작업 수입니다.

**backgroundTasks.backpressure** (`'queue' | 'reject' | 'fallback-sync'`): 동시 실행 한도에 도달했을 때의 동작입니다.

**backgroundTasks.defaultTimeoutMs** (`number`): 기본 작업 제한 시간(밀리초)입니다.

**backgroundTasks.defaultRetries** (`RetryConfig`): 기본 재시도 구성입니다.

**scheduler** (`object`): 크론 기반 Workflow 트리거를 위한 스케줄러 워커를 구성합니다. 어떤 Workflow든 schedule을 선언하면 자동으로 활성화됩니다. 예약된 Workflow를 참조하세요.

**scheduler.enabled** (`boolean`): 스케줄러를 명시적으로 활성화하거나 비활성화합니다.

**recovery** (`MastraRecoveryConfig`): 고아 상태인 Agent 및 Workflow 실행에 대한 부팅 시 복구 동작입니다. 충돌 복구를 참조하세요. (Default: `{ durableAgents: 'off' }`)

**recovery.durableAgents** (`'auto' | 'off'`): 서버 부팅 시 고아 상태인 RUNNING 영속 Agent 실행을 자동으로 다시 구동하려면 'auto'로 설정합니다. 복구 과정에서는 LLM 호출과 Tool 호출을 다시 실행하므로 Tool은 멱등성을 보장해야 합니다. 충돌 복구를 참조하세요.

## 행동 양식

### `recoverAllDurableAgents()`

등록된 모든 영속 Agent에서 고아 상태인 모든 `running` 영속 Agent 실행을 다시 구동합니다. `recovery.durableAgents`가 `'auto'`이면 부팅 시 자동으로 호출됩니다. 수동 복구를 위해 직접 호출하거나 예약된 작업에서 호출할 수도 있습니다. 영구 저장소가 필요합니다. Memory 내 저장소를 사용하면 프로세스를 다시 시작한 후 복구할 것이 없습니다.

```typescript
const result = await mastra.recoverAllDurableAgents()
// { agents: 2, recovered: 3, succeeded: 3, failed: 0 }
```

보고:

**agents** (`number`): 검사한 영속 Agent의 수입니다.

**recovered** (`number`): 다시 구동한 총 실행 수입니다.

**succeeded** (`number`): 성공적으로 다시 시작된 실행 수입니다.

**failed** (`number`): 다시 시작하는 동안 오류가 발생한 실행 수입니다.