본문으로 건너뛰기

목표

추가된 항목: @mastra/core@1.42.0

:::실험적

목표 기능은 베타 단계에 있으며 베타 상태가 종료될 때까지 부 버전에서 주요 변경 사항이 적용됩니다.

:::

목표는 내구성이 있는 스레드 범위의 목표입니다. 즉, 판사 Model이 만족했다고 결정하거나 실행 예산이 소진될 때까지 Agent가 루프 반복을 통해 계속 작업하는 지속적인 명령입니다.

목표는 스레드 상태에서 유지되므로 이미 실행 중인 차례 도중에 새 메시지가 도착하는 경우에도 재로드 후에도 유지되고 루프 내에서 평가됩니다.

목표는 목표와 동일한 기계를 기반으로 구축됩니다.isTaskComplete: LLM-as-judge가 각 iteration에서 Agent의 출력을 채점하고 루프 진행 여부를 제어합니다. 차이점은 goal이 durable 이며, 호출마다 전달되는 것이 아니라 thread 상태에 저장되고 다음을 통해 설정 및 업데이트된다는 점입니다: Agent methods rather than per-stream() options.

목표를 사용해야 하는 경우
목표를 사용해야 하는 경우에 대한 직접 링크

모든 호출에 성공 기준을 다시 제공하지 않고 Agent가 여러 반복 및 메시지에서 단일 목표를 향해 계속 작업하도록 하려는 경우 목표를 사용합니다.

  • 판사가 완료했다고 말할 때까지 Agent가 추구해야 하는 지속적인 목표입니다.
  • 중간 실행 메시지에서 계속되어야 하는 작업(실시간 실행으로 전달된 메시지는 여전히 목표에 대해 판단됩니다).
  • 스레드를 다시 로드하거나 프로세스를 다시 시작해도 지속되어야 하는 목표입니다.

단일 내에서 일회성 완료 확인을 위해stream() call, use isTaskComplete instead.

빠른 시작
빠른 시작에 대한 직접 링크

목표에는 구성이 필요합니다.storage backend and a memory-backed thread. Add a goal config를 Agent에 전달하세요. goal이 작동하려면 judge Model이 필요하며, 그런 다음 thread의 objective를 설정합니다:

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 config는 state-signal projection을 자동으로 등록하므로 Model은 현재 objective를 항상 다음과 같이 확인합니다: <current-objective> in its context without extra setup.

목표 단계의 작동 방식
목표 단계의 작동 방식에 대한 직접 링크

목표 단계는 Agent 실행 루프 내에서 바로 실행됩니다.isTaskComplete. 실제 candidate answer에서는 objective를 기준으로 conversation을 채점하고 루프 진행 여부를 제어합니다:

  • 만족하지 않음, 예산이 남음→ 루프가 계속됩니다. 평가별 피드백이 주입되어 Agent가 반복됩니다.
  • 만족하는→ 루프가 중지되고 목표가 표시됩니다.done.
  • 예산 소진 (runsUsed >= maxRuns) → the loop stops and the objective is marked paused. Raise maxRuns, then resume the objective to continue.

이 단계는 다음과 동일한 게이팅인 백그라운드 작업, 중간 Tool 루프 및 작업 Memory 전용 반복에 대해 무작동입니다.isTaskComplete.

판사 Model은 활성화 스위치입니다.심판이 해결하지 못한 경우(목표별 재정의나 Agent의 결정 모두)goal.judge)이면 goal 단계는 채점하거나 budget을 소비하지 않으며 다음을 내보내지도 않습니다: goal chunk.

효과적인 설정은 목표별 기록 값으로 결정 → Agentgoal config → built-in default (maxRuns 50, a default judge prompt).

기본적으로 이 단계에서는 다음을 반환하는 내장된 LLM-as-judge 채점기를 사용합니다.1 when the objective is achieved and 0 otherwise. Supply your own scorer with goal.scorer to customize judging.

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) so a UI can show goal progress mid-run.

목표 관리
목표 관리에 대한 직접 링크

다음을 사용하여 스레드의 목표를 제어합니다.Agent methods입니다. 실행이 Memory 기반이 아니면 모두 아무 작업도 하지 않습니다. 이 methods에는 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 값은 활성 추구 시간을 표시하는 user interfaces에 사용됩니다. Mastra는 Agent가 활성 objective를 향해 실행되는 동안 이 값을 증가시키고, 실행이 종료되거나 Tool 승인을 기다릴 때 checkpoint합니다. 값이 없으면 0을 의미하며, 이 duration은 goal이 생성된 후 실제로 흐른 시간이 아니라 Agent 실행 시간을 측정합니다.

목표별 값은 다음에 의해 작성됩니다.setObjective / updateObjectiveOptions take precedence over the agent's goal config가 우선하며, 해당 우선순위는 thread 상태에 저장됩니다. 다음을 참조하세요: GoalEvaluationPayload in the ChunkType reference for the full goal chunk shape.

On this page