> For the complete documentation index, see [llms.txt](https://help.genesis.autify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.genesis.autify.com/features-ja/workflow/ai-agent-block.md).

# AIエージェントブロック

本記事では、Autify Genesis の AI エージェントブロックの設定と操作方法について説明します。AI エージェントブロックは、LLM（大規模言語モデル）を使用してテキストや構造化されたデータを生成するワークフローの基本単位です。

## 基本設定

ブロックをクリックすると、右側のインスペクターに **詳細** タブが表示されます。以下の項目を設定します。

| 設定項目             | 内容                                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------- |
| 名前               | ブロックの表示名。キャンバス上やインスペクターに表示されます                                                              |
| 説明               | ブロックの役割や処理内容の補足説明                                                                           |
| プロンプト            | AI エージェントに実行させる内容を記述します。ユーザー入力や明示的に設定した入力は `{{変数名}}` で参照でき、接続した上流ブロックの出力は自動でコンテキストとして渡されます。 |
| 出力をアーティファクトとして保存 | 有効にすると、このブロックの出力がダウンロード可能なアーティファクトとして保存されます。                                                |
| レビュー必須           | 有効にすると、このブロックの実行後に処理が一時停止し、手動承認を待ちます。                                                       |
| モデル              | 使用する AI モデルを選択します。プロバイダーごとに複数のモデルから選択できます。                                                  |

## プロンプトの書き方

プロンプトでは、ユーザー入力を `{{変数名}}` で参照する方法と、接続した上流ブロックの出力を自動コンテキストとして使う方法があります。

### ユーザー入力を変数で参照する

プロンプト内で `{{変数名}}` の形式を使用すると、ワークフロー実行時のユーザー入力や、このブロックに明示的に設定した入力を参照できます。

変数を挿入するには、プロンプトエディター上部の **{}変数** をクリックして変数挿入メニューを開きます。変数メニューには、設定内容に応じて以下の種類が表示されます。

| 変数の種類  | 内容                        | 参照形式の例               |
| ------ | ------------------------- | -------------------- |
| 入力     | このブロックに定義された入力変数          | `{{input_key}}`      |
| コンテキスト | ワークフロー実行時にユーザーが指定するユーザー入力 | `{{my_input}}`       |
| ブロック出力 | 明示的に入力として追加した他ブロックの出力     | `{{previous_block}}` |

他ブロックの出力を自動コンテキストとして使うだけなら、変数を挿入しなくてもかまいません。

{% hint style="warning" %}
プロンプト内で参照している変数がブロックの入力に定義されていない場合、検証エラーが発生します。変数挿入メニューを使用すると、利用可能な変数の選択画面が表示されます。
{% endhint %}

### 接続した上流ブロックの出力を参照する

キャンバスでこのブロックに接続した上流ブロックの出力は、実行時に自動でコンテキストとして渡されます。上流出力を使うために、毎回 `{{変数名}}` を手動で挿入する必要はありません。

接続がある場合、プロンプト欄の下に利用可能な接続ブロック数とブロック名が表示されます。ここに表示されたブロックの出力を前提にプロンプトを書きます。

### ファイル・フォルダ・スキルを参照する

ワークスペース内のファイル、フォルダ、スキルをプロンプトに直接挿入し、実行時のコンテキストとして利用できます。

#### ファイルとフォルダ

1. プロンプトエディター上部の **ファイルを追加** をクリックして、ファイルブラウザを開きます。
2. ファイルを検索したり、フォルダをたどったりして、挿入したいファイルやフォルダを選択します。
3. 選択した項目を追加すると、プロンプトに参照が挿入されます。
4. 特定バージョンのファイルを参照したい場合は、プロンプト内で `@` を入力し、ファイル名の横のメニューから対象バージョンを選択します。

フォルダを参照すると、そのフォルダ内のファイルも AI エージェントが実行時に確認できます。

プロジェクトのファイル参照とフォルダ参照は、内部 ID をもとに実行時に解決し直されます。プロンプトを書いたあとに対象を移動したり名前を変えたりしても、ワークフロー実行時には現在の `/project/files/...` パスに自動で追従します。

AI エージェントは、チャットやワークフローの実行中にプロジェクトファイルを新規作成したり、既存のテキストファイルを直接編集したりすることもできます。作成や編集に対応しているのは Markdown、テキスト、JSON、HTML の各ファイルです。エージェントが先にサンドボックス内でファイルを作った場合でも、実行中にそのファイルをプロジェクトのファイルエクスプローラーへ保存できます。

実行が完了すると、エージェントが書き込んだファイルはチャットヘッダーやワークフロー実行詳細に表示され、そこから直接開けます。

#### スキル

スキルは、ワークスペースにアップロードした `SKILL.md` ファイルや、接続したコードベースから見つかる再利用可能な指示セットです。

1. プロンプトエディター上部の **スキルを追加** をクリックするか、プロンプト内で新しいトークンの先頭に `/` を入力します。
2. 使いたいスキルを検索します。
3. 一覧からスキルを選択します。
4. プロンプトに `/skill-name` として挿入されます。

ワークスペースのスキルモードが **自動** の場合、AI エージェントは関連するスキルを自動で選ぶこともできます。 `/skill-name` を明示すると、そのプロンプトには必ずそのスキルが適用されます。

### プロンプトを洗練する

プロンプトエディター右上の **プロンプトを洗練** をクリックすると、AI によるプロンプト改善機能を利用できます。

| 操作      | 内容                               |
| ------- | -------------------------------- |
| 自動改善    | 言語を簡潔にし、手順を明確にします                |
| 実行可能にする | 明確な出力・受け入れ基準・制約を含む形式に書き換えます      |
| カスタム指示  | 改善したい内容を自由に記述すると、AI がプロンプトを調整します |

![プロンプトを洗練する画面](/files/0LJzsRlECXMsCDHwD9hD)

## モデルの選択

**モデル** ドロップダウンから、タスクの内容に適したモデルを選択します。利用可能なモデルの詳細については、[AIモデル](/features-ja/ai-feature/ai-models.md) を参照してください。

## アーティファクトとして保存する

**出力をアーティファクトとして保存** を有効にすると、このブロックの出力がダウンロード可能なファイルとして保存されます。

1. インスペクターの **出力をアーティファクトとして保存** トグルをオンにします。
2. **アーティファクトのタイトル** にファイル名を入力します（省略した場合は自動的に命名されます）。
3. **アーティファクト形式** で **Markdown**・**JSON**・**HTML** から選択します。
4. **再実行時の動作** で、再実行時にアーティファクトをどう更新するかを選択します。

   | 動作     | 内容                                              |
   | ------ | ----------------------------------------------- |
   | 再生成    | 実行ごとに新しいアーティファクトをゼロから作成します。各実行が独立している場合に適しています。 |
   | その場で編集 | 既存のアーティファクトの最新バージョンに、ピンポイントな編集だけを加えます。          |

**構造化出力** を有効にしている場合、アーティファクト形式は **JSON** に固定されます。

{% hint style="info" %}
保存されたアーティファクトは、ワークフロー実行完了後に実行詳細画面からアクセスしてダウンロードできます。HTML アーティファクトは、実行詳細画面やファイル詳細画面でレンダリング結果をそのままプレビューできます。 **その場で編集** で生成されたバージョンには、追加・削除行数を表示する **編集内容** チップから前バージョンとの差分パネルを開けます。差分パネル内の行をクリックすると、現在の本文の該当箇所にジャンプします。
{% endhint %}

## レビュー機能を使う

**レビュー必須** を有効にすると、このブロックの実行後に処理が一時停止し、人によるレビューを待ちます。詳細については、[ワークフローの作成](https://help.genesis.autify.com/features-ja/workflow/pages/PrS2SW0TqNPa5U9GaAnQ#レビュー機能) を参照してください。

## 詳細設定

インスペクター内の **詳細設定** を展開すると、以下の高度な設定が利用できます。

![詳細設定の画面](/files/wF5SnFEXAvMwxq5QQKyK)

### 構造化出力

**構造化出力** を有効にすると、AI エージェントの出力形式を JSON Schema で定義できます。後続ブロックがこのブロックの出力を利用する場合に特定のフィールドへアクセスしやすくなります。

スキーマは 2 つの方法で定義できます。

| 編集モード     | 内容                                |
| --------- | --------------------------------- |
| スキーマエディター | フィールドをひとつずつ追加・削除・設定する UI デザイナーモード |
| JSON      | JSON Schema を直接入力するテキストモード        |

スキーマエディターでは、各フィールドに以下を設定します。

| 設定項目   | 内容                                              |
| ------ | ----------------------------------------------- |
| フィールド名 | 出力 JSON のプロパティ名                                 |
| スキーマ種別 | string / number / boolean / array / object から選択 |
| 説明（任意） | AI エージェントへの補足説明。適切な値を生成させるために活用できます             |
| 必須     | このフィールドを必須にするかどうかの設定                            |

**スキーマを調整** をクリックすると、改善したい内容を自然言語で入力するだけで AI がスキーマを自動調整します。

{% hint style="warning" %}
構造化出力を有効にした場合、スキーマにフィールドが 1 つも定義されていないと検証エラーになります。
{% endhint %}

### 推論の深さ

対応する推論モデルでは、 **推論の深さ** で AI エージェントブロックが内部で行う推論量を調整できます。 **デフォルト** のままにするとモデルの推奨設定が使われます。複雑なタスクでは上げ、より速い応答を優先したい単純なタスクでは下げて調整します。

選択したモデルが **推論の深さ** に対応していない場合、この項目は使用できません。

### ツール

**ツール** では、AI エージェントが実行中に使用できるビルトインツールを個別に選択します。有効にしたツールは、エージェントが必要と判断した際に自動的に呼び出されます。

有効化中のツールはキャンバス上のブロックにアイコンで一覧表示されます。右下の **+** ボタンをクリックすると、インスペクターを開かずに **ツール** タブと同じ内容をポップオーバー上で追加・削除できます。

GitHub・Slack・Aximo などの外部サービス連携が設定されている場合、対応するツールは **ツール** タブには表示されず、ワークフロー実行時に自動的に AI エージェントから利用できます。ツール全体の種類と利用条件については、[ツール](/features-ja/ai-feature/tools.md) を参照してください。

### MCP サーバー

**MCP サーバー** では、ワークスペースに登録済みの外部 MCP（Model Context Protocol）接続を追加して、AI エージェントの機能を拡張できます。外部 MCP 接続の登録方法については、[ワークスペースの設定](/features-ja/settings/workspace-settings/workspace-configuration.md) を参照してください。

## トラブルシューティング

### モデルエラー

| 状況                         | 原因                         | 対処方法           |
| -------------------------- | -------------------------- | -------------- |
| 「選択中のモデル「{model}」は利用できません」 | 選択したモデルが有効なプロバイダーで提供されていない | 別のモデルを選択してください |

### 構造化出力エラー

| 状況                | 原因                                     | 対処方法                                  |
| ----------------- | -------------------------------------- | ------------------------------------- |
| 構造化出力が有効なのに実行できない | スキーマにフィールドが 1 つも定義されていない               | スキーマエディターでフィールドを追加するか、構造化出力を無効にしてください |
| 「JSONスキーマが無効です」   | JSON 編集モードで入力した内容が正しい JSON Schema ではない | JSON の構文を確認して修正してください                 |

### プロンプトエラー

| 状況                             | 原因                                 | 対処方法                                               |
| ------------------------------ | ---------------------------------- | -------------------------------------------------- |
| 「プロンプトで使用されている変数が入力に定義されていません」 | プロンプト内の `{{変数名}}` に対応する入力が設定されていない | 変数挿入メニューから変数を挿入し直すか、 **入力** タブで対応する入力を追加してください     |
| 実行前にブロックでファイル参照の検証エラーが表示される    | プロンプトで参照していたファイルがワークスペースから削除された    | 古い参照を削除するか、 **ファイルを追加** から現在のファイルを入れ直してから再実行してください |

### MCP サーバーエラー

| 状況                               | 原因                                       | 対処方法                      |
| -------------------------------- | ---------------------------------------- | ------------------------- |
| 「このワークスペースに存在しない MCP 接続を使用しています」 | ブロックで参照している MCP 接続が削除されているか、別のワークスペースのもの | MCP サーバー設定で接続を再追加してください   |
| 接続確認が「エラー」になる                    | MCP サーバーが応答していない、または認証情報が正しくない           | URL と認証情報を確認し、接続を編集してください |