会話ターンごとに、操作が行われます。インタラクション中に、エンドユーザーが会話エージェント(Dialogflow CX)に入力を送信し、会話エージェント(Dialogflow CX)がレスポンスを送信します。システムを実装して操作を処理する際には、API を使用する方法と統合を使用する方法の 2 つの選択肢が存在します。
API の使用時には、システム側で以下の処理を行う必要があります。
- エージェントをビルドする。
- エンドユーザー向けのユーザー インターフェースを用意する。
- 会話ターンごとに Dialogflow API を呼び出して、エンドユーザー入力を API に送信します。
- エージェントのレスポンスが純粋に静的な(一般的でない)場合を除き、webhook サービスをホストして、Webhook 対応フルフィルメントを処理する必要があります。
統合を使用する場合、システムでは次の処理のみを行う必要があります。
- エージェントをビルドする。
- 必要に応じて Webhook サービスを実装します。
次の図は、セッションの 1 回の対話ターンで実行される手順を示しています。
- エンドユーザーが、エンドユーザー入力と呼ばれる何かしらの情報を入力または発声します。
- ユーザー インターフェースまたは統合システムが入力を受信し、インテント検出リクエストで Dialogflow API に転送します。
- Dialogflow API がインテント検出リクエストを受信します。入力とインテントまたはフォーム パラメータを照合し、必要に応じてパラメータを設定し、セッションの状態を更新します。Webhook 対応フルフィルメントを呼び出す必要がある場合、Webhook サービスに Webhook リクエストを送信します。それ以外の場合は、手順 6 に進みます。
- Webhook サービスが Webhook リクエストを受け取ります。サービスは、外部 API の呼び出し、データベースのクエリや更新など、必要なアクションを実行します。
- Webhook サービスがレスポンスをビルドし、Webhook レスポンスを会話エージェント(Dialogflow CX)に返します。
- 会話エージェント(Dialogflow CX)がインテント検出レスポンスを作成します。Webhook が呼び出された場合、Webhook レスポンスで提供されたレスポンスが使用されます。Webhook が呼び出されなかった場合は、エージェントで定義された静的レスポンスが使用されます。会話エージェント(Dialogflow CX)は、ユーザー インターフェースまたは統合システムにインテント検出レスポンスを送信します。
- ユーザー インターフェースまたは統合システムがインテント検出レスポンスを受信し、テキストまたは音声のレスポンスをエンドユーザーに転送します。
- エンドユーザーがレスポンスを確認または聞き取ります。
ガイドの目的
このガイドでは、統合を使用していないエージェントが 1 回の会話ターンで API を呼び出す方法について説明します(上の図の手順 2)。このガイドでは、お客様のエンドユーザーがユーザー インターフェースを実装する方法はご紹介していません。
始める前に
このガイドを読む前に、次の手順を行ってください。
- フローの基本をご覧ください。
- 手順に沿って設定してください。
- 新しいエージェントを作成するか、フローを使用してエージェントをビルドするまたはハンドブックを使用してエージェントをビルドするで作成したエージェントを引き続き使用します。
ID を収集する
次のサンプルでは、入力として複数の ID が必要です。プロジェクト ID、リージョン ID、エージェント ID は次の手順で確認できます。
Dialogflow CX コンソール
- Dialogflow CX コンソールを開きます。
- Google Cloud プロジェクトを選択し、エージェント セレクタを開きます。
- リスト内のエージェントのオプション メニュー more_vert をクリックします。
- コピー名 filter_none ボタンをクリックします。
- これにより、エージェントの完全な識別名がコピーされます。これには、
projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID の形式のプロジェクト ID、リージョン ID、エージェント ID が含まれます。
Agent Builder コンソール
Agent Builder コンソールに移動します。
プロジェクト ID はコンソールの上部に表示されます。
[ロケーション] 列にリージョン ID が表示されます。
アプリを選択します。
agents/
の後のブラウザ URL パスセグメントには、エージェント アプリ ID が含まれます。
セッション ID も必要です。セッションは、会話エージェント(Dialogflow CX)エージェントとエンドユーザー間の会話を表します。会話の開始時に一意のセッション ID を作成し、会話のターンごとにそれを使用します。API を試す場合、test-session-123
のように、最大 36 バイトの任意の文字列 ID を使用できます。
detectIntent を呼び出す
次のサンプルでは、Sessions.detectIntent
メソッドを呼び出します。
セッション リファレンスのプロトコルとバージョンを選択:
プロトコル | V3 | V3beta1 |
---|---|---|
REST | セッション リソース | セッション リソース |
RPC | セッション インターフェース | セッション インターフェース |
C++ | SessionsClient | 利用できません |
C# | SessionsClient | 利用できません |
Go | SessionsClient | 利用できません |
Java | SessionsClient | SessionsClient |
Node.js | SessionsClient | SessionsClient |
PHP | 利用不可 | 利用できません |
Python | SessionsClient | SessionsClient |
Ruby | 利用不可 | 利用できません |
REST
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: 実際の Google Cloud プロジェクト ID
- AGENT_ID: エージェント ID
- REGION_ID: リージョン ID
- SESSION_ID: セッション ID
- END_USER_INPUT: エンドユーザーの入力
HTTP メソッドと URL:
POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent
リクエストの本文(JSON):
{ "queryInput": { "text": { "text": "END_USER_INPUT" }, "languageCode": "en" }, "queryParams": { "timeZone": "America/Los_Angeles" } }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "responseId": "38e8f23d-eed2-445e-a3e7-149b242dd669", "queryResult": { "text": "I want to buy a shirt", "languageCode": "en", "responseMessages": [ { "text": { "text": [ "Ok, let's start a new order." ] } }, { "text": { "text": [ "I'd like to collect a bit more information from you." ] } }, { "text": { "text": [ "What color would you like?" ] } }, {} ], "currentPage": { "name": "projects/PROJECT_ID/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/flows/00000000-0000-0000-0000-000000000000/pages/ce0b88c4-9292-455c-9c59-ec153dad94cc", "displayName": "New Order" }, "intent": { "name": "projects/PROJECT_ID/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665", "displayName": "order.new" }, "intentDetectionConfidence": 1, "diagnosticInfo": { ... }, "match": { "intent": { "name": "projects/PROJECT_ID/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665", "displayName": "order.new" }, "resolvedInput": "I want to buy a shirt", "matchType": "INTENT", "confidence": 1 } } }
Java
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Python
Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
プロダクション
エージェントを本番環境で実行する場合は、必ずプロダクションのベスト プラクティスを実施してください。