SaaS 企業のサポートが製品の更新の記録とヘルプセンターの記事を n8n のエージェントで突き合わせ、古くなった記事と食い違う箇所を見つけて直しの下書きを作る

処理の起点を決める

GitHub Trigger で、リリースノートのリポジトリの Release のイベントを受けます。 直後に IF ノードを置き、release.draft が false で、release.prerelease が false のときだけ先へ進めます。下書きの段階で記事を探し始めると、公開の前に変わった項目まで候補になります。

取りこぼしに備えて、週に1回の見直しも置きます。 Schedule Trigger で週に1回動かし、GitHub の Releases の API で直近7日のリリースを取って、候補の一覧に「処理済み」の記録が無いリリースだけを流し直します。 Webhook が届かなかった週があっても、ここで拾えます。

記事の写しは、別のワークフローで毎晩更新します。 Zendesk の Help Center API には、指定した時刻以降に更新された記事を返す incremental の記事の一覧があり、start_time に Unix の時刻を渡します。前の晩に取った時刻を覚えておき、その後に更新された記事だけを取り直します。

入力データを集める

言い換えの一覧が、探しきれない問題への手当てです。 「休暇の設定」「休暇設定」「［設定］＞［休暇］」を同じものとして並べた表で、エージェントのシステムメッセージに入れて、探す言葉を選ぶ手がかりにします。 一覧に足すのは担当で、エージェントが足すことはしません。

記事の写しを持つのは、本文を読むたびに Zendesk を呼ばないためです。 1つの変更で記事を10本読めば、1回のリリースで100回の呼び出しになります。写しから読めば、検索だけを Zendesk に向けられます。 写しは前の晩の状態なので、その日に直した記事は古い本文のまま読まれることを、担当の確かめの段階で考えに入れます。

データの取得方法を決める

検索は、Zendesk の Search Articles を HTTP Request のツールで呼びます。 公式のページでは、GET /api/v2/help_center/articles/search に query・category・section・label_names のどれか1つ以上が要り、既定で1ページに25本、最大で1,000件まで返るとされています。locale を渡さなければヘルプセンターの既定の言語で探します。この構成では locale=ja を固定で渡します。

検索の言葉は、エージェントに決めさせます。 n8n の $fromAI() を query の値に使うと、エージェントがその場で値を入れます。公式のページでは、$fromAI() は AI Agent につないだツールでだけ使えるとされ、キー・説明・型・既定の値を指定できます。

検索の結果には、一致した部分の抜粋（snippet）が付きます。 抜粋だけで判断させず、記事の本文はツール2で読ませます。 抜粋は一致した言葉の前後だけで、手順の前後の流れが分からないからです。

本文は、Call n8n Workflow Tool で記事の写しを読むサブワークフローを呼びます。 公式のページでは、このツールは別のワークフローを動かして結果を受け取り、入力に $fromAI() を使えるとされています。記事のIDを入力にし、写しから本文を返します。本番でサブワークフローを公開していないと「Workflow is not active」の失敗が返り、その失敗がエージェントへの結果として返るため、長い出力の中で見落としやすいと書かれています。

AIへ渡す前に整形する

1. リリースノートを項目に分ける … Code ノードで、本文の箇条書きの行（- や * で始まる行）を1項目ずつに分けます。見出し（「新機能」「改善」「不具合の修正」）は、項目の種類として行に添えます
2. 影響の無い項目を外す … 「内部の処理の改善」「表示の速度の改善」のように、画面や操作に触れない項目は、種類と言葉で外します。外した項目も一覧に「対象外」として残します
3. 記事の写しを文字にする … HTML のタグを外し、見出しと段落の区切りを改行で残します。画像は ［画像：代替テキスト］ に置き換え、画像があったことを本文に残します
4. 言い換えの一覧を添える … 変更の項目に出てくる言葉が言い換えの一覧にあれば、その行をエージェントへの入力に添えます

3番目の画像の置き換えが、後で効きます。 手順の記事の多くは、画面の画像に「ここを押す」と描いてあります。文字の上では食い違いが無くても、画像が古い画面のままということがあります。 画像があった位置を残しておけば、エージェントが「この見出しの下に画像があり、確かめが要る」と書けます。

AIに処理させる

させるのは、1つの変更の項目について、影響する記事を探し、食い違う文を引用して、直しの案を書くことです。 探す言葉を変えながら何回探すかは、エージェントが決めます。

探す言葉を残させるのが、人の確かめの土台です。 エージェントが「影響する記事は無し」と返したとき、どの言葉で探して無かったのかが分かれば、担当は足りない言葉だけを足して探し直せます。

指示内容を固定する

（システムメッセージ）
あなたは SaaS 企業のサポートのナレッジの担当を手伝う係です。
製品の変更の項目を1つ受け取り、その変更で古くなったヘルプセンターの記事を探し、
食い違う文を見つけて直しの案を書きます。

【使えるツール】
- search_articles：ヘルプセンターの記事を言葉で検索します。1回に1つの言葉で探してください。
- read_article：記事のIDを渡すと本文を返します。

【進め方】
1. 変更の項目から、画面・設定・ボタン・メニューの名前を書き出してください。
2. 【言い換えの一覧】に同じものの別の書き方があれば、それも探す言葉に加えてください。
3. 言葉を変えて search_articles を使ってください。新旧の両方の名前で探してください。
4. 抜粋が変更に関係しそうな記事だけ read_article で本文を読んでください。
5. 変更の後の製品と合わない文を見つけたら、記事の本文から一字一句そのまま引用してください。

【厳守事項】
- quote には記事の本文の文字列をそのまま写してください。言い換え・要約をしないでください。
- 変更の項目に書かれていない仕様を推測で書かないでください。
  分からない点は open_questions に書いてください。
- ［画像：…］がある見出しの下で手順が変わる場合は、image_check を true にしてください。
  画像の中身を推測しないでください。
- 記事を直す・公開する操作はしないでください。
- 影響する記事が無いと判断した場合も、searched_terms に使った言葉と件数を必ず書いてください。

【言い換えの一覧】{alias_rows}

（ユーザーメッセージ）
リリース：{tag_name}（{published_at}）
変更の種類：{item_kind}
変更の項目：{item_text}

「新旧の両方の名前で探す」を書くのは、新しい名前だけで探すからです。 古い記事に書かれているのは古い名前で、変更の後の名前で探しても、直すべき記事は当たりません。 言い換えの一覧に新旧を並べておくと、この取りこぼしが減ります。

「影響が無い場合も言葉を書く」は、空の結果を確かめられるようにするためです。 何も返さないエージェントと、10の言葉で探して何も無かったエージェントは、出力が同じ「無し」でも意味が違います。

出力形式を固定する

Structured Output Parser に次の形の JSON の例を渡します。 公式のページでは、JSON の例から作るスキーマはすべての項目を必須として扱い、$ref を使った参照には対応していないとされています。入れ子は1段にとどめます。

{
  "release": "v5.12.0",
  "item_text": "有休の付与の設定を『休暇の設定』から『休暇のルール』に移動",
  "searched_terms": [
    { "term": "休暇の設定", "hits": 14 },
    { "term": "休暇設定", "hits": 6 }
  ],
  "candidates": [
    {
      "article_id": 0,
      "title": "",
      "quote": "",
      "reason": "",
      "suggested_text": "",
      "image_check": false
    }
  ],
  "open_questions": [""]
}

JSON で受けるのは、Code ノードで引用を照らし、候補を記事の担当ごとに分けるためです。 自由文で返されると、どの部分が引用でどの部分が直しの案かを機械で分けられません。

Code ノードの照らし方は単純です。 記事の写しの本文（タグを外したもの）に、quote の文字列がそのまま含まれるかを見ます。空白と改行の違いだけは揃えてから比べます。

引用不一致の候補に直しの案を出さないのは、誤った前提の案だからです。 記事に無い文を「古い」と言っている案を担当が読むと、直す必要の無い記事を直しかねません。

システムへ連携する

Zendesk には読むだけでつなぎます。 資格情報は、ヘルプセンターの記事を読める権限のものを使います。記事を書き換えられる管理者の資格情報をエージェントのツールに渡さないでください。 エージェントがツールの使い方を誤っても、書き込みが起きない形にしておきます。

Max Iterations は、既定の10から変更の大きさで決めます。 1つの変更で、言葉を4つ探し、記事を6本読めば10回に達します。大きな変更で探し足りないまま終わるなら、15から20に上げ、それ以上は項目を分けます。 回数を増やすほど、1項目あたりの費用と時間が増えます。

人が確認する

記事の担当が、候補の一覧の 照合済 の行を見ます。

1. 引用と直しの案を読む … 記事を Zendesk の画面で開き、引用の前後を読みます。本当に古いかは、変更の後の製品の画面で確かめます
2. image_check の行は画像を見る … 画像が古い画面なら、撮り直します
3. open_questions を開発に聞く … 変更の中身が曖昧な点は、リリースノートを書いた担当に聞きます
4. 探した言葉を見る … 言い換えの一覧に無い書き方を思いついたら、一覧に足し、その言葉で探し直します
5. 直して公開する … 直しの案は叩き台です。記事の文体に合わせて担当が書き、公開します

4番目を省かないでください。 エージェントが当てられなかった記事は、候補の一覧にそもそも出てきません。 出てきた候補を確かめるだけでは、漏れは減りません。

直したら、候補の一覧に「直した」「直さない（理由）」を残します。 直さない理由が「エージェントの誤り」なら、その種類も書きます。

例外に対処する

4行目を、機械で見分けられるようにしておきます。 サブワークフローが失敗すると、エージェントは「記事を読めませんでした」と書くか、何も書かずに「影響なし」と返すことがあります。Return Intermediate Steps を有効にし、本文を読むツールを1回も成功させずに「影響なし」と返した結果は、失敗として担当に回します。

記録を残す

• リリースのタグ・公開の日時と、変更の項目ごとの処理の日時
• エージェントの途中の手順（Return Intermediate Steps）：使った検索の言葉、読んだ記事のID
• 出力の JSON と、Code ノードの照らした結果
• 担当の判断 … 直した・直さない（理由）、エージェントの誤りの種類
• 言い換えの一覧に足した行と、足した日
• 記事の写しを更新した時刻（incremental の start_time に使った値）

2つ目の途中の手順が、漏れを調べるときの材料です。 お客様の問い合わせで古い記事が見つかったとき、その記事がエージェントの検索に当たっていたのか、当たったのに読まれなかったのか、読まれたのに候補にならなかったのかを、ここで切り分けます。