הצעה למאמר

התכונה 'הצעות למאמרים' ב-Agent Assist עוקבת אחרי שיחה בין נציג אנושי לבין משתמש קצה, ומספקת לנציג האנושי הצעות למסמכים רלוונטיים. נציג אנושי יכול לבדוק את ההצעות האלה בזמן שהשיחה מתנהלת ולקבל החלטה לגבי המסמכים שצריך לקרוא או לשתף עם משתמש הקצה. אתם יכולים להשתמש בהצעות למאמרים כדי לעזור לנציג תמיכה אנושי להבין ולפתור בעיות של משתמשי קצה בזמן שהנציג ומשתמש הקצה מנהלים שיחה.

‫Agent Assist מספק מודלים בסיסיים להצעת מאמרים שבהם אפשר להשתמש כדי להציע מאמרים לסוכנים. אפשר גם לאמן מודל מותאם אישית באמצעות נתוני שיחות שהועלו כדי לשפר את הביצועים. אם אתם רוצים לאמן מודל מותאם אישית להצעות לשימוש בהצעות למאמרים, אתם יכולים לפנות לנציג שלכם ב-Google.

במאמר הזה מוסבר איך להשתמש ב-API כדי להטמיע את התכונה 'הצעות למאמרים' ולקבל הצעות מהתכונה הזו במהלך זמן הריצה. יש לכם אפשרות להשתמש במסוף Agent Assist כדי לבדוק את תוצאות ההצעה למאמר בזמן העיצוב, אבל אתם צריכים לקרוא ל-API ישירות בזמן הריצה. פרטים על בדיקת הביצועים של התכונה באמצעות מסוף Agent Assist זמינים בקטע ההדרכות.

לפני שמתחילים

לפני שמתחילים לקרוא את המדריך הזה, צריך לבצע את הפעולות הבאות:

  1. מפעילים את Dialogflow API בפרויקטGoogle Cloud .

הגדרת פרופיל שיחה

כדי לקבל הצעות מ-Agent Assist, צריך ליצור מאגר מידע שמכיל את המסמכים שהועלו ולהגדיר פרופיל שיחה. אפשר גם לבצע את הפעולות האלה באמצעות מסוף Agent Assist אם אתם מעדיפים לא להפעיל את ה-API ישירות.

יצירת מאגר ידע

לפני שמתחילים להעלות מסמכים, צריך ליצור מאגר ידע שאליו יועלו המסמכים. כדי ליצור מאגר ידע, צריך לבצע קריאה ל-method‏ create בסוג KnowledgeBase.

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב-GCP
  • ‫KNOWLEDGE_BASE_DISPLAY_NAME: השם הרצוי של מאגר הידע

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/knowledgeBases

תוכן בקשת JSON: 

{
  "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME"
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/PROJECT_ID/knowledgeBases/NDA4MTM4NzE2MjMwNDUxMjAwMA",
  "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME"
}

פלח הנתיב אחרי knowledgeBases מכיל את המזהה החדש של מאגר הידע.

Python

כדי לבצע אימות ב-Agent Assist, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

def create_knowledge_base(project_id, display_name):
    """Creates a Knowledge base.

    Args:
        project_id: The GCP project linked with the agent.
        display_name: The display name of the Knowledge base."""
    from google.cloud import dialogflow_v2beta1 as dialogflow

    client = dialogflow.KnowledgeBasesClient()
    project_path = client.common_project_path(project_id)

    knowledge_base = dialogflow.KnowledgeBase(display_name=display_name)

    response = client.create_knowledge_base(
        parent=project_path, knowledge_base=knowledge_base
    )

    print("Knowledge Base created:\n")
    print("Display Name: {}\n".format(response.display_name))
    print("Name: {}\n".format(response.name))

יצירת מסמך ידע

עכשיו אפשר להוסיף מסמכים למאגר הידע. כדי ליצור מסמך במאגר הידע, מבצעים קריאה ל-method‏ create בסוג Document. מגדירים את KnowledgeType לערך ARTICLE_SUGGESTION. בדוגמה הזו נעשה שימוש בקובץ HTML עם פרטי הזמנה להחזרה שהועלה לקטגוריה ב-Cloud Storage ששותפה באופן ציבורי. כשמגדירים את התכונה 'הצעות למאמרים' במערכת שלכם, המסמכים צריכים להיות באחד מהפורמטים הבאים. מידע נוסף על שיטות מומלצות ליצירת מסמכים זמין במאמרי העזרה בנושא מסמכי ידע.

פורמטים של מסמכי ידע:

  • קובץ שמאוחסן בקטגוריה של Cloud Storage. אפשר לציין את הנתיב כשמפעילים את ה-API.
  • תוכן הטקסט של מסמך, שאפשר לשלוח בבקשת API.
  • כתובת URL ציבורית.

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב-GCP
  • ‫KNOWLEDGE_BASE_ID: מזהה מאגר הידע שהוחזר מהבקשה הקודמת
  • ‫DOCUMENT_DISPLAY_NAME: השם הרצוי של מסמך הידע

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID/documents

תוכן בקשת JSON: 

{
  "displayName": "DOCUMENT_DISPLAY_NAME",
  "mimeType": "text/html",
  "knowledgeTypes": "ARTICLE_SUGGESTION",
  "contentUri": "gs://agent-assist-public-examples/public_article_suggestion_example_returns.html"
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/PROJECT_ID/operations/ks-add_document-MzA5NTY2MTc5Mzg2Mzc5NDY4OA"
}

התגובה היא פעולה ממושכת, שאפשר לשלוח לה בקשות כדי לבדוק אם היא הסתיימה.

Python

כדי לבצע אימות ב-Agent Assist, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

def create_document(
    project_id, knowledge_base_id, display_name, mime_type, knowledge_type, content_uri
):
    """Creates a Document.

    Args:
        project_id: The GCP project linked with the agent.
        knowledge_base_id: Id of the Knowledge base.
        display_name: The display name of the Document.
        mime_type: The mime_type of the Document. e.g. text/csv, text/html,
            text/plain, text/pdf etc.
        knowledge_type: The Knowledge type of the Document. e.g. FAQ,
            EXTRACTIVE_QA.
        content_uri: Uri of the document, e.g. gs://path/mydoc.csv,
            http://mypage.com/faq.html."""
    from google.cloud import dialogflow_v2beta1 as dialogflow

    client = dialogflow.DocumentsClient()
    knowledge_base_path = dialogflow.KnowledgeBasesClient.knowledge_base_path(
        project_id, knowledge_base_id
    )

    document = dialogflow.Document(
        display_name=display_name, mime_type=mime_type, content_uri=content_uri
    )

    document.knowledge_types.append(
        getattr(dialogflow.Document.KnowledgeType, knowledge_type)
    )

    response = client.create_document(parent=knowledge_base_path, document=document)
    print("Waiting for results...")
    document = response.result(timeout=120)
    print("Created Document:")
    print(" - Display Name: {}".format(document.display_name))
    print(" - Knowledge ID: {}".format(document.name))
    print(" - MIME Type: {}".format(document.mime_type))
    print(" - Knowledge Types:")
    for knowledge_type in document.knowledge_types:
        print("    - {}".format(KNOWLEDGE_TYPES[knowledge_type]))
    print(" - Source: {}\n".format(document.content_uri))

יצירת פרופיל שיחה

פרופיל שיחה מגדיר קבוצה של פרמטרים ששולטים בהצעות שמוצגות לסוכן במהלך שיחה. בשלבים הבאים יוצרים ConversationProfile עם אובייקט HumanAgentAssistantConfig. אפשר גם לבצע את הפעולות האלה באמצעות Agent Assist Console אם אתם מעדיפים לא להתקשר ישירות ל-API.

מומלץ להגדיר סף ראשוני של מהימנות של 0.44 (או 0.1 אם משתמשים במודל הבסיסי הקודם). אם צריך, אפשר להגדיל את הסף מעבר לטווח המומלץ. העלאת הסף מובילה לתוצאות מדויקות יותר ולכיסוי נמוך יותר (פחות הצעות), והורדת הסף מובילה לתוצאות פחות מדויקות ולכיסוי גבוה יותר (יותר הצעות).

ההגדרה 'הצעות מוטמעות' מופעלת כברירת מחדל. אפשר גם להפעיל התראות של Cloud Pub/Sub כשמגדירים את פרופיל השיחה.

REST

כדי ליצור פרופיל שיחה, מבצעים קריאה ל-method‏ create במשאב ConversationProfile.

‫noSmallTalk: אם true, ההצעות לא יופעלו אחרי הודעות של שיחה קלילה (כמו 'היי', 'מה שלומך' וכו'). אם false, ההצעות יופעלו אחרי הודעות של שיחה קלילה.

‫onlyEndUser: אם הערך הוא true, ההצעות יופעלו רק אחרי הודעות של משתמשי קצה. אם false, ההצעות יופעלו אחרי הודעות של משתמשי קצה ושל סוכנים אנושיים.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב-GCP
  • ‫KNOWLEDGE_BASE_ID: מזהה מאגר הידע

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/conversationProfiles

תוכן בקשת JSON: 

{
  "name": "projects/PROJECT_ID/conversationProfiles/CONVERSATION_PROFILE_ID",
  "displayName": "my-conversation-profile-display-name",
  "humanAgentAssistantConfig": {
    "notificationConfig": {},
    "humanAgentSuggestionConfig": {
      "featureConfigs": [
        {
          "enableInlineSuggestion": true,
          "SuggestionTriggerSettings": {
            "noSmallTalk": true,
            "onlyEndUser": true,
          },
          "suggestionFeature": {
            "type": "ARTICLE_SUGGESTION"
          },
          "queryConfig": {
            "knowledgeBaseQuerySource": {
              "knowledgeBases": [
                "projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID"
              ]
            }
          }
        }
      ]
    }
  },
  "sttConfig": {},
  "languageCode": "en-US"
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/PROJECT_ID/conversationProfiles/CONVERSATION_PROFILE_ID",
  "displayName": "my-conversation-profile-display-name",
  "humanAgentAssistantConfig": {
    ...
  }
}

פלח הנתיב אחרי conversationProfiles מכיל את המזהה החדש של פרופיל השיחה.

Python

כדי לבצע אימות ב-Agent Assist, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

def create_conversation_profile_article_faq(
    project_id,
    display_name,
    article_suggestion_knowledge_base_id=None,
    faq_knowledge_base_id=None,
):
    """Creates a conversation profile with given values

    Args: project_id:  The GCP project linked with the conversation profile.
        display_name: The display name for the conversation profile to be
        created.
        article_suggestion_knowledge_base_id: knowledge base id for article
        suggestion.
        faq_knowledge_base_id: knowledge base id for faq."""

    client = dialogflow.ConversationProfilesClient()
    project_path = client.common_project_path(project_id)

    conversation_profile = {
        "display_name": display_name,
        "human_agent_assistant_config": {
            "human_agent_suggestion_config": {"feature_configs": []}
        },
        "language_code": "en-US",
    }

    if article_suggestion_knowledge_base_id is not None:
        as_kb_path = dialogflow.KnowledgeBasesClient.knowledge_base_path(
            project_id, article_suggestion_knowledge_base_id
        )
        feature_config = {
            "suggestion_feature": {"type_": "ARTICLE_SUGGESTION"},
            "suggestion_trigger_settings": {
                "no_small_talk": True,
                "only_end_user": True,
            },
            "query_config": {
                "knowledge_base_query_source": {"knowledge_bases": [as_kb_path]},
                "max_results": 3,
            },
        }
        conversation_profile["human_agent_assistant_config"][
            "human_agent_suggestion_config"
        ]["feature_configs"].append(feature_config)
    if faq_knowledge_base_id is not None:
        faq_kb_path = dialogflow.KnowledgeBasesClient.knowledge_base_path(
            project_id, faq_knowledge_base_id
        )
        feature_config = {
            "suggestion_feature": {"type_": "FAQ"},
            "suggestion_trigger_settings": {
                "no_small_talk": True,
                "only_end_user": True,
            },
            "query_config": {
                "knowledge_base_query_source": {"knowledge_bases": [faq_kb_path]},
                "max_results": 3,
            },
        }
        conversation_profile["human_agent_assistant_config"][
            "human_agent_suggestion_config"
        ]["feature_configs"].append(feature_config)

    response = client.create_conversation_profile(
        parent=project_path, conversation_profile=conversation_profile
    )

    print("Conversation Profile created:")
    print("Display Name: {}".format(response.display_name))
    # Put Name is the last to make it easier to retrieve.
    print("Name: {}".format(response.name))
    return response

(אופציונלי) הגדרת הגדרות אבטחה

יש לכם אפשרות להגדיר פרמטרים של אבטחה כדי לטפל בבעיות כמו צנזורה של נתונים ושמירת נתונים. כדי לעשות את זה, צריך ליצור משאב SecuritySettings ולקשר אותו לפרופיל שיחה באמצעות השדה securitySettings.

הגדרות האבטחה שמוסיפים לפרופיל שיחה משפיעות רק על ההתנהגות של הודעות טקסט ב-Agent Assist. ההתנהגות של היסטוריית האינטראקציות ב-Dialogflow נקבעת על ידי הגדרות האבטחה של Dialogflow, שאפשר להגדיר באמצעות מסוף Dialogflow CX.

ניהול שיחות בזמן ריצה

יצירת שיחה

כשמתחיל דיאלוג בין משתמש קצה לבין נציג אנושי או וירטואלי, נוצרת שיחה. כדי לראות הצעות, צריך גם ליצור משתתף שהוא משתמש קצה ומשתתף שהוא נציג שירות אנושי, ולהוסיף אותם לשיחה. בקטעים הבאים מפורט תהליך ההגדרה.

קודם צריך ליצור שיחה:

REST

כדי ליצור שיחה, מבצעים קריאה ל-method‏ create במשאב Conversation.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט בענן
  • ‫LOCATION_ID: מזהה המיקום
  • ‫CONVERSATION_PROFILE_ID: המזהה שקיבלתם כשנוצר פרופיל השיחה

ה-method של ה-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",
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת 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 מכיל את מזהה השיחה החדש.

Python

כדי לבצע אימות ב-Agent Assist, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

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

כדי ליצור משתתף שהוא משתמש קצה, צריך להפעיל את method‏ create במשאב Participant.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט בענן
  • ‫LOCATION_ID: מזהה המיקום
  • ‫CONVERSATION_ID: מזהה השיחה

ה-method של ה-HTTP וכתובת ה-URL: 

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

תוכן בקשת JSON: 

{
  "role": "END_USER",
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

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

פלח הנתיב אחרי participants מכיל את מזהה המשתתף החדש של משתמש הקצה.

Python

כדי לבצע אימות ב-Agent Assist, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

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

כדי ליצור משתתף שהוא נציג שירות אנושי, צריך להפעיל את method‏ create במשאב Participant.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט בענן
  • ‫LOCATION_ID: מזהה המיקום
  • ‫CONVERSATION_ID: מזהה השיחה

ה-method של ה-HTTP וכתובת ה-URL: 

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

תוכן בקשת JSON: 

{
  "role": "HUMAN_AGENT",
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

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

פלח הנתיב אחרי participants מכיל את מזהה המשתתף החדש של הסוכן האנושי.

Python

כדי לבצע אימות ב-Agent Assist, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

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 לעיבוד. ההצעות של Agent Assist מבוססות על ניתוח של הודעות מנציגים אנושיים וממשתמשי קצה. בדוגמה הבאה, הנציג האנושי מתחיל את השיחה בשאלה "איך אוכל לעזור לך?". עדיין לא מוחזרות הצעות בתשובה.

REST

כדי להוסיף ולנתח הודעה של נציג אנושי בשיחה, צריך לבצע קריאה ל-method‏ analyzeContent במשאב Participant.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב-GCP
  • ‫CONVERSATION_ID: מזהה השיחה
  • ‫PARTICIPANT_ID: מזהה המשתתף של הסוכן האנושי

ה-method של ה-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"
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת 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"
        },
        "humanAgentSuggestionResults": [
          {
            "suggestArticlesResponse": {
              "latestMessage": "projects/PROJECT_ID/conversations/CONVERSATION_ID/messages/MESSAGE_ID",
              "contextSize": 1
            }
          }
        ]
      }
    }
  ]
}

Python

כדי לבצע אימות ב-Agent Assist, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

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 מכילה מסמך מוצע עם ציון רמת הביטחון שמשויך אליו. מוקדם יותר במדריך הזה הוספנו מסמך ידע אחד למאגר הידע, והמסמך הזה הוחזר. הציונים לרמת הוודאות נעים בין 0 ל-1. ערכים גבוהים יותר מצביעים על סבירות גבוהה יותר לכך שהמסמך רלוונטי לשיחה. מוחזר גם קטע טקסט שמכיל את 100 התווים הראשונים של המסמך. הקטע יכול לעזור לנציג אנושי לקבוע במהירות אם המסמך שימושי. מומלץ לספק את המידע הזה לנציג שירות אנושי, שיכול לבחור לשתף את המסמך המומלץ עם משתמש הקצה.

REST

כדי להוסיף ולנתח הודעה של משתמש קצה בשיחה, צריך לבצע קריאה ל-method‏ analyzeContent במשאב Participant.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב-GCP
  • ‫CONVERSATION_ID: מזהה השיחה
  • ‫PARTICIPANT_ID: מזהה המשתתף של משתמש הקצה

ה-method של ה-HTTP וכתובת ה-URL: 

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

תוכן בקשת JSON: 

{
  "textInput": {
    "text": "I want to return my order.",
    "languageCode": "en-US"
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "message": {
    "name": "projects/PROJECT_ID/conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "content": "I want to return my order.",
    "languageCode": "en-US",
    "participant": "PARTICIPANT_ID",
    "participantRole": "END_USER",
    "createTime": "2020-02-13T00:07:35.925Z"
  },
  "humanAgentSuggestionResults": [
    {
      "suggestArticlesResponse": {
        "articleAnswers": [
          {
            "title": "Return an order",
            "uri": "gs://agent-assist-public-examples/public_article_suggestion_example_returns.html",
            "snippets": [
              "\u003cb\u003eReturn\u003c/b\u003e an \u003cb\u003eorder\u003c/b\u003e. Follow the steps below for Made-up Store \u003cb\u003ereturns\u003c/b\u003e. At this time, \nwe don't offer exchanges. In most cases, you can drop off \u003cb\u003ereturns\u003c/b\u003e at any Made-up\n ..."
            ],
            "metadata": {
              "title": "Return an order",
              "snippet": "\n  \n\n\u003ch1\u003eReturn an order\u003c/h1\u003e \nFollow the steps below for Made-up Store returns. At this time, we do...",
              "document_display_name": "my-kdoc"
            },
            "answerRecord": "projects/PROJECT_ID/answerRecords/ANSWER_RECORD_ID"
          }
        ],
        "latestMessage": "projects/PROJECT_ID/conversations/CONVERSATION_ID/messages/MESSAGE_ID",
        "contextSize": 2
      }
    }
  ]
}

Python

כדי לבצע אימות ב-Agent Assist, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

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

כדי לסיים את השיחה, מבצעים קריאה ל-method‏ complete במשאב conversations.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב-GCP
  • ‫CONVERSATION_ID: המזהה שקיבלתם כשפתחתם את השיחה

ה-method של ה-HTTP וכתובת ה-URL: 

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

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת 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

כדי לבצע אימות ב-Agent Assist, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

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

אפשרויות לבקשת API

בקטעים הקודמים הוסבר איך ליצור ConversationProfile כדי לקבל הצעות. בקטעים הבאים מפורטות כמה פונקציות אופציונליות שאפשר להטמיע במהלך שיחה.

התראות על הצעות ללוח הזמנים ב-Pub/Sub

בקטעים הקודמים, נוצר ConversationProfile רק עם עוזר אנושי. במהלך השיחה, היה צריך להתקשר ל-API כדי לקבל הצעות אחרי שכל הודעה נוספה לשיחה. אם אתם מעדיפים לקבל התראות על אירועים לגבי הצעות, אתם יכולים להגדיר את השדה notificationConfig כשאתם יוצרים את פרופיל השיחה. באפשרות הזו נעשה שימוש ב-Cloud Pub/Sub כדי לשלוח לאפליקציה התראות על הצעות במהלך השיחה, כשהצעות חדשות זמינות.