跳至主要內容

目標

新增於： @mastra/core@1.42.0

beta

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

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

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

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

何時使用目標
何時使用目標 的直接連結

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

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

如果只需在單次 stream() 呼叫內進行一次完成狀態檢查，請改用 isTaskComplete。

快速開始
快速開始 的直接連結

Goals 需要已設定的儲存空間後端，以及由記憶體功能支援的執行緒。將 goal 設定加入 Agent；目標必須有評判模型才會發揮作用。然後為執行緒設定目的：

src/mastra/agents/worker.ts
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 提供自己的評分器。

src/mastra/agents/worker.ts
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）：

src/mastra/objective.ts
// 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，了解完整的目標區塊結構。

On this page