n8n-agents

n8n エージェント

n8n Agent ノード（@n8n/n8n-nodes-langchain.agent）は、モデル、メモリ、ツール、任意の出力パーサーをサブノードとして備えた、複数ターン対応の LLM ドライバーです。

Agent ノードと生のチャット補完の使い分け

判断基準：

• ツール呼び出し、複数ターンの推論、またはメモリが必要ですか？ Agent を使います。迷ったときの標準的な選択肢としても適しています。ワークフロー全体で Agent に統一するのは妥当で、アップグレードも容易になります。
• 可能な限り軽量な、単発のテキスト出力呼び出しが必要ですか？ チャットモデルのサブノード（OpenRouter Chat Model、OpenAI Chat Model、Anthropic Chat Model など）と組み合わせた Basic LLM Chain（@n8n/n8n-nodes-langchain.chainLlm）を使います。エージェントのループがなく、ツール／メモリ／パーサーのスロットもないため、デバッグが容易です。注：チャットモデルノードはサブノードであり、単独では実行されません。チェーンまたはエージェントに接続します。この場合も、統一したい場合は Agent を使えます。
• 自然言語の入力に基づいて、N 個の出力ブランチのいずれかに振り分けますか（AI がブランチを選ぶタスクですか）？ Text Classifier ノード（@n8n/n8n-nodes-langchain.textClassifier）を使います。カテゴリごとに 1 つ、合計 N 個の出力ハンドルがあり、下流のパスをそれぞれに直接接続できます。各カテゴリには名前と説明の両方が必要です（モデルは説明を基に選択するため、名前だけでは不十分です）。入力の境界ケースに対する堅牢性を高めるには、options.enableAutoFixing: true を設定します。チャットモデルのサブノード（OpenRouter Chat Model、OpenAI Chat Model など）と組み合わせます。この用途に Agent + Switch を選ぶ必要はありません。Text Classifier は、用途に特化した単一のノードです。
• ツールなしで構造化出力が必要ですか？ 将来的な拡張も考慮すると、Agent がより簡単な標準の選択肢です。軽量なノードを使いたい場合は、Basic LLM Chain でも outputParserStructured サブノードを使えるため、問題なく動作します。
• 画像／音声／動画の生成ですか？ プロバイダーを直接呼び出す場合は、そのプロバイダーのネイティブな単一呼び出しノード（OpenAI Image、Gemini Image、ElevenLabs など）を使います。アグリゲーター（OpenRouter、Together など）を経由する場合は、HTTP Request を使います。ネイティブなアグリゲーターノードはなく、メディア操作用のネイティブノードはプロバイダーのベース URL をハードコードしているためです。メディア生成を Agent でラップしないでください。詳しくは、下記の「バイナリデータと Agent の境界」を参照してください。

特定のタスクに特化した LangChain の「チェーン」／ユーティリティノードもあります。テキストから構造化フィールドを抽出する Information Extractor、3 方向に分岐する Sentiment Analysis、Summarization Chain、Basic LLM Chain などです。

ほとんどの LLM ステップでは、Agent を標準の選択肢として使えます。ツール、メモリ、反復処理を使わない単発のテキスト呼び出しで、より軽量なノードを明確に必要とする場合は、Basic LLM Chain を選びます。タスクに完全に一致する用途特化型ノードがある場合は、Information Extractor／Sentiment Analysis／Summarization Chain／Text Classifier を選びます。

必須事項

1. ツール名と説明はプロンプトの一部です。 モデルは名前と説明を基にツールを選びます。doStuff のような曖昧なツールノード名や、「データに対して何かを行う」といった不十分な説明は、気づかないうちに失敗する原因になります。モデルがツールをスキップしたり、誤って選択したり、パラメーターを幻覚したりする可能性があります。どちらも API 設計の一部として扱ってください。references/TOOLS.md を参照してください。
2. 構造化出力では、パースと自動修正の両方を行います。 autoFix: true を設定した outputParserStructured と、コーディング能力のある修正モデル（例：Claude Sonnet 4.6）を使うのが、本番環境での標準的なパターンです。

明確なデフォルト

• ツールの説明は、モジュール式のプロンプト断片です。 このツールの呼び出し方法に固有の内容は、システムプロンプトではなくツールの説明に記述します。システムプロンプトを簡潔に保ち、ツールを複数のエージェントで再利用できるようにします。references/SYSTEM_PROMPT.md を参照してください。
• 複数ステップの処理には、サブワークフローツール（toolWorkflow）を使います。 ワークフローを、型付きの fromAi() 入力を持つツールにすれば、分岐、エラー処理、サブワークフローを組み合わせられます。references/SUBWORKFLOW_AS_TOOL.md を参照してください。
• ユーザーに見える副作用を伴うツールは、人によるレビューを挟みます。 送信、支払い、返金、アカウント変更などが対象です。Slack／Chat／Discord／Telegram の承認ノードを介して実行を制御し、ツールの実行前に人が承認できるようにします。references/HUMAN_REVIEW.md を参照してください。

サブノードのパターン

Agent ノードには、メイン入力（プロンプトまたはユーザーメッセージ）とサブノード入力があります。

const aiAgent = node({
    type: '@n8n/n8n-nodes-langchain.agent',
    config: {
        name: 'Customer Support Agent',
        parameters: {
            promptType: 'define',
            text: '={{ $json.userMessage }}',
            options: {
                systemMessage: '...',
                passthroughBinaryImages: true,    // for vision / multimodal
            },
        },
        subnodes: {
            model: openRouterModel,
            memory: simpleMemory,
            tools: [generateImage, editImage, searchKnowledgeBase],
            outputParser: structuredParser,    // optional
        },
    },
})

4 つのサブノードスロット：

• model（必須）：言語モデルです。OpenAI、Anthropic、OpenRouter などが該当します。Completion 系ではなく、Chat Model 系を使用してください。
• memory（任意）：会話メモリです。これがない場合、呼び出しは毎回ステートレスになります。references/MEMORY.md を参照してください。
• tools（任意ですが、エージェントを使う主な目的です）：エージェントが呼び出せるツールです。references/TOOLS.md を参照してください。
• outputParser（任意）：構造化された JSON 出力を強制します。references/STRUCTURED_OUTPUT.md を参照してください。

トリガー

トリガーによって入力の形式が変わります。

• **Chat Trigger（@n8n/n8n-nodes-langchain.chatTrigger）**の availableInChat: true を有効にすると、キャンバスのチャットテスターで、エージェントの構築中に動作を試せます。入力は { chatInput, sessionId, files[] } です。メモリは sessionId をキーにするため、会話の継続が必要な箇所には必ず渡してください。ファイルは files[] 経由で渡されます。下記のバイナリのセクションを参照してください。本番環境での利用には適していないため、その用途には Slack／Discord／Teams／Telegram／Webhook を使用してください。

• Webhook：入力形式は任意で、デフォルトではセッションがありません。リクエスト本文にセッション ID または会話 ID を渡し、メモリノードに引き渡すことで、会話の継続を管理します。

• 外部チャットサービス（Slack、Discord、Teams、Telegram）：返信を投稿するチャットトリガー付きのワークフローでは、ボット自身のユーザー ID を必ず除外してください。除外しないとループが続き、n8n がクラッシュする可能性があります。チャットサービスが対応している場合は、トリガーレベルでのフィルタリングを推奨します（Slack の options.userIds は除外リストです）。対応していない場合は、トリガーの直後にある最初のノードでフィルタリングします。サービスごとに動作が異なるため、references/CHAT_AGENT_PATTERNS.md を参照してください。ループ防止フィルターを追加したうえで、シンプルなボット（トリガー → エージェント → 返信）は 1 つのワークフローで問題ありません。ローディング表示、サブエージェント、複数サービス間での再利用、堅牢なエラー処理が必要になったら、「シェル」ワークフローとエージェントコアのサブワークフローに分割してください。

• 手動／スケジュール：臨時の呼び出しに使用します。以前の実行を明示的に継続する場合を除き、メモリが役立つことはほとんどありません。

• Execute Workflow Trigger（サブワークフロー）：あるエージェントが別のエージェントのツールになる場合に使います。トリガーで宣言された入力を契約として扱ってください。

バイナリとエージェントの境界

passthroughBinaryImages: true を指定すると、モデルはアップロードされたファイルを（視覚機能を通じて）見ることができます。ただし、ツールはバイナリを受け取れません。また、fromAi() のパラメーターは JSON のみです。ツールでは、AI 以外のバインディングを通じても Base64 は受け付けられません。

回避策として、エージェントの実行前にアップロードファイルをストレージに保存し、ストレージキーをシステムプロンプトに注入します。ツールは文字列パラメーターとしてキーを受け取り、内部でファイルを再取得します。完全なパターンについては、n8n-binary-and-data の references/AGENT_TOOL_BINARY.md を参照してください。

出力側では、エージェントの出力フォーマッターはテキスト形式です（outputParser を接続している場合は構造化テキスト形式です）。モデルがバイナリ（画像データ、音声データ、動画）を返しても、エージェントからは一切出力されません。後続処理で取り出せるものは何もなく、エージェントの後に Code ノードや Set ノードを使って復元しようとしても機能しません。メディアを一度だけ生成する場合は、@n8n/n8n-nodes-langchain.googleGemini や @n8n/n8n-nodes-langchain.openAi など、プロバイダーのネイティブな単一呼び出しノードを直接使ってください。

例外として、メディア処理が実際にエージェントの一部となる場合（複数あるツールの1つで、会話のコンテキストに応じて選択される場合や、すでに生成された画像を編集する場合）には、結果をストレージにアップロードしてキーまたは URL を返すツールのサブワークフローを使う回避策があります。パターンについては、n8n-binary-and-data の references/AGENT_TOOL_BINARY.md を参照してください。これをデフォルトで使わないでください。アップロード、キーの受け渡し、再取得という経路には、通常は必要のないノードとストレージへの依存が追加されます。エージェントによるツール選択がオーケストレーション上必要な場合にのみ使用してください。

システムプロンプトとツールの説明の使い分け

システムプロンプトに記載する内容	ツールの説明に記載する内容
ペルソナ、役割、口調	このツールが具体的に何をするか
出力形式のルール（「Markdown で回答する」など）	このツールを他のツールより優先して使う場面
拒否や安全性に関する動作	各パラメーターの意味と期待される形式
表示プロトコル（「![]() Markdown で画像を表示する」など）	適切な呼び出しと不適切な呼び出しの例
共通のコンテキスト（現在の日付、ユーザーの役割）	ツール固有の注意点（レート制限、エッジケースなど）
ツール間のフロー（「生成後は必ず表示プロトコルを使って表示する」など）	ツール固有の入力変換

メリット：ツールを再利用しやすくなります。説明が適切なツールは、組み込む先のエージェントを問わず機能します。システムプロンプトは役割と共通の動作に集中できます。

より詳しいガイダンスと実例については、references/SYSTEM_PROMPT.md と references/TOOLS.md を参照してください。

ツールの選択：4つの種類

目的を満たす中で、最も軽量な選択肢を使ってください。

• ネイティブの n8n ツールノードがありますか？（例：slackTool、gmailTool、calculatorTool）それを使ってください。設定の手間が最小限です。
  • ネイティブノードに必要な操作がない、またはカスタムパラメーターが必要ですか？（例：ノードから利用できない Notion エンドポイント、標準外のヘッダー、異なるページネーション形式）サービスの「Predefined Credential Type」を指定した HTTP Request Tool を使ってください。既存の OAuth／API キー認証情報を再利用でき、API にフルアクセスでき、カスタム認証コードも不要です。
• 複数ステップのロジックが必要ですか？ または、プロジェクト内にあるサブワークフローを再利用しますか？ サブワークフローをツールとして使います（toolWorkflow）。ワークフローとして構築できるものなら、型付きの fromAi() 入力を持つツールにできます。n8n で最も強力な選択肢なので、迷った場合はデフォルトでこちらを選んでください。references/SUBWORKFLOW_AS_TOOL.md を参照してください。
• エージェントが直接オーケストレーションする外部 HTTP API を呼び出しますか？ HTTP Request Tool を使ってください。ロングポーリングコールバックを使う低速な非同期処理にも適しています。
• 公開済みで、MCP からアクセスできるワークフローとしてツールがすでにありますか？ MCP ツールを使ってください。複数のワークフローにまたがるエージェント機能に役立ちます。n8n-extending-mcp を参照してください。

各選択肢の詳細なガイダンスと fromAi() パラメーターの接続方法については、references/TOOLS.md を参照してください。

人によるレビュー

ツールに人によるレビューを追加するか省略するかを決める前に、ユーザーに確認してください。承認が必要かどうかは、影響範囲、監査要件、モデルへの信頼度などに基づく製品／ポリシー上の判断であり、あなたよりもユーザーのほうが適切に判断できます。質問を提示し、以下の基準に基づいて推奨したうえで、ユーザーに決定してもらってください。

ツールの実行前に人の承認が必要な場合（送信、支払い、返金、アカウント変更、顧客向けの操作など）は、レビュー用ツールノードでラップします。例：slackHitlTool、discordHitlTool、telegramHitlTool、gmailHitlTool など。（n8n のノード名では human-in-the-loop パターンに Hitl を使い、UI では「人によるレビュー」と呼ばれます。）レビュー用ノードは、ai_tool 接続上でラップ対象のツールとエージェントの間に配置します。ラップ対象のツールの ai_tool 出力をレビュー用ノードに接続し、レビュー用ノードの ai_tool 出力をエージェントに接続します。エージェントが呼び出しを行うと、レビュー用ノードが承認まで一時停止し、承認されるとラップ対象のツールが実行されます。

次の場合は、人によるレビューをデフォルトで適用するか、推奨してください。

• ツールが送信、支払い、返金を行う場合、またはユーザーに見える状態を変更する場合。
• 承認者が会話相手と異なる場合（マネージャーが顧客向けの操作を承認する、サポートチームが顧客起点の返金を承認するなど）。
• トリガーが非対話型（注文、フォーム、スケジュール）で、ツールの実行に人の承認が必要な場合。

承認メッセージには、モデルが言い換えたテキストではなく、ラップ対象のツールが実際に受け取る実際のパラメーターを表示してください。$tool.parameters.<name> を直接使うか、$tool.parameters を反復処理してすべてのパラメーターを一覧表示します。承認テキストの生成に fromAi() を使わないでください。承認するのは、実際の呼び出しではなく言い換えです。ボタンのラベルは、実際の値を使ってカスタマイズします。例：Approve {{ $tool.parameters.amount }} refund。

完全な設定パターン、プラットフォームごとのセットアップ、複数チャンネルの承認者パターンについては、references/HUMAN_REVIEW.md を参照してください。

出力の解析：いつ、どのように行うか

後続処理で自由形式のテキストではなく構造化データが必要な場合は、outputParser サブノードを追加してください。

const parser = outputParser({
    type: '@n8n/n8n-nodes-langchain.outputParserStructured',
    config: {
        parameters: {
            schemaType: 'manual',
            inputSchema: JSON.stringify({
                type: 'object',
                properties: {
                    score: { type: 'integer', minimum: 1, maximum: 5 },
                    category: { type: 'string', enum: ['bug', 'feature', 'question'] },
                    reason: { type: 'string' },
                    tags: { type: 'array', items: { type: 'string' } },
                },
                required: ['score', 'category', 'reason'],
            }),
            autoFix: true,
            customizeRetryPrompt: true,
            prompt: '...retry instructions...', // generally leave as default
        },
        subnodes: {
            languageModel: fixerModel,    // coding-capable model, e.g. Claude Sonnet 4.6
        },
    },
})

1. jsonSchemaExample ではなく、実際の JSON スキーマを使って schemaType: 'manual' を指定してください。 例だけでは、任意フィールド、列挙型、値の範囲、配列の制約を表現できないため、データ構造が少し複雑になっただけで対応できなくなります。スキーマを使えば、必須フィールドと任意フィールドを指定し、列挙型を定義し、数値や文字列の形式を制約できるほか、モデルが従うべきルールも明確になります。制約が増えることはないと確信できる一度限りのデータ構造に限り、例とともに schemaType: 'fromJson' を使ってください。
2. autoFix: true を指定すると、解析に失敗した場合に再試行します。 修正用サブノードとして、コーディングに対応できるモデル（例：Claude Sonnet 4.6 など）を接続してください。スキーマに照らして不正な JSON を修正するのは、構造化出力／コーディングのタスクです。性能の低いモデルや汎用モデルでは、再試行後も不正な出力になりやすく、目的を果たせないことがあります。

カスタムの再試行プロンプトを含む完全なパターンについては、references/STRUCTURED_OUTPUT.md を参照してください。

メモリ：簡単な考え方

• メモリなし： ステートレスです。単発のタスク（分類、要約）に適しています。
• memoryBufferWindow： メモリキーごとに直近 N 件のメッセージを保持し、n8n の内部ストアを介して実行をまたいで永続化します。キーには sessionKey に割り当てた任意の式を使います。チャットトリガーでは sessionId が自動的に設定されますが、任意の値をキーにできます（Slack の thread_ts、Webhook の会話 ID、複数テナントの複合キーなど）。チャットメモリのデフォルトです。「ウィンドウ」は、コンテキストに保持されるメッセージ数のスライディング上限であり、永続化の範囲ではありません。
• memoryPostgres／memoryRedis／類似のもの： エージェントの外部からメモリをクエリしたり読み取ったりする必要がある場合に使います。たとえば、独自の UI で会話履歴を表示する場合、過去のチャットを分析する場合、別のシステムとメモリを共有する場合などです。それ以外の場合は、memoryBufferWindow で十分です。

トリガーからメモリまで一貫して安定したキーを渡してください。そうしないと、会話が混線します。references/MEMORY.md を参照してください。

RAG（検索拡張生成）

n8n には LangChain の RAG プリミティブ（ドキュメントローダー、テキストスプリッター、埋め込み、ベクトルストア、リトリーバー、再ランカー）が用意されています。各要素は機能しますが、エンドツーエンドのレシピ（「どのベクトルストアを使うか」「どのようにチャンク分割するか」「いつ再ランクするか」）は、データの形状と規模に大きく左右されます。

このスキルでは、RAG に関する見解を意図的に最小限にしています。RAG の詳細については、references/RAG.md を参照してください。

参考ファイル

ファイル	読むタイミング
references/TOOLS.md	エージェントにツールを追加する場合、4 種類のツールから選ぶ場合、ツール名や説明を書く場合
references/SUBWORKFLOW_AS_TOOL.md	toolWorkflow を介してサブワークフローをエージェントツールとして接続する場合、fromAi オーバーライドをマッピングする場合
references/SYSTEM_PROMPT.md	システムプロンプトを作成またはリファクタリングする場合、システムプロンプトとツールの説明のどちらに記述するかを判断する場合
references/STRUCTURED_OUTPUT.md	JSON 出力を強制する場合、autoFix の再試行を設定する場合、後続の処理で検証する場合
references/MEMORY.md	メモリの種類を選ぶ場合、永続化や sessionId の処理を行う場合
references/RAG.md	検索拡張エージェントを構築する場合。意図的にスタブとなっています
references/HUMAN_REVIEW.md	ツールに人間による承認を追加する場合、承認メッセージを設定する場合、複数チャネルの承認者パターンを実装する場合
references/CHAT_AGENT_PATTERNS.md	Slack、Discord、Teams、Telegram、または任意のカスタムチャット画面でチャットエージェントを構築する場合、複数ワークフローのシェル＋コア＋サブエージェントのトポロジーを実装する場合

アンチパターン

アンチパターン	問題点	修正方法
汎用的なツール名（doStuff、runQuery）	モデルがどのツールを選べばよいか判断できず、ツールを使わなかったり、パラメーターを幻覚で補ったりします	動詞から始まる具体的な名前にします：顧客データベースを検索、Veoで画像を生成
空、または1行だけのツールの説明	モデルがいつ呼び出すべきかわからず、適切に選択できません	実際に役立つ説明を書きます：何をするか、いつ使うか、パラメーターの意味
すべてをシステムプロンプトに詰め込む	プロンプトが肥大化し、再利用できず、ツールごとのガイダンスが埋もれます	ツール固有の指示はツールの説明に移し、システムプロンプトはペルソナと全体的なルールに絞ります
サブワークフローで実現できる処理にコードノードのツールを使う	再利用できず、独立してテストできず、分岐との組み合わせもできません	適切なサブワークフローで toolWorkflow を使用します
バイナリをツールに直接渡す	機能しません。バイナリはツールの境界を越えられません	あらかじめストレージに置き、キーを fromAi で渡して、ツール内で取得します。n8n-binary-and-data を参照してください
autoFix を指定せずに outputParserStructured を使う	モデルの出力に問題が1つあるだけでワークフローが失敗します	低コストの修正用モデルとともに autoFix: true を設定します
sessionId をハードコードする、または指定しない	会話が混在したり、メモリーが一致しなくなったりします	トリガーから渡される sessionId を、メモリーとツールに一貫して渡します
分岐させる代わりに、ほぼ同一のツールを2つ用意する	モデルが混乱し、選択が非決定的になります	パラメーターに応じて内部で分岐するツールを1つ用意します
複数のワークフローで再利用する、または頻繁に変更するシステムプロンプトをハードコードする	編集のたびに再公開が必要で、ワークフロー間で共有できず、調整の履歴がノードのJSON内に蓄積されます	Data Table に保存し、実行時に読み込みます
画像／音声／動画の生成を Agent でラップする	バイナリがツールや出力フォーマッターを通じて流れず、Agent を使っても利点がないのにノードが増えます	プロバイダーのネイティブな単一呼び出しノード（OpenAI Image、Gemini Image、ElevenLabs）を直接使います。アグリゲーターを経由する場合に限り、HTTP Request を使います
自然言語の入力を振り分けるために Agent + Switch を使う	Text Classifier なら組み込みの出力分岐を N 個備えた1つのノードで済むところに、定型プロンプトを伴う2つのノードが必要になります	Text Classifier（@n8n/n8n-nodes-langchain.textClassifier）を使います。各カテゴリに専用の出力ハンドルがあるので、後続の経路に直接接続します
人による確認なしに、ユーザーに見える状態を変更するツール（送信、支払い、返金）	Agent が誤った推論に基づいて、取り消せない操作を実行します	チャネルに適した確認用ツールノード（Slack/Chat/Discord/Telegram）でラップし、実際のパラメーターを $tool.parameters で表示します
fromAi() で確認メッセージを埋める	モデルが言い換えるため、値ではなく文章を確認してしまいます	$tool.parameters.<name> を直接使い、呼び出し内容をそのまま確認できるようにします
ボット自身のユーザー ID を除外せずに、チャットトリガーのエージェントワークフローで返信を投稿する	ボット自身のメッセージがワークフローを再トリガーし、レート制限または n8n の同時実行制限に達するまで、実行回数とトークンを消費する無限ループが発生します	利用可能な場合は、トリガーレベルでフィルタリングします（Slack Trigger の options.userIds は除外リストなので、そこにボット ID を指定します）。それ以外の場合は、トリガー直後の最初のノードで $json.user !== '<BOT_USER_ID>'（または各サービスに相当する値）を条件にフィルタリングします。複雑さにかかわらず、返信を送信するあらゆるチャットトリガーのワークフロー（Slack、Discord、Teams、Telegram）で必須です。サービスごとの動作については references/CHAT_AGENT_PATTERNS.md を参照してください
エージェントが Block Kit を返したときに、Slack ノードの blocksUi に blocks 配列をそのまま渡す	Slack ノードは入力をエラーも警告もなく受け付けますが、リッチコンテンツのないメッセージを投稿します	実際の配列を値として { "blocks": [...] } でラップします。文字列化した配列は使わないでください。式：={{ { "blocks": $('Agent').item.json.output.blocks } }}。n8n-node-configuration の references/COMMS_NODES.md「Block Kit messages」を参照してください