n8nで人の承認とOpenAI互換APIを使った文書Q&Aワークフローを構築する

承認を挟む場所を決める

文書の質問応答では、AIモデルを使うという理由だけで人の承認を追加する必要はありません。ワークフローが機微な情報にアクセスする可能性がある箇所や、確認が必要な回答を公開する箇所に承認を設けましょう。

n8nでの基本的な設計例は次のとおりです。

1. 質問を受け取る。
2. AI Agentに文書検索リクエストを作成させる。
3. コーパスに機微な情報が含まれる場合、クエリによって制限対象の情報が漏れる可能性がある場合、または検索に運用コストがかかる場合は、検索ツールの実行前に人の承認を求める。
4. 出典メタデータ付きの文書箇所を取得する。
5. 取得した箇所だけを根拠に回答するようモデルに指示する。
6. 出典付きの回答を返す。または、公開前に別の承認ステップへ下書きを送る。

この設計では、混同されがちな3つの判断を切り分けられます。質問自体を受け付けてよいか、検索を実行してよいか、生成された回答を送信できる状態か、という判断です。

n8nのドキュメントでは、AI Agentに接続した特定のツールに対する人のレビューが説明されています。レビューを有効にするとワークフローが一時停止し、レビュアーはツール呼び出しを承認または拒否できます。対応する動作や承認チャネルの詳細は、n8nのhuman-in-the-loopドキュメントを参照してください。

前提条件

必要なものは次のとおりです。

• AI Agentとモデル接続を含むn8nワークフロー。
• ベクトルストア、データベース、社内検索サービスなどの検索可能な文書ソース。具体的なコネクターは利用するアプリケーションによって異なり、引用したn8nのページでは特定されていません。
• テキストと文書メタデータを一緒に返す検索ツール。
• n8nで設定済みの承認チャネル。ドキュメントでは、利用可能なチャネルとしてChat、Slack、Discord、Telegram、Microsoft Teams、Gmail、WhatsApp Business Cloud、Google Chat、Microsoft Outlookが挙げられています。
• OpenAI互換APIエンドポイントへのアクセス。OneMuxでは、1つのOpenAI互換APIを通じて主要なAIモデルを利用できます。最新のエンドポイントと認証手順は、OneMuxクイックスタートおよびAPIドキュメントを確認してください。

互換性は条件付きです。n8nを接続する前に、選択したエンドポイントが、使用するn8nノードまたはHTTPリクエストのリクエスト形式、モデル識別子、認証方式、ストリーミング動作、ツール呼び出し、パラメーターに対応しているかを確認してください。この記事では、特定のOneMuxモデルやn8n設定がテスト済みであるとは主張していません。

推奨するn8nワークフローの構成

ワークフローを、次の5つの論理的な段階に分けて作成します。

1. 質問を受け取り、形式を整える

任意のn8nエントリーポイントで質問を受け取り、ユーザーの質問、ユーザーまたはワークスペースのコンテキスト、任意の文書範囲フィルターを含む簡潔なオブジェクトに整形します。

制限のないユーザー入力をシステム指示にそのまま含めないでください。質問はデータとして扱い、エージェントの動作は別途定義します。テナントや部門ごとの境界を設ける場合は、モデルにその境界を作らせるのではなく、制御されたフィールドとして検索ツールに渡してください。

2. 文書検索ツールを追加する

検索ツールをAI Agentに接続します。入力は、たとえば次のように範囲を限定し、明確にします。

{
  "query": "string",
  "document_scope": "string or controlled value",
  "max_results": "integer"
}

検索結果には、適切な出典を示すのに十分なメタデータを残します。

{
  "text": "Approved passage from the document",
  "title": "Document title",
  "url": "Document URL or stable identifier",
  "page": "Page number when available",
  "section": "Section heading when available",
  "chunk_id": "Stable passage identifier"
}

上記のフィールド名は実装例であり、n8nで必須のスキーマを示すものではありません。利用するコネクターやサービスに合わせて調整してください。重要なのは追跡可能性です。回答生成モデルには、文書箇所とその出典をセットで渡す必要があります。

3. 対象ツールに人のレビューを設定する

AI AgentのToolsパネルを開き、Human reviewセクションで承認チャネルを選び、文書検索ツールをレビューのステップに接続します。選択したチャネルの認証情報と設定をn8nで構成してください。

レビュアーに送るメッセージには、実行予定のアクションとパラメーターを含められます。n8nのドキュメントでは、この用途に$tool.nameと$tool.parameters変数を使用できると説明されています。メッセージの例は次のとおりです。

The AI wants to use {{ $tool.name }} with these parameters:
{{ JSON.stringify($tool.parameters, null, 2) }}

Approve only if the query and document scope are appropriate for this request.

レビュアーが、別チームの文書を検索しようとしているようなリスクの高い範囲を特定できる場合に役立ちます。一般公開されているドキュメントを対象に毎回承認を求めると、不要な手間が増えることがあります。その場合は検索を自動で行い、最終回答を公開または送信する別のツールに承認を設定してください。

4. OpenAI互換モデルのエンドポイントを接続する

プロバイダーが公開しているエンドポイントと認証情報を使って、モデルレイヤーを設定します。OneMuxを利用する場合は、まずOneMuxクイックスタートを参照し、n8nノードが必要とする機能に対応したモデルを選び、モデル識別子とリクエストパラメーターを確認してください。

一般的なリクエスト形式は次のようになります。ただし、これは説明用であり、テスト済みのOneMux設定例ではありません。

curl https://api.example-provider.invalid/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "system", "content": "Answer only from supplied document passages."},
      {"role": "user", "content": "What does the document say about retention?"}
    ]
  }'

URL、キーの取り扱い、モデルIDのプレースホルダーは、プロバイダーの最新ドキュメントに記載された値に置き換えてください。ワークフローのエクスポートやユーザーに表示される承認メッセージに認証情報を含めないでください。n8nのモデルノードがエンドポイント非対応のパラメーターを必要とする場合は、互換性のある設定を使うか、セキュリティとレスポンス解析の要件を満たせる場合に限り、HTTP Requestを使った構成を検討してください。

5. 回答プロンプトで出典の明示を徹底する

取得した文書箇所を、明確に区切ったコンテキストとしてモデルに渡し、内容に関わる主張すべてに出典を付けるよう求めます。例は次のとおりです。

You answer questions about the supplied documents.

Rules:
- Use only the passages in DOCUMENT_CONTEXT.
- If the passages do not support an answer, say that the documents do not establish it.
- Do not create titles, URLs, page numbers, or quotations.
- Cite each factual answer using the supplied title and page, section, URL, or chunk ID.
- Distinguish a direct statement from an inference.

DOCUMENT_CONTEXT:
{{ JSON.stringify($json.documents) }}

QUESTION:
{{ $json.question }}

正確な式の構文は、先行するn8nノードがデータをどのような形式に整えているかによって異なります。このプロンプトはひな型として扱い、そのままインポートできるワークフロー設定としては扱わないでください。

承認設計：検索前か公開前か

承認を設ける箇所として、次の2つが考えられます。

リスクの高いワークフローでは、両方に承認を設けることもできます。n8nのドキュメントでは、AI Agentに接続されたすべてのツール、または選択したツールにレビューを設定できると説明されており、このような選択的な設計が可能です。また、メインのやり取りとは別のチャネルで承認することもできます。たとえば、ユーザー向けのチャットと、Slackでのレビュアー承認を組み合わせられます。

システムプロンプトと拒否時の動作

どのツールに承認が必要か、また拒否された場合にどう動作するかをエージェントに伝えます。レビュアーが検索を拒否した場合、同じ呼び出しを表現を変えて再試行したり、根拠を見つけたと主張したりしてはいけません。要求された検索が承認されなかったことを説明し、許可された範囲の代替案があれば提示します。

簡潔なポリシーの例は次のとおりです。

The document_search tool requires human approval. If it is denied, do not call it again for the same request. Tell the user that the lookup was not approved. Never answer from memory when document evidence is required.

これは、拒否された呼び出しに適切に対応できるよう、ツールと人のレビューに関する動作をシステムプロンプトに含めるというn8nのガイダンスに沿ったものです。

トラブルシューティングと制限事項

承認リクエストに役立つ情報が含まれていない

ツールの入力で明確なフィールドを使っていること、レビュー用メッセージに$tool.nameと$tool.parametersが含まれていることを確認してください。重要な検索範囲を、内容が分かりにくい文字列にまとめないようにします。

出典が表示されない

モデルに渡す前の検索出力を確認してください。マッピングノードによってタイトル、URL、ページ、セクション、チャンクIDが削除されている場合、モデルはそれらを確実に再構成できません。また、根拠のない主張を拒否するようモデルに指示してください。

エンドポイントがリクエストを拒否する

ベースURL、認証ヘッダー、モデルID、ツール呼び出しへの対応、コンテキスト上限、パラメーター名を確認してください。OpenAI互換は完全に同一であることを意味しません。n8nのリクエスト形式とプロバイダーのAPI仕様の両方に照らして互換性を確認してください。

拒否後の応答が不自然になる

システムプロンプトに拒否時の動作を明記し、承認と拒否の両方の経路をテストします。n8nのドキュメントでは、承認とキャンセルは別の結果として扱われています。ツールが必ず実行される前提にせず、ワークフローで両方に対応してください。

ワークフローに時間がかかりすぎる

リスクの低い検索すべてに承認を求めるのではなく、必要な箇所だけをレビューする設計にします。機微な検索や公開には承認を残し、運用への影響を自環境で計測してください。モデルの速度、検索品質、承認にかかる時間を、テストなしに決めつけないでください。

コストと運用計画

ここでのOneMuxは、n8nのワークフロー制御を置き換えるものではなく、モデルへのアクセス手段の一つです。モデルを選ぶ前にOneMuxの料金を確認し、入力と出力の利用量、検索量、承認の再試行回数、文書検索サービスの費用を考慮してください。適用される料金は選択したモデルと最新の公開条件によって異なります。この記事では料金を提示したり、コスト削減を約束したりしていません。

支出の把握やモデル選定の参考として、OneMuxモデルカタログも確認してください。特に構造化出力やツール呼び出しなど、ワークフローに実際に必要な機能を満たすかどうかを基準にモデルを選びます。

まとめ

堅牢なn8n文書Q&Aワークフローは、エージェントをモデルに接続するだけでは完成しません。アクセスが許可された文書箇所を検索し、メタデータを保ち、適切なツール実行の境界でレビューを求め、受け取った根拠だけを引用して回答する、一連の制御された処理が必要です。

n8nをオーケストレーションと人の承認に使い、仕様に記載されたエンドポイントやパラメーターが設計に合致する場合は、実用的なOpenAI互換モデルへのアクセス手段としてOneMuxを検討してください。小規模なコーパスから始め、承認・拒否の両方の経路をテストしましょう。根拠のない主張、出典の欠落、互換性のないパラメーターは、原因不明のモデルの問題ではなく、ワークフローの失敗として扱ってください。

出典

• n8n：ツールのHuman-in-the-loop — ツール承認の動作、承認チャネル、$tool式、拒否時の対応に関する情報。
• OneMuxドキュメント — APIの現在の利用方法と互換性の詳細を確認できるプロバイダーのドキュメント。
• OneMuxクイックスタート — エンドポイントと認証の設定を始めるためのガイド。
• OneMuxの料金 — 導入前に確認する最新の料金情報。