> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent の構築

> Agent を作成し、手動設定またはチャットでの対話によって能力を形づくる

> [!NOTE]
>
> 新しい Agent はベータ機能です。利用するには、クラスターで agent-backend とサンドボックス環境を有効にする必要があります。デプロイ方法は [Agent Sandbox のデプロイ](/ja/3.12.x/deploy/advanced-configuration/agent-sandbox.md) を参照してください。
>
> 本番環境では、Helm values の `agentBackend.serverSecretKey` を独自のランダムな値に置き換えてください。

## Agent の作成

**Agents** ページで **作成** > **最初から作成** をクリックし、Agent に名前を付けます。必要に応じて、「リサーチアシスタント」のようなロールや説明も入力します。残りはすべて **設定** で形づくります。

共有された DSL ファイルから Agent を作成する場合は、代わりに **DSL ファイルをインポート** を選択します。DSL ファイルにスキルとファイルは含まれません。

> [!NOTE]
>
> Agent の作成と管理には **Agentsを管理** 権限が必要です。オーナー、管理者、編集者のロールにはデフォルトで付与されています。詳細は [権限リファレンス](/ja/3.12.x/use/workspace/permission-reference.md) を参照してください。

## 能力の設定

各能力を手動で設定することも、[ビルドモード](#チャットによるビルド) で実現したいことをチャットで伝えながら構築することもできます。

**設定** で指定した内容はすべて Agent の能力として保存され、以後のあらゆるタスクで使われます。これとは別に、Agent は専用の「サンドボックス」の中で動作し、作業を進めながらコマンドの実行やファイルの操作を行います。

Agent の能力を変更できるのはここだけです。公開済みの Agent にエンドユーザーがプロンプト、スキル、ツールの変更を求めても、Agent は応じません。

### モデル

Agent の実行に使うチャットモデルを選びます。推論に強く、ツール呼び出しをネイティブにサポートするモデルがおすすめです。Agent は、いつ行動するか、どのツールが適しているか、結果をどう読み取るかを自分で判断する必要があるためです。

> [!NOTE]
>
> Agent の出来はモデルしだいで大きく変わります。できるだけ新しいモデルを選んでください。
>
> 古いモデルはサンドボックスを使いこなせないことが多く、必要な場面でもコマンド実行やツールのインストールを行わないのが典型的な症状です。

### プロンプト

プロンプトでは、Agent のロールと仕事の進め方を定めます。どのように推論するか、いつツールやナレッジに頼るか、何を避けるかを具体的に書いてください。

押さえておきたい項目：

* **ペルソナと目標**：Agent が演じる役割と、達成を目指すゴール。
* **進め方**：典型的なタスクで期待する手順や順序。
* **ツールとファイルの使い方**：それぞれを使う場面（名前を挙げて明示）。
* **出力**：望む形式、長さ、トーン。

特定のスキル、ファイル、ツール、ナレッジソースを Agent に指定することも、どれを使うかを Agent に任せることもできます：

* **プロンプト内で参照する**：`/` で参照を挿入すると、使ってほしいまさにその箇所で、Agent をその対象へ直接導けます。特定のステップが特定の対象に依存する場合に向いています。

* **セクションに追加するだけ**：いつ使うかは Agent 自身に判断させます。一手一手を指示するより、Agent の判断を信頼したい場合に向いています。

### スキル

「スキル」は、Agent 向けにパッケージ化する自己完結型の手順書です。1 つの専門タスクのための指示、参考資料、スクリプトをひとまとめにし、一度定義すれば繰り返し使えます。

プロンプトが Agent の全体的なロールを定めるのに対し、スキルは特定のタスクで必要になったときだけ取り出す作業手順、いわば有能な人材に渡す SOP です。Agent 側は汎用的な能力を、スキル側はその仕事専用の手順、資料、ツールを持ち寄ることで、期待どおりの成果につながります。

たとえば `marketing-copy` というスキルにスタイルガイド、ブランド素材、チェックリストをまとめておけば、毎回説明し直す必要がなくなります。

スキルパッケージは、50 MB 以内の `.zip` または `.skill` ファイルで、`SKILL.md` が入っている必要があります。フォーマットの詳細や作成方法は、[Agent Skills](https://agentskills.io/home) を参照してください。[ビルドモード](#チャットによるビルド) で Agent にスキルを作成させることもできます。

### ファイル

ファイルは、仕様書、テンプレート、ガイドラインなど、Agent が作業中に参照できるドキュメントです。スキルと違い、実行する手順ではなく、読むための資料です。

ファイルは、Agent に全文を読ませて忠実に従わせたい少数のドキュメントに向いています。大量の資料から検索させたい場合は、[ナレッジベース](#ナレッジ検索) を接続してください。

サイズ上限はファイルタイプごとに異なり、いずれもデフォルト値を [環境変数](/ja/3.12.x/deploy/advanced-configuration/environment-variables.md) で調整できます。

| ファイルタイプ | デフォルト上限 | 環境変数 |
| :- | :- | :- |
| ドキュメント | 15 MB | `UPLOAD_FILE_SIZE_LIMIT` |
| 画像 | 10 MB | `UPLOAD_IMAGE_FILE_SIZE_LIMIT` |
| 動画 | 100 MB | `UPLOAD_VIDEO_FILE_SIZE_LIMIT` |
| 音声 | 50 MB | `UPLOAD_AUDIO_FILE_SIZE_LIMIT` |

> [!NOTE]
>
> ここで追加したファイルは、Agent の能力の一部として保存されます。一方、Agent がサンドボックス内に作成したファイルは、タスクが終わると消去されます。

[ビルドモード](#チャットによるビルド) では、Agent にファイルを作成させ、ここに保存させることもできます。

### ツール

[Dify ツール](/ja/3.12.x/use/workspace/tools) を持たせると、Agent はチャットの外でも行動できるようになります。ワークスペースにあるプラグイン、カスタム API、ワークフロー、MCP サーバーを利用できます。一部のツールは使用前に認証が必要です。

> [!TIP]
>
> ここで追加する Dify ツールのほかにも、Agent は必要になれば、サンドボックス内で自らコマンドラインプログラムをインストールして実行できます。
>
> こうしたプログラムは「ツール」のリストに表示されません。また、作業ディレクトリ内のファイルと異なり、一度インストールすれば以後のタスクでも使えます。

### ナレッジ検索

Agent が作業中に検索できる [ナレッジベース](/ja/3.12.x/use/knowledge/readme.md) を接続します。

検索ではクエリに関連する内容だけを取り込むため、[ファイル](#ファイル) には収まらない大量の資料にも対応できます。ナレッジベースはワークスペース共有の資産でもあり、他のアプリから使えるほか、データソースと同期させておくこともできます。

ナレッジベースごとにクエリの方法を設定します：

* **エージェントが決定**：Agent が会話から自分で検索クエリを作成します。

  質問が多岐にわたり、何を調べるかを Agent に判断させたい場合に最適です。ユーザーが尋ねた内容を何でも検索するドキュメントアシスタントなどが典型です。

* **カスタムクエリ**：毎回実行する固定クエリを指定します。

  ソースを常に同じ方法で検索させたい場合に最適です。質問の言い回しによらず必ず返品ポリシーを参照する、返品対応アシスタントなどが典型です。

**検索設定** では、結果のランク付けと絞り込みを調整します：

* **Rerank**：リランクモデルで結果を関連度順に並べ替えます。または、意味の一致とキーワード一致のバランスを取る **ウェイト設定** を使うこともできます。

  > [!NOTE]
  >
  > ウェイト設定が表示されるのは、接続したすべてのナレッジベースが高品質インデックスを使い、同じ埋め込みモデルを共有し、外部ナレッジベースを含まない場合だけです。
  >
  > 経済的インデックスや外部ナレッジベース、別の埋め込みモデルが 1 つでもあると、このオプションは表示されません。

* **トップ K**：リランク後に残す結果の最大数です。

* **スコア閾値**：結果の採用に必要な最小の類似度です。高くするほど厳しく絞り込み、低くするほど幅広く拾います。

検索対象を特定のドキュメントに絞るには、[メタデータ](/ja/3.12.x/use/knowledge/metadata.md) フィルタリングを有効にします。

### 詳細設定

> [!WARNING]
>
> **セキュリティに関する注意：Agent 環境変数の外部送信リスク**
>
> 本注意事項は Dify Enterprise 3.12.x を対象としています。Agent に環境変数を設定し、かつネットワークアクセスを許可している場合に適用されます。
>
> Dify Enterprise 3.12.x の Agent ランタイムは、機密性の高い環境変数の値がユーザーへの応答やツールの実行出力に平文で表示されるリスクを低減するため、パターンマッチングによるマスキングを適用しています。ただし、この仕組みだけでは、ネットワークアクセス権限を持つ Agent が、送信前に値をエンコード（Base64、16 進数、文字列分割、その他の難読化手法など）した上で、外部のエンドポイントへ送信することを完全に防ぐことはできません。
>
> デプロイの運用者は、システム、データ、および認証情報の機密性レベルに応じて、Agent の権限とアクセス範囲を適切に設定する責任があります。以下の対策を強く推奨します：
>
> * 長期間有効な認証情報を Agent 環境に設定しない。
> * 可能な限り、有効期限が短く、最小権限のみを持つトークンを使用する。
> * ネットワークの外部送信先を、タスクの実行に必要な最小限の範囲に制限する。
>
> これは、パターンマッチング方式のマスキングを採用しているシステム全般に共通する制約事項です。

**環境変数** は、実行中の Agent が読み取れるキーと値のペアです。ツールが必要とするエンドポイントや API キーなどに使います。

環境変数は Agent のサンドボックス内に保持されます。そのため、プロンプトに書かずに、コマンドラインツールやスキルへシークレットを渡す手段になります。値を **Secret** に指定するとマスク表示のまま保てます。`.env` ファイルをインポートすれば、複数の変数を一度に追加できます。

[ビルドモード](#チャットによるビルド) で Agent に設定させることもできます。

> [!TIP]
>
> チャット体験を仕上げるには、**チャット機能** でオープニングメッセージ、提案質問、音声などを追加できます。詳細は [アプリツールキット](/ja/3.12.x/use/build/additional-features.md) を参照してください。

## チャットによるビルド

すべてを手動で設定する代わりに、Agent にさせたいことを言葉で伝えて構築できます。チャットを進めると、Agent が自らスキル、ファイル、環境変数を設定していきます。

たとえば、最初のメッセージは次のように書けます。

```text wrap theme={null}
会議の生メモを、出席者、決定事項、アクションアイテムを含む構造化された議事録に整理する Agent を作ってください。
```

会話の相手は実際に動いている Agent です。作りながら試し、振る舞いを確かめ、同じビルドチャットの中で磨き込めます。作業中のファイルを見るには、**ファイルシステム** をクリックします。これらのファイルは、ビルドモードを終了すると消去されます。

Agent は作業しながら、パネルの設定を直接変更していきます。すべての変更は **ビルドドラフト** に一覧表示されます。**適用** で変更を取り込むか、**破棄** で捨てます。どちらの場合もビルドモードを終了し、会話はクリアされます。

> [!NOTE]
>
> **破棄** で戻るのは設定だけです。Agent がサンドボックス内ですでに行った操作（プログラムのインストールなど）は元に戻りません。

ビルドモード中、設定パネルは読み取り専用です。変えたいことは、そのまま Agent に伝えてください。

### ビルドノート

Agent は作業しながら、設定した内容を「ビルドノート」（`build_note.md`）に記録します。このファイルは、最初に **適用** した時点で **ファイル** に表示されます。

作業中のファイルと異なり、ビルドノートは Agent のセットアップと一緒に保存されます。Agent は新しい会話を始めるたびにこのノートを読み込み、**プロンプト** と組み合わせて自らの指示とします。

適用したら、ビルドノートを開いて Agent が記録した内容を確認してください。

* 望んだ内容が揃っていれば、それで完了です。

* 記載を変えたい場合は、ビルドモードで Agent に修正させます。

  > [!NOTE]
  >
  > Agent が更新するのは、自動生成されたビルドノートだけです。ダウンロードして再アップロードした複製はただのファイルとして扱われ、次のビルドチャットでは新しいノートが別途生成されます。

* 足りない内容があれば、**プロンプト** に追記します。

* 記録をいちからやり直したい場合は、**ファイル** でノートを削除します。

ビルドチャットをまたいで、このノートは Agent の記憶のような役割も果たします。たとえば、あるチャットで議事録 Agent の形式を決めておけば、後日アクションアイテムの担当者を追加するチャットは、決めた形式や方針を引き継いだ状態から始まります。

## プレビュー

右側のパネルを **ビルド** から **プレビュー** に切り替えると、公開後にエンドユーザーが目にするのと同じ形で Agent を試せます。返信は整った表示になり、チャット機能が有効です。

プレビューでの対話が Agent の設定を変えることはありません。公開前の最終確認に使ってください。

## 公開

編集内容はドラフトとして自動保存されます。Agent の準備ができたら公開して、そのバージョンを本番にします。バージョン履歴はいつでも開けるので、以前のバージョンの確認や復元もできます。

> [!NOTE]
>
> バージョンを復元しても、巻き戻るのは Agent の設定だけです。サンドボックス環境にはバージョン管理がなく、インストールしたツールなどの環境への変更はそのまま残ります。

**アクセスポイント** タブでは、共有可能なリンクで Web アプリとして公開したり、自分のサイトに埋め込んだり、サービス API 経由でコードから呼び出したりできます。誰がアクセスできるかは [Web アプリアクセス制御](/ja/3.12.x/use/publish/webapp/web-app-access.md) で設定できます。

> [!WARNING]
>
> セッションの隔離レベルは、クラスターでのサンドボックス実行方式によって決まります。Sandbox Gateway を有効にした標準デプロイでは、セッションごとに専用のサンドボックス Pod が割り当てられ、ファイルシステムはセッション単位で隔離されます。
>
> 「共有サンドボックス」モードでは、すべてのセッションが単一のサンドボックスコンテナを共有するため、エンドユーザー間の隔離性が低下します。マルチテナント環境など、ユーザー間の厳格な隔離が必要な場合はご注意ください。

> [!NOTE]
>
> Agent の API はストリーミングにのみ対応しています。API アクセスのオン・オフを切り替えられるのは、ワークスペースのオーナーと管理者だけです。

ワークフローの [Agent ノード](/ja/3.12.x/use/nodes/agent.md#新しい-agent) に Agent を招いて、1 ステップを任せることもできます。

公開後は、**ログ** で会話を、**モニタリング** で使用状況、品質、速度、コストを確認できます。

Agent をワークスペース間で共有するには、DSL ファイルとしてエクスポートします。エクスポートされるファイルにスキルとファイルは含まれません。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.