トラブルシューティング

エージェントの Cloud Logging を有効にする

エージェントの Cloud Logging を有効にします。これは、実際の会話でデータを取得して問題を診断するために不可欠です。

会話 ID を収集する

予期しない動作が発生した場合は、Dialogflow の会話 ID を収集します。会話履歴にあるこれらの ID を使用すると、会話の実行パスをトレースして、特定のインタラクションを調べることができます。

API 呼び出しで権限が拒否される

問題

API 呼び出しに対して「PERMISSION_DENIED」というレスポンスが返されました。

ソリューション

（Dialogflow CX、Dialogflow ES）認証とロールが正しく設定されていることを確認します。特に、次のことを行っていることを確認します。

• サービス アカウントを作成しており、誤って削除していない。
• 選択したメソッドを呼び出す権限を付与するロールをサービス アカウントに付与した。
• サービス アカウントの秘密鍵ファイルをダウンロードした。
• GOOGLE_APPLICATION_CREDENTIALS 環境変数を秘密鍵ファイルに設定した。

API 呼び出しでの不明なプロジェクト

問題

API 呼び出しで Dialogflow API has not been used in project 32555940559 エラーが発生する。

解決策

次のことを行っていることを確認します。

• GOOGLE_APPLICATION_CREDENTIALS 環境変数を設定した（PERMISSION_DENIED を参照）。
• API 呼び出しに正しいプロジェクト ID を指定した。

API 呼び出しで無効な認証情報エラーが表示される

問題

API 呼び出しに対して「Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.」というレスポンスが返されました。

ソリューション

これは、デフォルト以外のリージョンを指定するときに、クライアント ライブラリを使用して認証情報を手動で作成していることが原因かもしれません。次のいずれかをご覧ください。

• API を使用してリージョンを選択する（Dialogflow CX）
• API を使用してリージョンを選択する（Dialogflow ES）

API 呼び出しのレスポンスで別のホストへの切り替えがリクエストされる

問題

API 呼び出しに対して「Please switch to 'REGION-dialogflow.googleapis.com' to access resources located in 'REGION'」というレスポンスを受信しました。REGION は特定のリージョン ID です。

ソリューション

これは、リクエストでリージョンを指定するが、エンドポイントでは指定しない場合に発生します。次のいずれかをご覧ください。

• API を使用してリージョンを選択する（Dialogflow CX）
• API を使用してリージョンを選択する（Dialogflow ES）

API 呼び出しのレスポンスにフィールドがない

問題

API レスポンスのフィールドが一部欠如しています。

ソリューション

API レスポンスの特定のフィールドに数値を想定する場合、戻り値が 0 であれば、フィールドはレスポンスに存在しない可能性があります。

デフォルト値の動作（数以外の値を含む）について詳しくは、以下をご覧ください。

• プロトコル バッファ（Dialogflow CX）
• プロトコル バッファ（Dialogflow ES）

リーエンが原因でプロジェクトを削除できない

問題

Google Cloud プロジェクトを削除しようとすると、そのプロジェクトにリーエンが設定されていてリーエンの 1 つが Dialogflow ES に関連付けられているため、プロジェクトを削除できないという内容の通知が表示されます。

ソリューション

1. プロジェクトに関連付けられている Dialogflow ES エージェントが不要になったことを確認してください。エージェントが存在しないという通知が表示された場合、エージェントが削除済みであることを意味します。

   Dialogflow ES コンソール

   https://dialogflow.cloud.google.com/#/agent/project-id/intents を開きます。

   このリンクは、 Google Cloud プロジェクトの削除ダイアログのリンクとは異なります。

   Dialogflow API

   agent タイプの search メソッドを使用します。

2. リーエン名を取得します。

   gcloud

   プロジェクトに適用されているリーエンを一覧表示するのドキュメントで説明されている gcloud alpha resource-manager liens list コマンドを使用します。

   API Explorer

   [Method: liens.list] ページの [この API を試す] パネルを使用します。

   • パラメータの説明で推奨されているように、parent フィールドに入力します。
   • [実行] をクリックします。

3. リーエンを削除します。

   gcloud

   プロジェクトからリーエンを削除するのドキュメントで説明されている gcloud alpha resource-manager liens delete LIEN_NAME コマンドを使用します。

   API Explorer

   [Method: liens.delete] ページの [この API を試す] パネルを使用します。

   • name フィールドに、ステップ 2 で取得したリーエン名を入力します。
   • [実行] をクリックします。

4. プロジェクトをシャットダウンします。

Dialogflow CX Webhook が期限超過エラーで失敗する

問題

Dialogflow CX から呼び出された Webhook が次のエラー メッセージで失敗することがあります。

Webhook call failed. Error: DEADLINE_EXCEEDED

これは、Webhook 呼び出しが Webhook のタイムアウト上限を超えているために発生することがあります。Webhook 呼び出しがタイムアウト上限を超える原因としては、次のことが考えられます。

• 存在しないインテントをトリガーしようとしている。
• Webhook バックエンド（Cloud Functions など）のコールド スタートの問題。
• Webhook が他のサービスを呼び出して、応答時間が増加する。
• エージェントと Webhook バックエンド間の接続がない（ロードバランサの構成ミスなど）。
• 上り（内向き）トラフィックまたは Dialogflow メソッドの実行を禁止する組織のポリシー。

回避策

Webhook のデフォルトのタイムアウトは 5 秒に制限されています。Webhook リソースを作成または編集するときに Webhook タイムアウトの上限を増やすと、Webhook が応答するまでの時間が長くなります。

コンソールでプロジェクトを設定できない

問題

コンソールを使用してエージェントを作成すると、Failed to set up GCP project エラーが発生する。

ソリューション

Google Cloud プロジェクトを作成する権限がない可能性があります。コンソールから直接 Google Cloud プロジェクトを作成できるかどうかを確認します。プロジェクトを作成できない場合は、エラー メッセージに記載されている推奨事項に従ってください。

レスポンスに表示されるセッション パラメータ リファレンス

問題

Dialogflow から返されるレスポンスには、パラメータの値ではなくパラメータ参照が含まれます。次に例を示します:
Hello, $session.params.customer_name

パラメータが現在のセッションで見つからない場合、またはパラメータがその型に従って使用されていない場合、パラメータは解決されず、パラメータ参照が表示されます。

ソリューション

この問題は、使用されたパラメータが会話に含まれていない、タイプミスがある、使用された型と異なる型であるなどの理由で発生することがあります。

API が有効化されていないと、コンソールでのエージェント作成に失敗する

問題

コンソールを使用してエージェントを作成すると、Dialogflow API has not been enabled for the project. Code: FAILED_PRECONDITION エラーが発生する。

ソリューション

設定手順に沿って Dialogflow API を有効にします。

組織アカウントからコンソールにアクセスしようとすると、サービスエラーが発生する

問題

組織アカウントからコンソールにアクセスしようとしたときに You don't have access to this service エラーが発生する。

ソリューション

組織のシステム管理者に連絡し、組織の設定でコンソールにアクセスできることを確認してください。それ以外の場合は、別の組織から移行したアカウントが Google によって制限されていると報告されていないか確認します。組織内の他のユーザーがコンソールにアクセスできるにもかかわらずアクセスできない場合は、これがおそらく問題になります。

または、サポートにお問い合わせください。

フローがないため、エージェントを JSON 形式でエクスポートできない

問題

エージェントの未加工バイトとしてのエクスポートは正常に完了しますが、JSON 形式でエージェントをエクスポートすると、次のようなエラー メッセージが表示されて失敗します。

Flow 'projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/flows/FLOW_ID' does not exist
in the agent

この問題は、削除されたフローを参照するテストケースが原因で発生することがあります。

ソリューション

この問題を解決するには、未使用のテストケースを調べて、エラー メッセージで参照されているフローがテストケースで使用されているかどうかを確認し、確認されたテストケースを削除します。

Phone Gateway の接続

問題

電話ゲートウェイを使用する場合に、ビジー信号を受信するか、通話が中断されます。

ソリューション

この機能には割り当てと制限があります。ビジー信号を受信するか、通話が中断される場合、割り当てを超えている可能性があります。

新しい電話番号を作成しようとすると RESOURCE_EXHAUSTED エラーが発生する

問題

Dialogflow CX、Dialogflow ES、または Agent Assist で新しい電話番号を作成しようとすると、RESOURCE_EXHAUSTED エラーが返されます。

ソリューション

このエラーは、プロジェクトあたりの電話番号の上限を超えたことを意味します。新しい電話番号を作成するには、プロジェクトに関連付けられている未使用の電話番号を上限以下になるまで削除します。

Dialogflow CX Phone Gateway または Dialogflow ES Phone Gateway で電話番号を作成した場合は、コンソールで削除できます。電話番号を削除せずにエージェントを削除しても、関連付けられている電話番号は削除されません。

または、次の手順で API を使用することもできます。

手順 1. プロジェクトに関連付けられているすべての電話番号を特定する

プロジェクトに関連付けられている電話番号を特定するには、電話番号を作成した可能性のあるすべてのリージョンで projects.phoneNumbers/list または projects.locations.phoneNumbers.list API メソッドを使用します。

• global リージョンの場合は、次のコマンドを使用します。

  curl -X GET \
  -H "Authorization: Bearer "$(gcloud auth print-access-token) \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json; charset=utf-8" \
  https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/global/phoneNumbers
  

• 他のリージョンでは、リージョンを次の 2 か所で指定する必要があります。

  curl -X GET \
  -H "Authorization: Bearer "$(gcloud auth print-access-token) \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json; charset=utf-8" \
  https://REGION_ID-dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/REGION_ID/phoneNumbers
  

手順 2. （省略可）会話プロファイルに関連付けられたエージェントを特定する

会話プロファイルから電話番号に関連付けられた Dialogflow CX エージェント ID を取得すると、エージェントがまだ使用されているかどうか、電話番号がまだ必要かどうかを特定できます。これを行うには、projects.conversationProfiles/get API メソッドを使用します。会話プロファイル ID は、手順 1 で実行したコマンドのレスポンスで確認できます。

• global リージョンの場合は、次のコマンドを使用します。

  curl -X GET \
  -H "Authorization: Bearer "$(gcloud auth print-access-token) \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json; charset=utf-8" \
  https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/global/conversationProfiles/CONVERSATION_PROFILE_ID
  

• 他のリージョンの場合は、次の 2 か所でリージョンを指定します。

  curl -X GET \
  -H "Authorization: Bearer "$(gcloud auth print-access-token) \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json; charset=utf-8" \
  https://REGION_ID-dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/REGION_ID/conversationProfiles/CONVERSATION_PROFILE_ID
  

Dialogflow CX コンソールで、[すべてのエージェントを表示] ページの [検索] オプションを使用して、ID でエージェントを見つけることができます。

Dialogflow ES の場合、1 つのプロジェクトに関連付けることができるエージェントは最大 5 つまでで、1 つの Dialogflow ES エージェントに関連付けることができる電話番号は 1 つです。そのため、https://dialogflow.cloud.google.com/#/editAgent/PROJECT_ID/intents から Dialogflow ES コンソールでエージェントを開くことができます。

エージェントが見つからない場合でも、電話番号が不要になったことが確実であれば、電話番号を削除できます。

手順 3. 未使用の電話番号を削除する

不要になった電話番号を削除するには、projects.phoneNumbers/delete または projects.locations.phoneNumbers.delete API メソッドを使用します。電話番号 ID は、ステップ 1 で実行したコマンドのレスポンスで確認できます。

• global リージョンの場合は、次のコマンドを使用します。

  curl -X DELETE \
      -H "Authorization: Bearer "$(gcloud auth print-access-token) \
      -H "X-Goog-User-Project: PROJECT_ID" \
      -H "Content-Type: application/json; charset=utf-8" \
      https://dialogflow.googleapis.com/v2beta1/PHONE_NUMBER_ID
  

• 他のリージョンの場合は、リージョンを指定します。

  curl -X DELETE \
      -H "Authorization: Bearer "$(gcloud auth print-access-token) \
      -H "X-Goog-User-Project: PROJECT_ID" \
      -H "Content-Type: application/json; charset=utf-8" \
      https://REGION_ID-dialogflow.googleapis.com/v2beta1/PHONE_NUMBER_ID
  

Dialogflow CX Messenger のレスポンスがない

問題

Dialogflow CX Messenger のインタラクションに対するエージェント レスポンスがありません。

ソリューション

Dialogflow CX Messenger からのレスポンスが表示されない場合は、プロジェクトで課金が有効になっていて、Dialogflow API が有効になっていることを確認します。設定手順をご覧ください。

エンティティの類義語ではないパラメータ値が一致した

問題

• 一般的なケース: パラメータ値は、パラメータに対応するエンティティに類義語として一致する値がない場合でも、実行時に抽出されます。
• より具体的なケース: 類義語がエンティティから削除され、エージェントが再トレーニングされた後でも、この類義語は引き続きエンティティのパラメータ値として抽出されます。

ソリューション

1. search オプションを使用して、一致する値が暗黙的なエンティティ（Dialogflow CX、Dialogflow ES）としてエージェントに存在するかどうかを確認します。このパラメータとエンティティがあるアノテーションを持つすべてのインテントを見つけます。
2. 望ましくない値を表すテキストにこうしたアノテーションがいずれも適用されないように、アノテーションを修正します。
3. 実行時にエージェントをテストして、問題が解決したかどうかを確認します。
4. 問題が解決しない場合は、高度なエンティティ設定で [自動拡張] オプションと [ファジー マッチング] オプションがオフになっていることを確認し、エージェントを再度テストします。

音声 bot が一部のレスポンスをスキップする

問題

テキストと音声の両方用に設計されたエージェントで、音声 bot が一部の回答を読まない。

ソリューション

特定の会話ターンに対して少なくとも 1 つの出力音声テキストのレスポンスが定義されている場合は、この会話ターンのすべてのステップで、出力音声テキスト オプションがエージェントのフルフィルメントと Webhook のレスポンスよりも一貫して存在することを確認します。

SSML タグが機能しない

問題

SSML タグはエージェント フルフィルメントで定義されるが、音声 bot は SSML 効果なしで合成されたテキストを読み取る。

ソリューション

Dialogflow コンソールのレスポンス カードごとに、または API や Webhook を介してレスポンスが提供される場合はレスポンス メッセージ オブジェクトごとに、1 つの <speak></speak> ペアのみが存在するようにします。

音声エージェントがゼロを文字 O と発音

問題

音声用に設計されたエージェントで、音声エージェントがゼロをゼロではなく文字 O と発音する。

ソリューション

1. 出力音声テキスト ダイアログ オプションを使用するようにエージェントの発話を変更します。
2. [SSML] チェックボックスをオンにします。
3. テキストを SSML タグで囲みます。

     <speak>
       <say-as interpret-as='verbatim'>YOUR_TEXT</say-as>
     </speak>

4. 保存します。

たとえば、クレジット カード番号のゼロは、0 とスペルされます。

   <speak>
      <say-as interpret-as='verbatim'>5177 7702 8500 4578</say-as>
   </speak>

予期しない合成発音

問題

エージェントのレスポンスで合成された発音（固有名詞、略語など）が、想定どおりではありません。

ソリューション

一般的ではない単語に対して特定の発音を保証するには、エージェント レスポンスで SSML の say-as または phoneme タグを使用します。

ステートマシンの許容される最大実行ステップ数に達しました

問題

エージェントにランタイム リクエストを送信したときに、Dialogflow CX コンソールまたはログに次のエラー メッセージが表示された場合:

You have reached the maximum allowed state machine execution steps. You may consider simplifying your agent/flow design. Current execution steps are: [<array_of_objects>]

エラー メッセージの配列には、リクエストの実行ステップのリストが含まれています。ステップ数が多すぎると、リストが不完全になることがあります。

ソリューション

このエラー メッセージは通常、1 回の会話ターンの移行回数が大きすぎることを示します。よくある例としては、同じページに遷移し、無限ループが発生します。

この問題を解決するには:

1. エラー メッセージから JSON 配列をコピーします。
2. （省略可）読みやすくするために、コピーした配列を Pretty JSON 形式にします。エラー メッセージが切り捨てられた場合は、最後の「Step」オブジェクトを検索し、不完全なステップ オブジェクトとその前のカンマを削除し、JSON の検証と絞り込みの前に閉じられた配列かっこを追加します。
3. 各ステップの "TriggeredTransitionRouteId" 値と "TargetPage" 値を確認します。無限ループの場合、"TriggeredTransitionRouteId" フィールドと "TargetPage" フィールドにほとんどのステップの値が繰り返し入っています。
4. エージェントの設計を変更して、無限ループの移行を削除するか、1 回の会話ターンの移行の回数を減らします。

正規表現の一致範囲が広すぎる

問題

正規表現エンティティ（Dialogflow CX、Dialogflow ES）の作成時にエラー Regular expression match is too broad が返されました。

ソリューション

次の方法を検討してください。

• 正規表現で ^ と $ を使用して、テキストの先頭と末尾をそれぞれ指定します。
• 必須パラメータ（Dialogflow CX、Dialogflow ES）を含む正規表現エンティティを使用します。
• 必須パラメータのプロンプトを定義し、単語を前後に配置することなくエンティティ値のみを指定するようエンドユーザーに要求します。

音声認識によって挿入された望ましくない英数字以外の文字

問題

英数字を照合しようとすると、望ましくない英数字以外の文字（スペース、ダッシュなど）が音声認識機能によって挿入されるため、エンティティが一致しません。

ソリューション

1. 数字の照合にシステム エンティティを使用する場合は、代わりに正規表現エンティティ（Dialogflow CX、Dialogflow ES）の使用を検討してください。
2. 正規表現エンティティによる不正確な英数字の音声認識のセクションの推奨事項にすべて従ってください。
3. テレフォニー統合を使用して数字を照合する場合は、音声認識に加えて DTMF オプションを検討してください。

音声入力の空の文字起こし

問題

音声入力の Dialogflow レスポンスは、空の文字起こしを返します。リクエストは入力なしまたは一致なしとして処理されます。

ソリューション

音声録音を聞き、音声が含まれていることを確認します。

エージェントの設定（Dialogflow CX、Dialogflow ES）で音声適応が有効になっていることを確認します。

音声適応を有効にしても効果がない場合は、非本番環境の設定で次の音声モデルを試し、最良の結果をレンダリングするモデルを使用してください。

• latest_short
• phone_call
• command_and_search

英語以外の言語については、Speech-to-Text でサポートされている言語のドキュメントで、サポートされている音声モデルを確認してください。

音声モデルの指定方法は、Dialogflow とのやり取りの設定方法によって異なります。

• API リクエストの場合は、InputAudioConfig の model フィールドにモデル名を入力します（Dialogflow CX、Dialogflow ES）。

• Phone Gateway（Dialogflow CX、Dialogflow ES）を使用している場合は、統合を有効にしたときに Dialogflow によって作成された会話プロファイルで音声モデルを更新できます。

  1. 会話プロファイル ID を取得します。

     • conversationProfiles.list メソッドを使用して、プロジェクトにリンクされているすべての会話プロファイルを取得します。
     • 更新する会話プロファイルを見つけて、name フィールドの値をコピーします。

     Dialogflow CX Phone Gateway の場合、会話プロファイルの表示名はインテグレーション設定で確認できます。Dialogflow ES Phone Gateway の場合、会話プロファイルの表示名は、インテグレーションを有効にしたエージェント名に対応します。

     同じ表示名の会話プロファイルが複数ある場合は、conversationProfiles.list メソッドのレスポンスから automatedAgentConfig フィールドのエージェント ID を確認します。

  2. conversationProfiles.patch API メソッドを使用して、SpeechToTextConfig の model フィールドを更新します。

• Contact Center AI の統合の場合は、統合または個々のリクエスト用に音声モデルを更新する方法について、テレフォニー インテグレータに確認してください。

ハンドブックのループエラーについて

問題

ハンドブックをリンクする際に、Playbook <playbookID> caused loop in playbook routes エラーが発生します。

ソリューション

ループは、現在のプレイブックを直接的または間接的に呼び出した「親」プレイブックにルーティングしようとすると発生する可能性があります。この問題を解決するには、プレイブックのルーティングが単方向であり、同じ会話パスで親プレイブックに戻らないことを確認します。

エージェント バージョンの比較時に「ファイルのサイズが 2 MB を超えています」というエラーが表示された空白画面

問題

2 つの異なるエージェント バージョンを比較しようとすると、画面が空白になり、次のエラー メッセージが表示されます。

File size exceeds 2MB

この問題は、いずれかのファイルのサイズが 2 MB を超えていることが原因です。

ソリューション

ファイルのいずれかのサイズが 2 MB を超えるエージェント バージョンを比較するには、API メソッド compareVersion を使用することをおすすめします。

正規表現エンティティによる不正確な英数字の音声認識

問題

正規表現エンティティ（Dialogflow CX、Dialogflow ES）と一致するよう設計された英数字の音声入力について、不正確な文字起こしが返されました。

ソリューション

1. エージェントの設定（Dialogflow CX、Dialogflow ES）で音声適応が有効になっていることを確認します。
2. 1 つ以上のエンティティ エントリが、正規表現のエントリ要件（Dialogflow CX、Dialogflow ES）をすべて満たしていることを確認します。
3. 特定のパターンには、最も具体的な正規表現を使用します。たとえば、2 文字の後に 5 桁の数字が続く英数字の場合は、[a-zA-Z0-9]{7} ではなく [a-zA-Z]{2}\d{5} を使用します。
4. 正規表現エンティティで、音声認識機能によって挿入される可能性のある英数字以外の文字（スペース、ダッシュなど）の一致が考慮されていることを確認します。このリストの 2 番目の要件を満たすには、複数のエンティティ エントリを作成します。1 つはこのリストの 2 番目の要件を満たすエントリ、もう 1 つは英数字以外の文字のエントリを考慮します。たとえば、5 桁の数字に一致し、英数字以外の文字を許可するには、次のようにします。

    \d{5}
    (\d[^a-zA-Z0-9]*){5}
   

5. エージェントがパラメータ定義要件（Dialogflow CX、Dialogflow ES）を満たしていることを確認します。

   Dialogflow CX の例

   

   Dialogflow ES の例

   
6. エージェントがトレーニング フレーズのアノテーション要件（Dialogflow CX、Dialogflow ES）を満たしていることを確認します。

   Dialogflow ES の例

   
7. テストがテスト ガイドライン（Dialogflow CX、Dialogflow ES）に準拠していることを確認します。
8. 音声認識機能によって挿入された可能性のある英数字以外の文字を削除するには、次を使用します。
   • Dialogflow CX の場合: SUBSTITUTE システム関数または Webhook
   • Dialogflow ES の場合: Webhook
9. 音声適応の制限事項（Dialogflow CX、Dialogflow ES）を確認します。

制御された会話の設計

明確に定義された会話パスを使用してエージェントを構築します。エージェントがユーザーの要件を満たすために必要な情報をリクエストできるようにします。会話の範囲が広すぎると、予期しない動作につながる可能性があるため、避けてください。

ログを分析する

Playbook、ツール、データストアの入力と出力はログにキャプチャされます。収集した会話 ID を使用して、呼び出しのチェーンを追跡し、実行がうまくいかなかった場所を特定します。

プロンプトを試す

特定の指示が想定どおりに機能しない場合は、言い換えてみてください。または、Gemini を使用してプロンプトを生成することもできます（メタプロンプト）。この反復的なアプローチは、ユースケースに最適なフレーズを見つけるのに役立ちます。

サポートに完全な情報を提供する

Cloud サポートにサポートケースを登録する場合は、調査中に収集した関連する会話 ID とログを含めてください。この情報は、問題を効率的にデバッグするために重要です。