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

# 작업 Tool

Agent 실행을 위해 구조화된 작업 목록을 관리하는 4개의 기본 제공 Agent 독립적 Tool입니다. 작업 목록은 스레드 범위에 유지됩니다.`threadState`스토리지 도메인을 Agent에 투영하여[상태 신호](https://mastra.zisheng.pro/ko/docs/long-running-agents/signals)레인 그래서 살아남는다[관찰 기억](https://mastra.zisheng.pro/ko/docs/memory/observational-memory)잘림.

작업 추적에는 Memory를 지원하는 스레드(`threadId` + `resourceId`)가 필요합니다. Memory가 없으면 Tool이 작업 추적에 Agent Memory가 필요하다는 오류를 반환합니다. 권장 설정은 네 가지 Tool과 `TaskStateProcessor`를 하나의 등록으로 묶는 [`TaskSignalProvider`](https://mastra.zisheng.pro/ko/reference/signals/task-signal-provider)입니다. 개념 가이드는 [기본 제공 Tool](https://mastra.zisheng.pro/ko/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`

전체 작업 목록을 생성하거나 교체합니다. 각 호출은 이전 목록을 대체합니다.

### 입력 스키마

**tasks** (`TaskItemInput[]`): 업데이트된 전체 작업 목록입니다.

**tasks.id** (`string`): 안정적인 작업 식별자입니다(예: 'task\_investigate\_tests'). 업데이트 전반에서 변경하지 마세요. 생략하면 자동으로 생성됩니다.

**tasks.content** (`string`): 명령형으로 작성한 작업 설명(예: '인증 버그 수정').

**tasks.status** (`'pending' | 'in_progress' | 'completed'`): 현재 작업 상태입니다.

**tasks.activeForm** (`string`): 실행 중에 표시되는 현재진행형 표현(예: '인증 버그 수정 중').

### 산출

사람이 읽을 수 있는 `content` 요약, 할당된 ID가 포함된 전체 `tasks` 배열, `isError` 플래그가 있는 `TaskToolResult`를 반환합니다.

### 행동

- ID는 호출 내에서 고유해야 합니다. 명시적 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`): Total tracked tasks.

**summary.completed** (`number`): Completed tasks.

**summary.inProgress** (`number`): In-progress tasks.

**summary.pending** (`number`): Pending tasks.

**summary.incomplete** (`number`): Tasks not yet completed (in-progress + pending).

**summary.hasTasks** (`boolean`): True when at least one task exists.

**summary.allCompleted** (`boolean`): 작업이 하나 이상 존재하고 모든 작업이 완료되었으면 참입니다.

**incompleteTasks** (`TaskItem[]`): 아직 작업이 필요한 항목입니다(진행 중 및 대기 중).

**isError** (`boolean`): 검사 중 오류가 발생했는지 여부입니다.