跳至主要內容

目標

新增於： @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 設定，而且此優先順序會記錄於對話串狀態。完整 goal 區塊結構請參閱 ChunkType 參考中的 GoalEvaluationPayload。

On this page