마스트라 수업
그만큼Mastra클래스는 모든 Mastra 애플리케이션의 중앙 조정자로서 Agent, Workflow, 스토리지, 로깅, Observability 등을 관리합니다. 일반적으로 단일 인스턴스를 생성합니다.Mastra귀하의 신청서를 조정합니다.
Mastra는 애플리케이션 전체에서 접근해야 하는 Agent, Workflow, Tool 및 기타 구성 요소를 등록하는 최상위 레지스트리라고 생각하면 됩니다.
사용예사용예에 대한 직접 링크
src/mastra/index.ts
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 스케줄러를 통해 자동으로 전달되어야 하는 경우 예약된 알림 발송을 활성화합니다.
src/mastra/index.ts
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 스케줄러는 처음으로 지연 알림이나 요약 알림이 생성될 때 지연 활성화되므로, 알림을 연기하지 않는 앱에서는 스케줄러가 전혀 실행되지 않습니다.
생성자 매개변수생성자 매개변수에 대한 직접 링크
사용 가능한 모든 구성 옵션의 자세한 문서는 구성 레퍼런스를 참조하세요.
agents?:
Record<string, Agent>
= {}
이름을 키로 하여 등록할 Agent 인스턴스
tools?:
Record<string, ToolApi>
= {}
등록할 Tool 인스턴스입니다. 키는 `getTool()`에서 사용하는 등록 키이고 값은 Tool 인스턴스입니다. Tool 자체의 ID로 조회하려면 `getToolById()`를 사용하고, 레지스트리를 읽으려면 `listTools()`를 사용합니다.
storage?:
MastraCompositeStore
데이터를 영구 저장하기 위한 스토리지 엔진 인스턴스
vectors?:
Record<string, MastraVector>
의미론적 검색 및 벡터 기반 Tool에 사용되는 벡터 스토어 인스턴스(예: Pinecone, PgVector 또는 Qdrant)
logger?:
Logger
= INFO 수준의 콘솔 로거
new PinoLogger()로 생성한 로거 인스턴스
idGenerator?:
(context?: IdGeneratorContext) => string
사용자 정의 ID 생성기 함수입니다. Agent, Workflow, Memory 및 기타 구성 요소에서 고유 식별자를 생성하는 데 사용됩니다. 컨텍스트 인식 ID 형식을 지원하도록 idType, source, entityId, threadId 등의 선택적 컨텍스트를 받습니다.
workflows?:
Record<string, Workflow>
= {}
등록할 Workflow입니다. 키-값 쌍으로 구성되며, 키는 Workflow 이름이고 값은 Workflow 인스턴스입니다.
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: false, transpilePackages: [], dynamicPackages: [] }
externals, sourcemap, transpilePackages 및 dynamicPackages 옵션을 포함하는 애셋 번들러 구성입니다.
scorers?:
Record<string, Scorer>
= {}
Agent 응답과 Workflow 출력을 평가하기 위한 스코어러
processors?:
Record<string, Processor>
= {}
Agent 입력과 출력을 변환하기 위한 입출력 프로세서
gateways?:
Record<string, MastraModelGateway>
= {}
대체 Provider 또는 비공개 배포를 통해 AI Model에 접근하도록 등록할 사용자 정의 Model 게이트웨이입니다. 키-값 쌍으로 구성되며, 키는 레지스트리 키(getGateway()에서 사용)이고 값은 게이트웨이 인스턴스입니다.
memory?:
Record<string, MastraMemory>
= {}
등록할 Memory 인스턴스입니다. 저장된 Agent에서 이를 참조하고 런타임에 해석할 수 있습니다. 키-값 쌍으로 구성되며, 키는 레지스트리 키이고 값은 Memory 인스턴스입니다.
notifications?:
object
알림 신호 디스패치를 위한 런타임 구성입니다.
object
dispatch?:
NotificationDispatchConfig
지연 알림 및 알림 요약을 위한 예약 디스패치 구성입니다. 디스패치는 기본적으로 활성화됩니다.
object
enabled?:
boolean
자동 예약 알림 디스패치를 사용하지 않으려면
false로 설정합니다.cron?:
string
내부 알림 디스패처 Workflow에서 사용하는 크론 일정입니다.
batchSize?:
number
디스패치 실행당 처리할 수 있는, 처리 시점이 된 알림 레코드의 최대 수입니다.
versions?:
VersionOverrides
하위 Agent 위임을 위한 전역 버전 재정의입니다. 감독자 Agent가 하위 Agent에 위임하면 이 재정의에 따라 코드에 정의된 기본값 대신 해당 하위 Agent의 어떤 저장 버전을 사용할지 결정됩니다. editor 패키지를 구성해야 합니다. 자세한 내용은 Editor 버전 관리를 참조하세요.
VersionOverrides
agents?:
Record<string, VersionSelector>
Agent ID를 버전 선택기에 매핑한 맵입니다. 각 선택기는 ID 또는 게시 상태를 기준으로 특정 버전을 지정할 수 있습니다.
VersionSelector
versionId?:
string
사용할 특정 버전의 ID입니다.
status?:
'draft' | 'published'
이 게시 상태에 해당하는 최신 버전을 선택합니다.
workers?:
MastraWorker[] | false
이 Mastra 인스턴스에서 실행할 워커를 구성합니다. 생략하면 Mastra가 PubSub 및 구성에 따라 기본 워커를 자동 생성합니다. 모든 이벤트 처리를 비활성화하려면
false를 전달합니다(독립 실행형 워커를 별도로 실행할 때 유용함). 사용자 정의 워커를 추가하려면 MastraWorker[]를 전달합니다. 이 워커들은 자동 생성된 기본 워커와 병합되며, 기본 워커와 name이 같은 사용자 정의 워커가 기본 워커를 대체합니다.backgroundTasks?:
BackgroundTaskManagerConfig
Agent의 백그라운드 작업 실행을 구성합니다. 모든 옵션은 백그라운드 작업 구성 레퍼런스를 참조하세요.
BackgroundTaskManagerConfig
enabled?:
boolean
백그라운드 작업 디스패치를 활성화합니다.
globalConcurrency?:
number
모든 Agent에 걸쳐 동시에 실행할 수 있는 최대 작업 수입니다.
perAgentConcurrency?:
number
Agent당 동시에 실행할 수 있는 최대 작업 수입니다.
backpressure?:
'queue' | 'reject' | 'fallback-sync'
동시 실행 한도에 도달했을 때의 동작입니다.
defaultTimeoutMs?:
number
기본 작업 제한 시간(밀리초)입니다.
defaultRetries?:
RetryConfig
기본 재시도 구성입니다.
scheduler?:
object
크론 기반 Workflow 트리거를 위한 스케줄러 워커를 구성합니다. 어떤 Workflow든
schedule을 선언하면 자동으로 활성화됩니다. 예약된 Workflow를 참조하세요.object
enabled?:
boolean
스케줄러를 명시적으로 활성화하거나 비활성화합니다.
행동 양식행동 양식에 대한 직접 링크
recoverAllDurableAgents()recoveralldurableagents에 대한 직접 링크
등록된 모든 영속 Agent에서 고아 상태인 모든 running 영속 Agent 실행을 다시 구동합니다. recovery.durableAgents가 'auto'이면 부팅 시 자동으로 호출됩니다. 수동 복구를 위해 직접 호출하거나 예약된 작업에서 호출할 수도 있습니다.
영구 저장소가 필요합니다. Memory 내 저장소를 사용하면 프로세스를 다시 시작한 후 복구할 것이 없습니다.
const result = await mastra.recoverAllDurableAgents()
// { agents: 2, recovered: 3, succeeded: 3, failed: 0 }
보고:
agents:
number
검사한 영속 Agent의 수입니다.
recovered:
number
다시 구동한 총 실행 수입니다.
succeeded:
number
성공적으로 다시 시작된 실행 수입니다.
failed:
number
다시 시작하는 동안 오류가 발생한 실행 수입니다.