# Mastra: features, protocols, quickstart

## TL;DR

Mastra is a TypeScript framework from Kepler Software, which trades as Mastra, for building agents, supervisor-style multi-agent setups and step-based workflows with memory, evals and tracing. Most code is Apache-2.0, while `ee/` directories use a source-available enterprise license. It suits Node.js and Next.js teams adding agents to an existing app.

## Key facts

| Field | Value |
| --- | --- |
| Type | Framework |
| Languages / SDKs | TypeScript |
| License | unknown |
| Pricing model | [Open core](https://mastra.ai/pricing) |
| Orchestration pattern | Supervisor |
| GitHub stars | 28,460 (as of 2026-10-01) |
| GitHub forks | 2,895 |
| Last push | 2026-10-01 |
| Latest release | @mastra/core@1.72.0 |
| Repository | [mastra-ai/mastra](https://github.com/mastra-ai/mastra) |
| Website | [mastra.ai](https://mastra.ai) |
| Documentation | [mastra.ai](https://mastra.ai/docs) |
| Last verified | 2026-09-30 |

## Key features

- Agents that combine a model, `createTool()` tools, structured output and memory, addressed through a `provider/model` string router. ([source](https://mastra.ai/docs/agents/overview))
- Supervisor agents: subagents listed in a parent's `agents` property, with `onDelegationStart` / `onDelegationComplete` hooks and a `messageFilter` for what context each subagent sees. ([source](https://mastra.ai/docs/subagents))
- Workflows built from typed `createStep()` steps and composed with `.then()`, `.parallel()`, `.branch()`, `.dountil()` and `.foreach()`. ([source](https://mastra.ai/docs/workflows/control-flow))
- Workflow `suspend()` / `resume()` backed by snapshots in the configured storage provider, so paused runs survive restarts. ([source](https://mastra.ai/docs/workflows/suspend-and-resume))
- Memory layers: message history, observational memory, working memory and semantic recall, persisted through storage providers. ([source](https://mastra.ai/docs/memory/overview))
- Tool-call approval (`requireApproval`, `requireToolApproval`) with `approveToolCall()` / `declineToolCall()` and in-tool `suspend()`. ([source](https://mastra.ai/docs/agents/human-in-the-loop))
- `@mastra/mcp` provides `MCPClient` for consuming MCP servers and `MCPServer` for exposing agents, tools and workflows. ([source](https://mastra.ai/docs/connections/mcp))
- `@mastra/acp` runs ACP-speaking coding agents (for example OpenCode or Cline) as a Mastra tool or subagent. ([source](https://mastra.ai/docs/connections/acp))

## Architecture and orchestration pattern

Pattern: Supervisor.

Mastra has two execution primitives. An `Agent` runs a model-and-tool loop until the model stops or `maxSteps` is reached. A workflow is an explicit graph of typed steps chained with `.then()`, run side by side with `.parallel()`, routed with `.branch()` or looped with `.dountil()` / `.foreach()`. Workflows run on a built-in engine by default, and the docs list workflow runners such as Inngest for managed execution.

Multi-agent work is centred on supervisor agents. Subagents go in the parent's `agents` property and the parent decides, from each subagent's `description`, when to delegate; delegation hooks can rewrite or reject a call. The older `.network()` routing API is deprecated in favour of this pattern. The multi-agent guide also describes handoffs and councils, but builds them from agents plus workflows; there is no dedicated council primitive.

State lives in storage providers (for example LibSQL or PostgreSQL). Workflow and approval snapshots are saved there so a suspended run can resume later. Agent memory combines message history with optional observational memory, working memory and semantic recall. During delegation a subagent sees the parent's conversation, but only the delegation prompt and its own reply are written to the subagent's memory.

### Human in the loop

For agents, a tool marked `requireApproval: true`, or every tool when `requireToolApproval: true` is passed to `stream()` / `generate()`, pauses before `execute` runs. The stream emits a `tool-call-approval` chunk and the caller answers with `approveToolCall()` or `declineToolCall()` using the run ID; a decline can carry a `reason` that is returned to the model. With `generate()`, the result comes back with `finishReason: 'suspended'` instead. A tool can also call `suspend()` mid-execution and wait for `resumeStream()` with data matching its `resumeSchema`.

Workflows pause with `suspend()` inside a step and continue with `run.resume()` from any part of the application, such as an HTTP handler. Both mechanisms rely on snapshots, so a storage provider must be configured or resuming fails with a "snapshot not found" error. For supervisors, `onDelegationStart` can block or rewrite a delegation before the subagent runs.

### Harnesses it can drive

- OpenCode ([evidence](https://mastra.ai/docs/connections/acp))
- Claude Code ([evidence](https://mastra.ai/docs/connections/sdk-agents))

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://mastra.ai/docs/connections/mcp) | Client and server: `MCPClient` connects to MCP servers over stdio or Streamable HTTP, and `MCPServer` exposes Mastra agents, tools, workflows, prompts and resources (`@mastra/mcp`). |
| A2A | Yes (checked 2026-09-30) | [link](https://mastra.ai/docs/connections/a2a) | Both directions: Mastra Server publishes an agent card and JSON-RPC endpoint per agent, and `A2AAgent` wraps a remote A2A agent as a subagent; v0.3 is the default and v1.0 is selected with the `A2A-Version` header. |
| AG-UI | Partial (checked 2026-09-30) | [link](https://mastra.ai/integrations/agentic-ui/copilotkit) | Adapter maintained in the AG-UI repository: Mastra's CopilotKit guide serves Mastra agents over AG-UI with `@ag-ui/mastra`, which npm lists as published from ag-ui-protocol/ag-ui (integrations/mastra), not from Mastra's own packages; the AG-UI README labels Mastra 1st party. |

## Best for

- TypeScript teams adding agents to an existing React, Next.js or Node.js application ([shortlist](https://multiagentguide.top/best/typescript.md))
- Research-and-write flows where a supervisor delegates to specialised subagents ([shortlist](https://multiagentguide.top/best/research-agents.md))
- Delegating repository work to external coding agents such as OpenCode over ACP ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Tool calls that must wait for a person to approve or decline them

## Not for

- Python-only teams; Mastra is a TypeScript framework
- Production use of `ee/` features without a written agreement and license key from Mastra
- Runtimes older than Node.js 22.13, the minimum declared by `@mastra/core`

## Quickstart

```sh
npm create mastra@latest
```

Install verified 2026-09-30 (temp dir, Node v22.22.3, macOS arm64: local `npm i @mastra/core` (no -g) ok, `node -e "import('@mastra/core/agent').then(m=>console.log(typeof m.Agent))"` ok, @mastra/core 1.72.0. This is the core package from the documented manual install; the interactive `npm create mastra@latest` scaffolder was not run. Packages came from the registry.npmmirror.com mirror, so the version is the one that mirror served on this date. Install and import check only; not a functional test.).

```ts
import { Agent } from '@mastra/core/agent'
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

const lookup = createTool({
  id: 'lookup-order',
  description: 'Look up an order status by ID',
  inputSchema: z.object({ orderId: z.string() }),
  execute: async ({ orderId }) => ({ orderId, status: 'shipped' }),
})
const orders = new Agent({ id: 'orders', name: 'Orders', description: 'Answers order status questions.',
  instructions: 'Use lookup-order.', model: 'openai/gpt-5-mini', tools: { lookup } })
const lead = new Agent({ id: 'lead', name: 'Lead', instructions: 'Send order questions to orders.',
  model: 'openai/gpt-5-mini', agents: { orders } })

const res = await lead.generate('Where is order A-17?', { maxSteps: 5 })
console.log(res.text)
```

### Common pitfalls

- `@mastra/core` declares `node >=22.13.0` and is an ES module; the manual setup uses `{ "type": "module" }` in `package.json`.
- A `provider/model` string reads the provider key from the environment, for example `OPENAI_API_KEY` for `openai/...` models.
- The docs warn that tools passed as plain objects do not execute; define them with `createTool()`.
- Tool approval and workflow suspend/resume need a storage provider on the Mastra instance, otherwise resuming fails with "snapshot not found".
- `.network()` is deprecated; new multi-agent code should use supervisor agents via `generate()` / `stream()`. `@mastra/mcp` 1.x users have a separate v2 migration guide.

Official quickstart: https://mastra.ai/docs

## Pros

- One package covers MCP in both directions: consume external MCP servers and publish Mastra agents and tools as an MCP server. ([source](https://mastra.ai/docs/connections/mcp))
- A2A works as server and client, and one endpoint accepts both v0.3 and v1.0 requests. ([source](https://mastra.ai/docs/connections/a2a))
- Delegation hooks can reject or rewrite a subagent call, and a message filter limits what context a subagent receives. ([source](https://mastra.ai/docs/subagents))
- Approval flows cover pre-execution approval, declines with a reason, and tools that suspend themselves mid-run. ([source](https://mastra.ai/docs/agents/human-in-the-loop))
- Existing agents built with the Claude Agent SDK, Cursor Agent SDK or OpenAI Agents SDK can be registered inside a Mastra project. ([source](https://mastra.ai/docs/connections/sdk-agents))

## Cons

- Code under any `ee/` directory is source-available only; production use requires a written agreement and a license key, which is why GitHub reports no single license. ([source](https://github.com/mastra-ai/mastra/blob/main/ee/LICENSE))
- The `.network()` multi-agent API is deprecated and slated for removal, so older examples need migrating to supervisor agents. ([source](https://mastra.ai/reference/migrations/network-to-supervisor))
- Approvals and suspended workflows depend on a configured storage provider; without one, resume fails. ([source](https://mastra.ai/docs/agents/human-in-the-loop))
- Coding agents started through `@mastra/acp` run in the configured directory without sandboxing and can reach files through their own tools. ([source](https://mastra.ai/docs/connections/acp))
- Minor releases of `@mastra/core` arrive every few days (1.64.0 to 1.71.0 in September 2026), so pinning versions matters. ([source](https://github.com/mastra-ai/mastra/releases))

## Alternatives

- [VoltAgent](https://multiagentguide.top/tools/voltagent.md) ([Mastra vs VoltAgent](https://multiagentguide.top/compare/mastra-vs-voltagent.md))
- [LangGraph.js](https://multiagentguide.top/tools/langgraphjs.md)
- [OpenAI Agents SDK (JavaScript/TypeScript)](https://multiagentguide.top/tools/openai-agents-js.md)
- [AgentKit by Inngest](https://multiagentguide.top/tools/inngest-agentkit.md)
- [KaibanJS](https://multiagentguide.top/tools/kaibanjs.md)

## FAQ

### Does Mastra support MCP?

Yes. The `@mastra/mcp` package includes `MCPClient` for connecting agents to MCP servers over stdio or Streamable HTTP and `MCPServer` for exposing Mastra agents, tools and workflows to MCP clients.

### Is Mastra free?

Most of the repository is Apache-2.0 and free to use. Code in `ee/` directories needs a commercial agreement for production use, and the hosted Mastra Platform has a free Starter tier plus paid Teams and Enterprise tiers.

### Why is Mastra's license listed as unknown?

GitHub cannot assign one SPDX id because `LICENSE.md` combines Apache-2.0 for most code with the Mastra Enterprise License for everything under `ee/` directories.

### Does Mastra work with A2A and AG-UI?

A2A is built in: Mastra Server exposes agents over A2A and `A2AAgent` consumes remote A2A agents. AG-UI works through `@ag-ui/mastra`, an adapter maintained in the AG-UI repository that Mastra's docs use for CopilotKit frontends.

### How does Mastra coordinate several agents?

The recommended pattern is a supervisor agent that lists subagents in its `agents` property and delegates to them. The older `.network()` API is deprecated.

## Sources

- [Mastra GitHub repository](https://github.com/mastra-ai/mastra)
- [Mastra README](https://github.com/mastra-ai/mastra/blob/main/README.md)
- [Mastra docs: Get started](https://mastra.ai/docs)
- [LICENSE.md (license mapping)](https://github.com/mastra-ai/mastra/blob/main/LICENSE.md)
- [Mastra Enterprise Edition License (ee/LICENSE)](https://github.com/mastra-ai/mastra/blob/main/ee/LICENSE)
- [@mastra/core package.json](https://github.com/mastra-ai/mastra/blob/main/packages/core/package.json)
- [Mastra releases](https://github.com/mastra-ai/mastra/releases)
- [Agents overview (docs)](https://mastra.ai/docs/agents/overview)
- [Subagents / supervisor agents (docs)](https://mastra.ai/docs/subagents)
- [Workflows overview (docs)](https://mastra.ai/docs/workflows/overview)
- [Workflow control flow (docs)](https://mastra.ai/docs/workflows/control-flow)
- [Workflow suspend and resume (docs)](https://mastra.ai/docs/workflows/suspend-and-resume)
- [Memory overview (docs)](https://mastra.ai/docs/memory/overview)
- [Agent human-in-the-loop (docs)](https://mastra.ai/docs/agents/human-in-the-loop)
- [Multi-agent systems guide (docs)](https://mastra.ai/docs/guides/multi-agent-systems)
- [MCP connections (docs)](https://mastra.ai/docs/connections/mcp)
- [A2A connections (docs)](https://mastra.ai/docs/connections/a2a)
- [Agent Client Protocol connections (docs)](https://mastra.ai/docs/connections/acp)
- [SDK agents (docs)](https://mastra.ai/docs/connections/sdk-agents)
- [Migrate from .network() to supervisor agents](https://mastra.ai/reference/migrations/network-to-supervisor)
- [CopilotKit integration via AG-UI (docs)](https://mastra.ai/integrations/agentic-ui/copilotkit)
- [AG-UI README, supported integrations](https://github.com/ag-ui-protocol/ag-ui/blob/main/README.md)
- [AG-UI repository, Mastra integration](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/mastra)
- [Mastra pricing](https://mastra.ai/pricing)
- [Mastra homepage](https://mastra.ai)

## Unknown fields

license: GitHub reports NOASSERTION. LICENSE.md states that everything outside `ee/` directories is Apache-2.0 (Copyright Kepler Software, Inc.) and that code in any `ee/` directory is under the Mastra Enterprise Edition License v2.0, a source-available license that allows development and testing but requires a written agreement and license key for production use (https://github.com/mastra-ai/mastra/blob/main/LICENSE.md, https://github.com/mastra-ai/mastra/blob/main/ee/LICENSE).

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-10-01. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/mastra