メインコンテンツへ移動

Goal

追加バージョン： @mastra/core@1.42.0

beta

Goals 機能はベータ段階です。ベータを終了するまでは、マイナーバージョンで破壊的変更が行われる可能性があります。

Goal は、スレッド単位で永続化される目標です。判定モデルが達成済みと判断するか、実行予算を使い切るまで、Agent がループの反復をまたいで取り組み続ける常設の指示として機能します。

目標はスレッドの状態に保存されるため、再読み込み後も維持されます。また、実行中のターンの途中で新しいメッセージが届いた場合でも、ループ内で評価されます。

Goals は isTaskComplete と同じ仕組みを基盤にしています。LLM-as-judge が反復ごとに Agent の出力を採点し、ループを継続するかどうかを制御します。違いは、Goal が永続的であり（呼び出しごとに渡すのではなくスレッドの状態に保存される）、stream() ごとのオプションではなく Agent のメソッドで設定、更新される点です。

Goal を使用する場面
Goal を使用する場面への直接リンク

成功条件を呼び出しのたびに指定し直すことなく、多数の反復やメッセージをまたいで Agent に単一の目標へ取り組ませたい場合に Goal を使用します。

  • 判定モデルが完了と判断するまで Agent が追求すべき常設の目標。
  • 実行途中のメッセージをまたいで継続すべき処理（実行中の処理に届いたメッセージも、引き続き Goal に照らして判定されます）。
  • スレッドの再読み込みやプロセスの再起動後も維持する必要がある目標。

単一の stream() 呼び出し内で一度だけ完了判定を行う場合は、代わりに isTaskComplete を使用します。

クイックスタート
クイックスタートへの直接リンク

Goals には、設定済みのストレージバックエンドと Memory によって管理されるスレッドが必要です。Agent に goal 設定を追加し、スレッドの目標を設定します。Goal を機能させるには判定モデルが必要です。

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 のみの反復では何も行いません。

判定モデルが有効化スイッチです。 目標ごとのオーバーライドと Agent の goal.judge のどちらからも判定モデルを解決できない場合、Goal ステップは採点も予算の消費も行わず、goal チャンクも出力しません。

有効な設定は、目標ごとのレコード値 → Agent の goal 設定 → 組み込みのデフォルト（maxRuns は 50、判定プロンプトはデフォルト値）の順で解決されます。

デフォルトでは、目標が達成されていれば 1、そうでなければ 0 を返す組み込みの LLM-as-judge Scorer を使用します。判定をカスタマイズするには、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 ストリームチャンク（GoalEvaluationPayload：objective、iteration、maxRuns、passed、status、results、reason、duration、timedOut、maxRunsReached、suppressFeedback）が出力されるため、UI で実行途中の Goal の進捗を表示できます。

目標を管理する
目標を管理するへの直接リンク

Agent のメソッドを使用してスレッドの目標を制御します。実行が 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 })

目標レコードには、実際に取り組んだ時間を表示する UI 向けに、任意の activeDurationMs 値が含まれます。Mastra は Agent がアクティブな目標に取り組んでいる間にこの値を増加させ、実行の終了時または Tool の承認待ちになった時点でチェックポイントを保存します。値がない場合はゼロを表し、この時間は Goal が作成されてからの経過時間ではなく Agent の実行時間を測定します。

setObjective / updateObjectiveOptions で設定した目標ごとの値は Agent の goal 設定より優先され、その優先関係はスレッドの状態に保存されます。Goal チャンクの完全な形式については、ChunkType リファレンスの GoalEvaluationPayloadを参照してください。

On this page