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

# Workflow\.agent()

`.agent()` メソッドは、Agent を宣言的なステップとして追加します。このステップは入力として `{ prompt: string }` を受け取り、デフォルトでは `{ text: string }` を返します。Workflow のデータからプロンプトを構築するには、Agent の前に `.map()` を使用します。

Agent を `createStep()` でラップする場合とは異なり、`.agent()` は Workflow グラフに宣言的なエントリを記録します。これにより Workflow は移植可能になり、同じグラフをシリアライズして[動的 Workflow](https://mastra.zisheng.pro/ja/docs/workflows/dynamic-workflows) として永続化できます。

## 使用例

```typescript
workflow
  .map({ prompt: mapVariable({ initData: workflow, path: "topic" }) })
  .agent(testAgent)
  .commit();
```

## パラメーター

**agentOrId** (`Agent | string`): Agent インスタンス、または Mastra インスタンスに登録されている Agent の ID。ID を渡した場合、実行時にレジストリから Agent が解決されます。

**options** (`AgentStepOptions & { structuredOutput?: { schema }, retries?: number, scorers?: DynamicArgument<MastraScorers>, metadata?: StepMetadata }`): maxSteps、modelSettings、memory、providerOptions などの Agent 呼び出しオプションに加え、ステップレベルの retries、scorers、metadata を指定します。requestContext、resourceId、threadId、onStepFinish など、リクエスト単位のフィールドは Workflow エンジンによって管理されるため、対象外です。

**stepOptions** (`{ id?: string }`): Workflow 内でのステップの呼び出し位置 ID。デフォルトは Agent の ID です。同じ Workflow 内に同じ Agent が複数回登場する場合に設定します。

## 戻り値

**workflow** (`Workflow`): メソッドチェーンに使用する Workflow インスタンス

## 構造化出力

デフォルトでは、このステップの出力は `{ text: string }` です。ステップから別の形式を返すには、`structuredOutput.schema` を渡します。このスキーマがステップの出力スキーマになるため、後続のステップへ完全な型安全性を保ったままチェーンできます。

```typescript
workflow
  .agent(testAgent, {
    structuredOutput: {
      schema: z.object({
        subtopics: z.array(z.string()),
      }),
    },
  })
  .commit();
```

## ID で Agent を参照する

登録済みの Agent をインポートせずに参照するには、文字列を渡します。Workflow の実行時に、その Agent が Mastra インスタンスへ登録されている必要があります。

```typescript
workflow.agent("test-agent", { maxSteps: 3 }).commit();
```

## Agent ステップを永続化する

`.agent()` で構築した Workflow は、[動的 Workflow](https://mastra.zisheng.pro/ja/docs/workflows/dynamic-workflows) が使用するものと同じ宣言的なエントリにシリアライズされます。保存と復元の間で維持されるのは `retries` と `metadata` のみです。`onFinish` や関数値の `toolChoice` など、関数を保持するオプションがある場合、Workflow の保存時にエラーがスローされます。

## 関連項目

- [Agent と Tool](https://mastra.zisheng.pro/ja/docs/workflows/agents-and-tools)
- [動的 Workflow](https://mastra.zisheng.pro/ja/docs/workflows/dynamic-workflows)
- [Workflow.tool()](https://mastra.zisheng.pro/ja/reference/workflows/workflow-methods/tool)