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

# 目標

**新增於：** `@mastra/core@1.42.0`

> **Beta:** Goals 功能目前處於 beta 階段，在脫離 beta 狀態前，次要版本中可能會有破壞性變更。

目標是持久且以對話串為範圍的目的：Agent 會在多次迴圈反覆運算中持續朝這項常駐指示努力，直到裁判模型判定已達成，或耗盡執行預算。

此目的會持久化於對話串狀態，因此即使重新載入也會保留，並在迴圈內接受評估；即使已有輪次正在執行時收到新訊息也一樣。

Goals 建構於與 [`isTaskComplete`](https://mastra.zisheng.pro/zh-TW/docs/capabilities/subagents) 相同的機制：由 LLM 擔任裁判，在每次反覆運算中為 Agent 輸出評分並控制迴圈。差別在於目標是**持久的**（儲存於對話串狀態，而非每次呼叫時傳入），並透過 `Agent` 方法設定及更新，而不是透過每次 `stream()` 的選項。

## 何時使用目標

當你希望 Agent 跨越多次反覆運算與訊息，持續朝單一目的努力，而不必在每次呼叫中重新提供成功條件時，請使用目標：

- Agent 應持續追求，直到裁判判定完成的常駐目的。
- 應跨越執行途中訊息繼續進行的工作（傳入進行中執行的訊息仍會依目標接受判定）。
- 必須在對話串重新載入或處理程序重新啟動後持續存在的目的。

若只需在單次 `stream()` 呼叫內進行一次性完成檢查，請改用 [`isTaskComplete`](https://mastra.zisheng.pro/zh-TW/docs/capabilities/subagents)。

## 快速開始

Goals 需要已設定的[儲存空間](https://mastra.zisheng.pro/zh-TW/docs/storage/overview)後端，以及由記憶體支援的對話串。將 `goal` 設定加入 Agent；目標必須有裁判模型才會產生作用；接著替對話串設定目的：

```typescript
import { Agent } from '@mastra/core/agent'

const worker = new Agent({
  id: 'worker',
  name: 'worker',
  instructions: 'You complete software tasks end to end.',
  model: 'openai/gpt-5.6-sol',
  memory,
  goal: {
    judge: 'openai/gpt-5-mini',
    maxRuns: 50,
  },
})

// Set the durable objective for a thread.
await worker.setObjective('Add and test a /health endpoint', {
  threadId,
  resourceId,
})

// The objective is judged each iteration until it's complete or maxRuns is hit.
const stream = await worker.stream('Start working on the goal', {
  memory: { thread: threadId, resource: resourceId },
})
```

`goal` 設定會自動註冊狀態訊號投影，因此模型不需額外設定，就能在情境的 `<current-objective>` 中一律看到目前目的。

## 目標步驟的運作方式

目標步驟會在 Agent 執行迴圈內、緊接著 `isTaskComplete` 之後執行。遇到真正的候選答案時，它會依目的為對話評分並控制迴圈：

- **尚未達成，且仍有預算** → 迴圈繼續。系統會注入每次評估的意見回饋，讓 Agent 繼續反覆改進。
- **已達成** → 迴圈停止，目的標記為 `done`。
- **預算已耗盡**（`runsUsed >= maxRuns`）→ 迴圈停止，目的標記為 `paused`。提高 `maxRuns`，再恢復目的即可繼續。

對於背景任務、Tool 迴圈途中，以及僅限工作記憶體的反覆運算，此步驟不會執行任何操作；其控制方式與 `isTaskComplete` 相同。

**裁判模型是啟用開關。** 若無法解析出裁判（既沒有每個目的的覆寫，也沒有 Agent 的 `goal.judge`），目標步驟不會評分或消耗預算，也不會發出 `goal` 區塊。

有效設定的解析順序為：每個目的記錄的值 → Agent 的 `goal` 設定 → 內建預設值（`maxRuns` 為 `50`，以及預設裁判提示詞）。

此步驟預設使用內建的 LLM 裁判評分器，達成目的時傳回 `1`，否則傳回 `0`。若要自訂判定方式，請透過 `goal.scorer` 提供自己的評分器。

```typescript
const worker = new Agent({
  id: 'worker',
  name: 'worker',
  instructions: 'You complete software tasks end to end.',
  model: 'openai/gpt-5.6-sol',
  memory,
  goal: {
    // A resolver function lets you inject provider credentials and read the
    // current judge selection at runtime; returning `undefined` keeps the
    // goal step a no-op.
    judge: ({ requestContext }) => resolveJudgeModel(requestContext),
    maxRuns: 30,
    prompt: 'Only mark the goal complete when tests pass.',
  },
})
```

每次評估都會發出具型別的 `goal` 串流區塊（`GoalEvaluationPayload`：`objective`、`iteration`、`maxRuns`、`passed`、`status`、`results`、`reason`、`duration`、`timedOut`、`maxRunsReached`、`suppressFeedback`），讓 UI 能在執行途中顯示目標進度。

## 管理目的

使用 `Agent` 方法控制對話串的目的。若執行不是由記憶體支援，所有方法都不會執行任何操作（它們需要儲存空間及 `threadId`）：

```typescript
// Read the current objective record.
const record = await worker.getObjective({ threadId })

// Update options on the active objective (only provided fields are written;
// unset fields fall back to the agent's `goal` config).
await worker.updateObjectiveOptions({ threadId, maxRuns: 100 })

// Drop the objective.
await worker.clearObjective({ threadId })
```

目的記錄包含選用的 `activeDurationMs` 值，供使用者介面顯示主動追求目標的時間。Agent 朝作用中目的執行時，Mastra 會增加此值；執行結束或等待 Tool 核准時則建立檢查點。缺少此值代表零，而且這段時間衡量的是 Agent 執行時間，而非目標自建立以來的實際時間。

由 `setObjective` / `updateObjectiveOptions` 寫入的每個目的值優先於 Agent 的 `goal` 設定，而且此優先順序會記錄於對話串狀態。完整 goal 區塊結構請參閱 [ChunkType 參考中的 `GoalEvaluationPayload`](https://mastra.zisheng.pro/zh-TW/reference/streaming/ChunkType)。

## 相關內容

- [監督 Agent](https://mastra.zisheng.pro/zh-TW/docs/capabilities/subagents)：`isTaskComplete` 與評分規準評分器
- [訊號 Provider](https://mastra.zisheng.pro/zh-TW/docs/long-running-agents/signal-providers)：目的如何投影至情境
- [記憶體儲存空間](https://mastra.zisheng.pro/zh-TW/docs/storage/overview)：Goals 所需的儲存空間後端