メインコンテンツへ移動

Step クラス

Step クラスは、実行ロジック、データ検証、入出力処理をカプセル化し、Workflow 内の個々の処理単位を定義します。 Tool または Agent をパラメーターとして受け取り、それらからステップを自動的に作成することもできます。

使用例
使用例への直接リンク

src/mastra/workflows/test-workflow.ts
import { createWorkflow, createStep } from '@mastra/core/workflows'
import { z } from 'zod'

const step1 = createStep({
  id: 'step-1',
  description: 'passes value from input to output',
  inputSchema: z.object({
    value: z.number(),
  }),
  outputSchema: z.object({
    value: z.number(),
  }),
  execute: async ({ inputData }) => {
    const { value } = inputData
    return {
      value,
    }
  },
})

スキーマを定義する
スキーマを定義するへの直接リンク

ステップの inputSchema と outputSchema は、Standard JSON Schema をサポートする任意のライブラリで定義できます。Zod、Valibot、ArkType などのライブラリが該当します。

src/mastra/workflows/test-workflow.ts
import { createStep } from '@mastra/core/workflows'
import { z } from 'zod'

const step1 = createStep({
  id: 'step-1',
  inputSchema: z.object({
    message: z.string(),
  }),
  outputSchema: z.object({
    formatted: z.string(),
  }),
  execute: async ({ inputData }) => {
    const { message } = inputData

    return {
      formatted: message.toUpperCase(),
    }
  },
})

Agent からステップを作成する
Agent からステップを作成するへの直接リンク

Agent からステップを直接作成できます。ステップの ID には Agent の名前が使用されます。

基本的な Agent ステップ
基本的な Agent ステップへの直接リンク

src/mastra/workflows/test-workflow.ts
import { testAgent } from '../agents/test-agent'

const agentStep = createStep(testAgent)
// inputSchema: { prompt: string }
// outputSchema: { text: string }

構造化出力を使用する Agent ステップ
構造化出力を使用する Agent ステップへの直接リンク

Agent が型付きの構造化データを返すようにするには、structuredOutput を渡します。

src/mastra/workflows/test-workflow.ts
const articleSchema = z.object({
  title: z.string(),
  summary: z.string(),
  tags: z.array(z.string()),
})

const agentStep = createStep(testAgent, {
  structuredOutput: { schema: articleSchema },
})
// inputSchema: { prompt: string }
// outputSchema: { title: string, summary: string, tags: string[] }

Agent ステップのオプション
Agent ステップのオプションへの直接リンク

structuredOutput:

{ schema: StandardJSONSchemaV1 }
指定すると、Agent はプレーンテキストではなく、このスキーマに一致する構造化データを返します。ステップの outputSchema には、指定したスキーマが設定されます。

onFinish:

(result: AgentResult) => void
Agent が生成を完了したときに呼び出されるコールバック。

コンストラクターのパラメーター
コンストラクターのパラメーターへの直接リンク

id:

string
ステップの一意な識別子

description:

string
ステップの処理内容を示す任意の説明

inputSchema:

StandardJSONSchemaV1
入力構造を定義する Standard JSON Schema

outputSchema:

StandardJSONSchemaV1
出力構造を定義する Standard JSON Schema

resumeSchema:

StandardJSONSchemaV1
ステップを再開するための任意の Standard JSON Schema

suspendSchema:

StandardJSONSchemaV1
ステップを中断するための任意の Standard JSON Schema

stateSchema:

StandardJSONSchemaV1
ステップの state に使用する任意の Standard JSON Schema。Mastra の state system を使用すると自動的に挿入されます。stateSchema は Workflow の stateSchema のサブセットである必要があります。指定しない場合、型は「any」になります。

requestContextSchema:

StandardJSONSchemaV1
request context の値を検証する Standard JSON Schema。指定すると、ステップの execute() が実行される前に context が検証され、検証に失敗した場合はステップが失敗します。

execute:

(params: ExecuteParams) => Promise<any>
ステップのロジックを含む非同期関数
ExecuteParams

inputData:

z.infer<TStepInput>
inputSchema に一致する入力データ

resumeData:

z.infer<TResumeSchema>
中断状態からステップを再開するときの、resumeSchema に一致する再開データ。ステップを再開する場合にのみ存在します。

suspendData:

z.infer<TSuspendSchema>
ステップの中断時に suspend() へ渡した中断データ。ステップを再開し、かつ以前にデータを指定して中断していた場合にのみ存在します。

mastra:

Mastra
Mastra のサービス（Agent、Tool など）へのアクセス

getStepResult:

(step: Step | string) => any
ほかのステップの結果にアクセスする関数

getInitData:

() => any
任意のステップから Workflow の初期入力データにアクセスする関数

suspend:

(suspendPayload: any, suspendOptions?: { resumeLabel?: string }) => Promise<void>
Workflow の実行を一時停止する関数

state:

z.infer<TState>
現在の Workflow state。すべてのステップと中断／再開サイクルで保持される共有値が含まれます。構造はステップの stateSchema で定義されます。

setState:

(state: z.infer<TState>) => void
Workflow の state を設定する関数。'setState({ ...state, ...newState })' のように reducer 形式で挿入します

runId:

string
現在の Run ID

requestContext?:

RequestContext
依存性注入とコンテキスト情報に使用する Request Context。

retryCount?:

number
このステップ固有の再試行回数。ステップが再試行されるたびに自動的に増加します

scorers:

MastraScorers | (({ requestContext }) => MastraScorers | Promise<MastraScorers>)
ステップが正常に完了した後に自動実行される Scorer。各 Scorer はステップ自身の入力と出力を評価し、結果は保存されてステップの trace に付加されます。{ [name]: { scorer, sampling? } } のマップ、またはこのマップを返す関数を指定します。スコアリングは非同期で実行され、Workflow をブロックしません。ステップ出力をスコアリングするを参照してください。

retries:

number
ステップの execute 関数が例外をスローした場合の再試行回数。

metadata:

Record<string, any>
追加のステップ情報を保存する任意のキーと値のペア。値はシリアライズ可能である必要があります（関数、循環参照などは使用できません）。

ステップ出力をスコアリングする
ステップ出力をスコアリングするへの直接リンク

scorers をステップに付加すると、Workflow の最終回答だけをスコアリングするのではなく、ステップの実行時にその出力を自動的に評価できます。複数ステップの Workflow や RAG Workflow で品質が低下したステップを特定したい場合に役立ちます。たとえば、後続のステップが取得結果について推論する前に、取得ステップが関連性のあるチャンクを返したかどうかを確認できます。

各 Scorer は、そのステップ自身の input と output を受け取ります。スコアリングはステップが成功した後に非同期で実行され、結果はそのステップの trace に保存されます。Scorer の実行頻度を制御するには sampling を使用します。

次の例では、すべての実行がスコアリングされるよう、取得ステップに Scorer を付加します。

src/mastra/workflows/rag-workflow.ts
import { createStep } from '@mastra/core/workflows'
import { z } from 'zod'
import { retrievalRelevanceScorer } from '../scorers/retrieval-relevance'

const retrievalStep = createStep({
  id: 'retrieval',
  inputSchema: z.object({ query: z.string() }),
  outputSchema: z.object({ query: z.string(), chunks: z.array(z.string()) }),
  scorers: {
    retrievalRelevance: {
      scorer: retrievalRelevanceScorer(),
      sampling: { type: 'ratio', rate: 1 },
    },
  },
  execute: async ({ inputData }) => {
    const chunks = await retrieve(inputData.query)
    return { query: inputData.query, chunks }
  },
})

測定する各ステップに Scorer を付加すると、複数ステップの Workflow 全体でステップ単位のスコアを構築できます。スコアリングの対象は 1 つのステップに限定されるため、品質の変化箇所を確認するためにステップをまたぐ専用の指標を用意する必要はありません。

Workflow.agent() と Workflow.tool() で追加した Agent ステップと Tool ステップも、ステップオプションで同じ scorers オプションを受け取ります。

注記

Scorer の概要では live evaluation の実行方法と結果の保存場所を、カスタム Scorerでは独自の Scorer の構築方法を確認できます。

On this page