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

# Task Tools

這四個不限定 Agent 的內建 Tool，可管理 Agent 執行期間的結構化任務清單。任務清單會保存在 thread 範圍的 `threadState` 儲存網域，並投射至 Agent 的 [state-signal](https://mastra.zisheng.pro/zh-TW/docs/long-running-agents/signals) lane，因此即使 [observational-memory](https://mastra.zisheng.pro/zh-TW/docs/memory/observational-memory) 截斷內容，任務清單仍會保留。

任務追蹤需要由 Memory 支援的 thread（`threadId` + `resourceId`）。若沒有 Memory，Tool 會回傳錯誤，說明任務追蹤需要 Agent Memory。

建議使用 [`TaskSignalProvider`](https://mastra.zisheng.pro/zh-TW/reference/signals/task-signal-provider) 進行設定，它會在一次註冊中整合四個 Tool 與 `TaskStateProcessor`。概念說明請參閱[內建 Tool](https://mastra.zisheng.pro/zh-TW/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()],
})
```

或直接匯入 Tool：

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

建立或取代整份任務清單。每次呼叫都會取代先前的清單。

### 輸入 schema

**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，只有在恰好有一項明確相符的任務時，才會沿用先前的 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`): 結構化數量統計。

**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`): 檢查過程是否發生錯誤。