> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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,
    }
  },
})
```

## 定義 schema

你可以使用任何支援 [Standard JSON Schema](https://standardschema.dev/json-schema) 的程式庫，定義步驟的 `inputSchema` 與 `outputSchema`。包括 [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 建立步驟。此步驟會使用 Agent 的名稱作為 ID。

### 基本 Agent 步驟

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

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

### 具有結構化輸出的 Agent 步驟

傳入 `structuredOutput`，讓 Agent 回傳具有型別的結構化資料：

```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 會回傳符合此 schema 的結構化資料，而不是純文字。步驟的 outputSchema 會設為提供的 schema。

**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`): 步驟狀態的選用 Standard JSON Schema。使用 Mastra 的狀態系統時會自動注入。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 狀態。包含所有步驟與暫停／繼續週期之間持續保存的共用值。結構由步驟的 stateSchema 定義。

**execute.setState** (`(state: z.infer<TState>) => void`): 設定 Workflow 狀態的函式。請透過類似 reducer 的模式注入，例如 'setState({ ...state, ...newState })'

**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>`): 用來儲存其他步驟資訊的選用 key-value 配對。值必須可以序列化（不可包含函式、循環參照等）。

## 為步驟輸出評分

將 `scorers` 附加至步驟，即可在步驟執行時自動評估該步驟的輸出，而不只對 Workflow 的最終答案評分。這對多步驟及 RAG Workflow 很實用，因為你能看出是哪個步驟降低品質，例如檢索步驟是否在後續步驟推理前回傳了相關區塊。

每個 scorer 都會收到步驟本身的 `input` 與 `output`。評分會在步驟成功後以非同步方式執行，結果則會儲存在步驟的 Trace 中。使用 `sampling` 控制 scorer 的執行頻率。

下列範例將 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 中建立逐步分數。由於評分範圍限於單一步驟，因此不需要專門的跨步驟指標，也能看出品質在哪裡發生變化。

透過 [`Workflow.agent()`](https://mastra.zisheng.pro/zh-TW/reference/workflows/workflow-methods/agent) 與 [`Workflow.tool()`](https://mastra.zisheng.pro/zh-TW/reference/workflows/workflow-methods/tool) 新增的 Agent 和 Tool 步驟，也能在其步驟選項中接受相同的 `scorers` 選項。

> **備註:** 請參閱 [Scorer 概觀](https://mastra.zisheng.pro/zh-TW/docs/evals/overview)，瞭解即時評估如何執行及結果的儲存位置；另請參閱[自訂 scorer](https://mastra.zisheng.pro/zh-TW/docs/evals/custom-scorers)，瞭解如何自行建立 scorer。

## 相關內容

- [Workflow 狀態](https://mastra.zisheng.pro/zh-TW/docs/workflows/workflow-state)
- [控制流程](https://mastra.zisheng.pro/zh-TW/docs/workflows/control-flow)
- [使用 Agent 與 Tool](https://mastra.zisheng.pro/zh-TW/docs/workflows/agents-and-tools)