> ## 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 のデプロイ](https://enterprise-docs.dify.ai/ja/3.13.x/deploy/advanced-configuration/agent-sandbox.md) を参照してください。
>
> 本番環境では、Helm values の `agentBackend.serverSecretKey` を独自のランダムな値に置き換えてください。

## Agent の作成

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

共有された DSL ファイルから Agent を作成するには、**DSL ファイルをインポート** を選択します。ワークスペースの [スキルライブラリ](https://enterprise-docs.dify.ai/ja/3.13.x/use/build/skills.md) に同名のスキルがあれば、自動的に再関連付けされます。埋め込みスキルとファイルは含まれないため、インポート後に追加してください。

> [!NOTE]
>
> **作成** には **エージェントを作成** 権限が必要です。**DSL ファイルをインポート** には **エージェント DSL のインポートとエクスポート** 権限が必要です。
>
> オーナー、管理者、編集者はデフォルトで両方を持っています。それ以外のメンバーには、[カスタムロール](https://enterprise-docs.dify.ai/ja/3.13.x/use/workspace/roles-and-permissions#カスタムロール) で付与できます。

## 能力の設定

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

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

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

### モデル

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

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

### プロンプト

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

押さえておきたい項目：

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

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

* **プロンプト内で参照する**：`/` で参照を挿入すると、使ってほしいまさにその箇所で、Agent をその対象へ直接導けます。特定のステップが特定の対象に依存する場合に向いています。
* **セクションに追加するだけ**：いつ使うかは Agent 自身に判断させます。一手一手を指示するより、Agent の判断を信頼したい場合に向いています。

### スキル

スキルは、Agent が特定のタスクで従う手順です。プロンプトが Agent の全体的なロールを定めるのに対し、スキルはそのタスクだけを扱います。

たとえば、サポート担当の Agent では、プロンプトであらゆる問い合わせに対応する役割を設定できます。`refund-requests` スキルでは、返金だけを扱います。注文を確認し、30 日以内に限って返金し、最後にヘルプセンターへのリンクを案内します。

**追加** をクリックし、どちらの種類のスキルを追加するかを選びます：

* **From skill library** を選択すると、ワークスペース全体で共有する [スキルライブラリのスキル](https://enterprise-docs.dify.ai/ja/3.13.x/use/build/skills.md) を追加できます。1 つの Agent に最大 20 個追加でき、それぞれの最新公開バージョンが反映されます。

* **Upload package** を選択すると、`.zip` または `.skill` パッケージを埋め込みスキルとして追加できます。埋め込みスキルは、その Agent だけが使用します。

  パッケージには `SKILL.md` が必要で、サイズはデフォルトで最大 50 MB です。上限は [`UPLOAD_SKILL_FILE_SIZE_LIMIT`][upload-skill-file-size-limit] で調整できます。

  埋め込みスキルをほかの Agent と共有するには、[スキルライブラリに追加](https://enterprise-docs.dify.ai/ja/3.13.x/use/build/skills.md#スキルのインポート) してください。

[ビルドモード](#build-by-chatting) では、Agent に埋め込みスキルを作成させることもできます。

> [!TIP]
>
> Dify ツールやファイルを Agent 自身の能力の一部にするには、スキルパッケージに入れるのではなく、Agent に直接追加してください。

### ファイル

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

サイズ上限はファイルタイプごとに異なり、いずれもデフォルト値を [環境変数](https://enterprise-docs.dify.ai/ja/3.13.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` |

[ビルドモード](#build-by-chatting) では、Agent にファイルを作成させ、ここに保存させることもできます。

> [!NOTE]
>
> Agent が作成して保存するファイルは、デフォルトで 1 ファイルあたり最大 50 MB です。`DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT` で調整できます。詳細は [環境変数](https://enterprise-docs.dify.ai/ja/3.13.x/deploy/advanced-configuration/environment-variables.md#agent-backend-設定) を参照してください。

### ツール

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

> [!TIP]
>
> ここで追加する Dify ツールのほかにも、Agent は必要になれば、サンドボックス内で自らコマンドラインツールをインストールして実行できます。これらのツールはツール一覧には表示されません。
>
> Agent が [ビルドモード](#build-by-chatting) でインストールしたツールは、公開後も引き続き使えます。一方、公開後の実行中にインストールされたものは一時的です。

### 環境変数

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

**詳細設定** では、**環境変数** を追加できます。環境変数は、Agent が作業中にサンドボックス内で読み取れるキーと値のペアです。

たとえば、Agent の複数のスキルが同じ注文システムを使うとします。在庫を確認するスキル、注文を出すスキル、レポートを取得するスキルなどです。システムのアドレスを `ORDER_API_URL` としてここに保存すれば、どのスクリプトも同じ名前で読み取ります。テスト用システムから本番システムへ切り替えるときも、ここで値を 1 つ更新するだけで、すべてのスキルが切り替わります。

`.env` ファイルをインポートすれば、複数の変数を一度に追加できます。[ビルドモード](#build-by-chatting) で Agent に設定させることもできます。

> [!NOTE]
>
> ここに保存した値は、Agent が読み取るコマンド出力に現れることがあります。機密性の高い文字列をマスクするには、`DIFY_AGENT_SHELL_REDACT_PATTERNS` を設定してください。詳細は [環境変数](https://enterprise-docs.dify.ai/ja/3.13.x/deploy/advanced-configuration/environment-variables.md#agent-backend-設定) を参照してください。

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

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

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

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

会話の相手は実際に動いている Agent です。作りながら試し、振る舞いを確かめ、同じビルドチャットの中で磨き込めます。

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

> [!NOTE]
>
> **破棄** を選ぶと、このビルドチャットの内容はすべて失われます。設定の変更も、[**ファイルシステム**](#ファイルシステム) の永続ファイルへの変更も対象です。

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

### ファイルシステム

ビルドモードでは、Agent はサンドボックス内で実際のファイルを扱います。生成した成果物や自らインストールしたプログラムなど、作業に関わるあらゆるものです。ビルドチャット中は、右上の **ファイルシステム** をクリックすると閲覧できます。

ビルドチャットは Agent そのものを形づくる場です。そのため、Agent が追加したもの（作成したテンプレートやインストールしたツールなど）はデフォルトで **永続ファイル** になります。以後のすべての会話とワークフロー実行のために保持され、実質的にプロンプトやスキルと同じく、Agent のセットアップの一部になります。

テスト用ファイルや一度しか使わない変換ツールのような一回限りの作業には、チャットで「このファイルは一時扱いにして」のように伝えてください。そうしたファイルは **一時ファイル** に入り、このビルドチャットが終わると消去されます。

公開後の実行では、Agent が追加するものは常に一時的です。そのため、実行中に何が起きても Agent 自体が変わることはありません。

### ビルドノート

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

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

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

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

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

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

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

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

このノートは、ビルドチャットをまたいで Agent の記憶のように機能します。たとえば、あるチャットで議事録 Agent の形式を決めたとします。後日、アクションアイテムの担当者を追加するチャットを始めると、決めた形式や方針が引き継がれます。

## プレビュー

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

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

## 公開

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

> [!NOTE]
>
> バージョンを復元すると、Agent のサンドボックス内の永続ファイルも、そのバージョンの状態に戻ります。

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

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

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

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

Agent をワークスペース間で共有するには、DSL ファイルとしてエクスポートします。同名のスキルがあるワークスペースでは、スキルライブラリのスキルが自動的に再関連付けされます。埋め込みスキルとファイルは含まれないため、一緒に共有してください。

### 実行の制限

* **実行時間**

  どのアクセスポイントから開始しても（Web アプリ、サービス API、ワークフロー）、1 回の実行はデフォルトで 1 時間後に停止され、未完成の返信は破棄されます。

  実行が打ち切られた場合は、もう一度試すか、タスクを小さく分割してください。より長く実行するには、`APP_MAX_EXECUTION_TIME`、`WORKFLOW_MAX_EXECUTION_TIME`、`DIFY_AGENT_RUN_TIMEOUT_SECONDS` をいずれも目標の実行時間より高く設定します。

  これらの変数の詳細は [環境変数](https://enterprise-docs.dify.ai/ja/3.13.x/deploy/advanced-configuration/environment-variables.md) を参照してください。

* **モデルリクエスト数**

  Agent がモデルを呼び出すたびに、1 回の実行につき 500 回の上限を消費します。推論が重く、ツールを多く使うほど早く達します。

  タスクを小さく分割して、各実行を上限内に収めてみてください。

* **返信ファイル**

  Agent が返信で送り返すファイルは、デフォルトで 1 ファイルあたり最大 50 MB で、それを超えるファイルは届きません。

  より大きな成果物が必要な場合は、`DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT` を引き上げてください。詳細は [環境変数](https://enterprise-docs.dify.ai/ja/3.13.x/deploy/advanced-configuration/environment-variables.md#agent-backend-設定) を参照してください。

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

> **Agents ページに Agent が表示されない、または編集できない**
>
> ほかのメンバーには表示される Agent が自分には表示されない場合、その Agent の許可されたメンバーの一覧に入っていません。その Agent を管理している人に、Agent の **リソースアクセス** セクションで追加してもらってください。
>
> Agent を開けるのに編集できない場合は、その Agent の **アクセス権限** を **ロール権限に従う** から権限セットに切り替えてもらいます。**エージェント情報と設定の編集** を含むセット、たとえば組み込みの **コンテンツ編集** を選びます。このセットは、この Agent に限ってロールの権限を置き換えます。

> **ノード一覧に Agent ノードがない**
>
> Chatflow アプリでこのノードが見当たらないのは仕様です。新しい Agent ノードは Workflow アプリでのみ使用できます。

> **Agent の実行が開始直後に失敗する**
>
> 毎回すぐにエラーになる場合、クラスターに agent-backend サービスやサンドボックスランタイムが欠けている可能性があります。
>
> 必要なコンポーネントと確認方法は [Agent Sandbox のデプロイ](https://enterprise-docs.dify.ai/ja/3.13.x/deploy/advanced-configuration/agent-sandbox.md) を参照してください。

> **OpenAI 互換モデルで Agent がエラーになる、またはツールを使わない**
>
> OpenAI 互換エンドポイント経由のモデル（vLLM など）には、ネイティブなツール呼び出しに完全対応していないものがあります。Agent はビルドチャットでも公開後の実行でも、この機能を前提としています。
>
> ツール呼び出しをネイティブにサポートするモデルを選んでください。互換モデルでもエラーになる場合は、プロバイダーのモデル設定にある **Token parameter name** を確認してください。新しいモデルの一部は `max_completion_tokens` を必要とし、自動判定が誤ることがあります。
>
> 一部の OpenAI 公式モデルは、推論を有効にすると Chat Completions プロトコルではツールを呼び出せません。その場合は、プロバイダー資格情報の **API Protocol** を Responses API に変更してください。

> **アップロードした画像で Agent がエラーになる、または画像を無視する**
>
> Agent のモデルがビジョンに対応しているかどうかにかかわらず、**チャット機能** で画像アップロードを有効にできます。非対応のモデルでは、Agent が画像の処理でエラーになるか、画像を受け取っていないかのように返信することがあります。
>
> ビジョン対応のモデルに切り替えてください。モデル選択時に Vision タグが目印になります。

> **Agent が社内ネットワークのファイルやページを取得できない**
>
> サンドボックスの外部アクセスはプロキシを経由し、プライベートネットワークのアドレスはデフォルトでブロックされます。公開 URL へのアクセスは可能です。社内の資料は Agent の [ファイル](#files) に追加してください。

[upload-skill-file-size-limit]: https://enterprise-docs.dify.ai/ja/3.13.x/deploy/advanced-configuration/environment-variables.md#upload_skill_file_size_limit


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