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

# Step クラス

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

## 使用例

```typescript
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](https://standardschema.dev/json-schema) をサポートする任意のライブラリで定義できます。[Zod](https://zod.dev/)、[Valibot](https://valibot.dev/)、[ArkType](https://arktype.io/) などのライブラリが該当します。

**Zod**:

```typescript
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(),
    }
  },
})
```

**Valibot**:

```typescript
import { createStep } from '@mastra/core/workflows'
import * as v from 'valibot'
import { toStandardJsonSchema } from '@valibot/to-json-schema'

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

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

**ArkType**:

```typescript
import { createStep } from '@mastra/core/workflows'
import { type } from 'arktype'

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

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

## Agent からステップを作成する

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

### 基本的な Agent ステップ

```typescript
import { testAgent } from '../agents/test-agent'

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

### 構造化出力を使用する Agent ステップ

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

```typescript
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 ステップのオプション

**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>`): ステップのロジックを含む非同期関数

**execute.inputData** (`z.infer<TStepInput>`): inputSchema に一致する入力データ

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

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

**execute.mastra** (`Mastra`): Mastra のサービス（Agent、Tool など）へのアクセス

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

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

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

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

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

**execute.runId** (`string`): 現在の Run ID

**execute.requestContext** (`RequestContext`): 依存性注入とコンテキスト情報に使用する Request Context。

**execute.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 を付加します。

```typescript
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()`](https://mastra.zisheng.pro/ja/reference/workflows/workflow-methods/agent) と [`Workflow.tool()`](https://mastra.zisheng.pro/ja/reference/workflows/workflow-methods/tool) で追加した Agent ステップと Tool ステップも、ステップオプションで同じ `scorers` オプションを受け取ります。

> **注記:** [Scorer の概要](https://mastra.zisheng.pro/ja/docs/evals/overview)では live evaluation の実行方法と結果の保存場所を、[カスタム Scorer](https://mastra.zisheng.pro/ja/docs/evals/custom-scorers)では独自の Scorer の構築方法を確認できます。

## 関連項目

- [Workflow state](https://mastra.zisheng.pro/ja/docs/workflows/workflow-state)
- [制御フロー](https://mastra.zisheng.pro/ja/docs/workflows/control-flow)
- [Agent と Tool を使用する](https://mastra.zisheng.pro/ja/docs/workflows/agents-and-tools)