← Frameworks

模型与开放条件Model & openness

它的答案是 model routing，规格写得最狠。 官方 /models 目录页原文：

"giving you access to 7815 models from 213 providers through a single API."

用法是 provider/model 字符串。官方示例： openai/gpt-5.6-sol、anthropic/claude-sonnet-4-6、openrouter/anthropic/claude-haiku-4.5。

缺 key 时，运行时错误会明确指出缺哪个变量。

官方原文："Mastra reads the relevant environment variable (e.g. ANTHROPIC_API_KEY) and routes requests to the provider."

官方支持 model fallbacks。

也可按任务 mix-and-match 不同模型。 还能用 requestContext 动态选模型。

官方原文："If a provider experiences an outage, Mastra can automatically switch to another provider at the application level"

本地模型是官方明确支持的。 /models 页有专节：

官方原文："Use local models with Mastra"

官方原文："Mastra also supports local models like gpt-oss, Qwen3, DeepSeek ... that you run on your own hardware"

前提是本地要提供 OpenAI 兼容 API server。官方推荐 LMStudio。

本地示例：

• id: "lmstudio/qwen/qwen3-30b-a3b-2507"
• url: "http://localhost:1234/v1"

⚠ 一处官方自身数字打架：README 亮点段写的是 "Connect to 40+ providers"， 而 /models 目录页写 "213 providers / 7815 models"。

旧口径：本站以目录页为准，README 的 40+ 视为旧口径。

换 provider 后各家 tool calling / structured output 的对齐度，官方未说明（已查 /models 页）。

Its answer is model routing, with the most aggressive spec. Official /models catalog page, verbatim:

"giving you access to 7815 models from 213 providers through a single API."

Usage is a provider/model string. Official examples: openai/gpt-5.6-sol, anthropic/claude-sonnet-4-6, openrouter/anthropic/claude-haiku-4.5.

When a key is missing, the runtime error names the missing variable.

Official wording: "Mastra reads the relevant environment variable (e.g. ANTHROPIC_API_KEY) and routes requests to the provider."

Official model fallbacks are supported.

You can also mix-and-match different models per task. And select models dynamically via requestContext.

Official wording: "If a provider experiences an outage, Mastra can automatically switch to another provider at the application level"

Local models are explicitly supported by the official docs. The /models page has a dedicated section:

Official wording: "Use local models with Mastra"

Official wording: "Mastra also supports local models like gpt-oss, Qwen3, DeepSeek ... that you run on your own hardware"

The prerequisite is that the local side provides an OpenAI-compatible API server. The official docs recommend LMStudio.

Local example:

• id: "lmstudio/qwen/qwen3-30b-a3b-2507"
• url: "http://localhost:1234/v1"

⚠ One place where the official numbers conflict: the README highlights section says "Connect to 40+ providers", while the /models catalog page says "213 providers / 7815 models".

Old wording: we take the catalog page as authoritative; the README's 40+ is treated as outdated.

After switching providers, the alignment of each vendor's tool calling / structured output is not stated by the official docs (/models page checked).

运行位置Where it runs

纯库起步，但官方把「独立 server」和「托管平台」两条路都铺好了。

形态是 npm 包（@mastra/core，官方 .npmrc 要求 Node.js >=22.13.0）。

官方原文："Mastra applications can be deployed to any Node.js-compatible environment."

运行时支持 Node.js v22.13.0+、Bun、Deno、Cloudflare。

它内置一个基于 Hono 的 server。可用 mastra build 打出后部署到任意 VM / 容器 / PaaS， 或作为 standalone server 独立运行；也能嵌进 Next.js / React / Node 应用。

本地开发：用 mastra dev，Studio 起在 http://localhost:4111。

谁运营 agent loop：默认是你自己（自托管）。要托管可选 Mastra 平台 Server —— 官方原文："A production deployment target that runs your Mastra application as an API server"。

多 agent 并发调度：走 workflows（内置执行引擎），或部署到 Inngest 等 workflow runner。 生产可用独立 worker 进程跑编排与 cron（官方 Workers 页）。

即「代码在哪」= 你的进程；「要不要托管」= 可选平台。

It starts as a pure library, but the official docs pave both the "standalone server" and "hosted platform" roads.

The form is an npm package (@mastra/core; the official .npmrc requires Node.js >=22.13.0).

Official wording: "Mastra applications can be deployed to any Node.js-compatible environment."

Runtime support: Node.js v22.13.0+, Bun, Deno, Cloudflare.

It ships a built-in Hono-based server. mastra build produces a bundle deployable to any VM / container / PaaS, or runs as a standalone server; it can also be embedded in Next.js / React / Node apps.

Local development: mastra dev; Studio starts at http://localhost:4111.

Who runs the agent loop: by default you do (self-hosted). For hosting there is the Mastra platform Server — Official wording: "A production deployment target that runs your Mastra application as an API server".

Multi-agent concurrent scheduling: via workflows (built-in execution engine), or deploy to workflow runners like Inngest. Production can run orchestration and cron in separate worker processes (official Workers page).

In short: "where the code lives" = your process; "whether to host" = an optional platform.

本地文件Local files

核心框架不内置文件系统，文件能力要显式加装。

Mastra 的定位是 AI 应用/agent 框架。官方文档没有把文件读写当成默认 agent 能力。

工具面：README 与 agents 页讲的工具面是两样。一是 createTool() 自定义工具，二是 MCP。

官方给的三条文件路径（已查 harness 页与 platform 页）：

① 自己用 createTool() 提供文件工具。

② 走 Harness 的 createCodingAgent()（官方 harness 表）。官方原文："Give an agent files, a shell, and the defaults a coding agent needs → createCodingAgent()"

它 "Build a standard agent with a workspace, task tracking, and retries already configured"。

③ 用 Mastra 平台的 Workspace（官方称每个 environment 会得到一个 managed Workspace）：

"gives agents a filesystem and sandbox with no manual configuration"

核心框架自身的文件访问默认边界（是否限制在项目目录、越界是否拦截），官方未说明。

核验：已查 agents 页、harness 页、deployment 页。宿主权限模型落在平台 Workspace 那侧，不在 OSS 核心。

The core framework does not ship a file system; file capability must be added explicitly.

Mastra positions itself as an AI application/agent framework. The official docs do not treat file read/write as a default agent capability.

Tool surface: the README and agents page describe two different tool surfaces. One is createTool() custom tools, the other is MCP.

The three file paths the official docs give (harness page and platform page checked):

① Provide file tools yourself via createTool().

② Use the Harness's createCodingAgent() (official harness table). Official wording: "Give an agent files, a shell, and the defaults a coding agent needs → createCodingAgent()"

It "Build a standard agent with a workspace, task tracking, and retries already configured".

③ Use the Mastra platform's Workspace (officially each environment gets a managed Workspace):

"gives agents a filesystem and sandbox with no manual configuration"

The default boundary of file access in the core framework itself (restricted to the project directory? out-of-bounds intercepted?) is not stated by the official docs.

Verified: agents page, harness page, deployment page checked. The host permission model sits on the platform Workspace side, not in the OSS core.

关机后的任务Tasks after shutdown

这是它非常强的一维：durable agents + 可跨重启的 snapshot 都是可查证的核心机制。 官方 suspend-and-resume 页原文：

"Suspension saves the current execution state as a snapshot. Later, resume from a specific step ID to restore the exact captured state. Snapshots are stored in your configured storage provider and persist across deployments and application restarts."

机制细节：

• suspend() 在某个 step 内暂停，并把状态标为 suspended
• workflow 级 .sleep()/.sleepUntil() 标 waiting
• resume({ step, resumeData }) 从暂停处继续；只给 runId 时需先 createRun({ runId })
• suspendData 可在恢复时取回当初传给 suspend() 的数据
• workflow.getWorkflowRunById() + createWorkflowStateReader() 可从存储中恢复悬挂的 run

Harness 层还有：

• Durable Agents："Persist run state and let clients reconnect to its stream"
• Background Tasks："Run slow tools, workflows, or subagents without blocking"
• Schedules：cron 定时起 run

托管后台：Mastra 平台 Server 提供 24/7 常驻（Persistent Server 按项目计费，单价见官方页）。 OSS 自托管则是「你自己把进程跑起来」，关了就停。

A very strong dimension: durable agents + restart-surviving snapshots are verifiable core mechanisms. Official suspend-and-resume page, verbatim:

"Suspension saves the current execution state as a snapshot. Later, resume from a specific step ID to restore the exact captured state. Snapshots are stored in your configured storage provider and persist across deployments and application restarts."

Mechanism details:

• suspend() pauses within a step and marks the state suspended
• workflow-level .sleep()/.sleepUntil() mark waiting
• resume({ step, resumeData }) continues from the pause point; with only a runId you must first createRun({ runId })
• suspendData can retrieve the data originally passed to suspend() upon resume
• workflow.getWorkflowRunById() + createWorkflowStateReader() can recover dangling runs from storage

The Harness layer adds:

• Durable Agents: "Persist run state and let clients reconnect to its stream"
• Background Tasks: "Run slow tools, workflows, or subagents without blocking"
• Schedules: cron starts runs

Hosted background: the Mastra platform Server provides 24/7 residency (Persistent Server billed per project; unit price on the official page). OSS self-hosting is "you run the process yourself" — stop it and it's gone.

工具与扩展Tools & extensions

工具面是三件套：自定义工具 + MCP 一等支持 + 可作 MCP server。官方文档给得很全。

自定义工具必须用 createTool()。

官方 agents 页明确警告：plain object 工具会 静默失败。

官方原文："silently fail to execute" —— 需 id / description / inputSchema / execute()。

MCP 是独立包 @mastra/mcp，官方给两个类：

• MCPClient：连一个或多个 MCP server
• MCPServer：把 Mastra 的 agents / tools / workflows / prompts / resources 暴露成 MCP server

传输方式官方示例覆盖 stdio（command: npx ...）与远程 HTTP(S)（url: new URL(...)）。 并给了 Klavis AI、mcp.run、Composio、Smithery、Ampersand 等注册表接入示例。

还区分两类工具：静态工具（getTools()，配置固定） 与 动态工具（getToolsets()）：按用户/请求带凭据。对多租户 SaaS 很有用。

另有 A2A（@mastra/core 暴露 ./a2a 子路径）与 skills（./skills）子模块。 子代理/多 agent 委派官方称 supervisor + subagents（见 memory 页的 delegation 说明）。

The tool surface is a three-piece set: custom tools + first-class MCP support + acting as an MCP server. The official docs cover it well.

Custom tools must use createTool().

The official agents page warns explicitly: plain-object tools fail silently.

Official wording: "silently fail to execute" — requires id / description / inputSchema / execute().

MCP is the standalone package @mastra/mcp, with two official classes:

• MCPClient: connect to one or more MCP servers
• MCPServer: expose Mastra's agents / tools / workflows / prompts / resources as an MCP server

Official transport examples cover stdio (command: npx ...) and remote HTTP(S) (url: new URL(...)). And registry-access examples for Klavis AI, mcp.run, Composio, Smithery, Ampersand.

It also distinguishes two tool kinds: static tools (getTools(), fixed config) and dynamic tools (getToolsets()): per-user/per-request credentials. Very useful for multi-tenant SaaS.

There are also A2A (@mastra/core exposes the ./a2a subpath) and skills (./skills) submodules. Subagent/multi-agent delegation is officially called supervisor + subagents (see the delegation notes on the memory page).

上下文与记忆Context & memory

它把「记忆」拆成多层，且有「状态 ≠ 上下文」的两套机制。

官方 memory 页：默认存 message history，可另开三样：

• Observational Memory（推荐）："Uses background agents to maintain a dense observation log that replaces raw message history as it grows. This keeps the context window small while preserving long-term memory."

• Working memory：存结构化的用户数据（名字、偏好、目标）
• Semantic recall：按语义而非关键词召回历史消息

超限时用 memory processors filter / trim / prioritize。 作用域用两个 ID 划分：resource（用户/实体）和 thread（会话）。 多 agent 间可共享或隔离（scope: 'resource' | 'thread'）。

状态那一套是 workflow 的 snapshot（suspend/resume，见 background 轴）—— 与 memory 分离。

RAG 是独立系统（@mastra/rag）：MDocument 切块（recursive / sliding window）、embedding， 再落向量库（官方点名 pgvector、Pinecone、Qdrant、MongoDB）。

即：snapshot 存流程状态。memory 存对话与用户长期信息。RAG 存外部知识。三者用途不同。

It splits "memory" into multiple layers, with two separate mechanisms for "state ≠ context".

Official memory page: stores message history by default, with three more opt-in:

• Observational Memory (recommended): "Uses background agents to maintain a dense observation log that replaces raw message history as it grows. This keeps the context window small while preserving long-term memory."

• Working memory: structured user data (names, preferences, goals)
• Semantic recall: recall past messages semantically rather than by keyword

When over budget, memory processors filter / trim / prioritize. Scope is split by two IDs: resource (user/entity) and thread (conversation). Across agents it can be shared or isolated (scope: 'resource' | 'thread').

The state side is the workflow snapshot (suspend/resume, see the background axis) — separate from memory.

RAG is a standalone system (@mastra/rag): MDocument chunking (recursive / sliding window), embedding, then into a vector store (officially named: pgvector, Pinecone, Qdrant, MongoDB).

In short: snapshots store flow state. Memory stores conversation and long-term user information. RAG stores external knowledge. The three serve different purposes.

权限与限制Permissions & limits

认证是「可选、多 provider」，HITL 是完整的暂停/恢复，沙箱只落在平台侧。 官方 auth 页原文：

"Authentication is optional. If no auth is configured, all routes and Studio are publicly accessible."

配置后可同时锁住 Studio UI（登录 + RBAC）与 API 路由。 自定义路由可用 requiresAuth: false 单开。

• 内置：Simple Auth / JWT
• 第三方：Auth0、Better Auth、Clerk、Firebase、Google、Okta、Supabase、WorkOS
• 其他：Composite / 自定义 provider

已查：auth 页与定价页。

人工介入：用 workflow 的 suspend/resume 做审批（见 background 轴）。 官方另有 human-in-the-loop 页与 AgentController（会话内审批、排队跟进、停止 run）。

沙箱：OSS 核心是否提供进程/容器级沙箱，官方未说明。 沙箱能力落在平台 Workspace 与 createCodingAgent()。

企业级权限（RBAC、SSO、IAM、network policy）属 ee/ 企业许可 （官方定价页 Self-Hosted Enterprise 卖点）。

核心框架的网络访问控制机制，官方未说明（已查 auth 页与定价页）。

Authentication is "optional, multi-provider"; HITL is full suspend/resume; sandboxing sits only on the platform side. Official auth page, verbatim:

"Authentication is optional. If no auth is configured, all routes and Studio are publicly accessible."

Once configured, it locks both the Studio UI (login + RBAC) and API routes. Custom routes can opt out with requiresAuth: false.

• Built-in: Simple Auth / JWT
• Third-party: Auth0, Better Auth, Clerk, Firebase, Google, Okta, Supabase, WorkOS
• Other: Composite / custom providers

Checked: auth page and pricing page.

Human intervention: use workflow suspend/resume for approvals (see the background axis). The official docs also have a human-in-the-loop page and AgentController (in-session approvals, queued follow-ups, stopping runs).

Sandbox: whether the OSS core provides process/container-level sandboxing is not stated by the official docs. Sandbox capability sits in the platform Workspace and createCodingAgent().

Enterprise permissions (RBAC, SSO, IAM, network policy) belong to the ee/ enterprise license (Self-Hosted Enterprise selling points on the official pricing page).

Network access control in the core framework is not stated by the official docs (auth page and pricing page checked).

适合什么任务Best for

适合：

• TypeScript / Node 团队要一套「开箱即用」的 agent 框架 —— Agents + 图 Workflows + Memory + RAG + Evals + MCP + 内置 server + Studio 全在一个包里

• 需要材料化的 suspend/resume 与 durable run（snapshot 存在你自己的存储、跨重启可恢复）
• 要接大量模型 provider 与本地模型（官方推荐 LMStudio）
• 需要把 agent/workflow 用 MCP 暴露出去，或当 MCP 客户端
• 想把 agent 嵌进 Next.js / React 应用

不适合：

• Python 栈（该看 LangGraph / Pydantic AI）
• 想要 low-level、自己掌控图引擎与工具面（Mastra 抽象更高、包更大、约定更多）
• 坚持完全不用任何商业组件（平台 Studio/观测/托管部署是单独的付费产品，ee/ 目录需企业许可）
• 需要框架自带进程级沙箱与网络策略（那部分不在 OSS 核心）

Fits:

• TypeScript / Node teams wanting a batteries-included agent framework — Agents + graph Workflows + Memory + RAG + Evals + MCP + built-in server + Studio all in one package

• You need materialized suspend/resume and durable runs (snapshots in your own storage, resumable across restarts)
• You want many model providers and local models (officially recommended: LMStudio)
• You need to expose agents/workflows over MCP, or act as an MCP client
• You want to embed agents in Next.js / React apps

Does not fit:

• Python stacks (look at LangGraph / Pydantic AI)
• Wanting low-level control over the graph engine and tool surface (Mastra's abstraction is higher, the package bigger, the conventions more)
• Insisting on zero commercial components (platform Studio/observability/hosted deployment are separate paid products; the ee/ directory needs an enterprise license)
• Needing framework-shipped process-level sandbox and network policy (that part is not in the OSS core)

本页由This page is generated from the ai-handbook 数据层生成（CC BY 4.0）。data layer (CC BY 4.0). 方法论与坐标系定义见仓库内For the methodology and coordinate definitions, see METHODOLOGY.md.