Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

トラブルシューティング

エージェントで 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 呼び出しのレスポンスで別のホストへの切り替えがリクエストされる

問題

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

ソリューション

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

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

問題

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

ソリューション

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

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

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

問題

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

ソリューション

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

Dialogflow ES コンソール
https://dialogflow.cloud.google.com/#/agent/project-id/intents を開きます。

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

Dialogflow API
agent タイプの search メソッドを使用します。
リーエン名を取得します。
gcloud
プロジェクトに適用されているリーエンを一覧表示するのドキュメントで説明されている gcloud alpha resource-manager liens list コマンドを使用します。
API Explorer
[Method: liens.list] ページの [この API を試す] パネルを使用します。
- パラメータの説明で推奨されているように、parent フィールドに入力します。
- [実行] をクリックします。
リーエンを削除します。
gcloud
プロジェクトからリーエンを削除するのドキュメントで説明されている gcloud alpha resource-manager liens delete LIEN_NAME コマンドを使用します。
API Explorer
[Method: liens.delete] ページの [この API を試す] パネルを使用します。
- [name] フィールドに、ステップ 2 で取得したリーエン名を入力します。
- [実行] をクリックします。
プロジェクトをシャットダウンします。

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 の接続

問題

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 つです。そのため、Dialogflow ES コンソールでエージェントを開くには、https://dialogflow.cloud.google.com/#/editAgent/PROJECT_ID/intents を使用します。

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

手順 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 が有効になっていることを確認します。設定手順をご覧ください。

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

問題

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

ソリューション

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

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

問題

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

ソリューション

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

SSML タグが機能しない

問題

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

ソリューション

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

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

問題

音声用に設計されたエージェントの場合、音声エージェントはゼロをゼロではなく文字 O と読み上げます。

ソリューション

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

テキストを SSML タグで囲みます。

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

保存します。

たとえば、クレジットカード番号のゼロは、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 回の会話ターンの移行回数が大きすぎることを示します。よくある例としては、同じページに遷移し、無限ループが発生します。

この問題を解決するには、次の手順を行います。

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

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

問題

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

ソリューション

次のアプローチを検討してください。

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

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

問題

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

ソリューション

数字の照合にシステムエンティティを使用する場合は、代わりに正規表現エンティティ（Dialogflow CX、Dialogflow ES）の使用を検討してください。
正規表現エンティティによる不正確な英数字の音声認識のセクションの推奨事項にすべて従ってください。
テレフォニー統合で数字を照合する場合は、音声認識に加えて 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）と一致するよう設計された英数字の音声入力について、不正確な文字起こしが返されました。

ソリューション

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

Dialogflow CX の例

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

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

Cloud Run functions（第 2 世代）で Webhook が 403 Forbidden エラーで失敗する

問題

Dialogflow CX から Cloud Run functions（第 2 世代）でホストされている Webhook を呼び出すと、Webhook が失敗し、HTTP 403 Forbidden エラーまたは次のメッセージが関数ログに記録されます。

The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.

原因

Dialogflow CX Webhook の組み込み認証を備えた Cloud Run functions（第 1 世代）とは異なり、Cloud Run functions（第 2 世代）は Cloud Run で実行され、IAM 起動元の権限が必要です。Dialogflow CX サービスエージェントアカウントに Cloud Run サービスを呼び出す権限がない場合、呼び出しは HTTP 403 エラーで拒否されます。バージョンの違いの詳細については、Cloud Run functions のバージョンの比較をご覧ください。

解決策

Dialogflow CX サービスエージェントに Cloud Run 起動元ロールを付与します。

PROJECT_ID プロジェクト番号を特定します。
Google Cloud コンソールで、[IAM] ページに移動します。
[Google 提供のロール付与を含める] チェックボックスをオンにします。
Dialogflow CX サービスエージェントアカウント（service-PROJECT_NUMBER@gcp-sa-dialogflow.）を見つけます（PROJECT_NUMBER はプロジェクト番号に置き換えます）。
サービスエージェントアカウントに Cloud Run 起動元（roles/run.invoker）ロールを割り当てます。
または、組織のポリシーで許可されている場合は、未認証の呼び出しを許可するように Cloud Run 関数を構成します。

GitHub 統合エラー: 個人用アクセストークンでリソースにアクセスできない

問題

Dialogflow CX コンソールでエージェントの変更を GitHub に push しようとしたり、GitHub から復元しようとしたりすると、オペレーションが失敗し、次のエラーが発生します。

Received an error from GitHub: Resource not accessible by personal access token

原因

GitHub 接続用に構成された個人アクセストークンに、エージェントファイルを push または復元するために必要なリポジトリ権限がありません。

解決策

GitHub の個人アクセストークンの権限を更新します。

きめ細かい個人用アクセストークン:
1. GitHub で、個人用アクセストークンの設定に移動します。
2. [Repository permissions] で、[Contents] を [Read and write] に設定します。
3. [Metadata] が [Read-only] に設定されていることを確認します（Contents 権限が付与されると自動的に選択されます）。
クラシック個人用アクセストークン:
1. トークンで repo スコープが選択されていることを確認します。

また、指定されたリポジトリとブランチが存在し、トークンに関連付けられているアカウントにリポジトリへの書き込みアクセス権があることを確認します。

Service Directory の解決エラーまたはタイムアウトエラーで Webhook が失敗する

問題

Dialogflow CX から Service Directory を使用してプライベート Webhook を呼び出すと、Webhook が失敗し、次のようなエラーメッセージが表示されます。

Failed to resolve Service Directory: [projects/PROJECT_ID/locations/LOCATION_ID/namespaces/NAMESPACE_ID/services/SERVICE_ID]
DEADLINE_EXCEEDED ... URL_TIMEOUT ... Reason: TIMEOUT_WEB

原因

権限がない: Dialogflow CX サービスエージェントアカウントに、Service Directory サービスまたは Private Service Connect にアクセスするために必要な IAM ロールが付与されていません。
グローバルアクセスが無効になっている: 内部アプリケーションロードバランサの場合、グローバルアクセスが無効になっているため、Dialogflow CX はロードバランサのリージョン外のリージョンからバックエンドにアクセスできません。

解決策

PROJECT_ID プロジェクト番号を特定します。
Google Cloud コンソールで、Service Directory サービスをホストするプロジェクトの [IAM] ページに移動します。
[Google 提供のロール付与を含める] チェックボックスをオンにします。
Dialogflow CX サービスエージェントアカウントを見つけます。 service-PROJECT_NUMBER@gcp-sa-dialogflow. （PROJECT_NUMBER は、Dialogflow CX エージェントプロジェクトのプロジェクト番号に置き換えます）。
サービスエージェントアカウントに次のロールを割り当てます。
- Service Directory 閲覧者（roles/servicedirectory.viewer）
- Service Directory PSC 承認済みサービス（roles/servicedirectory.pscAuthorizedService）
Service Directory サービスが Dialogflow CX エージェントとは異なるプロジェクトにある場合は、サービスエージェントアカウントにエージェントのホストプロジェクトの Service Directory 閲覧者（roles/servicedirectory.viewer）ロールがあることも確認してください。
内部アプリケーションロードバランサを使用していて、タイムアウトエラー（TIMEOUT_WEB）が発生した場合は、ロードバランサのフロントエンドでグローバルアクセスが有効になっていることを確認します。

Neural2 音声で無効な SSML エラーが発生して Text-to-Speech が失敗する

問題

Dialogflow CX で Text-to-Speech に Neural2 音声を使用すると、エージェントのレスポンスで音声が合成されず、次のエラーが発生します。

While calling Cloud Text-to-Speech API: Invalid SSML. Newer voices like Neural2 require valid SSML.

原因

Neural2 音声では、XML と SSML のコンプライアンスが厳格に適用されます。エスケープされていない文字や引用符で囲まれていない属性を許容する古い音声階層とは異なり、Neural2 は、属性値を囲む引用符の欠落（例: <prosody rate="100%"> ではなく <prosody rate=100%>）、閉じられていないタグ（例: <break /> または </prosody> の欠落）、エスケープされていない XML 特殊文字（&、<、>）などの不正な SSML を拒否します。

解決策

すべての SSML 属性値が引用符で囲まれていることを確認します。次に例を示します。xml <speak> <break time="2s" /> <prosody rate="100%" pitch="-0.5st">Hello, how can I help you today?</prosody> </speak>
すべての要素がルート <speak>...</speak> 要素内に適切にネストされ、対応する終了タグがあることを確認します。
動的パラメータ値とテキストプロンプトの XML 特殊文字をエスケープします。
- & を & に置き換えます。
- < を < に置き換えます。
- > を > に置き換えます。
構文要件とサポートされているタグについては、SSML リファレンスをご覧ください。

GitHub 統合エラー: 500 ファイルの上限により、エージェントのエクスポートまたは push が失敗する

問題

Dialogflow CX エージェントを GitHub リポジトリにエクスポートまたは push しようとすると、GitHub からサーバーエラーが返されます。

原因

エージェントのサイズが大きすぎるため、GitHub に直接エクスポートできません。GitHub では、1 回の push に 500 個を超えるファイルが含まれる更新が制限されています。このシナリオは、空のリポジトリにエージェントを初めて push しようとする場合に最も一般的です。これは、ファイルセット全体を一度に生成して push するためです。

解決策

Dialogflow CX コンソールで、エージェントを .zip ファイルとしてエクスポートします。
GitHub ウェブインターフェースまたは Git CLI を使用して、解凍したファイルを GitHub にアップロードします。
今後の更新で変更されるファイルが 500 個未満であると想定される場合は、Dialogflow CX から直接変更を push します。

生成エージェントが `sys.agent-banned-phrase` エラーで失敗する

問題

生成エージェントまたはハンドブックが繰り返し失敗し、ユーザー入力が問題ない場合でも、フォールバックルートがトリガーされるか、sys.agent-banned-phrase が返されます。

Sorry, something went wrong.

原因

エージェントの禁止フレーズリストで構成された用語が、エージェントの内部プロンプト構成（ハンドブックの手順、目標、例、データストアツールのプロンプトなど）に存在します。禁止フレーズのガードレールは、内部 LLM プロンプト全体（指示、会話履歴、ユーザー入力を含む）を評価するため、指示に禁止フレーズが含まれていると、安全フィルタが自動的にトリガーされます。

解決策

Dialogflow CX コンソールで、[エージェントの設定] > [禁止フレーズ] に移動します。
設定されている禁止フレーズのリストを確認します。
ハンドブックの手順、目標、例、データストアのプロンプトテンプレートに、禁止されているフレーズが含まれていないか確認します。
禁止されたフレーズのリストと重複しないように、内部指示内の一致する用語を削除するか、言い換えます。

音声認識が `Phrases cannot be empty` エラーで失敗する

問題

音声操作が失敗するか、INVALID_ARGUMENT エラーで通話が予期せず切断される。

While calling Cloud Speech API: Phrases cannot be empty

このエラーは、Dialogflow CX コンソールで音声適応が無効になっているように見える場合でも発生することがあります。

原因

残りの音声最適化設定は、ページの基盤となる構成に残ります。手動音声適応が以前に有効にされ、バイアスフレーズが入力され、その後無効にされた場合、空のフレーズセットブロックがページ構成に残り、Cloud Speech-to-Text モデルで検証エラーが発生する可能性があります。

解決策

Dialogflow CX コンソールで、残りの音声適応設定をクリアします。

フローを開き、エラーが発生しているページに移動します。
ページ設定で [手動音声適応] を一時的に有効にします。
既存のフレーズセットと空のフレーズエントリを削除します。
[保存] をクリックします。
[手動音声適応] を無効にします。
[保存] をクリックして、エージェントをテストします。

Cloud Logging の `DetectIntentResponse` に `diagnosticInfo` がありません

問題

Cloud Logging で DetectIntentResponse または QueryResult ログエントリを検査すると、ログに記録されたレスポンスに diagnosticInfo フィールドがありません。

原因

Cloud Logging のログエントリのサイズ制限は 256 KB です。レスポンスペイロードの合計サイズが大きい場合（広範なセッションパラメータ、大きな Webhook ペイロード、詳細なクエリ結果が含まれている場合など）、Dialogflow CX は diagnosticInfo フィールドを切り捨て、ログエントリが 256 KB の上限を超えないようにします。

解決策

診断情報にアクセスするか、ログエントリのサイズを小さくするには:

Cloud Logging のみに依存するのではなく、クライアントサイドの API レスポンスから diagnosticInfo を直接キャプチャします。
Dialogflow CX コンソールシミュレータで、[Original response] タブに、切り捨てられていない完全なペイロードが表示されます。
WebhookResponse で必要なパラメータとフィールドのみを返すことで、Webhook レスポンスのサイズを小さくします。

Avaya テレフォニー統合の接続時に権限拒否エラーが発生する

問題

Dialogflow CX コンソール（[Integrations] > [One-click Telephony] > [Avaya] > [Connect]）で Avaya ワンクリックテレフォニー統合を接続しようとすると、リクエストが失敗し、次のエラーが表示されます。

PERMISSION_DENIED: Policy update access denied

原因

Avaya 統合を有効にしようとしているユーザーアカウントに、 Google Cloud プロジェクトの IAM ポリシーを更新する権限がありません。Avaya 統合を接続するには、プロジェクトの Avaya サービスアカウントに権限を付与する必要があります。

解決策

統合を構成するユーザーアカウントに必要な IAM ロールを付与します。

Google Cloud コンソールで、[IAM] ページに移動します。
ユーザーアカウントにプロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）ロールまたは resourcemanager.projects.setIamPolicy 権限を含むカスタムロールがあることを確認します。
付与されたら、Dialogflow CX コンソールで Avaya テレフォニー統合を再接続します。

制御された会話の設計

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

ログを分析する

ハンドブック、ツール、データストアの入力と出力はログに記録されます。収集した会話 ID を使用して、呼び出しのチェーンを追跡し、実行が失敗した場所を特定します。

プロンプトを試す

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

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

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

トラブルシューティング コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

会話 ID を収集する

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

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

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

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

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

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

Dialogflow ES コンソール

Dialogflow API

gcloud

API Explorer

gcloud

API Explorer

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

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

レスポンスに表示されるセッション パラメータ参照

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

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

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

Phone Gateway の接続

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

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

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

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

SSML タグが機能しない

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

予期しない合成発音

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

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

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

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

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

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

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

Dialogflow CX の例

Dialogflow ES の例

Dialogflow ES の例

Cloud Run functions（第 2 世代）で Webhook が 403 Forbidden エラーで失敗する

GitHub 統合エラー: 個人用アクセス トークンでリソースにアクセスできない

Service Directory の解決エラーまたはタイムアウト エラーで Webhook が失敗する

Neural2 音声で無効な SSML エラーが発生して Text-to-Speech が失敗する

GitHub 統合エラー: 500 ファイルの上限により、エージェントのエクスポートまたは push が失敗する

生成エージェントが sys.agent-banned-phrase エラーで失敗する

音声認識が Phrases cannot be empty エラーで失敗する

Cloud Logging の DetectIntentResponse に diagnosticInfo がありません

Avaya テレフォニー統合の接続時に権限拒否エラーが発生する

制御された会話の設計

ログを分析する

プロンプトを試す

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

トラブルシューティング

レスポンスに表示されるセッションパラメータ参照

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

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

GitHub 統合エラー: 個人用アクセストークンでリソースにアクセスできない

Service Directory の解決エラーまたはタイムアウトエラーで Webhook が失敗する

生成エージェントが `sys.agent-banned-phrase` エラーで失敗する

音声認識が `Phrases cannot be empty` エラーで失敗する

Cloud Logging の `DetectIntentResponse` に `diagnosticInfo` がありません