跳到主要内容

目标

加入版本： @mastra/core@1.42.0

beta

Goals 功能目前处于 beta 阶段，在脱离 beta 状态前，minor 版本中可能包含破坏性变更。

Goal 是限定于 thread 的持久目标：Agent 会在多次循环迭代中持续执行这项长期指令，直到 judge 模型判定目标已满足，或运行预算耗尽。

该目标会持久化到 thread 状态中，因此可在重新加载后保留，并在循环内接受评估，即使新的消息在已经运行的轮次中途到达也不例外。

Goal 建立在与 isTaskComplete 相同的机制之上：作为 judge 的 LLM 会在每次迭代时评估 Agent 的输出，并据此控制循环。区别在于，Goal 是持久的（存储在线程状态中，而不是按调用传递），并且通过 Agent 方法设置和更新，而不是通过每次 stream() 的选项来设置。

何时使用 Goal
何时使用 Goal的直接链接

如果希望 Agent 在多次迭代和多条消息中持续朝单一目标工作，而不必每次调用都重新提供成功标准，请使用 Goal：

  • Agent 应持续推进的长期目标，直到 judge 判定它已完成。
  • 应在运行中途收到消息后继续进行的工作（传入活跃运行的消息仍会依据 Goal 进行评判）。
  • 必须在 thread 重新加载或进程重启后继续保留的目标。

对于单次 stream() 调用内的一次性完成检查，请改用 isTaskComplete。

快速入门
快速入门的直接链接

Goal 需要已配置的 Storage 后端和由 Memory 支持的 thread。向 Agent 添加 goal 配置；Goal 必须使用 judge 模型才会生效。然后为 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 配置会自动注册 state-signal projection，因此模型无需额外设置，便能始终在上下文中以 <current-objective> 看到当前目标。

Goal 步骤的工作原理
Goal 步骤的工作原理的直接链接

Goal 步骤在 Agent 执行循环内部运行，位置紧随 isTaskComplete。当出现真正的候选答案时，它会依据目标评估对话并控制循环：

  • 未满足且仍有预算 → 循环继续。系统会注入每次评估的反馈，让 Agent 继续迭代。
  • 已满足 → 循环停止，目标标记为 done。
  • 预算耗尽（runsUsed >= maxRuns）→ 循环停止，目标标记为 paused。提高 maxRuns，然后恢复目标即可继续。

与 isTaskComplete 的控制逻辑相同，对于后台任务、Tool 循环中途以及仅更新 working memory 的迭代，此步骤不会执行任何操作。

Judge 模型是激活开关。 如果无法解析到 judge（无论是按目标覆盖的配置，还是 Agent 的 goal.judge），Goal 步骤都不会执行评分或消耗预算，也不会发出 goal chunk。

有效设置按以下顺序解析：按目标记录的值 → Agent goal 配置 → 内置默认值（maxRuns 为 50，以及默认 judge prompt）。

默认情况下，该步骤使用内置的 LLM-as-judge Scorer：目标达成时返回 1，否则返回 0。可以通过 goal.scorer 提供自定义 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 stream chunk（GoalEvaluationPayload：objective、iteration、maxRuns、passed、status、results、reason、duration、timedOut、maxRunsReached、suppressFeedback），因此 UI 可以在运行期间显示 Goal 进度。

管理目标
管理目标的直接链接

使用 Agent 方法控制 thread 的目标。当运行并非由 Memory 支持时，这些方法都不会执行任何操作（它们需要 Storage 和 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 值，供 UI 显示主动推进目标所用的时间。Agent 朝活跃目标运行时，Mastra 会增加该值，并在运行结束或等待 Tool 审批时保存 checkpoint。缺失值表示零，且该时长衡量的是 Agent 执行时间，而不是 Goal 已存在的实际时间。

通过 setObjective / updateObjectiveOptions 写入的按目标值优先于 Agent 的 goal 配置，并且该优先级会记录在 thread 状态中。有关 Goal chunk 的完整结构，请参阅 ChunkType Reference 中的 GoalEvaluationPayload。

On this page