> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# Task tools

四個內置且不依賴特定 Agent 的 Tools，用於管理某次 Agent 執行的結構化任務清單。任務清單會保存在以執行緒為範圍的 `threadState` 儲存網域中，並投射到 Agent 的 [state-signal](https://mastra.zisheng.pro/zh-HK/docs/long-running-agents/signals) 通道，因此可在 [observational-memory](https://mastra.zisheng.pro/zh-HK/docs/memory/observational-memory) 截斷後保留。

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

建議設定是 [`TaskSignalProvider`](https://mastra.zisheng.pro/zh-HK/reference/signals/task-signal-provider)，它在一次註冊中包含全部四個 Tools 及 `TaskStateProcessor`。概念指南請參閱[內置 Tools](https://mastra.zisheng.pro/zh-HK/docs/agents/using-tools)。

## 使用範例

```typescript
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：

```typescript
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[]`): 完整的已更新任務清單。

**tasks.id** (`string`): 穩定的任務識別符（例如 'task\_investigate\_tests'）。更新時請保持不變。如省略，系統會自動產生。

**tasks.content** (`string`): 使用祈使語氣撰寫的任務描述（例如 'Fix authentication bug'）。

**tasks.status** (`'pending' | 'in_progress' | 'completed'`): 目前的任務狀態。

**tasks.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`): 結構化計數。

**summary.total** (`number`): 追蹤中的任務總數。

**summary.completed** (`number`): 已完成的任務數目。

**summary.inProgress** (`number`): 進行中的任務數目。

**summary.pending** (`number`): 待處理的任務數目。

**summary.incomplete** (`number`): 尚未完成的任務數目（進行中 + 待處理）。

**summary.hasTasks** (`boolean`): 至少存在一項任務時為 True。

**summary.allCompleted** (`boolean`): 至少存在一項任務，而且每項任務均已完成時為 True。

**incompleteTasks** (`TaskItem[]`): 仍需處理的任務（進行中及待處理）。

**isError** (`boolean`): 檢查期間是否遇到錯誤。