# Background Tasks

> Dispatch long-running work to Mastra's BackgroundTaskManager and surface it as a live activity card in the chat.

## What is this? [#what-is-this]

Mastra's [background tasks](https://mastra.ai/docs/agents/background-tasks) let a tool run
outside the agentic loop without blocking it. When a tool is flagged
`background: { enabled: true }`, Mastra dispatches it to its `BackgroundTaskManager`, emits a
`background-task-started` lifecycle chunk, and returns a placeholder result so the conversation
keeps flowing.

`MastraAgent`, the AG-UI adapter, turns that lifecycle into an AG-UI **activity event** of type
`mastra-background-task`. It **hides the normal tool pill**, so the work shows only as a live
"working" card. A registered CopilotKit activity renderer paints that card inline in the
transcript.

If your agent uses Mastra's Observational Memory, you can show its memory cycles as the same
kind of card. See [Observational Memory as background activity](#observational-memory-as-background-activity).

## When should I use this? [#when-should-i-use-this]

Background tasks fit any work that is too slow to hold the chat hostage:

- **Deep research / long lookups**: kick off a multi-step investigation and let the user keep chatting
- **Report or artifact generation**: build something in the background and surface progress
- **Batch or fan-out work**: dispatch several jobs without serializing the conversation

<Callout type="info">
  Completion is delivered **out of band**. On the dispatching turn Mastra emits only the
  `started` lifecycle plus a placeholder result, so within that turn the card stays in the
  "working" state; the finished result is delivered on a later turn (or retrieved from the task
  manager). See [Completion is out of band](#completion-is-out-of-band) below.
</Callout>

## Implementation [#implementation]

<Steps>
<Step>
  ### Run and connect your agent [#run-and-connect-your-agent]
  You'll need to run your agent and connect it to CopilotKit before proceeding.

  If you don't already have CopilotKit and your agent connected, choose one of the following options:

  <Accordions>
    <Accordion title="I already have an agent">
      You can follow the instructions in the [quickstart](/mastra/quickstart) guide.
    </Accordion>
    <Accordion title="I want to start from scratch">
      Run the following command to create a brand new project with a pre-configured agent:

      ```bash
      npx copilotkit@latest create -f mastra
      ```

    </Accordion>
  </Accordions>
</Step>

<Step>
  ### Define a backgroundable tool [#define-a-backgroundable-tool]

  Flag the tool with `background: { enabled: true }`. Mastra dispatches it to the
  `BackgroundTaskManager` instead of running it inline.

  ```typescript title="src/mastra/tools/background-research.ts"
  import { createTool } from "@mastra/core/tools";
  import { z } from "zod";

  export const runDeepResearchTool = createTool({
    id: "run_deep_research",
    description:
      "Kick off a long-running deep-research task on a topic. This runs in " +
      "the background while the conversation continues.",
    inputSchema: z.object({
      topic: z.string().describe("The topic to research in depth."),
    }),
    background: { enabled: true }, // [!code highlight]
    execute: async ({ topic }) => {
      // Runs when the background worker executes the task.
      return JSON.stringify({
        topic,
        summary: `Deep research on "${topic}" completed.`,
      });
    },
  });
  ```
</Step>

<Step>
  ### Enable the BackgroundTaskManager on the Mastra instance [#enable-the-backgroundtaskmanager-on-the-mastra-instance]

  Backgroundable tools only dispatch when the manager is enabled on the instance. A configured
  `storage` is also required so tasks can be tracked.

  ```typescript title="src/mastra/index.ts"
  import { Mastra } from "@mastra/core/mastra";
  import { LibSQLStore } from "@mastra/libsql";
  import { backgroundAgentsAgent } from "./agents";

  export const mastra = new Mastra({
    agents: { backgroundAgentsAgent },
    storage: new LibSQLStore({ id: "mastra-storage", url: ":memory:" }),
    backgroundTasks: { enabled: true }, // [!code highlight]
  });
  ```
</Step>

<Step>
  ### Add the tool to your agent [#add-the-tool-to-your-agent]

  ```typescript title="src/mastra/agents/index.ts"
  import { Agent } from "@mastra/core/agent";
  import { openai } from "@ai-sdk/openai";
  import { runDeepResearchTool } from "@/mastra/tools/background-research"; // [!code highlight]

  export const backgroundAgentsAgent = new Agent({
    id: "background-agents",
    name: "Background Agents Agent",
    tools: { runDeepResearchTool }, // [!code highlight]
    model: openai("gpt-6-luna"),
    instructions:
      "You are a research assistant that dispatches long-running work to the " +
      "background. When the user asks you to research a topic, call the " +
      "run_deep_research tool ONCE, then send a short message saying the work " +
      "is running in the background.",
  });
  ```
</Step>

<Step>
  ### Render the activity card in your frontend [#render-the-activity-card-in-your-frontend]

  Write an activity renderer for the `mastra-background-task` activity type. The standard chat
  surface renders registered activity messages inline, so no custom message list is needed.

</Step>

<Step>
  ### Give it a try [#give-it-a-try]

  Ask the agent to research something.

  ```
  Kick off deep research on the current landscape of AI agent frameworks.
  ```

  The agent calls `run_deep_research`, Mastra dispatches it in the background, and a live
  "working" activity card appears inline (with no blocking tool pill) while the conversation
  stays responsive.
</Step>
</Steps>

## Completion is out of band [#completion-is-out-of-band]

By design, the dispatching run's stream carries only the `started` lifecycle plus a placeholder
result. The tool's `execute` has not finished by the time the stream closes. So within that turn
the card stays "working"; the finished result is delivered out of band.

`getLocalAgents` accepts `untilIdle: true`. It holds the run open and sends the pubsub chunks of
the task manager, including `background-task-completed`, into the same stream. Then the card can
change to "Completed" in the same turn. That only works when a **background worker actually executes the dispatched
task before the idle window closes**. In a single-process app with no such worker the task is never
executed within the run, so no completion chunk is produced and `untilIdle` only holds the stream
open with no benefit. When you run a deployment with a real background worker, enable `untilIdle`
and the adapter's lifecycle mapping (`running` → `completed`/`failed`/`cancelled`) flips the card
automatically. Otherwise, retrieve results out of band via the task manager
(`backgroundTaskManager.stream()` / `getTask(taskId)`).

## Observational Memory as background activity [#observational-memory-as-background-activity]

If your agent uses Mastra's [Observational Memory](https://mastra.ai/docs/memory/observational-memory),
you can surface its observation/buffering/activation cycles the same way, as a live activity card
instead of invisible background work. This is opt-in and OFF by default.

Two switches, both required:

1. **The agent's `Memory` must have Observational Memory enabled** (that's what makes Mastra stream
   the OM lifecycle in the first place):

   ```typescript title="src/mastra/agents/index.ts"
   memory: new Memory({
     storage,
     options: {
       observationalMemory: {
         scope: "thread",
         observation: { messageTokens: 600, bufferTokens: 300 },
         model: openai("gpt-6-luna"),
       },
     },
   }),
   ```

2. **The adapter must be told to forward it**: pass `observationalMemory: true` (or an array of
   agent ids) to `getLocalAgents`:

   ```typescript title="app/api/copilotkit/route.ts"
   const localAgents = getLocalAgents({
     mastra,
     resourceId: "user-1",
     observationalMemory: true, // [!code highlight]
   });
   ```

With both on, `MastraAgent` maps the OM lifecycle to AG-UI activity events under activity type
`mastra-observational-memory`. Render them exactly like the background-task card. Register a
renderer for that activity type:

The activity content carries the cycle (`cycleId`, `phase: "observation" | "buffering" | "activation"`,
`status`, token counts) and advances in place as the cycle progresses, so one card tracks each OM
cycle from start to completion.

<Callout type="info">
  OM cycles trigger on **unobserved message-token size**, not turn count. Short chats may never
  trip one. If you're testing the card, drive a few sizable messages.
</Callout>
