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

檢查過程是否發生錯誤。