n8n-agents

n8n エージェント

n8n AI Agent ノード（@n8n/n8n-nodes-langchain.agent）は、モデル、メモリ、ツール、および任意の出力パーサー用のサブノードを備えた、複数ターンに対応する LLM ドライバーです。このスキルでは、エージェントとその周辺にある LangChain ファミリーを設計するための詳細なガイドを提供します。「ワークフローのどこにエージェントを組み込むか」という概要については、n8n-workflow-patterns ai_agent_workflow.md をご覧ください。このスキルではさらに一歩踏み込み、適切な構築方法を解説します。

ノードタイプの形式について：ワークフロー JSON では、LangChain ノードは長い形式の @n8n/n8n-nodes-langchain.*（.agent、.lmChatOpenAi、.memoryBufferWindow、.outputParserStructured、.toolWorkflow、.toolHttpRequest、.toolCode）を使用します。get_node／validate_node を呼び出す際は、短い形式（nodes-langchain.agent）を使用してください。形式のルールについては、n8n-mcp-tools-expert をご覧ください。

---

まず適切なノードを選ぶ

単発の分類や抽出タスクでエージェントを使うのは、最もよくある過剰構築です。何かを接続する前に判断してください。

必要なこと…	使用するもの	理由
ツールを呼び出す、複数ターンにわたって推論する、またはメモリを保持する	AI Agent（.agent）	モデル＋ツール＋メモリ＋任意のパーサーという完全なループです。標準化を優先したい場合の既定値としても適しています。
ツールなしで、単発のテキスト入力からテキストを出力する	Basic LLM Chain（.chainLlm）	エージェントのループがなく、デバッグも容易です。outputParserStructured サブノードも引き続き使用できます。
自然言語の入力を N 個の分岐のいずれかに振り分ける	Text Classifier（.textClassifier）	1 つのノードに N 個の出力ハンドルがあり、それぞれに直接後続ノードを接続できます。Agent＋Switch ではありません。
自由記述のテキストから構造化フィールドを抽出する	Information Extractor（.informationExtractor）	スキーマを使ったフィールド抽出に特化しています。
肯定／中立／否定の 3 分類	Sentiment Analysis（.sentimentAnalysis）	分岐出力が組み込まれています。
長いドキュメントを要約する	Summarization Chain（.chainSummarization）	Map-Reduce による要約が組み込まれています。
画像／音声／動画を生成する	プロバイダーのネイティブな単一呼び出しノード（OpenAI、Gemini、ElevenLabs…）	メディア生成をエージェントで包むのは絶対に避けてください。「バイナリデータとエージェントの境界」をご覧ください。

**Text Classifier の詳細（Agent＋Switch のアンチパターン）：**各カテゴリには、名前と説明の両方が必要です。モデルは名前ではなく説明を基に振り分けます。説明のないカテゴリは、コイントスのように選ばれてしまいます。エッジケースへの対応力を高めるには、options.enableAutoFixing: true を設定してください。ノード 1 つ、分岐 N 個で完了です。Text Classifier が標準で行う処理のために、「判断」する Agent と「振り分ける」Switch を使うと、定型文を含むプロンプトに加えてノードが 2 つ必要になります。

チャットモデルノード（.lmChatOpenAi、.lmChatAnthropic、.lmChatOpenRouter など）はサブノードであり、単独では実行されません。ai_languageModel 接続を介して、チェーン、エージェント、分類器、または抽出器に接続します。

サブノードパターン

エージェントにはメイン入力（プロンプト／ユーザーメッセージ）と、最大4つのサブノードスロットがあります。それぞれ専用の ai_* 接続タイプで接続します。

スロット	接続タイプ	必須？	ノードの例
model	ai_languageModel	はい	.lmChatOpenAi、.lmChatAnthropic、.lmChatOpenRouter
memory	ai_memory	任意	.memoryBufferWindow、.memoryPostgresChat
tools	ai_tool	任意（ただしエージェントの要となるもの）	slackTool、.toolWorkflow、.toolHttpRequest、.toolCode
outputParser	ai_outputParser	任意	.outputParserStructured

サブノードは、サブノード自身を接続元、エージェントを接続先として接続します。ワークフロー JSON では、接続はサブノード側に ai_* タイプをキーとして保持されます。

"Main LLM": {
  "ai_languageModel": [[{ "node": "AI Agent", "type": "ai_languageModel", "index": 0 }]]
},
"Simple Memory": {
  "ai_memory": [[{ "node": "AI Agent", "type": "ai_memory", "index": 0 }]]
},
"Search customer DB": {
  "ai_tool": [[{ "node": "AI Agent", "type": "ai_tool", "index": 0 }]]
}

複数のツールはすべて同じ ai_tool のインデックス 0 に接続します。個別のインデックスに分けて接続するのではなく、積み重ねます。n8n_update_partial_workflow では、sourceOutput: "ai_tool" を指定した addConnection オペレーションを使って、それぞれを接続します。エージェントは最終回答を $json.output に格納します（.text でも .response でもありません）。後続ノードでは {{ $json.output }} を読み取ります。

ステートレスなエージェントコアのノードオブジェクトを含む完全なスニペットについては、EXAMPLES.md をご覧ください。

---

絶対に守るべき2つのこと

1. **ツール名と説明はプロンプトの一部です。**モデルはツール名と説明を読んでツールを選択します。それ以外の情報は参照しません。名前が tool1 で説明が空のツールは、モデルから見えません。スキップされたり、誤って選択されたり、パラメーターが幻覚されたりします。通常、エラーは発生しません。ただ「ツールを使ってくれない」エージェントになるだけです。どちらも API 設計の一部として扱ってください。→ TOOLS.md
2. 構造化出力はパースに加えて自動修正も必要です。autoFix: true を設定し、コーディングに対応した修正モデルを指定する outputParserStructured が、本番環境向けのパターンです。自動修正がなければ、不正な JSON レスポンスが1つあるだけでワークフロー全体が停止します。→ STRUCTURED_OUTPUT.md

---

推奨されるデフォルト設定

• **ツールごとの使い方は、システムプロンプトではなくツールの説明に記載します。**特定のツールの呼び出し方に関することはすべてツールの説明に記載します。そうすればエージェント間で共有でき、システムプロンプトも簡潔に保てます。→ SYSTEM_PROMPT.md
• **複数ステップが必要な場合は、サブワークフローツール（.toolWorkflow）を使います。**どのワークフローも、型付きの $fromAI() 入力を持つツールにでき、分岐、エラー処理、再利用にも対応します。迷った場合は、こちらをデフォルトにしてください。→ SUBWORKFLOW_AS_TOOL.md および n8n-subworkflows。
• **ユーザーに見える副作用を伴うツールには、人間によるレビューを組み込みます。**送信、支払い、返金、アカウント変更は承認ノードを通し、ツールが実行される前に人間が承認するようにします。→ HUMAN_REVIEW.md
• maxIterations を増やします。デフォルトのツール呼び出し上限は低く（ほとんどのバージョンで1桁）設定されています。ツールを1つだけ使うエージェントには十分ですが、1ターンで複数の呼び出しを連鎖させるエージェントには低すぎます。「最大反復回数に到達しました」や空の出力として表面化します。options.maxIterations に現実的な上限を設定してください（特化型のサブエージェントでは15、幅広い用途のオーケストレーターでは50～200）。
• **システムプロンプトに {{ $now }}（または {{ $now.format('DDDD') }}）で現在の日付を入れます。**日付をハードコードすると、すぐに古くなります。

---

4 種類のツールタイプ

用途を満たす、最もシンプルな選択肢を選んでください。

ツールタイプ	ノード	使用する場面
ネイティブツールノード	slackTool、gmailTool、toolCalculator、…	既存のノード 1 つと操作 1 つで機能を実現できる場合。オーバーヘッドが最小です。
ツールとしてのサブワークフロー	.toolWorkflow	複数のノードが必要な場合、ロジックを再利用する場合、または独立してテスト可能にしたい場合。n8n の標準的な方法であり、迷ったらデフォルトで選択してください。
HTTP リクエストツール	.toolHttpRequest	エージェントが直接オーケストレーションする単一の外部 HTTP API を使う場合。サービスの事前定義済み認証情報を再利用し、ネイティブノードでは公開されていない操作にも対応します。
MCP クライアントツール	.mcpClientTool	保守されている MCP サーバーで対応できる場合、または公開したワークフローを複数のエージェントに利用させたい場合。

インラインで純粋な計算を行うためのカスタムコードツール（.toolCode）もあります。ただし、そのランタイム契約（文字列入力／文字列出力、$fromAI なし、$helpers なし）は n8n-code-tool スキルが担当します。作成する前に、そちらをお読みください。経験則として、コード内で $fromAI() を使いたくなったら、代わりに .toolWorkflow を使ってください。

$fromAI()：エージェントによるツールパラメーターの設定方法

エージェントが値を決めるツールパラメーターは、$fromAI() でラップします。これは実際の n8n 式ヘルパーで、ツールノードのパラメーター式の中で使用します。

={{ $fromAI('paramName', 'what to put here — be specific: format, range, example', 'string') }}

• paramName — モデルが内部で使用する名前です（snake_case または camelCase を使い、一貫させてください）。
• description — 生成する値をモデルに伝えます。プロンプトの一部です。JSDoc のように記述してください。
• type（省略可）— 'string'（デフォルト）、'number'、'boolean'、'json'。型の誤った値を指定すると、呼び出しは失敗します。
• defaultValue（省略可）— モデルが値を省略した場合に使用されます。

$fromAI() が扱えるのは JSON のみです。バイナリは扱えません（base64 もファイルのバイト列も不可）。また、すべてのパラメーターを $fromAI にする必要はありません。エージェントが誤った値を設定したり、そもそも参照したりできないように、ID、権限の制限、相関 ID（userId、返金上限、sessionId）はワークフローのコンテキストから確定的に受け渡してください。→ 全体の構造と「エージェントにはハンドルではなくボタンを渡す」パターンについては TOOLS.md を参照してください。

---

システムプロンプトとツールの説明

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

分ける理由：説明が適切なツールは、それを組み込んだあらゆるエージェントで機能します。モデルがそのツールを検討するときだけツールの詳細が「読み込まれる」ため、トークン効率も向上します。また、5000 トークンのプロンプトに埋もれた段落を直す代わりに、ツールの説明を 1 か所更新すれば済みます。→ SYSTEM_PROMPT.md

---

構造化出力：使う場面と方法

後続の処理で自由形式のテキストではなく厳密な JSON が必要な場合は、サブノード outputParserStructured を追加し、ai_outputParser に接続します。次の 2 つのルールに従ってください。

1. jsonSchemaExample ではなく、実際の JSON Schema を指定する schemaType: 'manual' を使用してください。 例だけでは、必須と任意の区別、列挙値、数値の範囲、配列の制約を表現できません。形式が少し複雑になると、すぐに例だけでは対応できなくなります。使い捨ての形式には、fromJson と例を使用してください。
2. autoFix: true を、コーディング対応の修正モデルと組み合わせてください。 2 つ目のモデルをパーサーの ai_languageModel スロットに接続します。壊れた JSON をスキーマに照らして修正するのはコーディングタスクです。性能の低い修正モデルでは、また不正な形式の JSON を生成して再試行するだけになり、トークンを浪費します。

→ スキーマのパターン、重要な「Markdown で囲まないでください」という再試行用の行、解析失敗時の手順については STRUCTURED_OUTPUT.md を参照してください。

メモリ：簡単なメンタルモデル

メモリはサブノード（ai_memory）です。メモリがなければ、呼び出しはすべてステートレスです。分類や要約など、1回限りのタスクには適しています。メモリがあれば、エージェントは会話を保持し、sessionKey にバインドした式をキーとして使います。

• memoryBufferWindow — キーごとに直近 N 件のやり取りを保持し、n8n のストアを介して実行をまたいで永続化します。チャットでのデフォルトです。contextWindowLength のデフォルト値は 5 で、非常に少ない値です — まずは 50 にするのが妥当です。ウィンドウを超えたメッセージは完全に失われます。
• memoryPostgresChat / memoryRedisChat — メモリをエージェントの外部（独自 UI、分析、システム間連携）から読み取る必要がある場合に限って使います。再起動後も保持するだけなら不要です。BufferWindow で対応できます。

トリガーからメモリまで一貫して安定したキーを渡してください。 チャットトリガーは sessionId を自動で設定します。その他のインターフェースでは、Slack の thread_ts や Webhook の会話 ID などから導出してください。sessionId: 'default' をハードコードしたり、sessionId を $fromAI の背後に置いたりしないでください（モデルが UUID を捏造します）。→ MEMORY.md

---

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

ここが、多くの人がつまずく境目です。

• モデルはアップロードされた画像を確認できます（ビジョン）。そのためには、エージェントで options.passthroughBinaryImages: true を指定します。
• ツールはバイナリを受け取れません。 $fromAI() は JSON 専用です。base64 もバイト列も受け取れず、AI 以外のバインディング経由でも同様です。
• エージェントの出力はテキスト形式です（またはパーサーを使った構造化テキストです）。モデルが画像・音声・動画のバイト列を返しても、Agent はそれを一切出力しません。下流で復元する方法はありません。

回避策： エージェントの実行前にアップロードデータをストレージに保存し、ストレージキーをシステムプロンプトに挿入します。ツールはキーを文字列パラメーターとして受け取り、内部でデータを再取得するようにします。1回限りのメディア生成では、エージェントを使わず、プロバイダーのネイティブな単一呼び出しノードを直接使ってください。

バイナリの仕組み（使用するストレージ、保存方法、再取得方法）は n8n-binary-and-data が担当します。エージェントツールのバイナリに関するリファレンスを参照してください。このスキルが示すのは境界だけです。ここで仕組みを再解説しないでください。

---

人によるレビュー（破壊的なツールを保留する）

ツールの効果を実行前に人が承認する必要がある場合（送信、支払い、返金、アカウント変更など）は、レビュー用ツールノード（slackHitlTool、discordHitlTool、telegramHitlTool、gmailHitlTool など）でラップしてください（n8n ではこれらを「Hitl」／human-in-the-loop と呼びます）。レビュー用ノードは ai_tool 接続上で、ラップするツールとエージェントの間に配置します：ラップするツール → レビュー用ノード → Agent。

承認が必要かどうかは、プロダクトやポリシーに関する判断です。ユーザーに確認し、影響範囲に基づいて推奨し、決定はユーザーに委ねてください。

重要なルール：ラップするツールが実際に受け取るパラメーターを表示してください。 承認メッセージでは、$fromAI() による言い換えではなく、文字どおりの {{ $tool.parameters.<name> }} を使ってください。そうしないと、人が承認するのは、実行される呼び出しではなく、モデルが作り出したテキストになってしまいます。→ HUMAN_REVIEW.md

---

チャットエージェント（Slack、Discord、Teams、Telegram）

複雑さにかかわらず、必ず守るべきことが1つあります。 チャットをトリガーとするワークフローで返信を投稿する場合、必ずボット自身のユーザー ID を除外してください。除外しないと、ボット自身の返信が再びトリガーとなり、実行回数とトークンを消費する無限ループが発生します。可能であればトリガーレベルでフィルタリングしてください（Slack Trigger の options.userIds は除外リストです。ボットの ID を指定してください）。それ以外の場合は、トリガー直後の最初のノードで $json.user !== '<BOT_USER_ID>' をフィルタリングしてください。

このフィルターさえあれば、単純なボット（トリガー → エージェント → 返信）は1つのワークフローで問題なく動作します。ローディング表示、サブエージェント、複数のサーフェスでの再利用、または堅牢なエラー処理が必要になった場合にのみ、シェル + コア + サブエージェントに分割してください。

• シェル — トリガー、無限ループ防止フィルター、イベントタイプの Switch、ローディング／エラー表示、返信の描画を担当します。LLM は含みません。
• コア — ステートレスなエージェントです。chatInput + threadId を入力として受け取り、threadId をキーにメモリを管理し、ツールとサブエージェントを使用します。
• サブエージェント — それぞれ1つの限定的なドメインを担当し、.toolWorkflow 経由で呼び出されます。ステートレスとし、コンテキスト全体を chatInput に含めます。

→ CHAT_AGENT_PATTERNS.md では、サーフェスごとのセマンティクス、セッションとしてのスレッド管理、全体のトポロジーを説明しています。

---

永続化された n8n エージェント（n8n_manage_agents）

永続化された n8n エージェントは、前述の AI Agent ノードとは異なる成果物です。モデル、指示、ツール、スキル、タスク、メモリ、チャネルを含む独立したアシスタントレコードであり、ワークフローの JSON 内のノードではなく、n8n 自体によって保存・バージョン管理され、n8n_manage_agents（n8n のインスタンスレベルの MCP サーバー）を通じて管理されます。

必要なこと…	使用するもの
ai_* サブノードと接続された、ワークフロー内の推論ステップ	AI Agent ノード（このスキルの上記の説明）
特定のワークフローに依存しない、独自のライフサイクル（ドラフト、検証、公開、バージョン、チャネル）を持つ独立したアシスタント	永続化されたエージェント（n8n_manage_agents）

前提条件： N8N_MCP_ACCESS_TOKEN が設定されていること（Public API キーとは別です）。また、エージェントモジュールが有効になった n8n 2.34+ が必要です。このトークンは reference／search を含むすべてのアクションで必須です。トークンがなければ、何も機能しません。また、reference と search は MCP への公開状況にかかわらずすべてのエージェントで使用できます。それ以外のアクションには、対象エージェントが MCP に公開されている必要があります（このツールで作成されたエージェントは自動的に公開されます。公開の条件が問題になるのは、このツールを使う前から存在していたエージェントのみです）。

構築手順：

1. action: "reference" — ほかの作業に入る前に、設定スキーマと変更操作の正確な内容を確認します。
2. action: "discover_assets" — エージェントに実際に接続できるものを一覧表示します。projectId（n8n_list_catalog({kind: "projects"}) から取得）と kind を指定します。kind は models（provider も指定）、integrations、workflows、subagents、mcpServers のいずれかです。種類ごとに 1 回呼び出します。
3. action: "create" — projectId、name、config を指定します。
4. action: "mutate" — 呼び出しごとにリソースを 1 つ指定します（config.patch、skill.upsert／delete、task.upsert／delete、customTool.upsert／delete）。常に最新のハッシュを引き継ぎます。名前が 2 種類ある点に注意してください。n8n は configHash として返し、args.baseConfigHash として受け取ります。args はそのまま n8n に渡されるため、フィールド名を少しでも間違えると、修正方法が示されるのではなく INVALID_ARGS が返ります。そのため、ステップ 1 で先にスキーマを確認します。古いハッシュの場合は STALE_CONFIG が返されるので、再度 get を実行し、新しいハッシュで再試行します。
5. action: "validate" — call または publish を提案する前に実行します。
6. action: "publish" — ユーザーから明示的に依頼された場合のみ実行し、先回りして公開してはいけません。

action: "call" は、実際の認証情報と実際のツールを使ってエージェントを実行します。これはドライランではなく、実際の実行です。結果に、人間の判断が必要なツール呼び出しの approvals[] が含まれる場合があります。ユーザーに代わって承認してはいけません。内容を提示し、ユーザーの判断後にのみ再開します。

カスタムツールは 3 つ目のコードランタイムです。ほかの 2 つを流用しないでください。 customTool.upsert の本文は TypeScript であり、使用できるインポートは @n8n/agents と zod のみです。これは Code ノード（JavaScript／Python を使用し、[{json: …}] を返します）でも、n8n-code-tool で説明されている AI-agent Custom Code Tool（@n8n/n8n-nodes-langchain.toolCode を使用し、文字列を返し、$fromAI() は使いません）でもありません。3 つとも「エージェントが呼び出すコードを書く」ものなので、ここでは契約を取り違えやすい点に注意してください。作成前に action: "reference" で形式を確認してください。コンパイルエラーや不明な agentId は AGENT_TOOL_ERROR として返されます。

認証情報に関する注意： n8n 2.36.x では、エージェントのランタイムが azureOpenAiApi と aws の認証情報を拒否します（missing: ["credential"] と報告されます）。レスポンスの hint に、受け入れられるタイプが示されます。

不要なデータを残さずにテストするには： 使い捨てのエージェントには [TEST] … という名前を付け、作業後に delete してください。永続化されたエージェントは、会話後も残ります。非アクティブのままにしておけるワークフローとは異なります。

→ ツールのすべてのアクションとエラーコードについては、n8n-mcp-tools-expert の ## Agents を参照してください。

---

RAG（検索拡張生成）

n8n には LangChain の RAG プリミティブ（ドキュメントローダー、分割器、埋め込み、ベクトルストア、リトリーバー）が用意されています。まず、押さえておきたい考え方を 2 つ紹介します。

1. まず、より低コストな検索方法を検討します。 厳密な検索には、RAG ではなくデータベースまたは Data Table のクエリを使います。最新情報の取得には、ライブ検索ツールを使います。小規模または構造化されたドキュメントセットには、エージェントに一覧表示／取得ツールを用意します。ベクトルストアを使うのは、一覧表示するにはドキュメントが多すぎ、クエリがセマンティック検索を必要とする場合に限ります。
2. ベクトルストアを検索ツールとして接続します（mode: 'retrieve-as-tool'、ai_tool）。こうすることで、エージェントが検索の必要性を判断し、自分でクエリを作成できます。クエリとドキュメントの埋め込みには、同じモデルを使います。

→ RAG.md（意図的に簡潔にしています。デフォルト設定はデータの形状と規模によって異なります）。

---

参照ファイル

ファイル	参照するタイミング
TOOLS.md	ツールの追加、4 種類からの選択、名前／説明の記述、$fromAI の仕組み
SUBWORKFLOW_AS_TOOL.md	.toolWorkflow を使ったサブワークフローのツールとしての接続、エージェントが入力するパラメーターと受け渡すパラメーターのマッピング
SYSTEM_PROMPT.md	システムプロンプトの作成／リファクタリング、システムプロンプトとツール説明の使い分け
STRUCTURED_OUTPUT.md	JSON 出力の強制、autoFix の設定、修正モデル、解析失敗の修正
MEMORY.md	メモリータイプの選択、永続化、sessionId の処理
HUMAN_REVIEW.md	人による承認の追加、承認メッセージの内容、複数チャネルの承認者
CHAT_AGENT_PATTERNS.md	Slack／Discord／Teams／Telegram ボットの構築、シェル＋コア＋サブエージェントの構成
RAG.md	検索拡張エージェント（設計上、簡潔にしています）
EXAMPLES.md	具体的なノードオブジェクトの例：ステートレスなエージェントコア、Slack ルーターシェル、ドメイン別サブエージェント

---

アンチパターン

アンチパターン	問題点	対処法
汎用的なツール名（tool1、doStuff、runQuery）	モデルがどのツールを選ぶべきかわからず、ツールを使わなかったり、パラメーターを幻覚したりします	動詞から始まる具体的な名前にします：Search customer database、Generate image with Veo
空、または 1 行だけのツール説明	モデルが呼び出すタイミングを判断できず、選択が不適切になり、エラーも検出できません	実際の説明を記述します：機能、使用するタイミング、各パラメーターの意味
ツールごとの指示をシステムプロンプトに詰め込む	プロンプトが肥大化し、再利用できず、ツールごとの指針も埋もれます	ツール固有の指示をツール説明に移します
自然言語でルーティングするために Agent と Switch を使う	Text Classifier なら 1 つのノードで済むところに、2 つのノードとプロンプトの定型文が必要になります	Text Classifier を使います。各カテゴリには専用の出力ハンドル（名前と説明）が割り当てられます
画像／音声／動画生成を Agent でラップする	バイナリはツール経由でもエージェント出力経由でも流れません	プロバイダーのネイティブな単一呼び出しノードを直接使います
outputParserStructured に autoFix を設定しない	1 つの不正なレスポンスでワークフローが停止します	autoFix: true と、コーディングに対応した修正モデルを使います
バイナリをツールに直接渡す	バイナリはツール境界を越えられないため、動作しません	事前にストレージへ保存し、キーを渡します。n8n-binary-and-data を参照してください
sessionId をハードコードする／sessionId を設定しない／sessionId を $fromAI の背後に置く	会話が混線するか、モデルが UUID を捏造します	トリガーからメモリーとツールに、安定したキーを受け渡します
ほぼ同じツールを 2 つ用意する	選択が非決定的になり、モデルが混乱します	パラメーターに応じて内部で分岐する 1 つのツールにします
ボットユーザーのフィルターがないチャットボット	ボット自身の返信で再度トリガーされ、無限ループになります	トリガーまたは最初のノードで、ボットユーザー ID を除外します
複数のツールを使うエージェントで、maxIterations を低いデフォルト値のままにする	「Max iterations reached」または空の出力になります	options.maxIterations を引き上げます
$fromAI() で人によるレビューのメッセージを埋める	承認者は実際の呼び出しではなく、言い換えた内容を承認することになります	リテラルの {{ $tool.parameters.<name> }} を使います

---

コミュニティ版 MCP で利用できないこと

したいこと	実際のところ
ワークフローの AI Agent ノードを、エンドツーエンドで対話的にチャットテストする	n8n_test_workflow はワークフローを実行しますが、ノードとの実際の複数ターンのチャットセッションは UI の操作（キャンバスのチャットテスター）です。一方、永続化された Agent は n8n_manage_agents の call でライブ実行できます。上記の「永続化された n8n Agents」を参照してください。
認証情報に実際のシークレット値を設定する	n8n_manage_credentials は認証情報レコードを作成・更新しますが、エージェントプロバイダーのキー自体は UI で入力・検証します。
ワークフローのエラーワークフローを割り当てる	UI でのみ可能です。n8n-error-handling を参照してください。すべてを捕捉するワークフローを作成したら、UI での手順をユーザーに案内してください。
インスタンスごとに利用可能なモデルを正確に固定する	モデルの一覧はバージョン間で変わります。search_nodes／get_node でインストール済みのモデルを確認してください。対象のインスタンスで検証してください。

MCP でできること：すべての LangChain ノードを検索・確認する（search_nodes、get_node）、ノード設定とグラフ全体を検証する（validate_node、validate_workflow）、エージェントとそのサブノードを作成・パッチする（ai_* 出力に対する addConnection を使用した n8n_update_partial_workflow）、テストする（n8n_test_workflow）、保存された JSON を取得して配線を検証する（n8n_get_workflow）。AI エージェントの詳細ガイドは tools_documentation({topic: "ai_agents_guide", depth: "full"}) にもあります。

---

他のスキルとの連携

• n8n-workflow-patterns（ai_agent_workflow.md）—「ワークフロー内のエージェント」の全体的な構成です。このスキルでは詳細を解説しています。アーキテクチャについては、まずこちらを参照してください。
• n8n-mcp-tools-expert — ノードタイプの形式（get_node の短縮形式、JSON 内の長形式）とツール選択のガイダンスです。MCP を呼び出す前に参照してください。
• n8n-node-configuration — エージェントおよびサブノードの displayOptions によって決まるフィールド、Slack／Block Kit のメッセージ形式（NODE_FAMILY_GOTCHAS.md の Slack セクション）。
• n8n-expression-syntax — {{ }}、$json.output、$now、$fromAI／$tool.parameters はすべて、正しい式の構文に依存します。
• n8n-code-tool — Custom Code Tool のランタイム契約（文字列の入出力、$fromAI は使用不可）。.toolCode を記述する前にお読みください。
• n8n-subworkflows — .toolWorkflow の基盤となるサブワークフローのプリミティブ（Execute Workflow Trigger の入出力、命名、作成前の検索）。
• n8n-binary-and-data — エージェントツールにおけるバイナリ境界の仕組み（アップロードのステージング、生成ファイルの返却）。
• n8n-validation-expert — AI 接続に関する問題を含む validate_workflow の結果の解釈（ツールを ai_tool ではなく main に接続すると、未接続として検出されます）。
• n8n-error-handling — ツールのサブワークフローとエージェントコアの呼び出しにおける onError: 'continueErrorOutput'、チャットシェルでのエラー UX。
• n8n-code-javascript / n8n-code-python — ツールのサブワークフロー内にある Code ノードのロジック用（Code Tool とはサンドボックスが異なります）。

---

クイックリファレンスチェックリスト

エージェントをリリースする前に、次の項目を確認してください。

• 適切なノード：ツール／メモリ／複数ターンには Agent、ルーティングには Text Classifier、フィールド抽出には Information Extractor、メディアにはネイティブノードを使用します
• ai_languageModel 経由で モデル を接続します
• すべてのツール に、動詞から始まる具体的な名前と、実際の説明を設定します
• $fromAI() の説明 は具体的にします（形式、範囲、例）。ID／制限／sessionId は $fromAI 経由ではなく、決定的に渡します
• ツールごとのガイダンス はシステムプロンプトではなく、ツールの説明に記載します
• システムプロンプトでは $now を使います（日時をハードコードしないでください）
• 複数のツールを使うエージェントでは maxIterations を増やします
• メモリ はトリガーから取得した安定した sessionKey をキーにします（'default' や $fromAI は使わず、contextWindowLength は 5 より大きくします）
• 構造化出力：schemaType: 'manual' ＋ autoFix: true ＋ コーディングに対応できる修正用モデルを設定します
• 破壊的なツール は人によるレビューを挟みます。承認メッセージでは $fromAI ではなく $tool.parameters を使います
• チャットボット では、ボット自身のユーザー ID をフィルタリングします（トリガーレベルまたは最初のノードで設定）
• バイナリ：モデルのビジョン機能には passthroughBinaryImages を使います。ツールにはバイト列ではなく、ストレージキーを渡します
• validate_workflow で検証し、n8n_get_workflow で確認します（サブノードは main ではなく ai_* に接続します）

---

覚えておいてください：エージェントの性能は、ツール名、説明、システムプロンプトの設計に左右されます。モデルに見えるのは、配線ではなく、システムプロンプトと、名前および説明が設定されたツールの一覧です。API と同じように設計すれば、「エージェントが期待どおりに動かない」という問題のほとんどは解消されます。