著者 n8n AI AgentをVPSに構築する方法
n8nで動くAI agentを構築します。version 1.82.0以降のTools Agent、Claudeのcredential、HTTP Request tool、memory、trigger、コストを抑える設定を順に解説します。
n8n AI agentとは何か、chainとの違い
n8n AI agentは、サブノードを接続した1つの AI Agent ノードです。サブノードには、1つのチャットモデル、1つ以上のtool、任意のmemoryを指定します。自然言語で目標を指定すると、モデルは回答できるまで、呼び出すtoolとその順序を決定します。以下では、この1つの考え方に関する設定をすべて説明します。
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は存在しません。
Step 1: トリガーを選択する
会話エージェントには、Chat Trigger ノードを追加します。構築中は Make Chat Publicly Available をオフにします。これにより、エディターのチャットパネルからのみアクセスできます。エージェントの完成後、認証方式を決定してからオンにします。
Chat Trigger は、chatInput というフィールドをエージェントに渡します。この名前はステップ 3 で重要です。名前を間違えることが、最も多い初回の失敗原因です。
無人エージェントには、代わりに Schedule Trigger または Webhook ノードを使用します。どちらも chatInput を生成しないため、プロンプトを自分で記述します。
ステップ 2: モデル認証情報
キャンバスに AI Agent ノードを配置します。n8n はその直下に空の Chat Model コネクタをすぐに表示します。そこに Anthropic Chat Model サブノードを接続します。
platform.claude.com の Anthropic Console で、Settings、次に API Keys を開いて認証情報を作成します。キーが表示されるのは1回だけです。API の使用料金はトークン単位で発生し、Claude.ai のサブスクリプション料金とは別です。そのため、初回実行前にアカウントの請求設定を完了する必要があります。
モデルは会社単位ではなく、エージェント単位で選択します。1つのツールで情報を検索して報告するエージェントであれば、Haiku で問題なく動作します。2026年7月時点の料金は、入力トークン100万個あたり$1、出力トークン100万個あたり$5です。エージェントが複数のツールを使用し、それらをまたいで計画する必要がある場合は、Sonnet に変更します。避けるべきなのは、安価なモデルが誤ったツールを4回呼び出し、適切なモデルが正しいツールを1回呼び出すよりも高くつくことです。
サブノードのオプションで Maximum Number of Tokens を設定します。これは、モデルが生成する各レスポンスの長さを制限します。大きなデフォルト値のままにすると、混乱した1回の実行で非常に長い回答が生成され、その分の料金が発生する可能性があります。
n8n のドキュメントにある、誰もがつまずく注意点が1つあります。サブノード内の式は常に最初の入力アイテムを基準に解決され、アイテムごとには解決されません。アイテムごとの式は、ルートノードのプロンプトフィールドに記述します。
Step 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つから始めてください。正常に動作するツール1つのほうが、設定途中のツール4つより多くのことを確認できます。
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 と呼んでください」と指示します。モデルは会話、入力データ、他のツールの結果を調べて、その値を探します。チャットワークフローでは、単にユーザーに尋ねる場合もあります。
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サブノードを使用し、メインプロセスとワーカーの両方からアクセスできるデータベースを指定します。
Step 6: System Message
エージェントの 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 の背後にあるエージェントは、監視する人がいません。詳しい説明は 常時稼働 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は説明を読んでtoolを選択するため、「HTTP Request」のような説明では、toolを使用する状況が分かりません。どのようなデータが返り、どの状況で役立つのかを説明する内容に書き換えてください。その後、agentに回答前にそのtoolを呼び出すよう指示する行をSystem Messageに追加してください。
同じ質問なのに、実行ごとに料金が異なるのはなぜですか？
modelが実行するステップ数を選択するためです。各イテレーションでは、それまでの完全な会話履歴と、以前のtool出力が再送信されます。そのため、4回のイテレーションが必要な実行では、1回の呼び出しの4倍を大きく上回る料金がかかります。Max Iterationsはその上限を設定し、Return Intermediate Stepsでは、実行時に実際に使用されたステップ数を確認できます。
editorではmemoryが機能しますが、productionでは機能しません。何が変わったのですか？
インスタンスがqueue modeで実行されているか確認してください。Simple Memoryはworkflow自体のexecution dataに履歴を保存します。このデータは別のworker processに渡されると保持されないため、実行中のproduction workflowでは履歴が失われます。すべてのworkerが共有するdatabaseに履歴を保存するPostgres Chat Memoryサブノードに置き換えてください。