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

# Agent の構築

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

> このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/use-dify/build/new-agent/build) を参照してください。

<Note>
  新しい Agent はベータ機能です。ランタイムは Docker Compose デプロイに同梱され、デフォルトで有効です。

  本番環境では、[`DIFY_AGENT_SERVER_SECRET_KEY`](/ja/self-host/deploy/configuration/environments#dify_agent_server_secret_key) と [`DIFY_AGENT_API_TOKEN`](/ja/self-host/deploy/configuration/environments#dify_agent_api_token) を独自のランダムな値に置き換えてください。
</Note>

## Agent の作成

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

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

<Info>
  Agent の作成と管理には、エディター以上のロールが必要です。
</Info>

## 能力の設定

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

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

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

### モデル

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

<Note>
  Agent の出来はモデルしだいで大きく変わります。できるだけ新しいモデルを選んでください。

  古いモデルはサンドボックスを使いこなせないことが多く、必要な場面でもコマンド実行やツールのインストールを行わないのが典型的な症状です。
</Note>

### プロンプト

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

押さえておきたい項目：

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

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

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

### スキル

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

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

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

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

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

  パッケージには `SKILL.md` が必要で、サイズはデフォルトで最大 50 MB、[`UPLOAD_SKILL_FILE_SIZE_LIMIT`](/ja/self-host/deploy/configuration/environments#upload_skill_file_size_limit) で調整できます。

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

[ビルドモード](#チャットによるビルド) では、Agent に埋め込みスキルを作成させることもできます。

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

### ファイル

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

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

| ファイルタイプ | デフォルト上限 | 環境変数                           |
| :------ | :------ | :----------------------------- |
| ドキュメント  | 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` |

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

<Info>
  Agent が作成して保存するファイルは、デフォルトで 1 ファイルあたり最大 50 MB です。`DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT` で調整できます。詳細は [環境変数](/ja/self-host/deploy/configuration/environments) を参照してください。
</Info>

### ツール

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

<Tip>
  ここで追加する Dify ツールのほかにも、Agent は必要になれば、サンドボックス内で自らコマンドラインツールをインストールして実行できます。これらのツールはツール一覧には表示されません。

  Agent が [ビルドモード](#チャットによるビルド) でインストールしたツールは、公開後も引き続き使えます。一方、公開後の実行中にインストールされたものは一時的です。
</Tip>

### 環境変数

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

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

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

<Note>
  ここに保存した値は、Agent が読み取るコマンド出力に現れることがあります。機密性の高い文字列をマスクするには、`DIFY_AGENT_SHELL_REDACT_PATTERNS` を設定してください。詳細は [環境変数](/ja/self-host/deploy/configuration/environments#新しい-agent（ベータ版）) を参照してください。
</Note>

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

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

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

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

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

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

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

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

### ファイルシステム

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

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

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

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

### ビルドノート

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

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

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

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

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

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

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

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

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

## 公開

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

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

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

**アクセスポイント** タブでは、共有可能なリンクで Web アプリとして公開したり、自分のサイトに埋め込んだり、[サービス API](/ja/api-reference/guides/agent) 経由でコードから呼び出したりできます。

<Warning>
  **データセキュリティに関する注意**

  Community Edition では、同一の Agent を複数のエンドユーザーに公開する場合、ファイルアクセス制御により Agent ファイルおよびセッションファイルへのアクセスを制限します。この制御は、ファイルシステムを介した会話間のデータアクセスリスクを低減しますが、Agent ランタイムは、相互に信頼できないユーザーやワークロード間に強固なセキュリティ境界を提供することを意図したものではありません。

  強力な隔離や、厳格なセキュリティおよびコンプライアンス管理を必要とするデプロイでは、別途セキュリティを強化したインフラ環境をご利用いただくか、Cloud / Enterprise プランをご検討ください。Enterprise プランの詳細は、[営業へのお問い合わせ](https://share-na2.hsforms.com/176RpklY3TLeHo6qmuAdRKQ40s9fk) よりご連絡ください。
</Warning>

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

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

### 実行の制限

* **実行時間**

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

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

  これらの変数の詳細は [環境変数](/ja/self-host/deploy/configuration/environments) を参照してください。

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

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

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

* **返信ファイル**

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

  より大きな成果物が必要な場合は、`DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT` を引き上げてください。詳細は [環境変数](/ja/self-host/deploy/configuration/environments) を参照してください。

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

<AccordionGroup>
  <Accordion title="ナビゲーションに Agents が表示されない、またはノード一覧に Agent ノードがない">
    デプロイの `.env` が 1.16.0 より古く、Agents のスイッチが存在しないか、オフのままになっています。

    `.env.example` と同期してください（スイッチは [`NEXT_PUBLIC_ENABLE_AGENT_V2`](/ja/self-host/deploy/configuration/environments#next_public_enable_agent_v2)）。その後、web コンテナを再作成（`docker compose up -d web`）し、ブラウザを強制リロードします。

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

    ほかのメンバーには **Agents** が表示されるのに自分には表示されない場合は、ワークスペースのロールが原因です。この項目にはエディター以上のロールが必要です。
  </Accordion>

  <Accordion title="Agent の実行が開始直後に失敗する">
    毎回すぐにエラーになる場合、1.16.0 以降のイメージを古い `docker-compose.yaml` と組み合わせている可能性があります。そのファイルには Agent に必要なサービス（`agent_backend` や `local_sandbox` など）がありません。

    イメージと一緒に compose ファイルも更新し、スタック全体を起動し直してください。
  </Accordion>

  <Accordion title="OpenAI 互換モデルで Agent がエラーになる、またはツールを使わない">
    OpenAI 互換エンドポイント経由のモデル（vLLM など）には、ネイティブなツール呼び出しに完全対応していないものがあります。Agent はこの機能を前提としています。

    ツール呼び出しをネイティブにサポートするモデルを選んでください。互換モデルでもエラーになる場合は、プロバイダーの **Token parameter name** 設定を確認してください。新しいモデルの一部は `max_completion_tokens` を必要とし、自動判定が誤ることがあります。
  </Accordion>

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