Task tools

四個內置且不依賴特定 Agent 的 Tools，用於管理某次 Agent 執行的結構化任務清單。任務清單會保存在以執行緒為範圍的 threadState 儲存網域中，並投射到 Agent 的 state-signal 通道，因此可在 observational-memory 截斷後保留。

任務追蹤需要由記憶體支援的執行緒（threadId + resourceId）。如沒有記憶體，Tools 會傳回錯誤，說明任務追蹤需要 Agent 記憶體。

建議設定是 TaskSignalProvider，它在一次註冊中包含全部四個 Tools 及 TaskStateProcessor。概念指南請參閱內置 Tools。

使用範例

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

或者直接匯入 Tools：

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

建立或取代整份任務清單。每次呼叫都會取代上一份清單。

輸入結構描述

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，以保持穩定。
• 每次只能有一項任務處於 in_progress 狀態。提交多項 in_progress 任務會傳回錯誤。

task_update

透過穩定 ID 更新一項任務。只需包含已變更的欄位。

輸入結構描述

id:

string

要更新的穩定任務識別符。

content?:

string

使用祈使語氣撰寫的新任務描述。

status?:

'pending' | 'in_progress' | 'completed'

新的任務狀態。

activeForm?:

string

新的現在進行式。

必須提供 content、status 或 activeForm 其中至少一項。

行為

• 更新將任務設為 in_progress 時，任何其他 in_progress 任務都會自動降為 pending。
• 如果找不到該 ID，會傳回錯誤及可用的任務 ID。

task_complete

透過穩定 ID 將一項任務標記為已完成。

輸入結構描述

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

檢查期間是否遇到錯誤。