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

n8n AI エージェントとは何か、チェーンとどう異なるか

n8n AI エージェントは、サブノードを接続した単一の AI Agent ノードです。サブノードには、1 つのチャットモデル、1 つ以上のツール、必要に応じてメモリを指定します。自然言語で目標を指定すると、モデルが回答できるまで、呼び出すツールとその順序を判断します。以下では、この 1 つの考え方を中心に設定を説明します。

チェーンは逆の動作をします。Basic LLM Chain では手順を自分で決め、モデルはテキストを生成するだけです。エージェントではモデルが手順を決めるため、同じ質問でも、ある日はモデル呼び出しが 1 回で済み、別の日には 9 回必要になることがあります。この違いが、このガイドのすべての設定に影響します。このループの考え方が n8n の機能としてではなく概念として初めての場合は、ノードで組み立てる前に、一度手作業で実装することをおすすめします。ノードを使うと、このガイドの残りで検討することになる正確な処理部分が隠れるためです。

この説明では、管理下のマシンで n8n がすでに HTTPS の背後で動作していることを前提とします。まだ構築していない場合は、実際の証明書を使用して Docker で n8n をセルフホストする手順から始めてください。これから保存する API key には、その手順で必須とされている encryption key のバックアップが必要です。エージェントを使わない構成については、Webhook の要約処理とスケジュール実行する分類処理を扱った Claude と n8n のワークフローパターンを参照してください。

ここで使用しているフィールド名を信頼する前に、バージョンを確認してください。n8n では AI ノードが頻繁に変更されます。

docker compose exec n8n n8n --version

Version 1.82.0 では、agent-type 設定が非推奨となり、代わりに Tools Agent が導入されました。Legacy v1 ノードにはまだこの設定があります。n8n のドキュメントでは、このノードバージョンの削除は n8n 3.0 に予定されています。

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

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

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

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

手順 2: モデルの認証情報

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

認証情報は、Claude Console の platform.claude.com で、Settings、API keys の順に開いて作成します。キーは1回だけ表示されます。キーの作成時には有効期限も選択する必要があります。無人エージェントはキーの有効期限が切れた日に停止するため、その日付を確認できる場所に記録してください。無人エージェントでは、workspace にスコープを限定した service account key を使用します。これにより、リクエストごとに別の workspace ヘッダーを指定する必要がありません。

API の利用料金はトークン単位で請求されます。支払い方法は、2026年10月31日時点の Claude プランによって異なります。Max、Ultra、Team プランには月次の API クレジットが含まれます。Max は $100、Ultra は $200、Team は共有プールで最大 $500 です。Max または Ultra では Settings > Billing から、Team では Organization settings > Billing から、Console の organization をプランにリンクしてクレジットを取得します。Console に支払い方法を追加する必要はありません。新規サブスクライバーは、プラン加入後7日が経過すると取得できます。未使用のクレジットは各請求サイクルの終了時に失効します。年次プランでは毎月失効します。含まれるクレジットを使い切ると、リクエストは購入済みクレジットに対して引き続き実行されます。auto-reload を有効にすると追加購入できます。請求書払いの organization には超過分が請求されます。前払いの organization でクレジットがなくなると、リクエストは停止します。API の利用料金が Claude プランに請求されることはありません。Free、Pro、Enterprise プランには月次の API クレジットが含まれないため、API はサブスクリプション料金とは別に請求されます。

モデルは会社単位ではなく、エージェント単位で選択します。1つのツールで情報を検索して報告するエージェントなら、Haiku で十分に動作します。現行バージョンの Haiku 5.5 は、2026年10月12日時点で入力トークン100万あたり $0.10、出力トークン100万あたり $0.50 です。プロンプトが100,000トークンを超えるリクエストでは、それぞれ $0.50 と $2.50 に上がります。長いメモリ領域や大きなツール結果によって、この条件に該当することがあります。エージェントが複数のツールを使い、それらをまたいで計画する必要がある場合は、Sonnet に切り替えます。避けたいのは、安価なモデルが誤ったツールを4回呼び出し、適切なモデルが正しいツールを1回呼び出すより高くつくことです。

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

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

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

Source for Prompt (User Message) パラメーターには、次の 2 つの設定があります。

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

前段に Webhook node を置く場合、POST body は $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.

手順 4: エージェントにツールを 1 つだけ与える

n8n のドキュメントでは、AI Agent ノードに少なくとも 1 つのツールのサブノードを接続する必要があります。ただし、現在のノードコード（version 3.1）は、chat model がない場合にのみ実行を拒否します。どちらの場合でも、まずはツールを 1 つ追加してください。中途半端に設定した 4 つのツールより、正常に動作する 1 つのツールのほうが多くの情報を得られます。ツールのないエージェントは、コストが高いだけの chain です。

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

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

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

ツールの Description フィールドは、同僚向けのドキュメントではありません。model は、このツールが関係するかどうかを判断するとき、ツール名およびパラメータースキーマとともにこの説明を読みます。何が返るかを、簡潔な文で記述してください。「監視対象の 1 つのサービスについて、現在の up または down の状態と停止時間を JSON で返します。」

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

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

引数は key で、その後に任意の description、type、defaultValue が続きます。key は 1 文字以上 64 文字以下で、英字、数字、アンダースコア、ハイフンを使用します。type は string、number、boolean、json のいずれかで、デフォルトは string です。より完全な呼び出しは次のようになります。

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

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

Web 検索は一般的な 2 つ目のツールです。これは別の HTTP endpoint にすぎないため、有料の検索 API ではなく自分の SearXNG インスタンスをこの同じノードの接続先にできます。ただし、取得したすべてのページは信頼できないテキストとして扱い、プロンプト内に取り込まれることを前提にしてください。

ステップ 5: メモリとエージェントが以前の内容を忘れる理由

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

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

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

n8n が queue mode で動作している場合、Simple Memory はアクティブな本番ワークフローでは機能しません。履歴を、workflow ID と session ID をキーにしたプロセスローカルの singleton Map に保存し、worker 間でそのメモリを共有しないためです。queue mode のインスタンスでは、代わりに Postgres Chat Memory サブノードを使用し、main process と worker の双方から到達できるデータベースを指定します。

手順 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 には Max Iterations もあります。デフォルトは 10 です。1 回の反復は 1 回のモデル呼び出しに相当し、ツールを要求するか、最終回答を返します。ツールの結果は次の呼び出しに渡されます。つまり、エージェントの 1 回の実行は 1 回の API 呼び出しではなく、最大 10 回の呼び出しで構成されます。各呼び出しには、増加し続ける会話全体が入力として含まれます。

この値を下げてください。単一のツールを使うエージェントの多くは 2 回の反復で完了します。上限を 3 または 4 にすると、暴走するループを、実行リストで確認できる明確な失敗に変えられます。

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

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

docker compose logs -f n8n

人が監視しないエージェントの無駄な実行コストを抑える

Chat Trigger の背後にあるエージェントには人が付き、回答が誤っているように見えれば停止します。Schedule Trigger の背後にあるエージェントを監視する人はいません。ここで管理するのはライセンス費用ではなく、モデルの実行コストです。エージェント、ツール、メモリの各ノードは無料の self-hosted edition で動作するためです。有料キーが必要な機能の多くはチーム機能とガバナンス機能です。詳しくは 常時稼働する 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 サブノードが必要です。これがない場合、API を呼び出す前に「Please connect a model to the Chat Model input」と表示されて停止します。n8n のドキュメントでは、少なくとも 1 つのツールサブノードも必須とされています。モデルを接続してもノードが実行されない場合は、簡単なものでもよいのでツールを 1 つ接続して、もう一度実行してください。

エージェントは回答しますが、ツールをまったく呼び出しません。何が問題ですか？

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

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

モデルがステップ数を選択するためです。各反復では、それまでの会話全体が再送信されます。以前のツール出力も含まれます。そのため、4 回の反復が必要な実行では、4 回すべての API 呼び出しにおける入力トークンと出力トークンが課金対象になります。Max Iterations は反復回数の上限です。Return Intermediate Steps を有効にすると、実行で実際に使用したステップ数を確認できます。

エディターではメモリが機能しますが、本番環境では機能しません。何が変わったのですか？

インスタンスが queue mode で動作しているか確認してください。Simple Memory は、workflow ID と session ID をキーにしたプロセスローカルの singleton Map に履歴を保存します。そのため、別々の worker process では履歴を共有できません。Postgres Chat Memory サブノードに切り替えてください。これは、すべての worker が共有するデータベースに履歴を保存します。