n8n AI agentを自分のVPSで構築する方法

n8n AI agent とは何か、chain との違い

n8n AI agent は、サブノードを接続した単一の AI Agent ノードです。サブノードには、1 つの chat model、1 つ以上の tools、必要に応じた memory を指定します。プレーンテキストで目標を指示すると、モデルが回答できるまで、呼び出す tools とその順序を判断します。以下では、この仕組みを中心とした設定を説明します。

chain は逆の仕組みです。Basic LLM Chain では、手順をユーザーが決め、モデルはテキストを生成するだけです。agent ではモデルが手順を決めるため、同じ質問でも、ある日はモデル呼び出しが 1 回で済み、別の日には 9 回必要になることがあります。この違いが、このガイドで扱うすべての設定に影響します。

このガイドでは、管理下のマシン上で n8n が HTTPS の背後ですでに稼働していることを前提とします。まだ構築していない場合は、実際の証明書を使って Docker で n8n をセルフホストする から始めてください。これから保存する API key には、そのガイドで必須としている encryption-key のバックアップが必要です。agent を使わないパターンである webhook summarizer と scheduled classifier については、Claude と n8n の workflow パターン を参照してください。

ここに記載したフィールド名をそのまま使用する前に、バージョンを確認してください。n8n の AI node は頻繁に変更されます。

docker compose exec n8n n8n --version

このガイドの名称は、2026 年 7 月時点の n8n current stable に対応しています。version 1.82.0 以降、すべての AI Agent node は Tools Agent として実行されるため、以前の agent-type dropdown は存在しません。

手順 1: トリガーを選択する

会話エージェントには、Chat Trigger ノードを追加します。構築中は Make Chat Publicly Available をオフのままにしてください。これにより、エディターのチャットパネルからのみアクセスできます。エージェントが完成し、認証方式を決めたらオンにします。

Chat Trigger は、chatInput というフィールドをエージェントに渡します。この名前は手順 3 で重要です。名前を間違えることが、最初に発生する最も一般的なエラーです。

無人で実行するエージェントには、Schedule Trigger または Webhook ノードを使用します。どちらも chatInput を生成しないため、プロンプトを自分で記述します。

手順 2: モデル認証情報

キャンバスに AI Agent ノードを配置します。n8n に Chat Model コネクターがその下に空の状態で表示されます。そこに Anthropic Chat Model サブノードを接続します。

認証情報は、Anthropic Console の platform.claude.com で、Settings、API Keys の順に開いて作成します。キーは 1 回だけ表示されます。API の利用料金はトークン単位で課金され、Claude.ai のサブスクリプションとは別です。そのため、初回実行前にアカウントの課金設定を完了しておく必要があります。

モデルは会社単位ではなく、エージェント単位で選択します。1 つのツールで情報を検索して報告するエージェントであれば、Haiku で問題なく動作します。2026 年 7 月時点の料金は、入力トークン 100 万個あたり $1、出力トークン 100 万個あたり $5 です。エージェントが複数のツールを使い、それらをまたいで計画する必要がある場合は、Sonnet に切り替えます。避けるべきなのは、安価なモデルが誤ったツールを 4 回呼び出すことです。高価なモデルが正しいツールを 1 回呼び出す場合より、コストが高くなる可能性があります。

サブノードのオプションで Maximum Number of Tokens を設定します。これにより、モデルが生成する各レスポンスの長さを制限できます。大きなデフォルト値のままにすると、混乱した 1 回の実行で非常に長い回答が生成され、料金が増える可能性があります。

n8n のドキュメントにある注意点として、見落としやすいものがあります。サブノード内の式は常に最初の入力アイテムを基準に評価され、アイテムごとには評価されません。アイテムごとの式は、ルートノードのプロンプトフィールドに配置してください。

手順 3: エージェントが受け取るプロンプト

AI Agent ノードを開きます。Prompt パラメーターには 2 つの設定があります。

• Take from previous node automatically は、chatInput という名前の入力フィールドを想定します。Chat Trigger の後段では、この設定を使用します。
• Define below を選ぶと、静的なテキストまたは式を入力する Prompt (User Message) フィールドが表示されます。Schedule Trigger または Webhook ノードの後段では、この設定を使用します。

前段に Webhook ノードを配置すると、POST ボディは $json.body の下に格納されます。そのため、プロンプトフィールドは次のようになります。

Check the current status of {{ $json.body.service }} and tell me
whether it is up. If it is down, say for how long. No preamble.

Step 4: エージェントに1つのツールを与える

ツールのサブノードがない AI Agent ノードは実行を拒否します。まずは1つから始めてください。中途半端に設定した4つのツールより、正常に動作する1つのツールのほうが多くのことを学べます。

HTTP Request ノードをエージェントの Tool コネクタに接続します。通常の HTTP Request ノードと同じ手順で正確に設定し、まずシェルからそのエンドポイントをテストしてください。

curl -s -H 'Accept: application/json' \
  https://status.example.com/api/status/database | head -c 400

その curl がエラーや HTML のログインページを返す場合、エージェントも失敗します。この失敗はモデルの問題のように見えますが、実際には URL または認証の問題です。ノードではなく、シェルで修正してください。

ツールの Description フィールドは、同僚向けのドキュメントではありません。モデルがこのツールを使うべきか判断するときに読む唯一の情報です。何が返るかを簡潔に記述してください。「監視対象の1つのサービスについて、現在の稼働状態または停止状態と停止時間を JSON で返します」のように書きます。

リクエストの一部をモデルに入力させるには、$fromAI() 式を使用します。この式は AI Agent ノードに接続されたツールでのみ機能し、Code ツールでは機能しません。

{{ $fromAI('service', 'The name of the service to look up', 'string') }}

引数は key で、その後にオプションの description、type、defaultValue が続きます。キーは1～64文字で、英字、数字、アンダースコア、ハイフンを使用します。型には string、number、boolean、json のいずれかを指定し、省略時は string になります。より完全な呼び出しは次のようになります。

{{ $fromAI('limit', 'How many records to return', 'number', 20) }}

キーは既存データへの参照ではなく、ヒントです。$fromAI('service') は、どこかにある service というフィールドを読み取るものではありません。モデルに「値を生成し、それを service と呼んでください」と伝えるだけです。モデルは会話、入力データ、その他のツール結果を調べて値を探します。チャットワークフローでは、ユーザーにそのまま質問する場合もあります。

通常、2つ目のツールには Web 検索を使用します。Web 検索も単なる HTTP エンドポイントなので、有料の検索 API ではなく 独自の SearXNG インスタンスをこの同じノードの接続先にできます。ただし、取得したすべてのページは、プロンプト内に取り込まれる信頼できないテキストとして扱ってください。

Step 5: メモリとエージェントが忘れる理由

メモリのサブノードがない場合、すべてのメッセージは何もない状態から始まります。直近の会話を保持するには、Simple Memory サブノードを接続します。

パラメーターは2つあります。Session Key は会話を識別するキーです。そのため、異なるキーを使用する2人のユーザーには、別々の履歴が割り当てられます。Context Window Length は、プロンプトに再度含める過去のやり取りの数です。

Context Window Length は品質だけでなく、コストも左右します。記憶された各ターンは、その後の呼び出しごとに入力トークンとして再送信されるためです。会話の多いエージェントでウィンドウを20にすると、初期のメッセージに対して20回分の料金を支払うことになります。

n8n を queue mode で実行している場合、Simple Memory は本番のアクティブなワークフローでは機能しません。履歴が共有ストアではなく、ワークフロー自身のデータ内に保存されるためです。queue mode のインスタンスでは、代わりに Postgres Chat Memory サブノードを使用し、メインプロセスとワーカーの両方から到達できるデータベースを指定します。

手順 6: システムメッセージ

エージェントの Options を開き、System Message を追加します。ここにジョブの説明を記述します。このテキストがワークフローで最も大きな効果を発揮します。

You are an infrastructure status assistant. Always call the status
tool before answering a question about whether something is running.
Never guess. If the tool returns an error, say so and stop.

「回答する前に必ず status ツールを呼び出す」と指定すると、実際に効果があります。これを指定しないと、すでに答えを知っていると考えるモデルはツールを呼び出さず、記憶に基づいて回答します。その回答は、インフラストラクチャが変更された時点で確実に誤りになります。

エージェントがループする理由と停止方法

Options の下には、デフォルト値が 10 の Max Iterations もあります。1 回のイテレーションは、1 回のモデル呼び出しと、コンテキストに返される 1 件のツール結果で構成されます。つまり、エージェントの 1 回の実行は 1 回の API 呼び出しではありません。最大 10 回の呼び出しが行われ、各呼び出しには増え続ける会話全体が入力として渡されます。

この値を下げてください。単一ツールのエージェントの多くは 2 回のイテレーションで完了します。3 または 4 に制限すれば、無限ループを、実行リストで確認できる明確な失敗に変えられます。

デバッグ中は Return Intermediate Steps を有効にしてください。最終出力に、エージェントが途中で実行したツール呼び出しが含まれるようになります。これにより、「モデルがツールを呼び出さなかった」のか、「ツールが有用な結果を返さなかった」のかを区別できます。運用開始前には無効に戻してください。これらのステップはエンドユーザーにとって不要な情報です。

シェルから実行の様子を確認します。

docker compose logs -f n8n

人が見ていないエージェントの無駄な実行を防ぐ

Chat Trigger の背後にあるエージェントには人が付き、回答が間違っているように見えると、その人が停止します。Schedule Trigger の背後にあるエージェントを監視する人はいません。ここで監視する対象はライセンス費用ではなく、モデルの利用費です。エージェント、ツール、メモリの各ノードは、無料のセルフホスト版で動作するためです。有料キーが必要な機能の大半は、チーム機能とガバナンス機能です。詳しくは、常時稼働 VPS での AI エージェントのコスト管理を参照してください。ここでは、4 つの設定で大部分を制御できます。

• モデルのサブノードで Maximum Number of Tokens に上限を設定し、1 回の応答が長時間実行されないようにします。
• Max Iterations は、タスクを完了できる最小の回数に設定します。
• ツールの応答を小さく保ちます。4,000 行の JSON を返すツールでは、その全体が次のモデル呼び出しに渡され、同じ実行内のそれ以降の呼び出しにも毎回渡されます。
• エージェントに本当にスケジュールが必要かを確認します。5 分ごとに実行するジョブは、1 日に 288 回起動します。1 回の実行にかかるコストに 288 を掛けた値が、実際のコストです。

反復している間は、ワークフローを無効化します。有効なワークフローで Schedule Trigger を使用すると、n8n が保存したバージョンに対して実行され続けます。そのバージョンが、画面に表示されているバージョンとは限りません。

FAQ

AI Agent ノードが実行されないのはなぜですか？

AI Agent ノードには、chat model のサブノードと、少なくとも 1 つの tool サブノードが必要です。model はあっても tool がないノードは、API を呼び出す前に失敗します。簡単な tool でもよいので 1 つ追加し、もう一度実行してください。

agent は回答しますが、tool をまったく呼び出しません。原因は何ですか？

ほとんどの場合、tool の Description フィールドが原因です。model は Description を読んで tool を選択するため、「HTTP Request」のような説明では、tool をいつ使うべきか判断できません。どのようなデータが返り、どの状況で役立つのかが分かるように書き換えてください。そのうえで、回答前にその tool を呼び出すよう agent に指示する行を System Message に追加します。

同じ質問でも、実行するたびに料金が異なるのはなぜですか？

model が実行するステップ数を選択するためです。各イテレーションでは、それまでの完全な会話と過去の tool 出力を再送信します。そのため、4 回のイテレーションを要する実行は、1 回の呼び出しの 4 倍よりも大幅に高くなります。Max Iterations はイテレーション数の上限です。Return Intermediate Steps を有効にすると、各実行で実際に使用したステップ数を確認できます。

editor では memory が機能しますが、production では機能しません。何が変わったのですか？

インスタンスが queue mode で実行されているか確認してください。Simple Memory は workflow 自体の実行データに履歴を保存します。このデータは別の worker process に引き渡されると保持されないため、production で実行中の workflow では履歴が失われます。Postgres Chat Memory サブノードに置き換えてください。このサブノードは、すべての worker が共有する database に履歴を保持します。