生成ナレッジアシスト

生成ナレッジアシストは、提供されたドキュメントの情報に基づいて、エージェントの質問に回答します。フローベースのデータストアエージェントまたはハンドブックベースのデータストアエージェントのドメイン名を指定するか、ドキュメントをアップロードしてインデックスに登録できます。生成ナレッジアシストは、進行中の会話と利用可能な顧客メタデータを使用して情報を合成し、エージェントにタイムリーで関連性の高い回答を提供します。

プロアクティブ生成ナレッジアシストは、エージェントとお客様の間の進行中の会話を追跡します。現在の会話のコンテキストと回答に基づいて、検索語句を前もって提案できます。

始める前に

プロジェクトオーナーでない場合は、データストアエージェントを作成するために次のロールが必要です。

- Dialogflow API Admin
- Discovery Engine Admin

フローベースのデータストアエージェントを作成する

Vertex AI コンソールで AI Applications API を有効にします。
エージェントを作成するには、フローベースのデータストアエージェントの手順に沿って操作します。

Playbook ベースのデータストアエージェントを作成する

Vertex AI コンソールで AI Applications API を有効にします。
エージェントを作成するには、プレイブックベースのデータストアエージェントの手順に沿って操作します。
エージェントをデータストアに接続するには、データストアツールを作成します。詳しくは、プレイブックデータストアツールの例をご覧ください。

人間のエージェントからの質問に回答する

フローベースまたはハンドブックベースのデータストアエージェントは、提供されたドキュメントに基づいて、人間のエージェントからの質問に回答できます。

ステップ 1: 会話プロファイルを作成する

Agent Assist コンソールまたは API を使用して、会話プロファイルを作成します。

コンソールから作成する

生成型ナレッジアシストの候補タイプを有効にして、前のステップのフローベースまたはプレイブックベースのデータストアエージェントにリンクする必要があります。
省略可: [エージェント検索クエリのロギングを無効にする] チェックボックスを使用して、品質向上のために秘匿化済み検索クエリを収集して保存するかどうかを指定します。
[会話拡張クエリを有効にする] チェックボックスを使用すると、検索クエリの回答を生成する際に、人間のエージェントとユーザー間の会話コンテキストを考慮するかどうかを指定できます。

API から作成

次の手順では、HumanAgentAssistantConfig オブジェクトを使用して ConversationProfile を作成する方法について説明します。これらの操作は、Agent Assist コンソールを使用して行うこともできます。

会話プロファイルを作成するには、ConversationProfile リソースの create メソッドを呼び出します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: プロジェクト ID
LOCATION_ID: ロケーションの ID
AGENT_ID: 前の手順で取得したフローベースまたはプレイブックベースのデータストアエージェント ID

JSON の例を次に示します。

  {
    "displayName": "my-conversation-profile-display-name",
    "humanAgentAssistantConfig": {
      "humanAgentSuggestionConfig": {
        "featureConfigs": [
          {
            "suggestionFeature": {
              "type": "KNOWLEDGE_SEARCH"
            },
            "queryConfig": {
              "dialogflowQuerySource": {
                "humanAgentSideConfig": {
                  "agent": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID"
                }
              }
            },
            "disableAgentQueryLogging": false,
            "enableConversationAugmentedQuery": false,
          }
        ]
      }
    }
  }

Agent Assist コンソールで会話プロファイルを作成すると、生成ナレッジアシストとプロアクティブ生成ナレッジアシストの両方が自動的に有効になります。プロアクティブな生成ナレッジアシストを無効にするには、API を使用して会話プロファイルを作成する必要があります。

ステップ 2: データストアエージェントを使用する

必要に応じて、SearchKnowledge API を使用して、データストアエージェントから回答を取得します。SearchKnowledge リクエストの一部として、次の構成を使用することもできます。

querySource: エージェントがクエリを入力したか、プロアクティブな生成ナレッジアシストが自動的に提案したかを示すには、このフィールドを設定します。
exactSearch: クエリの書き換えなしで正確な入力クエリを検索するかどうかを示すように、このフィールドを設定します。
endUserMetadata: このフィールドを設定して、生成された回答を改善するエンドユーザーに関する追加情報を含めます。詳しくは、データストアエージェントのパフォーマンスのカスタマイズページをご覧ください。
searchConfig: ナレッジドキュメントのブーストとフィルタリングをさらに制御するには、このフィールドを設定します。詳細については、データストアエージェントのパフォーマンス検索構成ページをご覧ください。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: プロジェクト ID
LOCATION_ID: ロケーションの ID
CONVERSATION_PROFILE_ID: 前の手順で取得した会話プロファイル ID
SESSION_ID: 検索セッション ID
CONVERSATION_ID: 検索リクエストがトリガーされた会話（人間のエージェントとエンドユーザー間の会話）
MESSAGE_ID: 検索リクエストがトリガーされたときの最新の会話メッセージ

JSON リクエストの例を次に示します。

{
  "parent": "projects/PROJECT_ID/locations/LOCATION_ID"
  "query": {
    "text": "What is the return policy?"
  }
  "conversationProfile": "projects/PROJECT_ID/locations/LOCATION_ID/conversationProfiles/CONVERSATION_PROFILE_ID"
  "sessionId": "SESSION_ID
  "conversation": "projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID"
  "latestMessage": "projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/messages/MESSAGE_ID
  "querySource": AGENT_QUERY
  "exactSearch": false
  "searchConfig": {
    "filterSpecs": {
      "filter": "category: ANY(\"persona_B\")"
    }
  }
  "endUserMetadata": {
    "deviceOwned": "Google Pixel 7"
  }
}

エージェントの検索がユーザーとの会話中に行われる場合は、必要に応じて conversation と latest_message のリソース名を指定します。enable_conversation_augmented_query オプションを有効にして、エージェントとユーザー間の会話コンテキストを使用してクエリの回答エクスペリエンスを向上させる場合は、この 2 つのフィールドが必要です。

シミュレータ

Agent Assist シミュレータで、フローベースまたはハンドブックベースのデータストアエージェントをテストします。

前の例では、フローベースのデータストアエージェントがユーザーのクエリ What is the refund processing time? に次の情報で回答します。

生成 AI が生成した回答: 返品の荷物が販売者の返品センターに到着してから、処理が完了するまでに最大で 7 営業日ほどかかることがあります。払い戻しのステータスは、注文ページに記載されている返品の追跡番号で確認できます。
関連するナレッジドキュメントのタイトル: 返品と払い戻し。

エージェントに Q＆A をプロアクティブに提案する

プロアクティブ生成ナレッジアシストは、進行中の会話を追い、検索語句の提案や回答を前もって提供します。

ステップ 1: 会話プロファイルを作成する

Agent Assist コンソールを使用して会話プロファイルを作成することをおすすめしますが、API を使用することもできます。

コンソールから作成する

[生成ナレッジアシスト] の提案タイプを有効にして、前の手順で作成したフローベースのデータストアエージェントまたはプレイブックベースのデータストアエージェントにリンクします。これにより、フローベースまたはハンドブックベースのデータストアエージェントは、クエリと回答の候補を事前に提供し、人間のエージェントからの手動検索クエリに回答できます。
省略可: [会話のすべての候補クエリを表示] チェックボックスをオンにすると、ナレッジドキュメントから回答が見つからなかった場合でも、フローベースのデータストアエージェントまたはハンドブックベースのデータストアエージェントがこれらのクエリをすべて表示します。これは、進行中の会話から取得できるクエリをテストするためのものです。
省略可: [事前対応型の回答を非同期で読み込む] チェックボックスをオンにすると、クエリ候補のみを取得できます。提案されたクエリは、SearchKnowledge API に手動で送信できます。また、Agent Assist コンソールのシミュレータと UI モジュールで自動的に送信することもできます。

API から作成

次の手順では、HumanAgentAssistantConfig オブジェクトを使用して ConversationProfile を作成します。これらの操作は、Agent Assist コンソールを使用して行うこともできます。

会話プロファイルを作成するには、ConversationProfile リソースの create メソッドを呼び出します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: プロジェクト ID
LOCATION_ID: ロケーションの ID
AGENT_ID: 前の手順で取得したフローベースまたはプレイブックベースのデータストアエージェント ID

JSON の例を次に示します。

  {
    "displayName": "my-conversation-profile-display-name",
    "humanAgentAssistantConfig": {
      "humanAgentSuggestionConfig": {
        "featureConfigs": [
          {
            "suggestionFeature": {
              "type": "KNOWLEDGE_ASSIST"
            },
            "queryConfig": {
              "dialogflowQuerySource": {
                "agent": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID"
              }
            },
            "enableQuerySuggestionWhenNoAnswer": false,
          }
        ]
      }
    }
  }

ステップ 2: ランタイムに会話を処理する

プロアクティブな生成ナレッジアシストは、実行時に会話を処理し、現在の会話のコンテキストと回答に基づいて検索語句を前もって提案します。

会話を作成する

まず、会話を作成する必要があります。

REST

会話を作成するには、Conversation リソースの create メソッドを呼び出します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: 実際の Cloud プロジェクトの ID
LOCATION_ID: ロケーション ID
CONVERSATION_PROFILE_ID: 会話プロファイルの作成時に受け取った ID

HTTP メソッドと URL:

POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION_ID/conversations

リクエストの本文（JSON）:

{
  "conversationProfile": "projects/PROJECT_ID/locations/LOCATION_ID/conversationProfiles/CONVERSATION_PROFILE_ID",
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION_ID/conversations"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION_ID/conversations" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID",
  "lifecycleState": "IN_PROGRESS",
  "conversationProfile": "projects/PROJECT_ID/locations/LOCATION_ID/conversationProfiles/CONVERSATION_PROFILE_ID",
  "startTime": "2018-11-05T21:05:45.622Z"
}

conversations の後のパスセグメントには、新しい会話 ID が含まれます。

Python

詳細については、Vertex AI Search Python API のリファレンスドキュメントをご覧ください。

Vertex AI Search に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

def create_conversation(project_id, conversation_profile_id):
    """Creates a conversation with given values

    Args:
        project_id:  The GCP project linked with the conversation.
        conversation_profile_id: The conversation profile id used to create
        conversation."""

    client = dialogflow.ConversationsClient()
    conversation_profile_client = dialogflow.ConversationProfilesClient()
    project_path = client.common_project_path(project_id)
    conversation_profile_path = conversation_profile_client.conversation_profile_path(
        project_id, conversation_profile_id
    )
    conversation = {"conversation_profile": conversation_profile_path}
    response = client.create_conversation(
        parent=project_path, conversation=conversation
    )

    print("Life Cycle State: {}".format(response.lifecycle_state))
    print("Conversation Profile Name: {}".format(response.conversation_profile))
    print("Name: {}".format(response.name))
    return response

ユーザー参加者を作成する

候補を表示するには、ユーザーとエージェントの参加者を会話に追加します。まず、ユーザーを会話の参加者に追加します。

REST

ユーザー参加者を作成するには、Participant リソースの create メソッドを呼び出します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: 実際の Cloud プロジェクトの ID
LOCATION_ID: ロケーション ID
CONVERSATION_ID: 会話 ID

HTTP メソッドと URL:

POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/participants

リクエストの本文（JSON）:

{
  "role": "END_USER",
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/participants"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/participants" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID",
  "role": "END_USER"
}

participants の後のパスセグメントには、新しいユーザー参加者 ID が含まれます。

Python

詳細については、Vertex AI Search Python API のリファレンスドキュメントをご覧ください。

def create_participant(project_id: str, conversation_id: str, role: str):
    from google.cloud import dialogflow_v2beta1 as dialogflow

    """Creates a participant in a given conversation.

    Args:
        project_id: The GCP project linked with the conversation profile.
        conversation_id: Id of the conversation.
        participant: participant to be created."""

    client = dialogflow.ParticipantsClient()
    conversation_path = dialogflow.ConversationsClient.conversation_path(
        project_id, conversation_id
    )
    if role in ROLES:
        response = client.create_participant(
            parent=conversation_path, participant={"role": role}, timeout=600
        )
        print("Participant Created.")
        print(f"Role: {response.role}")
        print(f"Name: {response.name}")

        return response

エージェント参加者を作成する

エージェントの参加者を会話に追加します。

REST

エージェントの参加者を作成するには、Participant リソースの create メソッドを呼び出します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: 実際の Cloud プロジェクトの ID
LOCATION_ID: ロケーション ID
CONVERSATION_ID: 会話 ID

HTTP メソッドと URL:

POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/participants

リクエストの本文（JSON）:

{
  "role": "HUMAN_AGENT",
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/participants"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/participants" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID",
  "role": "HUMAN_AGENT"
}

participants の後のパスセグメントには、新しい人間のエージェントの参加者 ID が含まれます。

Python

詳細については、Vertex AI Search Python API のリファレンスドキュメントをご覧ください。

def create_participant(project_id: str, conversation_id: str, role: str):
    from google.cloud import dialogflow_v2beta1 as dialogflow

    """Creates a participant in a given conversation.

    Args:
        project_id: The GCP project linked with the conversation profile.
        conversation_id: Id of the conversation.
        participant: participant to be created."""

    client = dialogflow.ParticipantsClient()
    conversation_path = dialogflow.ConversationsClient.conversation_path(
        project_id, conversation_id
    )
    if role in ROLES:
        response = client.create_participant(
            parent=conversation_path, participant={"role": role}, timeout=600
        )
        print("Participant Created.")
        print(f"Role: {response.role}")
        print(f"Name: {response.name}")

        return response

エージェントからのメッセージを追加して分析する

いずれかの参加者が会話でメッセージを入力するたびに、API にメッセージを送信して処理する必要があります。データストアエージェントは、人間のエージェントとユーザーのメッセージの分析に基づいて提案を行います。次の例では、人間のエージェントが「ご用件はなんでしょうか？」という質問をして会話を開始します。

レスポンスでは候補がまだ返されていません。

REST

会話に人間のエージェントのメッセージを追加して分析するには、Participant リソースの analyzeContent メソッドを呼び出します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: プロジェクト ID
CONVERSATION_ID: 会話 ID
PARTICIPANT_ID: 人間のエージェントの参加者 ID

HTTP メソッドと URL:

POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID:analyzeContent

リクエストの本文（JSON）:

{
  "textInput": {
    "text": "How may I help you?",
    "languageCode": "en-US"
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID:analyzeContent"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID:analyzeContent" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "message": {
    "name": "projects/PROJECT_ID/conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "content": "How may I help you?",
    "languageCode": "en-US",
    "participant": "PARTICIPANT_ID",
    "participantRole": "HUMAN_AGENT",
    "createTime": "2020-02-13T00:01:30.683Z"
  }
}

Python

詳細については、Vertex AI Search Python API のリファレンスドキュメントをご覧ください。

def analyze_content_text(
    project_id: str, conversation_id: str, participant_id: str, text: str
):
    from google.cloud import dialogflow_v2beta1 as dialogflow

    """Analyze text message content from a participant.

    Args:
        project_id: The GCP project linked with the conversation profile.
        conversation_id: Id of the conversation.
        participant_id: Id of the participant.
        text: the text message that participant typed."""

    client = dialogflow.ParticipantsClient()
    participant_path = client.participant_path(
        project_id, conversation_id, participant_id
    )
    text_input = {"text": text, "language_code": "en-US"}
    response = client.analyze_content(
        participant=participant_path, text_input=text_input
    )
    print("AnalyzeContent Response:")
    print(f"Reply Text: {response.reply_text}")

    for suggestion_result in response.human_agent_suggestion_results:
        if suggestion_result.error is not None:
            print(f"Error: {suggestion_result.error.message}")
        if suggestion_result.suggest_articles_response:
            for answer in suggestion_result.suggest_articles_response.article_answers:
                print(f"Article Suggestion Answer: {answer.title}")
                print(f"Answer Record: {answer.answer_record}")
        if suggestion_result.suggest_faq_answers_response:
            for answer in suggestion_result.suggest_faq_answers_response.faq_answers:
                print(f"Faq Answer: {answer.answer}")
                print(f"Answer Record: {answer.answer_record}")
        if suggestion_result.suggest_smart_replies_response:
            for (
                answer
            ) in suggestion_result.suggest_smart_replies_response.smart_reply_answers:
                print(f"Smart Reply: {answer.reply}")
                print(f"Answer Record: {answer.answer_record}")

    for suggestion_result in response.end_user_suggestion_results:
        if suggestion_result.error:
            print(f"Error: {suggestion_result.error.message}")
        if suggestion_result.suggest_articles_response:
            for answer in suggestion_result.suggest_articles_response.article_answers:
                print(f"Article Suggestion Answer: {answer.title}")
                print(f"Answer Record: {answer.answer_record}")
        if suggestion_result.suggest_faq_answers_response:
            for answer in suggestion_result.suggest_faq_answers_response.faq_answers:
                print(f"Faq Answer: {answer.answer}")
                print(f"Answer Record: {answer.answer_record}")
        if suggestion_result.suggest_smart_replies_response:
            for (
                answer
            ) in suggestion_result.suggest_smart_replies_response.smart_reply_answers:
                print(f"Smart Reply: {answer.reply}")
                print(f"Answer Record: {answer.answer_record}")

    return response

提案のためにユーザーからのメッセージを追加する

エージェントに対して、お客様は「返品の払い戻しはいつ受け取れますか？」と質問します。今回は、API レスポンスに、ナレッジドキュメントに基づく提案されたクエリと生成 AI の回答が含まれています。

REST

会話のユーザーメッセージを追加して分析するには、Participant リソースの analyzeContent メソッドを呼び出します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: プロジェクト ID
CONVERSATION_ID: 会話 ID
PARTICIPANT_ID: エンドユーザーの参加者 ID

HTTP メソッドと URL:

POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID:analyzeContent

リクエストの本文（JSON）:

{
  "textInput": {
    "text": "When can I get my return refund?",
    "languageCode": "en-US"
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID:analyzeContent"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID/participants/PARTICIPANT_ID:analyzeContent" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "message": {
    "name": "projects/PROJECT_ID/conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "content": "When can I get my return refund?",
    "languageCode": "en-US",
    "participant": "PARTICIPANT_ID",
    "participantRole": "END_USER",
    "createTime": "2020-02-13T00:07:35.925Z"
  },
  "humanAgentSuggestionResults": [
    {
      "suggestKnowledgeAssistResponse": {
        "knowledgeAssistAnswer": {
          "suggestedQuery": {
            "queryText": "Refund processing time"
          },
          "suggestedQueryAnswer": {
            "answerText": "After your return is processed, you receive your refund in 7 days. The refund amount should be for the full value of the items returned, but doesn't include shipping & service fees.",
            "generativeSource": {
              "snippets": [
                {
                  "title": "Returns & refunds - Help",
                  "uri": "https://example.com/",
                  "text": "When the package with your return arrives at the seller's return center, it may take up to 7 additional business days to process. Check the status of your refund with the return tracking number found on your orders page."
                }
              ]
            },
          },
          "answerRecord": "projects/PROJECT_ID/answerRecords/ANSWER_RECORD_ID"
        },
      }
    }
  ]
}

Python

詳細については、Vertex AI Search Python API のリファレンスドキュメントをご覧ください。

def analyze_content_text(
    project_id: str, conversation_id: str, participant_id: str, text: str
):
    from google.cloud import dialogflow_v2beta1 as dialogflow

    """Analyze text message content from a participant.

    Args:
        project_id: The GCP project linked with the conversation profile.
        conversation_id: Id of the conversation.
        participant_id: Id of the participant.
        text: the text message that participant typed."""

    client = dialogflow.ParticipantsClient()
    participant_path = client.participant_path(
        project_id, conversation_id, participant_id
    )
    text_input = {"text": text, "language_code": "en-US"}
    response = client.analyze_content(
        participant=participant_path, text_input=text_input
    )
    print("AnalyzeContent Response:")
    print(f"Reply Text: {response.reply_text}")

    for suggestion_result in response.human_agent_suggestion_results:
        if suggestion_result.error is not None:
            print(f"Error: {suggestion_result.error.message}")
        if suggestion_result.suggest_articles_response:
            for answer in suggestion_result.suggest_articles_response.article_answers:
                print(f"Article Suggestion Answer: {answer.title}")
                print(f"Answer Record: {answer.answer_record}")
        if suggestion_result.suggest_faq_answers_response:
            for answer in suggestion_result.suggest_faq_answers_response.faq_answers:
                print(f"Faq Answer: {answer.answer}")
                print(f"Answer Record: {answer.answer_record}")
        if suggestion_result.suggest_smart_replies_response:
            for (
                answer
            ) in suggestion_result.suggest_smart_replies_response.smart_reply_answers:
                print(f"Smart Reply: {answer.reply}")
                print(f"Answer Record: {answer.answer_record}")

    for suggestion_result in response.end_user_suggestion_results:
        if suggestion_result.error:
            print(f"Error: {suggestion_result.error.message}")
        if suggestion_result.suggest_articles_response:
            for answer in suggestion_result.suggest_articles_response.article_answers:
                print(f"Article Suggestion Answer: {answer.title}")
                print(f"Answer Record: {answer.answer_record}")
        if suggestion_result.suggest_faq_answers_response:
            for answer in suggestion_result.suggest_faq_answers_response.faq_answers:
                print(f"Faq Answer: {answer.answer}")
                print(f"Answer Record: {answer.answer_record}")
        if suggestion_result.suggest_smart_replies_response:
            for (
                answer
            ) in suggestion_result.suggest_smart_replies_response.smart_reply_answers:
                print(f"Smart Reply: {answer.reply}")
                print(f"Answer Record: {answer.answer_record}")

    return response

会話を完了する

会話が終わったら、API を使用して会話を完了します。

REST

会話を完了するには、conversations リソースの complete メソッドを呼び出します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: GCP プロジェクト ID
CONVERSATION_ID: 会話の作成時に受け取った ID

HTTP メソッドと URL:

POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID:complete

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID:complete"

PowerShell（Windows）

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversations/CONVERSATION_ID:complete" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_ID/conversations/CONVERSATION_ID",
  "lifecycleState": "COMPLETED",
  "conversationProfile": "projects/PROJECT_ID/conversationProfiles/CONVERSATION_PROFILE_ID",
  "startTime": "2018-11-05T21:05:45.622Z",
  "endTime": "2018-11-06T03:50:26.930Z"
}

Python

詳細については、Vertex AI Search Python API のリファレンスドキュメントをご覧ください。

def complete_conversation(project_id, conversation_id):
    """Completes the specified conversation. Finished conversations are purged from the database after 30 days.

    Args:
        project_id: The GCP project linked with the conversation.
        conversation_id: Id of the conversation."""

    client = dialogflow.ConversationsClient()
    conversation_path = client.conversation_path(project_id, conversation_id)
    conversation = client.complete_conversation(name=conversation_path)
    print("Completed Conversation.")
    print("Life Cycle State: {}".format(conversation.lifecycle_state))
    print("Conversation Profile Name: {}".format(conversation.conversation_profile))
    print("Name: {}".format(conversation.name))
    return conversation

シミュレータ

フローベースまたはプレイブックベースのデータストアエージェントは、Agent Assist シミュレータでテストできます。

上記の例では、フローベースのデータストアエージェントが次の提案を行っています。

推奨されるクエリ: Refund processing time（払い戻しの処理時間）。
生成 AI が生成した回答: 返品手続きが完了すると、7 日以内に払い戻しが行われます。払い戻し額は、返品された商品の全額となりますが、送料とサービス料は含まれません。
関連するナレッジドキュメントのタイトル: 返品と払い戻し - ヘルプ。

ステップ 3: Pub/Sub 候補の通知

候補の通知を受け取るには、会話プロファイルの作成時に notificationConfig フィールドを設定します。このオプションでは、Pub/Sub を使用し、会話が進行して新しい候補が利用可能になったときに、候補の通知をアプリケーションに送信します。

AnalyzeContent API を介して統合している場合は、ConversationProfile で disable_high_latency_features_sync_delivery 構成を有効にして、AnalyzeContent API がプロアクティブな生成知識アシストの候補を待たずに応答し、Pub/Sub を介して候補を配信するようにできます。

この構成は、Agent Assist コンソールから有効にすることもできます。

Customer Experience Insights を通じてデータにアクセスする

また、プロアクティブ生成ナレッジアシストで生成されたクエリと回答は、カスタマーエクスペリエンス分析情報に自動的に入力されます。このデータにアクセスするには、Dialogflow ランタイムの統合を有効にするの手順に沿って操作します。

フィードバックを送信

フィードバックを送信する手順については、Agent Assist にフィードバックを送信するをご覧ください。

エージェントの質問に答える

以下は、回答エージェントの質問に関するフィードバックを送信するための JSON リクエストの例です。

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/answerRecords/ANSWER_RECORD_ID",
  "answerFeedback": {
    "displayed": true
    "clicked": true
    "correctnessLevel": "FULLY_CORRECT"
    "agentAssistantDetailFeedback": {
      "knowledgeSearchFeedback": {
        "answerCopied": true
        "clickedUris": [
          "url_1",
          "url_2",
          "url_3",
        ]
      }
    }
  }
}

Q&A をプロアクティブに提案する

以下は、プロアクティブな提案に関するフィードバックを送信するための JSON リクエストの例です。

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/answerRecords/ANSWER_RECORD_ID",
  "answerFeedback": {
    "displayed": true
    "clicked": true
    "correctnessLevel": "FULLY_CORRECT"
    "agentAssistantDetailFeedback": {
      "knowledgeAssistFeedback": {
        "answerCopied": true
        "clickedUris": [
          "url_1",
          "url_2",
          "url_3",
        ]
      }
    }
  }
}

メタデータ

ナレッジドキュメントのメタデータを構成すると、生成ナレッジアシストとプロアクティブ生成ナレッジアシストの両方で、レスポンスとともにドキュメントのメタデータが返されます。

たとえば、メタデータを使用して、ナレッジドキュメントが内部の限定公開記事か、外部の公開記事かをマークできます。エージェントアシストシミュレータと UI モジュールの両方で、生成ナレッジアシストとプロアクティブ生成ナレッジアシストは、特定のキーのドキュメントメタデータ値を自動的に表示します。

gka_source_label: 値は候補カードに直接表示されます。
gka_source_tooltip: 値が struct 型の場合、ソースリンクにカーソルを合わせると、値がツールチップに表示されます。

ナレッジドキュメントに次のメタデータがある場合、候補カードにはソースとして External Doc が表示され、ツールチップには doc_visibility: public doc が追加されます。

メタデータ: None { "title": "Public Sample Doc", "gka_source_label": "External Doc", "gka_source_tooltip": { "doc_visibility": "public doc" } }

エンドユーザーのメタデータ

エンドユーザーのメタデータを添付して、Datastore エージェントによって生成される回答の精度を高め、パーソナライズします。生成型ナレッジアシストでは、エンドユーザーのメタデータを end_user_metadata フィールドに添付するか、IngestContextReferences API を使用して会話に取り込むことができます。取り込んだエンドユーザーのメタデータは、生成ナレッジアシストとプロアクティブ生成ナレッジアシストの両方で使用できます。

例 1: エンドユーザーのメタデータを追加する

{
  "query": {
     "text": "test query"
  },
  "conversationProfile": "projects/PROJECT_ID/locations/LOCATION_ID/conversationProfiles/CONVERSATION_PROFILE_ID",
  "sessionId": "SESSION_ID",
  "conversation": "projects/PROJECT_ID/locations/LOCATION_ID/conversations/CONVERSATION_ID",
  "querySource": "AGENT_QUERY",
  "endUserMetadata": {
    "Name": "Jack",
    "Age": 33,
    "City": "Tokyo"
  }
}

例 2: エンドユーザーのメタデータを取り込む

{
  "conversation": "projects/PROJECT_ID/locations/global/conversations/CONVERSATION_ID",
  "contextReferences": {
   "gka_end_user_metadata": {
      "contextContents": [{
"content": "{\"Name\":\"Jack\",\"Age\":33,\"city\":\"Tokyo\"}",
        "contentFormat": "JSON"
      }],
      "updateMode": "OVERWRITE",
      "languageCode": "en-US"
    }
  }
}

Datastore のエンドユーザーメタデータの詳細については、Dialogflow のパーソナライズをご覧ください。

言語サポート

サポートされている言語の全リストをご覧ください。

生成ナレッジ アシスト コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

フローベースのデータストア エージェントを作成する

Playbook ベースのデータストア エージェントを作成する

人間のエージェントからの質問に回答する

ステップ 1: 会話プロファイルを作成する

コンソールから作成する

API から作成

ステップ 2: データストア エージェントを使用する

シミュレータ

エージェントに Q＆A をプロアクティブに提案する

ステップ 1: 会話プロファイルを作成する

コンソールから作成する

API から作成

ステップ 2: ランタイムに会話を処理する

会話を作成する

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Python

ユーザー参加者を作成する

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Python

エージェント参加者を作成する

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Python

エージェントからのメッセージを追加して分析する

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Python

提案のためにユーザーからのメッセージを追加する

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Python

会話を完了する

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Python

シミュレータ

ステップ 3: Pub/Sub 候補の通知

Customer Experience Insights を通じてデータにアクセスする

フィードバックを送信

エージェントの質問に答える

Q&A をプロアクティブに提案する

メタデータ

エンドユーザーのメタデータ

言語サポート

生成ナレッジアシスト

フローベースのデータストアエージェントを作成する

Playbook ベースのデータストアエージェントを作成する

ステップ 2: データストアエージェントを使用する