Introducing Background Tasks for Mastra Agents

Your agents can now respond before, during, and after long-running tool calls without blocking the agentic loop.

Background tasks are a new configuration option that allows tools to run asynchronously, letting you stream progress back to the user while the tool works in the background.

Background tasks also support parallel tool calling. When an agent calls multiple background-enabled tools, each one runs concurrently.

Get started

Enable background tasks on your Mastra instance:

 1import { Mastra } from "@mastra/core";
 2
 3export const mastra = new Mastra({
 4  storage: {
 5    //...
 6  },
 7  backgroundTasks: { enabled: true }
 8});

A storage provider is required to persist state, allowing tasks to resume and survive server restarts.

Configure a tool with backgroundTasks: { enabled: true } to run it in the background. The same configuration can also be set at the agent-level.

 1import { createTool } from "@mastra/core/tools";
 2import { z } from "zod";
 3
 4export const researchTool = createTool({
 5  id: "research",
 6  description: "Run a deep research job on a topic",
 7  inputSchema: z.object({ topic: z.string() }),
 8  backgroundTasks: {
 9    enabled: true,
10    timeoutMs: 600_000
11  },
12  execute: async ({ context }) => {
13    //...
14  }
15});

Call your agent with .streamUntilIdle() to keep the stream open and send feedback to the user.

 1const stream = await agent.streamUntilIdle("Research SpaceX for me", {
 2  memory: { thread: "t1", resource: "u1" }
 3});
 4
 5for await (const chunk of stream.fullStream) {
 6  // initial turn, in progress, and continuation turns
 7}

The stream surfaces chunks at each stage of the agentic loop. See the full list of stream chunks for the complete payload shapes.

For more information and full configuration options, see:

• Background tasks overview
• Background task streaming
• streamUntilIdle reference