Virtual Agent Assist

This how-to guide walks you through the process of enabling the Virtual Agent Assist feature by calling the API directly. The Virtual Agent Assist assistant follows the conversation and uses a Dialog Flow virtual agent to provide workflow support to human agents and detect intents for data analysis.

If you prefer, you can use the Agent Assist console to train a model and test its performance using the simulator. See the Virtual Agent Assist console tutorial for instructions.

Before you begin

Before you can enable Virtual Agent Assist you must have already implemented one or more Agent Assist features to use with the virtual agent. Smart Reply, FAQ Assist, Article Suggestion, and Smart Compose can be used alone with Virtual Agent Assist or in any combination. The following links take you to the relevant documentation for implementation details.

Create a conversation

When a dialog begins between an end-user and a human or virtual agent, you create a conversation. In order to see suggestions, you must also create both an end-user participant and a human agent participant and add them to the conversation. The following sections walk you through this process.

First, you must create a conversation:

REST

Create an end-user participant

You must add both end-user and human agent participants to the conversation in order to see suggestions. First, add the end-user participant to the conversation:

REST

To create an end-user participant, call the create method on the Participant resource.

The path segment after participants contains your new end-user participant ID.

Create a human agent participant

REST

To create a human agent participant, call the create method on the Participant resource.

Before using any of the request data, make the following replacements:

PROJECT_ID: your Cloud project ID
LOCATION_ID: your location ID
CONVERSATION_ID: your conversation ID

HTTP method and URL:

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

Request JSON body:

{
  "role": "HUMAN_AGENT",
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

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)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$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

You should receive a JSON response similar to the following:

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

The path segment after participants contains your new human agent participant ID.

Python

To authenticate to Agent Assist, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

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

Add a message from the end-user and get suggestions

To add and analyze an end-user message for the conversation, call the analyzeContent method on the Participant resource. The response includes a dialogflowAssistAnswers field containing the following data:

fulfillmentText: Contains a suggested response. You can configure your system to present this suggestion to the human agent.
answer record: A unique ID for the suggestion.

Select the suggestion

When a human agent receives a suggestion, they can accept it as-is or edit it before passing it on to the end-user. To select a suggestion, call analyzeContent again using the human agent participant. Set the suggestionInput field to your selected settings and provide the answer record you received earlier. The text override field should contain the actual text sent to the end-user. The following is an example of configuring the suggestionInput field:

{
  "answerRecord": "answer-record",
  "textOverride": {
    "text" : "Yes, there will be ponies.",
    "languageCode": "en-US"
  }
}

Complete the conversation

When the conversation ends, use the API to complete the conversation.

REST

To complete the conversation, call the complete method on the conversations resource.

Before using any of the request data, make the following replacements:

PROJECT_ID: your GCP project ID
CONVERSATION_ID: the ID you received when creating the conversation

HTTP method and URL:

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

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

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)

Execute the following command:

$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

You should receive a JSON response similar to the following:

{
  "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

To authenticate to Agent Assist, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

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

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-07-20 UTC.

Virtual Agent Assist Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Create a conversation

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Python

Create an end-user participant

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Python

Create a human agent participant

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Python

Add a message from the end-user and get suggestions

Select the suggestion

Complete the conversation

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Python