구성

다음 참조는 Mastra에서 지원되는 모든 옵션을 다룹니다. 인스턴스화하여 Mastra를 초기화하고 구성합니다.Mastra class.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  // Your options...
})

최상위 옵션

Agent

유형: Record<string, Agent>

이름으로 입력된 Agent 인스턴스의 기록입니다. Agent는 AI Model, Tool 및 Memory를 사용하여 결정을 내리고 조치를 취할 수 있는 자율 시스템입니다.

자세한 내용은 Agent 문서를 참조하세요.

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {
    weatherAgent: new Agent({
      id: 'weather-agent',
      name: 'Weather Agent',
      instructions: 'You help with weather information',
      model: 'openai/gpt-5.6-sol',
    }),
  },
})

배경작업

유형: BackgroundTaskManagerConfig

백그라운드 작업 관리자를 활성화하고 구성합니다. 활성화하면 Agent 루프가 계속되는 동안 장기 실행 Tool 호출(하위 Agent 호출 포함)을 비동기적으로 실행하도록 디스패치할 수 있습니다. 작업은 유지되므로 구성된 storage 백엔드가 필요합니다. 자세한 내용은 백그라운드 작업 문서를 참조하세요.

src/mastra/index.ts

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

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  backgroundTasks: {
    enabled: true,
    globalConcurrency: 10,
    perAgentConcurrency: 5,
    backpressure: 'queue',
    defaultTimeoutMs: 300_000,
  },
})

enabled:

boolean

= false

백그라운드 작업 관리자를 사용할 수 있는지 여부입니다. 이 값이 true이고 스토리지 백엔드가 구성된 경우에만 관리자가 초기화됩니다. 이는 기능 가용성 스위치일 뿐이며 어떤 Tool도 백그라운드 디스패치에 자동으로 참여시키지 않습니다. Tool 또는 Agent 계층에서 명시적으로 참여해야 합니다(백그라운드 작업 가이드 참조).

globalConcurrency?:

number

= 10

모든 Agent에서 동시에 실행되는 백그라운드 작업의 최대 개수입니다.

perAgentConcurrency?:

number

= 5

단일 Agent에서 동시에 실행되는 백그라운드 작업의 최대 개수입니다.

backpressure?:

'queue' | 'reject' | 'fallback-sync'

= 'queue'

동시성 제한에 도달했을 때의 동작입니다. 'queue'는 슬롯이 생길 때까지 대기하고, 'reject'는 큐에 추가할 때 오류를 발생시키며, 'fallback-sync'는 대신 Agent 루프에서 Tool을 동기적으로 실행합니다.

defaultTimeoutMs?:

number

= 300000

작업별 기본 타임아웃(밀리초)입니다. Tool별 또는 호출별로 재정의할 수 있습니다.

defaultRetries?:

RetryConfig

실패한 작업에 적용되는 기본 재시도 정책입니다.

maxRetries?:

number

작업을 실패로 표시하기 전까지의 최대 재시도 횟수입니다.

retryDelayMs?:

number

재시도 사이의 지연 시간(밀리초)입니다.

backoffMultiplier?:

number

이후 각 재시도에서 retryDelayMs에 적용되는 배수입니다.

maxRetryDelayMs?:

number

백오프와 관계없이 적용되는 재시도 지연 시간의 상한입니다.

retryableErrors?:

(error: Error) => boolean

주어진 오류를 재시도할지 결정하는 조건자입니다. 기본값: 모든 오류를 재시도합니다.

cleanup?:

CleanupConfig

작업 레코드의 보관 기간과 정리 프로세스 실행 주기를 제어합니다.

completedTtlMs?:

number

완료된 작업 레코드를 보관하는 기간(밀리초)입니다. 기본값: 1시간.

failedTtlMs?:

number

실패한 작업 레코드를 보관하는 기간(밀리초)입니다. 기본값: 24시간.

cleanupIntervalMs?:

number

정리 프로세스의 실행 주기(밀리초)입니다. 기본값: 1분.

waitTimeoutMs?:

number

Agent 루프가 다음으로 넘어가기 전에 백그라운드 작업 완료를 기다리는 시간입니다. 이 시간 내에 작업이 완료되지 않으면 루프는 isContinued를 설정하지 않고 진행합니다. 기본값: undefined(대기하지 않음). Agent별 또는 Tool별로 재정의할 수 있습니다.

onTaskComplete?:

(task: BackgroundTask) => void | Promise<void>

백그라운드 작업이 성공적으로 완료될 때 호출되는 전역 콜백입니다. Tool별 및 Agent별 콜백에 추가로 실행됩니다.

onTaskFailed?:

(task: BackgroundTask) => void | Promise<void>

백그라운드 작업이 실패할 때 호출되는 전역 콜백입니다. Tool별 및 Agent별 콜백에 추가로 실행됩니다.

배포자

유형: MastraDeployer

클라우드 플랫폼에 애플리케이션을 게시하기 위한 배포 공급자입니다.

자세한 내용은 배포 문서를 참조하세요.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { NetlifyDeployer } from '@mastra/deployer-netlify'

export const mastra = new Mastra({
  deployer: new NetlifyDeployer(),
})

이벤트

유형: Record<string, EventHandler | EventHandler[]>

내부 게시/구독 시스템용 이벤트 핸들러입니다. 이벤트가 해당 주제에 게시될 때 호출되는 처리기 함수에 이벤트 주제를 매핑합니다.

경고

이는 Mastra의 Workflow 엔진에서 내부적으로 사용됩니다. 대부분의 사용자는 이 옵션을 구성할 필요가 없습니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  events: {
    'my-topic': async event => {
      console.log('Event received:', event)
    },
  },
})

게이트웨이

유형: Record<string, MastraModelGateway>

LLM Provider에 액세스하기 위한 맞춤형 Model 라우터 게이트웨이입니다. 게이트웨이는 공급자별 인증, URL 구성 및 Model 확인을 처리합니다. 이를 사용하여 맞춤형 또는 자체 호스팅 LLM Provider에 대한 지원을 추가합니다.

자세한 내용은 사용자 정의 게이트웨이 문서를 참조하세요.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MyPrivateGateway } from './gateways'

export const mastra = new Mastra({
  gateways: {
    private: new MyPrivateGateway(),
  },
})

아이디 생성기

유형: (context?: IdGeneratorContext) => string
Default: crypto.randomUUID()

고유 식별자를 생성하기 위한 사용자 정의 ID 생성기 기능입니다. Mastra는 생성되는 항목을 기반으로 ID를 생성할 수 있도록 선택적 컨텍스트를 전달합니다.

IdGeneratorContext다음이 포함됩니다:

• idType: 'thread' | 'message' | 'run' | 'step' | 'generic'
• source?: 'agent' | 'workflow' | 'memory'
• entityId?: 요청 Agent/Workflow/Memory 엔터티의 ID
• threadId?: 관련된 경우 스레드 ID(예: 메시지 ID를 생성하는 경우)
• resourceId?: 관련된 경우 리소스 ID(예: 사용자 범위 스레드)
• role?: 메시지 ID 생성 시 메시지 역할
• stepType?: 단계 ID 생성 시 Workflow 단계 유형

경고

이는 Workflow 실행, Agent 대화 및 기타 리소스에 대한 ID를 생성하기 위해 Mastra에서 내부적으로 사용됩니다. 대부분의 사용자는 이 옵션을 구성할 필요가 없습니다.

src/mastra/index.ts

import { v4 as uuid } from '@lukeed/uuid'
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  idGenerator: context => {
    if (context?.idType === 'message' && context?.threadId) {
      return `msg-${context.threadId}-${uuid()}`
    }

    if (context?.idType === 'run' && context?.source && context?.entityId) {
      return `${context.source}-run-${context.entityId}-${uuid()}`
    }

    return uuid()
  },
})

나무꾼

유형: IMastraLogger | false
기본값: 개발 환경에서는 INFO 수준, 프로덕션 환경에서는 WARN 수준의 ConsoleLogger 애플리케이션 로깅 및 디버깅을 위한 로거 구현입니다. 로깅을 완전히 비활성화하려면 false로 설정하세요. 자세한 내용은 로깅 문서를 참조하세요.

src/mastra/index.ts

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

export const mastra = new Mastra({
  logger: new PinoLogger({ name: 'MyApp', level: 'debug' }),
})

mcp서버

유형: Record<string, MCPServerBase>

Mastra Tool, Agent, Workflow 및 리소스를 MCP 호환 클라이언트에 노출하는 MCP(Model 컨텍스트 프로토콜) 서버입니다. 이를 사용하여 프로토콜을 지원하는 모든 시스템에서 사용할 수 있는 자체 MCP 서버를 작성합니다.

자세한 내용은 MCP 개요를 참조하세요.

src/mastra/index.ts

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

const mcpServer = new MCPServer({
  id: 'my-mcp-server',
  name: 'My MCP Server',
  version: '1.0.0',
})

export const mastra = new Mastra({
  mcpServers: {
    myServer: mcpServer,
  },
})

Memory

유형: Record<string, MastraMemory>

Agent가 참조할 수 있는 Memory 인스턴스의 레지스트리입니다. 기억은 과거 대화의 관련 정보를 유지하여 Agent가 상호 작용 전반에 걸쳐 일관성을 갖도록 해줍니다. Mastra는 최근 메시지에 대한 메시지 기록과 지속적인 사용자별 세부 정보에 대한 작업 Memory를 지원합니다. 의미적 회상은 관련성을 기준으로 오래된 메시지를 검색합니다.

자세한 내용은 Memory 문서를 참조하세요.

노트

대부분의 사용자는 Agent에서 직접 Memory를 구성합니다. 이 최상위 구성은 여러 Agent에서 공유할 수 있는 재사용 가능한 Memory 인스턴스를 정의하기 위한 것입니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Memory } from '@mastra/memory'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: ':memory:',
  }),
  memory: {
    chatMemory: new Memory({
      options: {
        lastMessages: 20,
      },
    }),
  },
})

Observability

유형: ObservabilityEntrypoint

Mastra는 AI 애플리케이션에 대한 관찰 기능을 제공합니다. AI 관련 패턴을 이해하는 Tool을 사용하여 LLM 작업을 모니터링하고, Agent 결정을 추적하고, 복잡한 Workflow를 디버그하세요. 추적은 Model 상호 작용, Agent 실행 경로, Tool 호출 및 Workflow 단계를 캡처합니다.

자세한 내용은 Observability 문서를 참조하세요.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'
import { Observability, MastraStorageExporter } from '@mastra/observability'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})

프로세서

유형: Record<string, Processor>

Agent 입력 및 출력을 변환하기 위한 입력/출력 프로세서입니다. 프로세서는 Agent 실행 파이프라인의 특정 지점에서 실행되므로 언어 ​​Model에 도달하기 전에 입력을 수정하거나 반환되기 전에 출력을 수정할 수 있습니다. 프로세서를 사용하여 가드레일을 추가하고, 즉각적인 삽입을 감지하고, 콘텐츠를 조정하거나, 맞춤형 비즈니스 로직을 적용하세요.

자세한 내용은 프로세서 문서를 참조하세요.

노트

대부분의 사용자는 Agent에서 직접 프로세서를 구성합니다. 이 최상위 구성은 여러 Agent에서 공유할 수 있는 재사용 가능한 프로세서 인스턴스를 정의하기 위한 것입니다.

src/mastra/index.ts

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

export const mastra = new Mastra({
  processors: {
    moderation: new ModerationProcessor({
      model: 'openai/gpt-5-mini',
      categories: ['hate', 'harassment', 'violence'],
    }),
  },
})

게시자

유형: PubSub
Default: EventEmitterPubSub

구성 요소 간의 이벤트 기반 통신을 위한 Pub/Sub 시스템입니다. Workflow 이벤트 처리 및 구성 요소 통신을 위해 Mastra에서 내부적으로 사용됩니다.

경고

이는 Mastra에서 내부적으로 사용됩니다. 대부분의 사용자는 이 옵션을 구성할 필요가 없습니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { CustomPubSub } from './pubsub'

export const mastra = new Mastra({
  pubsub: new CustomPubSub(),
})

득점자

유형: Record<string, Scorer>

채점자는 Agent 응답 및 Workflow 출력의 품질을 평가합니다. Model 등급, 규칙 기반 및 통계 방법을 사용하여 Agent 품질을 측정하기 위한 수량화 가능한 측정항목을 제공합니다. 채점자를 사용하여 성과를 추적하고 접근 방식을 비교하세요. 또한 개선이 필요한 영역을 식별할 수도 있습니다.

자세한 내용은 스코어러 문서를 참조하세요.

노트

대부분의 사용자는 Agent에서 직접 채점자를 구성합니다. 이 최상위 구성은 여러 Agent에서 공유할 수 있는 재사용 가능한 채점자 인스턴스를 정의하기 위한 것입니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { createToxicityScorer } from '@mastra/evals/scorers/prebuilt'

export const mastra = new Mastra({
  scorers: {
    toxicity: createToxicityScorer({ model: 'openai/gpt-5-mini' }),
  },
})

저장

유형: MastraCompositeStore

애플리케이션 데이터를 유지하기 위한 스토리지 공급자입니다. 지속성이 필요한 Memory, Workflow, 추적 및 기타 구성 요소에서 사용됩니다. Mastra는 PostgreSQL, MongoDB, libSQL 등을 포함한 여러 데이터베이스 백엔드를 지원합니다.

자세한 내용은 스토리지 문서를 참조하세요.

src/mastra/index.ts

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

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

Tool

유형: Record<string, Tool>

Tool은 Agent가 외부 시스템과 상호 작용하는 데 사용할 수 있는 재사용 가능한 기능입니다. 각 Tool은 입력, 출력 및 실행 논리를 정의합니다.

자세한 내용은 Tool 문서를 참조하세요. :::참고 대부분의 사용자는 Agent에서 직접 Tool을 구성합니다. 이 최상위 구성은 여러 Agent에서 공유할 수 있는 재사용 가능한 Tool을 정의하기 위한 것입니다. :::

src/mastra/index.ts

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

const weatherTool = createTool({
  id: 'get-weather',
  description: 'Fetches weather for a city',
  inputSchema: z.object({
    city: z.string(),
  }),
  execute: async () => {
    return { temperature: 20, conditions: 'Sunny' }
  },
})

export const mastra = new Mastra({
  tools: {
    weather: weatherTool,
  },
})

ㅜㅜ

유형: Record<string, MastraVoice>

음성 합성 기능을 위한 텍스트 음성 변환 제공자입니다. Agent가 텍스트 응답을 음성 오디오로 변환할 수 있도록 음성 공급자를 등록하세요.

자세한 내용은 음성 문서를 참조하세요. :::참고 대부분의 사용자는 Agent에서 직접 음성을 구성합니다. 이 최상위 구성은 여러 Agent에서 공유할 수 있는 재사용 가능한 음성 공급자를 정의하기 위한 것입니다. :::

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { OpenAIVoice } from '@mastra/voice-openai'

export const mastra = new Mastra({
  tts: {
    openai: new OpenAIVoice(),
  },
})

벡터

유형: Record<string, MastraVector>

의미론적 검색 및 임베딩을 위한 벡터 저장소입니다. RAG 파이프라인, 유사성 검색 및 기타 임베딩 기반 기능에 사용됩니다. Mastra는 Pinecone, PostgreSQL(pgVector 포함), OracleDB, MongoDB 등을 포함한 여러 벡터 데이터베이스를 지원합니다.

자세한 내용은 RAG 문서를 참조하세요. :::참고 대부분의 사용자는 RAG 파이프라인을 구축할 때 벡터 저장소를 직접 생성합니다. 이 최상위 구성은 애플리케이션 전체에서 공유할 수 있는 재사용 가능한 벡터 저장소 인스턴스를 정의하기 위한 것입니다. :::

src/mastra/index.ts

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

export const mastra = new Mastra({
  vectors: {
    pinecone: new PineconeVector({
      id: 'pinecone-vector',
      apiKey: process.env.PINECONE_API_KEY,
    }),
  },
})

Workflow

유형: Record<string, Workflow>

Workflow는 유형이 안전한 입력 및 출력을 사용하여 단계 기반 실행 파이프라인을 정의합니다. 특정 실행 순서가 있는 여러 단계가 포함된 작업에 Workflow를 사용하면 단계 간 데이터 흐름 방식을 제어할 수 있습니다.

자세한 내용은 Workflow 문서를 참조하세요.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { testWorkflow } from './workflows/test-workflow'

export const mastra = new Mastra({
  workflows: {
    testWorkflow,
  },
})

작업 공간

유형: Workspace

Mastra Workspace는 Agent에 파일 저장 및 명령 실행을 위한 지속적인 환경을 제공합니다. 자체 Workspace가 구성되지 않은 Agent는 Mastra 클래스의 전역 Workspace를 상속합니다. 구현 세부 정보는 Workspace 문서를 참조하세요.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
})

const mastra = new Mastra({
  workspace,
})

번들러 옵션

번들러.항목

유형: Record<string, string>
Default: {}

Mastra 디렉터리 기준 소스 경로에 출력 이름을 매핑하여 서버 번들과 함께 내보낼 추가 프로세스 엔트리입니다. 각 엔트리는 .mastra/output에서 고유한 <name>.mjs가 됩니다. Mastra 서버 내부가 아니라 서버와 나란히 실행되는 장기 실행 프로세스(예: LiveKit 음성 worker)에 이 기능을 사용하세요. 이 엔트리는 서버와 출력 디렉터리, package.json, 설치된 종속성을 공유하므로 한 번의 mastra build로 각기 다른 명령으로 시작할 수 있는 하나의 배포 가능 아티팩트를 생성합니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    entries: { 'voice-worker': './voice-worker.ts' },
  },
})

이렇게 하면 .mastra/output/index.mjs 옆에 .mastra/output/voice-worker.mjs가 생성됩니다. 추가 엔트리에서만 가져오는 종속성도 분석되므로 출력에 설치됩니다. 엔트리 이름에는 출력을 중첩하기 위한 /를 포함할 수 있습니다. 서버 번들인 index, Tool 애그리게이터인 tools는 사용할 수 없으며, Tool 번들용으로 예약된 tools/로 시작할 수도 없습니다.

노트

mastra build는 번들러 옵션을 전혀 설정하지 않았을 때만 bundler.externals의 기본값 true를 적용합니다. entries를 설정한 후 추가 엔트리가 네이티브 모듈처럼 번들링할 수 없는 패키지에 의존한다면 externals도 명시적으로 설정하세요.

번들러.외부

유형: boolean | string[]
Default: true

mastra build를 실행하면 Mastra가 프로젝트를 .mastra/output 디렉터리에 번들링합니다. 이 옵션은 번들에서 제외되어 "external"로 표시되고 패키지 관리자를 통해 별도로 설치되는 패키지를 제어합니다. 내부 Mastra 번들러(Rollup)가 패키지를 번들링하는 데 문제가 있을 때 유용합니다. 기본적으로 mastra build는 이 옵션을 true로 설정합니다. 값에는 다음과 같은 의미가 있습니다.

• true: 프로젝트의 package.json에 나열된 모든 종속성을 external로 표시합니다
• false: 어떤 종속성도 external로 표시하지 않습니다. 모든 항목을 함께 번들링합니다
• string[]: external로 표시할 패키지 이름의 배열입니다. 나머지는 함께 번들링됩니다

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    externals: ['some-package', 'another-package'],
  },
})

번들러.소스맵

유형: boolean
Default: false

번들 출력에 대한 소스 맵 생성을 활성화합니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    sourcemap: true,
  },
})

Bundler.transpile패키지

유형: string[]
Default: []

빌드 프로세스 중에 esbuild를 통해 소스 코드를 트랜스파일해야 하는 패키지 목록입니다. 번들링하기 전에 컴파일이 필요한 TypeScript 또는 기타 코드가 포함된 종속성에 대해 이를 사용하세요.

컴파일되지 않은 소스 코드를 직접 가져오는 경우에만 이 옵션이 필요합니다. 패키지가 이미 CommonJS 또는 ESM으로 컴파일된 경우 여기에 나열할 필요가 없습니다.

Mastra는 모노레포 설정에서 작업 공간 패키지를 자동으로 감지하여 이 목록에 추가하므로 일반적으로 변환이 필요한 외부 패키지만 지정하면 됩니다.

Mastra는 빌드 중 tsconfig.json의 baseUrl 및 paths 별칭도 해석합니다. 여기에는 TypeScript 소스 파일을 가리키는 ~/utils/logger.js 같은 ESM 스타일 import가 포함됩니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    transpilePackages: ['@my-org/shared-utils'],
  },
})

서버 옵션

server.api경로

유형: ApiRoute[]

Mastra는 서버를 통해 등록된 Agent와 Workflow를 자동으로 노출합니다. 추가 동작을 위해 자체 HTTP 경로를 정의할 수 있습니다.

자세한 내용은 사용자 정의 API 경로 문서를 참조하세요.

src/mastra/index.ts

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

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      registerApiRoute('/my-custom-route', {
        method: 'GET',
        handler: async c => {
          return c.json({ message: 'Custom route' })
        },
      }),
    ],
  },
})

서버.인증

유형: MastraAuthConfig | MastraAuthProvider

서버에 대한 인증 구성입니다. Mastra는 JWT, Clerk, Supabase, Firebase, WorkOS 및 Auth0을 포함한 여러 인증 공급자를 지원합니다.

자세한 내용은 인증 문서를 참조하세요.

src/mastra/index.ts

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

export const mastra = new Mastra({
  server: {
    auth: new MastraJwtAuth({
      secret: process.env.MASTRA_JWT_SECRET,
      mapUserToResourceId: user => user.id,
    }),
  },
})

mapUserToResourceId 콜백은 인증된 사용자를 Memory/스레드 범위 지정에 사용할 리소스 ID로 매핑합니다. 제공하면 인증 성공 후 호출되며, 반환된 값이 요청 컨텍스트에 MASTRA_RESOURCE_ID_KEY로 설정됩니다. 자세한 내용은 권한 부여(사용자 격리)를 참조하세요.

server.bodySizeLimit

유형: number
Default: 4_718_592 (4.5 MB)

최대 요청 본문 크기(바이트)입니다. 애플리케이션이 더 큰 페이로드를 처리해야 하는 경우 이 제한을 늘립니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    bodySizeLimit: 10 * 1024 * 1024, // 10mb
  },
})

server.mcp옵션

유형: object
Default: undefined

모든 MCP HTTP 및 SSE 경로에 적용되는 MCP 전송 옵션입니다. 이를 사용하면 지속적인 연결과 Memory 내 세션 상태를 사용할 수 없는 서버리스 환경(Cloudflare Workers, Vercel Edge, AWS Lambda 등)에 대해 상태 비저장 모드를 활성화할 수 있습니다.

속성	유형	기본값	설명
serverless	boolean	false	세션 관리 없이 무상태 모드로 MCP 실행
sessionIdGenerator	() => string	undefined	사용자 정의 세션 ID 생성기 함수

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    mcpOptions: {
      serverless: true,
    },
  },
})

서버.빌드

서버 기능에 대한 빌드 타임 구성입니다. 이러한 옵션은 로컬 개발 중에는 활성화되지만 프로덕션 환경에서는 기본적으로 비활성화되는 Swagger UI 및 요청 로깅과 같은 개발 Tool을 제어합니다.

속성	유형	기본값	설명
swaggerUI	boolean	false	대화형 API 탐색을 위해 /swagger-ui에서 Swagger UI 활성화(openAPIDocs가 true여야 함)
apiReqLogs	boolean	false	콘솔에 API 요청 로깅 활성화
openAPIDocs	boolean	false	/api/openapi.json에서 OpenAPI 명세 활성화. 기본 제공 Mastra 경로는 servers: [{url: "/api"}]를 사용하고, 사용자 정의 경로에는 경로별 servers: [{url: "/"}] 재정의가 적용됩니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    build: {
      swaggerUI: true,
      apiReqLogs: true,
      openAPIDocs: true,
    },
  },
})

서버.cors

유형: CorsOptions | false

서버의 CORS(Cross-Origin Resource Sharing) 구성입니다. CORS를 완전히 비활성화하려면 false로 설정하세요. 모든 경로에 하나의 정책을 적용할 때 사용합니다. 경로별 사용자 정의 정책에는 registerApiRoute()의 cors 옵션을 사용하세요.

속성	유형	기본값	설명
origin	string | string[]	'*'	CORS 요청의 origin
allowMethods	string[]	['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']	HTTP 메서드
allowHeaders	string[]	['Content-Type', 'Authorization', 'x-mastra-client-type', 'x-mastra-dev-playground']	요청 헤더
exposeHeaders	string[]	['Content-Length', 'X-Requested-With']	브라우저에 노출할 헤더
credentials	boolean	false	자격 증명(쿠키, 인증 헤더)
maxAge	number	3600	preflight 요청 캐시 기간(초)

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    cors: {
      origin: ['https://example.com'],
      allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
      allowHeaders: ['Content-Type', 'Authorization'],
      credentials: false,
    },
  },
})

서버.호스트

유형: string
기본값: localhost(또는 설정된 경우 MASTRA_HOST 환경 변수) Mastra 개발 서버가 바인딩되는 호스트 주소입니다. MASTRA_HOST 환경 변수가 설정되어 있으면 기본값보다 우선합니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    host: '0.0.0.0',
  },
})

서버.https

유형: { key: Buffer; cert: Buffer }

TLS를 사용해 개발 서버를 실행하기 위한 HTTPS 구성입니다. Mastra는 인증서를 자동으로 생성하고 관리하는 mastra dev --https 플래그를 통해 로컬 HTTPS 개발을 지원합니다. 인증서를 직접 관리하려면 자체 키 및 인증서 파일을 제공하세요.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import fs from 'node:fs'

export const mastra = new Mastra({
  server: {
    https: {
      key: fs.readFileSync('path/to/key.pem'),
      cert: fs.readFileSync('path/to/cert.pem'),
    },
  },
})

서버.미들웨어

유형: Middleware | Middleware[]

경로 핸들러 전후에 요청을 가로채는 사용자 정의 미들웨어 함수입니다. 미들웨어는 인증, 로깅, 요청별 컨텍스트 삽입 또는 헤더 추가에 사용할 수 있습니다. 각 미들웨어는 Hono Context와 next 함수를 받습니다. 요청을 단락시키려면 Response를 반환하고, 처리를 계속하려면 next()를 호출하세요. 자세한 내용은 미들웨어 문서를 참조하세요.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    middleware: [
      {
        handler: async (c, next) => {
          const authHeader = c.req.header('Authorization')
          if (!authHeader) {
            return new Response('Unauthorized', { status: 401 })
          }
          await next()
        },
        path: '/api/*',
      },
    ],
  },
})

서버.오류

유형: (err: Error, c: Context) => Response | Promise<Response>

처리되지 않은 오류가 발생할 때 호출되는 사용자 정의 오류 핸들러입니다. 이를 사용하여 오류 응답을 사용자 정의하고, Sentry와 같은 외부 서비스에 오류를 기록하거나, 사용자 정의 오류 형식을 구현합니다.

이 후크는 모든 서버 어댑터에서 지원됩니다. c 매개변수는 Hono 호환 컨텍스트 객체를 제공합니다. Hono 이외의 어댑터(Koa, Express, Fastify)에는 c.json() 및 c.req.path처럼 자주 사용하는 메서드가 포함된 shim이 제공됩니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import * as Sentry from '@sentry/node'

export const mastra = new Mastra({
  server: {
    onError: (err, c) => {
      Sentry.captureException(err)

      return c.json(
        {
          error: err.message,
          timestamp: new Date().toISOString(),
        },
        500,
      )
    },
  },
})

server.onValidationError

유형: (error: ZodError, context: 'query' | 'body' | 'path') => { status: number; body: unknown } | undefined

요청이 Zod 스키마 검증에 실패하면 호출되는 사용자 정의 핸들러입니다. 이를 사용하여 유효성 검사 오류 응답을 사용자 지정하고, 상태 코드를 변경하고, API 표준에 맞게 오류 형식을 지정합니다.

기본 400 응답을 재정의하려면 { status, body } 객체를 반환하고, 기본 동작을 사용하려면 undefined를 반환하세요. 이 후크는 모든 서버 어댑터(Hono, Express, Fastify, Koa)에서 지원됩니다. context 매개변수는 요청에서 검증에 실패한 부분을 나타냅니다.

• 'query': 쿼리 매개변수
• 'body': 요청 본문
• 'path': 경로 매개변수

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    onValidationError: (error, context) => ({
      status: 422,
      body: {
        ok: false,
        errors: error.issues.map(i => ({
          path: i.path.join('.'),
          message: i.message,
        })),
        source: context,
      },
    }),
  },
})

createRoute()로 생성한 개별 경로에도 onValidationError를 설정할 수 있습니다. 경로 수준 후크가 서버 수준 후크보다 우선합니다.

서버.포트

유형: number
기본값: 4111(또는 설정된 경우 PORT 환경 변수) Mastra 개발 서버가 바인딩되는 포트입니다. PORT 환경 변수가 설정되어 있으면 기본값보다 우선합니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    port: 8080,
  },
})

서버.스튜디오베이스

유형: string
Default: /

Studio를 호스팅하기 위한 기준 경로입니다. 루트 대신 기존 애플리케이션의 하위 경로에서 Studio를 호스팅할 때 사용하세요. 이는 기존 애플리케이션과 통합하거나 공유 도메인의 이점을 활용하는 Cloudflare Zero Trust와 같은 인증 Tool을 사용하거나 단일 도메인에서 여러 서비스를 관리할 때 유용합니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    studioBase: '/my-mastra-studio',
  },
})

예시 URL:

• 기본값: http://localhost:4111/(루트의 Studio)
• studioBase 사용: http://localhost:4111/my-mastra-studio/(하위 경로의 Studio)

서버.시간 초과

유형: number
Default: 180000 (3 minutes)

요청 제한 시간(밀리초)입니다. 이 기간을 초과하는 요청은 종료됩니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    timeout: 30000, // 30 seconds
  },
})