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

# 目标

**加入版本：** `@mastra/core@1.42.0`

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

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

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

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

## 何时使用 Goal

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

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

对于单次 `stream()` 调用内的一次性完成检查，请改用 [`isTaskComplete`](https://mastra.zisheng.pro/docs/capabilities/subagents)。

## 快速入门

Goal 需要已配置的 [Storage](https://mastra.zisheng.pro/docs/storage/overview) 后端和由 Memory 支持的 thread。向 Agent 添加 `goal` 配置；Goal 必须使用 judge 模型才会生效。然后为 thread 设置目标：

```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` 配置会自动注册 state-signal projection，因此模型无需额外设置，便能始终在上下文中以 `<current-objective>` 看到当前目标。

## 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，定制评判方式。

```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` stream chunk（`GoalEvaluationPayload`：`objective`、`iteration`、`maxRuns`、`passed`、`status`、`results`、`reason`、`duration`、`timedOut`、`maxRunsReached`、`suppressFeedback`），因此 UI 可以在运行期间显示 Goal 进度。

## 管理目标

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

通过 `setObjective` / `updateObjectiveOptions` 写入的按目标值优先于 Agent 的 `goal` 配置，并且该优先级会记录在 thread 状态中。有关 Goal chunk 的完整结构，请参阅 [ChunkType Reference 中的 `GoalEvaluationPayload`](https://mastra.zisheng.pro/reference/streaming/ChunkType)。

## 相关内容

- [Supervisor Agent](https://mastra.zisheng.pro/docs/capabilities/subagents)：`isTaskComplete` 和 rubric Scorer
- [Signal Provider](https://mastra.zisheng.pro/docs/long-running-agents/signal-providers)：如何将目标投射到上下文中
- [Memory Storage](https://mastra.zisheng.pro/docs/storage/overview)：Goal 所需的 Storage 后端