Mastra

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.

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.

npm create mastra@latest

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)

• @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.

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.

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.

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.

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.

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