Task Tools

这四个不限定 Agent 的内置 Tool，可管理 Agent 运行期间的结构化任务清单。任务清单会保存在 thread 范围的 threadState 保存网域，并投射至 Agent 的 state-signal lane，因此即使 observational-memory 截断内容，任务清单仍会保留。

任务追踪需要由 Memory 支持的 thread（threadId + resourceId）。若没有 Memory，Tool 会返回错误，说明任务追踪需要 Agent Memory。

建议使用 TaskSignalProvider 进行设置，它会在一次注册中集成四个 Tool 与 TaskStateProcessor。概念说明请参阅内置 Tool。

使用示例

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()],
})

或直接导入 Tool：

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

创建或取代整份任务清单。每次调用都会取代先前的清单。

输入 schema

tasks:

TaskItemInput[]

更新后的完整任务清单。

TaskItemInput

id?:

string

稳定的任务识别码（例如 'task_investigate_tests'）。更新时请保持不变。省略时会自动产生。

content:

string

使用祈使语气撰写的任务说明（例如 'Fix authentication bug'）。

status:

'pending' | 'in_progress' | 'completed'

当前的任务状态。

activeForm:

string

运行期间显示的现在进行式文本（例如 'Fixing authentication bug'）。

输出

返回 TaskToolResult，其中包含易于阅读的 content 摘要、带有已分配 ID 的完整 tasks 数组，以及 isError 标志。

行为

• 同一次调用中的 ID 必须是唯一值。明确提供的重复 ID 会改用产生的备援 ID。
• 重写现有清单时若省略 ID，只有在恰好有一项明确相符的任务时，才会沿用先前的 ID 以维持稳定性。
• 同一时间只能有一项任务处于 in_progress 状态。提交多项 in_progress 任务会返回错误。

task_update

使用稳定 ID 更新一项任务。只需包含已变更的字段。

输入 schema

id:

string

要更新的稳定任务识别码。

content?:

string

使用祈使语气撰写的新任务说明。

status?:

'pending' | 'in_progress' | 'completed'

新的任务状态。

activeForm?:

string

新的现在进行式文本。

必须至少提供 content、status 或 activeForm 其中一项。

行为

• 当更新将某项任务设为 in_progress 时，其他处于 in_progress 的任务会自动降为 pending。
• 找不到 ID 时，会返回错误以及可用的任务 ID。

task_complete

使用稳定 ID 将一项任务标记为完成。

输入 schema

id:

string

要标记为完成的稳定任务标识符。

行为

找不到 ID 时，会返回错误以及可用的任务 ID。

task_check

检查任务清单的完成状态。不接受任何输入参数。

输出

返回包含下列内容的 TaskCheckResult：

content:

string

便于阅读的摘要，包含任务数量与未完成任务 ID。

tasks:

TaskItem[]

包含稳定 ID 的完整任务清单快照。

summary:

TaskCheckSummary

结构化数量统计。

TaskCheckSummary

total:

number

追踪的任务总数。

completed:

number

已完成的任务数。

inProgress:

number

进行中的任务数。

pending:

number

待处理的任务数。

incomplete:

number

尚未完成的任务数（进行中 + 待处理）。

hasTasks:

boolean

至少有一项任务时为 true。

allCompleted:

boolean

至少有一项任务且所有任务都已完成时为 true。

incompleteTasks:

TaskItem[]

仍需处理的任务（进行中与待处理）。

isError:

boolean

检查过程是否发生错误。