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

# 目標

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

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

目標是一個持久、限定於執行緒的目的：這是一項長期指示，Agent 會跨越多次循環反覆執行，直至評判模型判定已達成目標，或運行預算已耗盡。

該目的會持久保存於執行緒狀態，因此即使重新載入仍會保留，並在循環內接受評估；即使新訊息在已運行輪次的中途送達，亦不受影響。

Goals 建基於與 [`isTaskComplete`](https://mastra.zisheng.pro/zh-HK/docs/capabilities/subagents) 相同的機制：LLM 評判器會在每次反覆執行時為 Agent 輸出評分，並以此控制循環。兩者的分別在於目標是**持久的**（儲存在執行緒狀態，而非每次呼叫時傳入），而且是透過 `Agent` 方法設定及更新，而非使用每次 `stream()` 呼叫的選項。

## 何時使用目標

如果你希望 Agent 跨越多次反覆執行及多個訊息，持續朝單一目的工作，而不必在每次呼叫時重新提供成功準則，便可使用目標：

- Agent 應持續追求的長期目的，直至評判器判定已完成。
- 應在運行途中收到訊息後繼續進行的工作（傳送到現行運行的訊息，仍會依照目標接受評判）。
- 必須在重新載入執行緒或重新啟動程序後保留的目的。

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

## 快速開始

Goals 需要已設定的[儲存空間](https://mastra.zisheng.pro/zh-HK/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` 設定，而且此優先次序會記錄於執行緒狀態。請參閱 [ChunkType 參考資料中的 `GoalEvaluationPayload`](https://mastra.zisheng.pro/zh-HK/reference/streaming/ChunkType)，了解完整的目標區塊結構。

## 相關內容

- [Supervisor Agent](https://mastra.zisheng.pro/zh-HK/docs/capabilities/subagents)：`isTaskComplete` 及準則評分器
- [訊號 Provider](https://mastra.zisheng.pro/zh-HK/docs/long-running-agents/signal-providers)：如何將目的投影至上下文
- [記憶體儲存空間](https://mastra.zisheng.pro/zh-HK/docs/storage/overview)：Goals 所需的儲存後端