n8n-agents-official

n8n エージェント

ファーストクラスの n8n エージェントは、独自の指示、モデル、ツール、スキル、サブエージェント、メモリ、チャネル、スケジュール済みタスク、バージョン、利用上限を備えた保存済みリソースです。Agent MCP ツールを通じて JSON として設定し、Workflow SDK コードは使用しません。ワークフロー内の AI Agent ノードは別のもので、n8n-ai-nodes-official で説明されています。

エージェントは一般提供されています。頻繁に変更されることや、期待される機能の一部がまだ利用できないことから、UI には Preview タグが表示されています。まだ Enterprise での利用準備は整っていません。Enterprise インスタンスで有効になっている場合もありますが、利用できるとは限りません。ツール一覧に create_agent がない場合、このインスタンスではエージェントが有効になっていません。そのことを伝え、推測で進めず、代わりにワークフローを提案してください。

絶対に守ること

1. MCP 経由で作成するときは、必ずメモリブロックを送信してください。 "memory": { "enabled": true, "storage": "n8n" }。UI では保存のたびにこれが追加されます。create_agent は送信された内容をそのまま保存するため、これがないと、同じセッション内でもエージェントは前のターンを忘れます（実環境で確認済み）。
2. ユーザーから明示的な OK を得る前に、絶対に公開しないでください。 作成したエージェントはドラフトです。公開済みエージェントにチャネルを設定すると、すぐに接続されるため、その場合も確認してください。
3. エージェントが呼び出すものを公開してください。 ワークフローツールには When Executed by Another Workflow トリガー、同じプロジェクト、公開済みのワークフローが必要です（validate_agent で報告されます）。保存済みのサブエージェントも公開する必要がありますが、その確認は行われません。検証と公開は成功しても、本番環境での委譲は失敗し、親エージェントがひそかに単独で回答します。
4. 送信、変更、削除、または費用の発生を伴う操作には承認を設定し、承認者に何が表示されるかを把握してください。 references/APPROVALS.md を参照してください。
5. 変更ごとに mutate_agent を 1 回だけ呼び出し、必ず最新の configHash を指定してください。 古いハッシュを使うと stale_config が返されます。get_agent を呼び出して再試行してください。

エージェント、ワークフロー、それとも AI Agent ノード？

ビルドツールを呼び出す前に判断してください。最初の確認事項は「手順を声に出して説明できるか」です。

できること	作成するもの
リクエストを受け取る前にすべての手順を説明でき、判断が必要な手順がない	ワークフロー
すべての手順を説明でき、1 つの手順で判断（分類、抽出、要約、作成）が必要	AI ステップを含むワークフロー：Text Classifier、Information Extractor、chain、または AI Agent ノード（n8n-ai-nodes-official）
リクエストを見ないと手順を説明できず、人が話しかけるか、自律的に動作する	ファーストクラスの n8n エージェント
手順を説明できず、以下の制限のいずれかに該当する	ワークフロー内の AI Agent ノード
手順を説明できず、固定パイプラインでも同じ頭脳が必要	ワークフローから Message an Agent で呼び出すファーストクラスエージェント。エージェントが判断し、ワークフローが実行します

「エージェントを作って」や「アシスタント」は、制限に該当しない限り、ファーストクラスのエージェントを意味します。Chat Trigger と AI Agent ノードの組み合わせは、要求されたエージェントの代わりにはなりません。リクエストが実際には固定トリガーと固定手順の組み合わせである場合は、その不一致を説明し、代わりにワークフローを作成する前に確認してください。

現在、AI Agent ノードを選ぶべき制限事項

必要なこと	現時点でエージェントではできない理由	代わりに使用するもの
カスタムの承認メッセージ、または承認者に Slack でパラメーターを表示する必要がある	承認はオン／オフの切り替えのみで、メッセージは固定です。チャネルカードにはツール名のみが表示されます	値を含む独自の送信・待機承認を実行するワークフローツール（同じ Slack スレッドへの投稿も可能）
トリガーやノードのデータをツールパラメーターに正確にマッピングする	ツールの式から参照できるのはモデル自身の引数のみです（ノードツールとワークフローツールで実環境にて確認済み）	AI Agent ノード、または構造化出力を使う Message an Agent と、マッピングを行う後続ノード
ネイティブチャネルとワークフローで共有される 1 つの会話	チャネルのスレッドと Message an Agent のセッションキーは、別々の名前空間にあります	プラットフォームのトリガーを使ったシェルワークフローから、Message an Agent でエージェントを呼び出す
Message an Agent の呼び出し内での承認	「Suspend/resume is not supported in workflow execution context」というエラーで失敗します	呼び出し元のワークフローで操作を制御する

MCP の構築手順

1. get_agent_builder_reference を一度実行します。その configSchema がフィールド名の唯一の信頼できる情報源です。フィールド名がこのスキルと異なる場合は、configSchema を優先してください。
2. search_projects を実行し、続けて discover_agent_assets（models、integrations、workflows、subagents、mcpServers）、list_credentials、さらにノードツール用に usage: "agentTool" を指定して search_nodes を実行し、get_node_types を実行します。
3. モデル、認証情報、指示、メモリブロック、通常のツールを指定して create_agent を実行します。スキル、タスク、カスタムツールはサーバー生成の ID が必要なため、その後 mutate_agent で追加します。
4. mutate_agent は、1 回の呼び出しにつき 1 つの操作を行います。skill.upsert では configHash は変更されませんが、設定のパッチでは変更されます。
5. valid: true になり、missing が空になるまで validate_agent を実行します。
6. 代表的なケースで call_agent を 1 回実行します。実際のツールを使用して Preview でドラフトを実行するため、副作用が発生します。承認なしで送信、書き込み、または支払いを行うツールがある場合は、テストの前にユーザーに確認してください。返された承認はすべて人間に提示し、それぞれの continuation を使って再開します。
7. validate_agent の url とセッションリンク（references/SESSIONS_AND_DEBUGGING.md を参照）を添えてドラフトを報告し、公開するかどうかを尋ねます。
8. 明示的な「はい」があった場合に限り、publish_agent を実行します。チャネルについては update_agent_integration を参照してください（references/CHANNELS.md）。

各操作、エラーコード、バージョンツールの詳細は references/MCP_BUILD.md を参照してください。

詳細を確認するファイル

ファイル	読むタイミング
references/MCP_BUILD.md	mutate_agent の操作、エラーコード、バージョン、復元、削除、availableInMCP を確認するとき
references/CONFIG.md	Agent JSON を作成またはレビューするとき：各フィールド、制限、デフォルト、バージョン管理される項目
references/TOOLS.md	ノード、ワークフロー、カスタム、MCP サーバー、組み込みツール、入力モード、式から参照できる情報
references/APPROVALS.md	承認の追加、各サーフェスに表示される内容、承認を実行できない場所、ワークフローツールを使ったカスタム承認
references/SKILLS.md	Agent スキルの追加：読み込みの仕組み、説明の書き方、参照
references/SUB_AGENTS.md	委任、保存済みとインラインのサブエージェント、難易度に応じたモデルの振り分け
references/KNOWLEDGE.md	アップロードしたナレッジファイルと外部ベクトルストア
references/MEMORY.md	メモリの種類、セッションスコープ、セッションキー
references/CHANNELS.md	Slack、Telegram、Discord、Linear、n8n Chat、または「ネイティブチャネルかシェルワークフローか？」
references/TASKS.md	スケジュールされたタスク
references/MESSAGE_AN_AGENT.md	ワークフローから Agent を呼び出すとき
references/SESSIONS_AND_DEBUGGING.md	問題が発生したとき、または Agent の実行内容を確認する場所をユーザーが尋ねたとき

ネイティブチャネルのないプラットフォーム、スラッシュコマンド、カスタムルーティング向けに、ワークフローシェルとしてチャットボットを構築する場合は、n8n-ai-nodes-official の references/CHAT_SURFACE_PATTERNS.md にある「Core as Message an Agent」セクションにシェルのパターンがあります。すぐに適用すべきルールが 1 つあります。ボット自身のメッセージが配信されるサーフェス（Slack、Discord）では、返信を投稿するシェルはトリガーの直後にボットのユーザー ID を除外する必要があります。そうしないと、ボットが自分自身を無限にトリガーします。

指示の書き方

指示はシステムプロンプトです。ノードの場合と同様に、ペルソナ、ルール、出力形式、ツール間のフローは指示に記述し、特定のツールの呼び出し方はそのツールの説明に記述します。Agent が必要なときだけ使う長い手順はスキルに記述します。スキルは読み込まれたときだけトークンを消費します。結果の送信先（「要約を #ops に投稿する」など）を指定してください。スケジュール実行では、返信する相手がいないためです。

アンチパターン

アンチパターン	問題点	対処方法
memory を指定せずに create_agent を使う	1 つのセッション内でも、エージェントが直前のターンを忘れます	{ "enabled": true, "storage": "n8n" } を送信します
ユーザーがエージェントを求めているのに、Chat Trigger + AI Agent ノードを使う	チャネル、セッション、承認、バージョン、タスク、予算が失われます	制限が適用されない限り、専用の Agent を使用します
検証に合格したため公開する	ユーザーは稼働中の Agent を承認していないのに、チャネルまで稼働を開始します	ドラフトの状態を報告し、確認を求めます
保存したサブエージェントを未公開のままにする	本番環境での委任が通知なく失敗し、親エージェントはサブエージェントなしで回答します	親エージェントを稼働させる前に、子エージェントを公開します
ツール入力の式で $('Webhook') または $json.<trigger field> を読み取る	モデルの引数しか参照できないため、値が空または誤ったものになります	メッセージを介して値を渡すか、マッピングをワークフロー内に保持します
Message an Agent またはタスクからエージェントが呼び出すツールに承認を設定する	実行に失敗するか、誰も応答できない状態で停止します	呼び出し元のワークフローで制御し、タスクには安全なツールだけを指定します
プロジェクト内の 2 つのエージェントで、同じ Message an Agent セッションキーを使う（例：どちらも単独の Telegram ID をキーにする）	キーはエージェントごとではなくプロジェクト全体で共有されるため、2 つ目のエージェントは「Failed to create the agent execution record」で失敗します	エージェントごとにキーの先頭に接頭辞を付けます：support-<telegramId>
スキルの本文に「references/x.md を読んで」と曖昧に書く	モデルが読み飛ばすことがよくあります	「回答する前に、load_skill（filePath）で references/x.md を読み込む」と指定します
config.patch でインテグレーションを設定する	拒否されます	update_agent_integration を使います
Slack Trigger 用に作成した認証情報で Slack を接続する	すべてのチェックを通過しますが、何も受信しません	マネージドセットアップを使うか、リクエスト URL がこの Agent を指すアプリを使います