コンテンツにスキップ

会話中に AI エージェントができること。組み込みの Quickchat AI Actions と、自社 API・MCP サーバー・Google Sheets などのショートカットを呼び出すカスタムアクションを説明します。

会話中に AI エージェントが実行できることを定義します。リアルタイム API データを使った回答、リードや市場調査データの収集、カスタム処理の実行まで対応できます。

Quickchat AI エージェントのアクションには 2 種類あります。

Quickchat AI Actions は組み込み済みで、オンにして設定するだけです。

カスタムアクション は Quickchat AI の外部にアクセスします。

  • API アクション は任意の HTTP エンドポイントを呼び出します。このページで説明します。
  • MCP アクション は MCP サーバー全体を一度に接続します。
  • Google Sheets はワンクリックでログ記録用アクションを用意するショートカットです。

すべてのアクションは AI Action Variables を通じて会話中のデータを参照できます。Jira の例 では、アクションを最初から最後まで作成します。

カスタムアクションを使うと、AI が会話中に外部ツールを呼び出せます。社内検索、チケット作成、通知、ナレッジベースにない最新データの取得などに利用できます。アクションとMCP の カスタムアクション セクションにあります。

+ アクションを追加 をクリックして作成します。ドロップダウンには次の選択肢があります。

  • APIアクション: HTTP を使って任意の REST エンドポイントを呼び出します。最も汎用的な選択肢で、URL があり、JSON を受け付けるサービスに使用できます。
  • MCP: 外部の MCP サーバーにワンクリックで接続し、公開されているツールを AI が利用できるようにします。MCP アクションを参照してください。
  • HubSpotアクション: HubSpot CRM への接続があらかじめ用意されています。API Token を自分で管理せずに、コンタクト、取引、チケットを操作したり、チケットに非公開のメモを追加したりできます。
  • Discordアクション: サポートやモデレーション用の編集可能な APIアクションのテンプレートをインストールします。独自の Discord アプリが必要です。Discordアクションを参照してください。
  • Google Sheets: 接続したスプレッドシートを読み書きします。
  • Shopify MCP: Shopify Storefront MCP サーバーを通じて Shopify ストアに接続します。AI はカタログやストアのポリシーを検索し、商品詳細を読み取り、カートを作成できます。Shopify MCP アクションはシナリオごとに 1 つだけ設定できます。注文の検索には対応していません。以下の注意事項を参照してください。

各 AI エージェントは、最大 15 個のアクションを保存できます。有効なアクションと無効なアクションの両方がこの上限に含まれます。すべてのプランで、作成したアクションを有効にできます。有効なアクション数に対するプラン別の追加上限はありません。空きを作るには、不要なアクションを削除してください。無効にするだけでは空きは増えません。

Shopify Storefront MCP は顧客向けの機能であり、注文データを公開しません。そのため、この接続だけを使用する AI エージェントは顧客の注文を検索できません。注文状況は Shopify Admin API を読み取る別の Check order status APIアクションから取得します。このアクションは、Shopify App Store から Quickchat アプリをインストールすると自動的に設定されます。URL を貼り付けて接続したストアには Admin へのアクセス権がないため、注文を検索できません。必要な場合は App Store から再インストールしてください。

  1. アクションの種類を選びます: APIアクション、MCP、HubSpotアクション、Discordアクション、Google Sheets、Shopify MCP。接続と、AI に必要な指示を設定します。
  2. 会話中、通常は AI がアクションの説明と利用可能なツールまたはパラメータの詳細を使って、実行するタイミングを判断します。API Action は、代わりに最初の返信前、またはメタデータ条件が初めて一致したときに自動実行するよう設定できます。
  3. Quickchat が呼び出しを実行します。AI が選択した Action、または最初の返信前に実行される Action では、AI がレスポンスを利用できます。メタデータによってトリガーされる Action はサイレントに実行され、その出力はチャットに追加されません。
  4. 会話で使用する前に、アクションのエディターでテストまたは接続を行います。

説明は AI への指示として記述します。アクションをいつ使うか、何を返すか、どのような制約があるかを伝えてください。例えば、「ユーザーが注文番号を提供した場合にのみ呼び出す」と記述します。

説明からアクションの下書きを作成する

Section titled “説明からアクションの下書きを作成する”
  1. アクションとMCP で、+ アクションを追加 > APIアクション を選びます。
  2. ワークフロー、エージェントが処理を実行するタイミング、使用する API(またはそのドキュメントへのリンク)、各ステップで必要な情報を記述し、生成 をクリックします。
  3. Quickchat が新しい APIアクションの下書きを最大 4 つ、すべて無効な状態で作成します。生成結果では、重複したアクションを作成する代わりに既存のアクションの利用が提案されたり、追加情報を求められたりすることがあります。下書きを生成しても、アクションは実行されません。
  4. 使用する既存のアクション、前提条件、次のステップ を確認します。設定を完了し、プレースホルダーを実際の値に置き換えて、各アクションのリクエスト、指示、実行条件を確認してください。下書きや、実行に必要な無効状態の既存アクションを有効化する前に、各アクションをテストしてください。

提案された手順は、意図する動作を説明するものです。AI が選択するアクションの実行順序を保証するものではありません。必須入力、保存したメモリ、実行条件を使って、アクション間の依存関係を設定してください。アクションを有効化した後、会話で一連の流れ全体をテストしてください。

  1. アクションとMCP を開きます。
  2. カスタムアクション の + アクションを追加 をクリックし、APIアクション を選んでから、手動で作成 をクリックします。
  3. 詳細 を入力します。
    • 名前: 明快で内容が伝わる名前を付けます。
    • 説明: いつ使用し、パラメータに何を含めるかを記述します。
  4. 実行するタイミング で AIが判断、最初の返信前、メタデータが一致したとき のいずれかを選択します。
  5. 接続 を設定します。
    • APIリクエストメソッド: HTTP メソッド(GET、POST など)を指定します。
    • APIエンドポイントURL: API の完全な URL を入力します。
    • ヘッダー: Authorization や content-type: application/json など、必要なヘッダーを追加します。
  6. パラメータ を定義します。各パラメータに名前、場所(query、body、header)、AI に値の作成方法を伝える説明を設定します。path はパラメータの場所ではありません。{{placeholder}} テンプレートを使って、値をエンドポイント URL に直接挿入してください。
  7. リクエストをテストしてレスポンスを確認し、完了 をクリックします。

すべての値フィールド(URL、ヘッダー、body、query)では、+ AIデータを追加 ボタンから動的なプレースホルダーを挿入できます。AI パラメータ、組み込みの会話変数({{scenario_id}}、{{language}}、{{country}} など)、会話メタデータ({{metadata_*}})を使用できます。詳しくは AI Action 変数を参照してください。

リクエスト本体以外にも、API Action には知っておくと役立つ任意の設定が 3 つあります: メモリに保存、Run only when、Response filter。

APIアクションのリクエストをプレビューするでは、指定したテンプレートと合成のサンプル値を使ってリクエストを確認できます。認証情報を含むヘッダーは省いてください。プレビューではリクエストを表示するだけで、送信はしません。

パラメータのデフォルト値を選ぶ

Section titled “パラメータのデフォルト値を選ぶ”

AIが判断モードの Action で、AI が会話から値を収集する必要がある場合は、デフォルト値なしを選択します。デフォルト値のない必須パラメータでは、空の値を送信できません。意図的に空にしたデフォルト値は別の設定です。既存の空のデフォルト値は空のまま維持されます。エディタは数値の 0 と真偽値の false もデフォルト値として保持します。

テキストまたは数値のパラメータでは、デフォルト値の入力欄の横にある デフォルト値のオプション を開き、デフォルト値なし または 空の値 を選択します。空のデフォルト値は別の値に置き換えられます。真偽値のパラメータでは、ドロップダウンで デフォルト値なし を選択します。

API Action の実行タイミングを選ぶ

Section titled “API Action の実行タイミングを選ぶ”

実行するタイミング で、次の 3 つのモードから選択します。

このセクションはデフォルトで折りたたまれており、見出しの横に現在のモードが表示されます。モードを変更するには展開してください。

展開した「実行するタイミング」セクション。AIが判断、最初の返信前、メタデータが一致したとき の 3 つのモードが表示されている

  • AIが判断:デフォルトです。AI が Action の説明を読み、訪問者の依頼に Action が必要かどうかを判断します。特定の質問に対してのみ Action を実行する場合や、AI が訪問者から情報を収集した後に実行する場合に使用します。
  • 最初の返信前:訪問者が最初のメッセージを送信した後、AI が最初の返信を作成する前に、Quickchat が Action を 1 回実行します。通常の AI 返信には、API レスポンスと メモリに保存 で保存した値が渡されます。この Action は AI がツールとして選択できなくなるため、最初のターンでのみ実行され、会話の後半で再度実行されることはありません。顧客の識別、アカウント情報の取得、権限の確認など、実際に始まったすべての会話で必要な初期処理に使用します。
  • メタデータが一致したとき:Quickchat は各 AI ターンの後に Action の 次の場合に実行 条件を確認し、すべての条件が初めて一致したときに実行します。同じターン中に別の Action が メモリに保存 で保存した値もすぐに使用できます。AI はこの Action をツールとして選択できず、そのレスポンスはチャットに追加されません。会話データが利用可能になったときに自動的に行う必要がある社内通知、CRM の更新、フォローアップリクエストに使用します。

最初の返信前 は会話の作成時ではなく、訪問者の最初のメッセージを基準にします。チャットを開いたりウェルカムメッセージを受信したりするだけでは実行されないため、放棄されたチャットからリクエストは送信されません。Quickchat はエンドポイントを呼び出す前に実行を記録します。そのため、リクエストが失敗した場合や結果が不明な場合でも、同じ会話では再試行されません。

最初の返信はリクエストの完了を待つため、このモードでは待ち時間が長くなる場合があります。複数の Action がこのモードを使用する場合は順番に実行され、各リクエストの所要時間が加算されます。必要なメタデータがない場合、エンドポイントが利用できない場合、またはリクエストが失敗した場合でも、AI は返信します。詳細は Action の リクエストログ を開いて確認してください。

Action は AI がパラメータ値を選択する前に実行されるため、使用するすべての AI パラメータにデフォルト値が必要です。メタデータと組み込み変数は、URL、ヘッダー、query、body に直接挿入できます。

メタデータが一致したとき では、次の場合に実行 条件を少なくとも 1 つ設定し、すべての AI パラメータにデフォルト値を指定する必要があります。Quickchat はエンドポイントを呼び出す前に実行の試行を記録するため、リクエストがいったん送信されると、成功しても失敗しても結果が不明でも、同じ会話では再試行しません。必要な値がまだそろわずリクエストを組み立てられなかった場合は記録されず、後のターンで再び対象になります。Action は AI がターンを終えた直後に実行されるため、失敗しても AI の返信が置き換わることはありません。返信をストリーミングしないチャネルでは、リクエストの往復時間が訪問者の待ち時間に加わります。

メタデータが一致したとき を選ぶと、同じセクション内に 次の場合に実行 のエディタが表示され、トリガーと条件をまとめて確認できます。

「実行するタイミング」を「メタデータが一致したとき」に設定した状態。「次の場合に実行」に escalation_flag is true と order_id exists の 2 つの条件がある

メールアドレスまたは電話番号のどちらかが提供される可能性があるチャネルでは、識別子ごとに検索用 Action を 1 つずつ作成します。両方を 最初の返信前 に設定し、それぞれに visitor_email exists または visitor_phone_number exists のような対応する Run only when 条件を追加します。Quickchat は存在するメタデータに対応するリクエストだけを送信します。

会話終了時の Webhook と会話記録

Section titled “会話終了時の Webhook と会話記録”

API アクションはチャット中に Webhook へ通知できます。AIが判断 で会話の締めくくりに呼び出すよう指示しても、実行は保証されません。標準の実行モードでは、会話の終了、訪問者の非アクティブ化、ブラウザーのタブを閉じる操作による呼び出しは保証されません。

正確な会話記録が必要な場合は、連携側で会話の終了条件を定義してください。{{conversation_id}} をバックエンドに渡し、read_all 権限を持つ API トークンで、limit と offset を使って会話イベントのすべてのページを取得します。メッセージイベントから会話記録を作成してください。トークンはバックエンドに保管します。

会話記録を含む組み込み変数はありません。AI が生成した要約や会話記録のパラメーターは、正確なコピーを保証しません。送信できるコンテキストについては AI アクション変数を参照してください。

HubSpotアクションでは、接続済みの HubSpot アカウントを使用する、入力済みで編集可能な API Action のギャラリーを利用できます。

「HubSpot CRM Actions」ギャラリー。「Tickets」の下に「Add Note to Ticket」がある

チケットにメモを追加テンプレートは、会話に紐づいた HubSpot チケットに非公開のメモを作成します。メモの内容を hubspot_note_body として会話メモリに保存してから、テンプレートを追加して有効化します。このテンプレートでは メタデータが一致したとき があらかじめ設定されており、hubspot_note_body と Quickchat がサーバー側で提供する hubspot_ticket_id の両方が存在するまで待機します。note_body パラメータのデフォルト値を編集すると、{{metadata_hubspot_note_body}} の前後に固定テキストを追加できます。

このメモは HubSpot 内部専用で、訪問者には表示されません。テンプレートは Quickchat の会話ごとに 1 回だけリクエストを試行します。配信の確認や失敗したリクエストの調査には、Action の リクエストログ を開いてください。

Discordアクションでは、入力済みで編集可能な API Action のギャラリーを利用できます。

  • サポートとチケット: サポートチケットを開くでは、サーバーとテキストチャンネルを選択します。メンション可能なサポートロールは任意で選択できます。プライベートスレッドを開き、現在の依頼者を追加し、必要に応じてロールをメンションする要約を投稿する 3 つの Action が作成されます。
  • モデレーション: メンバーをタイムアウト、メンバーをキック、メンバーをBAN、メンバーのBANを解除、ロールを割り当て、スローモードを設定、アナウンスを送信。各テンプレートは 1 クリックでインストールされ、現在の Discord リクエストに含まれるサーバー、メンバー、ロール、チャンネルを使用します。

Quickchat は HTTP メソッド、URL、ヘッダー、body、パラメータ、説明、レスポンス設定、実行条件を backend で作成します。作成されたカードは通常の HTTP Request Action です。すべてのフィールドを確認して編集できます。

7 つのモデレーションテンプレートにはすべて、次の場合のみ実行に author_is_admin is true が含まれます。Discord が現在の送信者の Administrator 権限を計算し、Discord gateway がその値を渡し、Quickchat がリクエスト送信前に確認します。公開チャットと API メタデータからこのキーを設定することはできません。Discord 上で管理者アカウントと管理者ではないアカウントの両方を使ってモデレーション Action をテストしてください。AI Preview では認可済みの Discord 送信者を利用できません。

モデレーション Action は編集できます。author_is_admin is true 条件を削除または弱めると、提供されている認可境界がなくなります。メンバーをキックとメンバーをBANは、実行前に確認を求めません。

テンプレート自体は何も自動化しません。エージェントがテンプレートを実行するのは、会話の中で管理者が依頼したときだけです。会話をまたいだストライクの集計、スクリーンショットなどの証拠の検証、スケジュールされた制裁やエージェントが自発的に行う制裁はありません。

Bot 自体には、各リクエストに必要な Discord 権限が引き続き必要です。

アクションBot の権限またはアクセス
メンバーをタイムアウトModerate Members
メンバーをキックKick Members
メンバーをBAN、メンバーのBANを解除Ban Members
ロールを割り当てManage Roles
スローモードを設定Manage Channels
アナウンスを送信View Channels と Send Messages

Discord はロール階層も適用します。Bot のロールを、管理対象のメンバーやロールより上位に配置してください。テンプレートでは、リクエストした管理者のロール階層や個別の権限を追加で確認しません。

スローモードを設定とアナウンスを送信は、チャンネル ID パラメータを受け取ります。追加の固定対象がない場合、テンプレートはそのチャンネルが管理者のリクエスト元サーバーに属することを検証しません。同じ Bot が複数のサーバーに参加している場合は、これらの Action を固定チャンネル ID を使うよう編集するか、サーバーごとに Agent と Bot の認証情報を分け、別々の信頼境界にしてください。

Support Ticket のインストールでは、既存の Action 機能を使用してデータを渡します。

  1. open_support_ticket は選択したチャンネルにプライベートスレッドを作成し、$.id を取得して discord_ticket_thread_id として会話メモリに保存します。discord_message is true が必須で、選択したサーバーで、そのメモリキーが存在しない場合にのみ実行されます。
  2. add_ticket_requester は {{metadata_discord_ticket_thread_id}} と、Discord が提供する {{metadata_discord_author_id}} を読み取ります。discord_message is true が必須で、スレッド ID が存在する場合に、選択したサーバーでのみ実行されます。
  3. post_in_ticket は同じ保存済みスレッド ID を読み取り、Agent が作成した問題の 1 行要約を投稿して、依頼者をメンションします。サポートロールを選択した場合は、そのロールもメンションします。Discord メッセージ、サーバー、保存済みスレッドについて同じ条件が設定されています。Discord のリクエスト body にある allowed_mentions は、依頼者と、設定されている場合はそのロールに限定されます。

説明と Agent のメインプロンプトで、これらの Action をこの順序で実行するよう指示してください。専用のワークフロー状態、ロック、確認、再試行、復旧、照合、replay protection のレイヤーはありません。結果が不明な場合、Discord がすでにリクエストを完了している可能性があるため、再試行する前に Discord と Action ログを確認してください。

discord_ticket_thread_id は自動的に消去されません。そのため、このテンプレートで作成できるチケットは Quickchat の会話ごとに 1 件です。別のチケットには新しい Discord の会話またはスレッドを開始するか、必要なメモリのライフサイクルを追加するよう Action を編集してください。

Support Ticket では、選択したチケットチャンネルで Bot に View Channels、Send Messages、Read Message History、Create Private Threads、Send Messages in Threads、Manage Threads を付与してください。ロールをメンションしない場合は、ロールに通知(任意)をロールに通知しないに設定してください。ロールを選択した場合は、そのロールをメンション可能にし、そのメンバーがプライベートスレッドにアクセスできるようにします。ロールを選択しない場合やメンション可能なロールがない場合も、ロールへの通知なしでチケットは通常どおり開かれます。ギャラリーにはテキストチャンネルとメンション可能なロールが表示されますが、チャンネルの権限上書きをすべて検証するわけではありません。

Discordアクションには、外部アプリ → Discord → 高度なセットアップにある独自の Discord アプリの Token が必要です。共有のワンクリック Bot だけでは、その Token を提供できません。Discordも参照してください。

ギャラリーは設定を省力化するもので、追加のポリシーレイヤーではありません。生成された Action を編集する場合やカスタム Discord API Action を作成する場合は、有効化する前に認証情報、対象、パラメータ、レスポンスの公開範囲、次の場合のみ実行の条件を確認してください。

アクションの入力またはAPIレスポンスの値を、任意のキーを付けて会話のメモリに保存します。後続のアクションはそれを {{metadata_<key>}} として再利用でき、会話の詳細(Inbox、API、エクスポート)にも表示されます。

ある Action が生成した値を、後続の Action が必要とする場合に使います。検索系の Action がレスポンスから customer_id を保存しておけば、後続の Action は AI に値をコピーさせることなく {{metadata_customer_id}} を送信できます。

APIアクションのエディタで メモリに保存 を開き、行を追加します。

  1. 取得元 を選びます。APIレスポンス は API の JSON レスポンスを読み取り、新しい行のデフォルトになります。アクションの入力 は、そのアクションで定義した入力パラメータの値を読み取ります。
  2. アクションの入力 の場合は、保存する値 でドロップダウンからパラメータを選びます。APIレスポンス の場合は、$.customer_id などの JSONPath式 を入力します。
  3. メモリキー を選びます。名前、電話番号、メールアドレスを表す一般的な英語の入力名には、対応する訪問者のキーが提案されます。提案されたキーをそのまま使うことも、独自のキーを入力することもできます。

Inbox に連絡先を保存するには、アクションの入力 を選び、次のように対応付けます。

Actionパラメータメモリキー
Name または Full namevisitor_name
Phone number または Phonevisitor_phone_number
Email または Email addressvisitor_email

入力はアクションで定義する必要があります。アクションの入力 のメモリルールで保存すると、パラメータを使用しているとみなされます。そのため、HTTP リクエストに含めずに、メモリ用の値として収集できます。これらの訪問者のキーは、スマートデータ収集と同じ検証を行ったうえで、Inbox の未設定の連絡先フィールドと会話メタデータに値を入力します。既存の連絡先や、オペレーターが明示的に消去したフィールドは変更しません。APIレスポンスのルールからは、これらの訪問者のキーに書き込めません。CRM のレスポンスから取得した値には、customer_id などのカスタムキーを使用してください。

入力値は、アクションの必須入力と実行条件のチェックを通過した後、HTTP リクエストを送信する前に保存されます。そのため、API がエラーを返したりタイムアウトしたりしても、有効な連絡先は残ります。動作を確認するには、新しいプレビューの会話でアクションを実行し、その会話を Inbox で開いてください。エディタの単独の API テストには、メモリの保存先となる会話がありません。

メモリキーは、エージェントの Remote MCP ツールと共有されます。同じキーを MCP ツールがすでに保存している場合は、保存時に メモリキー の項目で重複が通知されるため、別のキーを指定してください。Remote MCP ツールは、引き続きツールの結果から値を保存します。

キーは snake_case(英字、数字、アンダースコア)を使ってください。customer_id のようなキーは {{metadata_customer_id}} として参照できますが、スペースやその他の記号を含むキーはプレースホルダーで使用できません。メタデータ変数の仕組みについては 会話メタデータ を参照してください。

Action を、会話メタデータの条件が満たされたときにのみ 実行されるよう制限します。条件は常にモデルの外側で、Quickchat によって確認されます。AIが判断 または 最初の返信前 では、Quickchat はリクエストを送信する直前に条件を確認します。メタデータが一致したとき では、AI が Action を選択するのを待たず、AI ターンの後に条件自体がリクエストをトリガーします。

これは、権限を要する操作や取り消せない操作(メンバーの BAN、返金、レコードの削除)に適したツールです。プロンプト内の「これは管理者のみ実行可能」という一文は有用な指示ではありますが、セキュリティ境界ではありません。執拗なユーザーはモデルを言いくるめたり、プロンプトインジェクションを試みたりできます。実行条件は決定論的でプロンプトの外側に存在するため、会話で何が言われようとも保持されます。

  • 実行条件が境界です。 サーバー側で評価され、モデルが読むプロンプトには含まれません。これが実際に Action の実行を止めるものです。
  • プロンプトのルールはユーザー体験のためです。 AI が無言になるのではなく丁寧に断り、理由を説明できるよう、プロンプトにも一文を残しておきましょう。

Action エディタの 次の場合のみ実行 セクションで条件を追加します。メタデータが一致したとき の Action では、このセクションは 次の場合に実行 と表示されます。条件を追加 をクリックし、メタデータキー(例: telegram_sender_is_admin)を選び、比較方法を選択します:

条件次の場合に通過します。メタデータの値が…
が truetruthy である
が falsefalsy である
が存在する会話に存在する
が存在しない存在しない
が次と等しい指定した値と一致する
が次と等しくない指定した値と異なる
いずれかと一致一覧のいずれかの値と、大文字と小文字や空白も含めて完全に一致する
テキストを含むテキストであり、指定した文字列を大文字と小文字を区別してそのまま含む

Action は すべて の条件が満たされたときにのみ実行されます。エディタでは、行の間に かつ が表示されます。AI が選択した Action が条件によってブロックされた場合、AI はその Action を利用できないことを説明できます。メタデータが一致したとき の Action は、条件が満たされるまで何も出力しません。

同じキーに複数の候補を指定するには、いずれかと一致 を使用し、候補の値をそれぞれ別のチップとして入力します。例えば、modelName is one of [K-65XR95M2, K-75XR95M2, K-85XR95M2] と country equals UK を併せて設定できます。この場合、両方の行の条件を満たす必要があります。候補は最大 50 個まで追加でき、各値は最大 500 文字です。カンマは値の一部としてそのまま扱われます。同じキーに対して異なる値の が次と等しい を別々の行に設定すると、すべてを満たすことはできません。

テキストを含む は、ワイルドカードや正規表現ではなく、文字列の一部を文字どおりに照合します。XR95M2 は、上記の 3 つ以外の派生モデル名にも一致します。どちらの新しい条件も、キーが存在しない場合、null、リスト、オブジェクトには一致しません。テキストを含む は数値や真偽値にも一致しません。比較するテキストを空にすることはできません。既存の が false、が次と等しくない、が存在しない は、キーが存在しない場合にも一致することがあります。

telegram_sender_is_admin が true という条件が 1 つ設定された Run only when セクション

AI が選択した Action で条件が満たされない場合、リクエストは送信されず、AI はユーザーにそれができない旨を伝えます。以下では、同じ BAN リクエストが、非管理者に対してはブロックされ、管理者に対しては許可されています。変わっているのは誰が依頼しているかだけです:

非管理者の BAN 試行が実行条件によってブロックされる様子: リクエストは送信されず、結果は拒否となる

管理者による同じ BAN リクエスト: 実行条件が通過し、Action は 200 を返す

ゲートに使うのは Quickchat が設定する メタデータ(チャネルで検証された telegram_sender_is_admin フラグなど)だけにし、訪問者が左右できる値は使わないでください。各キーの出所については 会話メタデータ を参照してください。

デフォルトでは、AI は API レスポンス全体 を見ます。Response filter セクションに JSONPath 式を追加すると、AI が見る範囲をその特定の部分だけに限定できます。

フィルターをかける一般的な理由は 2 つあります:

  • 機密フィールドを隠す。 エンドポイントが AI に必要な以上の情報を返す場合に、顧客のメールアドレス、支払い情報、内部 ID をモデルのコンテキストから除外します。
  • プロンプトを小さくする。 冗長な API は大きなペイロードを返すことがあります。重要な数フィールドにフィルターすることで、レスポンスを小さく保ち、AI の焦点を絞ります。

1 つ以上の JSONPath 式を追加します。フィルターは、選択したフィールドを値だけの平坦なリストに変換せず、それらを含むオブジェクトや配列の構造を保ちます。選択したパスに含まれないフィールドは除外されます。例えば、次の 2 行を使用します。

  • $.customer.name
  • $.orders[*].id

次の API レスポンスが返された場合:

{
"customer": {"name": "Ada", "email": "ada@example.com"},
"orders": [{"id": 101, "total": 25}, {"id": 102, "total": 40}]
}

AI は次のフィルター済みレスポンスを受け取ります。customer はオブジェクトのままで、orders はオブジェクトの配列のままです。

{
"customer": {"name": "Ada"},
"orders": [{"id": 101}, {"id": 102}]
}

Test Response パネルを使うと、フィルター適用後に AI が実際に受け取る内容を、運用に頼る前に正確に確認できます。Action のテスト を参照してください。

何にも一致しない JSONPath は、AI に空のレスポンスを残します。まずフィルターなしで始め、呼び出しが機能することを確認してから、絞り込んでください。

API Action エディタの Response filter セクション

JSONPath の一致をプレビューするでは、指定した JSON レスポンスを確認できます。レスポンスフィルタやメモリに保存のルールで使用する、ルート、フィールド、配列インデックス、ワイルドカードのパスに対応しています。

サイドバーの アクションとMCP の横に警告が表示されている場合は、確認が必要な Action があります。ページを開き、カードのバッジにカーソルを合わせるか、キーボードでフォーカスして理由を確認してください。

  • 失敗中: 最近の呼び出しが繰り返し失敗しています。バッジには失敗回数と、取得できる場合は最新のエラーが表示されます。
  • 未実行: Action が繰り返しスキップされ、現在の状態判定の対象期間には実行された呼び出しがありません。会話の値の不足や設定の問題など、表示された理由を確認してください。
  • 再接続が必要: MCP 接続の認証が失われ、無効になっています。編集 を開いて再接続し、再び有効にしてください。

状態の判定には、直近 7 日間の実際の会話が使用されます。ただし、Action の最終編集がそれより最近の場合は、編集後の会話が対象です。テストリクエストとは別に判定されます。Action を修正して保存したら、新しい会話で修正の効果を確認してください。以前の警告が消えただけでは、正常に動作することを確認できません。

失敗中 または 未実行 の場合は、詳細を表示 をクリックすると、問題のみ が有効な状態で リクエストログ が開きます。ログを表示 をクリックすると、すべての呼び出しが表示されます。問題のみ を無効にすると、問題のあった呼び出しと成功した呼び出しを比較できます。

スキップされた会話 には、Action を実行できなかった会話が、実行された呼び出しとは別に表示されます。会話を表示 で状況を確認し、さらに表示 で以前の項目を読み込めます。ある会話では Action が成功し、別の会話ではスキップされることもあるため、警告バッジがなくてもこの一覧が表示される場合があります。

理由に {{metadata_visitor_email}} などの不足している値が表示されている場合は、ウェブサイトやチャネルのメタデータを通じてその値を渡すか、先に実行される Action でメモリに保存してください。そのうえで、実行モードを確認します。

  • AIが判断: 必要な値がすでに存在する会話でのみ、AI がその Action を利用できます。
  • 最初の返信前: 訪問者が最初のメッセージを送信した時点で、値が存在している必要があります。
  • メタデータが一致したとき: 必要な値ごとに が存在する 条件を追加すると、Action はその値が揃うまで待機します。

会話の値の取得元については、AI Action の変数 を参照してください。

アクティビティサマリーメールには、HTTP またはリモート MCP Action に対応が必要な場合、AI Actions need attention セクションも含まれます。最大 5 件の Action が、理由と アクションとMCP へのリンクとともに表示されます。6 件以上ある場合は、ほかに対応が必要な Action の件数も表示されます。すべて正常な場合、このセクションは表示されません。

メールには現在の状態が表示されるため、日次サマリーのアクティビティ対象期間よりも広い期間が対象になる場合があります。API Action を修正して保存すると、その編集以降のデータを使って状態が判定されます。該当する MCP 接続を再接続または切断すると、その認可に関する警告が消えます。既存のサマリーメールの設定と送信対象の条件が適用され、個別のアラートメールは送信されません。

  • 説明は具体的に記述します。 アクションを使うタイミングと各パラメータに含める値を AI に伝えてください。
  • スコープを最小限にします。 エンドポイントに必要なヘッダーと Token だけを含めてください。Jira では、Atlassian のメールアドレスと API Token から作成した Basic ヘッダーを使用します。
  • 公開前にテストします。 リクエストのテストパネルを使い、対象ツールのステータスコードとサンプルのペイロードが適切であることを確認してください。

最終更新日: