跳到主要内容

Mastra 类

Mastra 类是所有 Mastra 应用中的中央协调器，用于管理 Agent、Workflow、Storage、日志、可观测性等。通常，你会创建单个 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 scheduler 自动交付延迟通知记录和通知摘要，请启用定时通知分发：

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

notifications.dispatch.enabled 允许内部 dispatcher Workflow 使用默认 cron */1 * * * * 运行。dispatcher 从 Storage 读取到期通知记录，按 agentId、resourceId 和 threadId 对摘要分组，并通过 Agent thread runtime 发出 signal。它不是面向用户的入口。分发计划（及其底层 Workflow scheduler）会在出现第一个延迟通知或摘要通知时延迟激活，因此从不延迟通知的应用不会运行 scheduler。

构造函数参数
构造函数参数的直接链接

所有可用配置选项的详细文档，请参阅配置参考。

agents?:

Record<string, Agent>
= {}
要注册的 Agent 实例，以名称作为键

tools?:

Record<string, ToolApi>
= {}
要注册的 Tool 实例。键是 `getTool()` 使用的注册键，值是 Tool 实例。使用 `getToolById()` 按固有 ID 查找，使用 `listTools()` 读取注册表。

storage?:

MastraCompositeStore
用于持久化数据的 Storage engine 实例

vectors?:

Record<string, MastraVector>
用于语义搜索和基于 vector 的 Tool 的 vector store 实例（例如 Pinecone、PgVector 或 Qdrant）

logger?:

Logger
= Console logger with INFO level
使用 new PinoLogger() 创建的 Logger 实例

idGenerator?:

(context?: IdGeneratorContext) => string
自定义 ID 生成器函数。供 Agent、Workflow、Memory 和其他组件生成唯一标识符。接收 idType、source、entityId 和 threadId 等可选上下文，以支持上下文感知的 ID 格式。

workflows?:

Record<string, Workflow>
= {}
要注册的 Workflow。采用键值对结构，键为 Workflow 名称，值为 Workflow 实例。

tts?:

Record<string, MastraVoice>
用于语音合成的 text-to-speech Provider

observability?:

ObservabilityEntrypoint
用于 tracing 和监控的可观测性配置

environment?:

string
部署环境名称（例如 production、staging、development）。设置后，会自动附加到所有可观测性 signal，以便按环境筛选，而无需在每次调用时传递 tracingOptions.metadata.environment。未设置时回退到 process.env.NODE_ENV；两者均未设置时保持 undefined。每次调用传入的 tracingOptions.metadata.environment 始终优先。

deployer?:

MastraDeployer
用于管理部署的 MastraDeployer 实例。

server?:

ServerConfig
Server 配置，包括 port、host、timeout、API route、middleware、CORS 设置，以及 Swagger UI、API 请求日志和 OpenAPI 文档的构建选项。

mcpServers?:

Record<string, MCPServerBase>
一个对象，其中键为注册键（供 getMCPServer() 使用），值为 MCPServer 实例或扩展 MCPServerBase 的类。每个 MCPServer 都必须具有 id 属性。可使用 getMCPServer() 按注册键获取 server，或使用 getMCPServerById() 按固有 id 获取。

bundler?:

BundlerConfig
= { externals: [], sourcemap: false, transpilePackages: [], dynamicPackages: [] }
asset bundler 配置，包含 externals、sourcemap、transpilePackages 和 dynamicPackages 选项。

scorers?:

Record<string, Scorer>
= {}
用于评估 Agent 响应和 Workflow 输出的 Scorer

processors?:

Record<string, Processor>
= {}
用于转换 Agent 输入和输出的输入/输出 Processor

gateways?:

Record<string, MastraModelGateway>
= {}
要注册的自定义模型 gateway，用于通过其他 Provider 或私有部署访问 AI 模型。采用键值对结构，键为注册键（供 getGateway() 使用），值为 gateway 实例。

memory?:

Record<string, MastraMemory>
= {}
要注册的 Memory 实例。已存储的 Agent 可以引用这些实例，并在运行时解析。采用键值对结构，键为注册键，值为 Memory 实例。

notifications?:

object
通知 signal 分发的运行时配置。
object

dispatch?:

NotificationDispatchConfig
延迟通知和通知摘要的定时分发配置。默认启用分发。
object

enabled?:

boolean
设为 false 可停用自动定时通知分发。

cron?:

string
内部通知 dispatcher Workflow 使用的 cron 计划。

batchSize?:

number
每次分发 run 最多处理的到期通知记录数。

versions?:

VersionOverrides
sub-agent 委派的全局版本覆盖。当 supervisor Agent 委派给 sub-agent 时，这些覆盖决定使用该 sub-agent 的哪个已存储版本，而不是代码中定义的默认版本。需要配置 Editor package。详情请参阅 Editor 版本控制。
VersionOverrides

agents?:

Record<string, VersionSelector>
Agent ID 到版本选择器的映射。每个选择器都可以按 ID 或发布状态指定特定版本。
VersionSelector

versionId?:

string
要使用的特定版本的 ID。

status?:

'draft' | 'published'
选择具有此发布状态的最新版本。

workers?:

MastraWorker[] | false
配置在此 Mastra 实例中运行哪些 Worker。省略时，Mastra 会根据 PubSub 和配置自动创建默认 Worker。传入 false 可禁用所有事件处理（适用于单独运行独立 Worker 的情况）。传入 MastraWorker[] 可添加自定义 Worker；它们会与自动创建的默认值合并，同默认 Worker 具有相同 name 的自定义 Worker 会替换该默认 Worker。

backgroundTasks?:

BackgroundTaskManagerConfig
配置 Agent 的后台任务执行。所有选项请参阅后台任务配置参考。
BackgroundTaskManagerConfig

enabled?:

boolean
启用后台任务分发。

globalConcurrency?:

number
所有 Agent 的最大并发任务数。

perAgentConcurrency?:

number
每个 Agent 的最大并发任务数。

backpressure?:

'queue' | 'reject' | 'fallback-sync'
达到并发限制时的行为。

defaultTimeoutMs?:

number
默认任务超时时间（毫秒）。

defaultRetries?:

RetryConfig
默认重试配置。

scheduler?:

object
配置用于 cron 驱动 Workflow 触发器的 scheduler Worker。当任一 Workflow 声明 schedule 时自动启用。请参阅定时 Workflow。
object

enabled?:

boolean
显式启用或禁用 scheduler。

recovery?:

MastraRecoveryConfig
= { durableAgents: 'off' }
孤立 Agent 和 Workflow run 的启动时恢复行为。请参阅崩溃恢复。
object

durableAgents?:

'auto' | 'off'
设为 'auto' 后，会在 server 启动时自动重新驱动孤立的 RUNNING durable Agent run。恢复会重新发出 LLM 调用并重新执行 Tool 调用，因此 Tool 必须具有幂等性。请参阅崩溃恢复。

方法
方法的直接链接

recoverAllDurableAgents()
recoveralldurableagents的直接链接

重新驱动所有已注册 durable Agent 中的每个孤立 running durable-Agent run。当 recovery.durableAgents 为 'auto' 时，会在启动时自动调用。也可以直接调用以手动恢复，或从定时任务中调用。

需要持久化 Storage。使用内存 store 时，进程重启后没有可恢复的内容。

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

返回值：

agents:

number
扫描的 durable Agent 数量。

recovered:

number
重新驱动的 run 总数。

succeeded:

number
成功重新启动的 run 数量。

failed:

number
重新启动时抛出错误的 run 数量。
On this page