Goals

新增于： @mastra/core@1.43.0

Goal 是一个持久化、thread 作用域的目标：一条常驻指令，agent 会跨越多个循环迭代持续朝它努力，直到 judge 模型判定目标已满足，或运行预算耗尽。

目标持久化在 thread 状态中，因此它能在重新加载后保留，并在循环内被评估，即使新消息在一轮已经运行的对话中途到达。

Goals 构建在与 isTaskComplete 相同的机制之上：LLM-as-judge 在每次迭代对 agent 的输出评分并控制循环。区别在于 goal 是持久化的（存储在 thread 状态中，而不是每次调用传入），并通过 Agent 方法而不是每次 stream() 选项来设置和更新。

何时使用 goals

当你希望 agent 在多个迭代和消息之间持续朝着单一目标努力，而无需每次调用都重新提供成功标准时，请使用 goal：

• agent 应追求的常驻目标，直到 judge 判定完成。
• 应在运行中途消息之间持续的工作（在正在运行的 run 中投递的消息仍会依据 goal 进行评估）。
• 必须在 thread 重新加载或进程重启后仍然保留的目标。

如果只是一次 stream() 调用内的一次性完成检查，请改用 isTaskComplete。

快速开始

Goals 需要已配置的存储后端和由 memory 支撑的 thread。为 agent 添加 goal 配置（judge 模型是 goal 生效所必需的），然后为 thread 设置目标：

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 配置会自动注册状态 signal 投影，因此模型总能在上下文中以 <current-objective> 看到当前目标，无需额外设置。

goal 步骤如何工作

goal 步骤在 agentic 执行循环内运行，紧跟在 isTaskComplete 之后。对于真实的候选答案，它会根据目标对对话评分并控制循环：

• 未满足且预算剩余 → 循环继续。系统会注入每次评估的反馈，促使 agent 迭代。
• 已满足 → 循环停止，目标被标记为 done。
• 预算耗尽（runsUsed >= maxRuns）→ 循环停止，目标被标记为 paused。提高 maxRuns，然后恢复目标以继续。

对于后台任务、工具循环中途以及仅涉及工作记忆的迭代，该步骤不执行任何操作，与 isTaskComplete 的 gating 相同。

每次评估会发出一个带类型的 goal 流 chunk（GoalEvaluationPayload：objective、iteration、maxRuns、passed、status、results、reason、duration、timedOut、maxRunsReached、suppressFeedback），以便 UI 在运行中途显示目标进度。

judge 模型是激活开关。 如果无法解析 judge（无论是每个目标的覆盖配置还是 agent 的 goal.judge），goal 步骤不会评分、不会消耗预算，也不会发出 goal chunk。该 gate 覆盖所有 scorer：Mastra 在选择 scorer 之前会先检查它，因此自定义 goal.scorer 仍然需要能解析出 judge。

生效设置的解析顺序为：每个目标的记录值，然后是 agent goal 配置，最后是内置默认值（maxRuns 为 50，以及默认 judge 提示词）。

Judge 与 scorer

goal.judge 和 goal.scorer 工作在不同层级。goal.scorer 是产生循环所依据分数的评估流水线。goal.judge 是默认流水线为得到该分数所调用的模型。

省略 scorer 时，Mastra 会构建一个默认的 LLM-as-judge scorer：目标达成时返回 1，否则返回 0。使用以下设置配置它：

• goal.judge：决定目标是否满足的模型。
• goal.prompt：给 judge 的额外指令。默认为内置的 goal judge 提示词。
• goal.tools：judge 在做出决定前可调用的只读验证工具，使其能够确认工作，而不是仅评估 agent 的文本。
• goal.maxSteps：judge 自身 agentic 循环的步骤预算。默认为 5。

传入 goal.scorer 可用你自己的 scorer替换该流水线，既可以是 scorer 实例，也可以是已注册的 scorer id。自定义 scorer 自带评判逻辑，因此 goal.prompt、goal.tools 和 goal.maxSteps 不再适用，Mastra 也不再为评判解析 judge 模型。goal.judge 的 resolver 函数仍会运行，但其返回值会被丢弃。

使用 judge、maxRuns 和 prompt 配置默认 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.',
  },
})

若要把决定权交给自己的 scorer，请将其作为 scorer 传入，并保持设置 judge，因为激活 gate 仍然适用：

goal: {
  judge: 'openai/gpt-5-mini',
  // Replaces the built-in judge pipeline. `prompt`, `tools`, and `maxSteps` no longer apply.
  scorer: 'tests-pass',
}

管理目标

使用 Agent 方法控制 thread 的目标。当运行不是由 memory 支撑时（它们需要存储和 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 会推进该值，并在运行结束或等待工具审批时对其做检查点。缺失值表示零，该时长衡量的是 agent 执行时间，而不是 goal 的实际日历年龄。

由 setObjective / updateObjectiveOptions 写入的每个目标值优先于 agent 的 goal 配置，且这一优先级会记录在 thread 状态中。完整的 goal chunk 结构请参阅 ChunkType 参考中的 GoalEvaluationPayload。

相关内容

• Supervisor agents：isTaskComplete 和 rubric scorer
• Signal providers：目标如何投影到上下文中
• Memory 存储：goals 所需的存储后端
• Mastra Factory 和 Mastra Code：目标驱动的编码 agent 示例