Task tools

Four built-in, agent-agnostic tools that manage a structured task list for an agent run. The task list is persisted in the thread-scoped threadState storage domain and projected onto the agent state-signal lane so it survives observational-memory truncation.

Task tracking requires a memory-backed thread (threadId + resourceId). Without memory the tools return an error explaining that task tracking requires agent memory.

The recommended setup is TaskSignalProvider, which bundles all four tools and the TaskStateProcessor in a single registration. See Built-in tools for the conceptual guide.

Usage example

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { TaskSignalProvider } from '@mastra/core/signals'

const agent = new Agent({
  id: 'coder',
  name: 'Coder',
  instructions: 'Track your progress with the task tools.',
  model,
  memory: new Memory(),
  signals: [new TaskSignalProvider()],
})

Or import the tools directly:

src/mastra/agents/index.ts

import { taskWriteTool, taskUpdateTool, taskCompleteTool, taskCheckTool } from '@mastra/core/tools'

const agent = new Agent({
  id: 'coder',
  name: 'Coder',
  instructions: 'Track your progress with the task tools.',
  model,
  memory: new Memory(),
  tools: { taskWriteTool, taskUpdateTool, taskCompleteTool, taskCheckTool },
})

task_write

Create or replace the entire task list. Each call replaces the previous list.

Input schema

tasks:

TaskItemInput[]

The complete updated task list.

TaskItemInput

id?:

string

Stable task identifier (e.g. 'task_investigate_tests'). Keep this unchanged across updates. Auto-generated when omitted.

content:

string

Task description in imperative form (e.g. 'Fix authentication bug').

status:

'pending' | 'in_progress' | 'completed'

Current task status.

activeForm:

string

Present continuous form shown during execution (e.g. 'Fixing authentication bug').

Output

Returns a TaskToolResult with a human-readable content summary, the full tasks array with assigned IDs, and an isError flag.

Behavior

• IDs must be unique within a call. Duplicate explicit IDs get a generated fallback.
• When an ID is omitted while rewriting an existing list, one unambiguous matching task reuses its previous ID for stability.
• Only one task can have in_progress status at a time. Submitting multiple in_progress tasks returns an error.

task_update

Update one task by its stable ID. Include only the fields that changed.

Input schema

id:

string

The stable task identifier to update.

content?:

string

New task description in imperative form.

status?:

'pending' | 'in_progress' | 'completed'

New task status.

activeForm?:

string

New present continuous form.

At least one of content, status, or activeForm is required.

Behavior

• When the update sets a task to in_progress, any other in_progress task is automatically demoted to pending.
• Returns an error with available task IDs when the ID is not found.

task_complete

Mark one task completed by its stable ID.

Input schema

id:

string

The stable task identifier to mark completed.

Behavior

Returns an error with available task IDs when the ID is not found.

task_check

Check the completion status of the task list. Takes no input parameters.

Output

Returns a TaskCheckResult with:

content:

string

Human-readable summary with task counts and incomplete task IDs.

tasks:

TaskItem[]

Full task list snapshot with stable IDs.

summary:

TaskCheckSummary

Structured counts.

TaskCheckSummary

total:

number

Total tracked tasks.

completed:

number

Completed tasks.

inProgress:

number

In-progress tasks.

pending:

number

Pending tasks.

incomplete:

number

Tasks not yet completed (in-progress + pending).

hasTasks:

boolean

True when at least one task exists.

allCompleted:

boolean

True when at least one task exists and every task is completed.

incompleteTasks:

TaskItem[]

Tasks that still need work (in-progress and pending).

isError:

boolean

Whether the check encountered an error.