Register and manage a Dialogflow agent

This page describes how to register and use Dialogflow agents with Gemini Enterprise.

Overview

To use a Dialogflow agent with Gemini Enterprise, you must first deploy then register your agent. Registering your Dialogflow agent links your deployed agent to Gemini Enterprise so that they can communicate.

Before you begin

Before registering your Dialogflow agent, you must ensure that these steps are completed:

  1. Deploy your Dialogflow agent. To view the Dialogflow and conversational agents dashboard, see Conversational agents.
  2. Enable the Discovery Engine API for your Google Cloud project.
  3. Enable the Vertex AI User and Vertex AI Viewer roles for your Discovery Engine service account. This is essential for Gemini Enterprise to communicate with your Dialogflow agent. You can configure these permissions in the Identity and Access Management section of the Google Cloud console.
  4. Select the Include Google-provided role grants checkbox to view the Discovery Engine service account.
  5. Create a Gemini Enterprise app. For more information, see Create an app.

Register a Dialogflow agent with Gemini Enterprise

You can register your Dialogflow agent with Gemini Enterprise using the Google Cloud console or the REST API. Registration makes your agent available to users within a Gemini Enterprise app.

Console

To register a Dialogflow agent using the Google Cloud console, follow these steps:

  1. In the Google Cloud console, go to the Gemini Enterprise page.

    Go to Gemini Enterprise

  2. Select your project.

  3. Click the name of the app that you want to register the agent with.

  4. Click Agents > Add Agents. The Choose an agent type pane appears.

  5. On the Custom agent via Dialogflow card, click Add to register your Dialogflow agent with Gemini Enterprise. The Configuration pane opens.

  6. To configure your agent, follow these steps:

    1. Enter a name in the Your agent name field. This value appears in Gemini Enterprise as the display name of your agent.

    2. Enter a description in the Describe your agent field. This value is used by an LLM to determine whether to invoke your agent in response to a user query.

    3. Enter the resource path of the Dialogflow agent that you want to register with Gemini Enterprise in the Dialogflow agent source field.

      Use this format: projects/{project}/locations/{location}/agents/{agent}

      The Agent availability option, When selected, is set by default.

    4. Under the Tool settings section, enter a description in the Tool description field. This description is used by the LLM to understand the tool's purpose and to decide when to use it.

    5. Enter the name in the Input parameter name field. This is the parameter name for the function call. This parameter name gives a hint to the LLM about what type of content the parameter is expected to contain, such as a question, a command, a search_query.

    6. Enter the description for the Input parameter description field. This is a parameter description for the function call. This description gives the LLM more information about the parameter, such as what kind of content is expected to be passed in and what actions should be performed.

    7. Click Create.

curl

This code sample demonstrates how you can register your agent:

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "icon": {
        "uri": "ICON_URI"
      },
      "dialogflowAgentDefinition": {
        "dialogflowAgent": "projects/DIALOGFLOW_PROJECT_ID/locations/DIALOGFLOW_LOCATION/agents/DIALOGFLOW_AGENT_ID"
      }
    }'

Replace the variables with values:

  • PROJECT_ID: the ID of your Google Cloud project.
  • APP_ID: the ID of your Gemini Enterprise app.
  • DISPLAY_NAME: the user-friendly name for your agent that displays in Gemini Enterprise.
  • DESCRIPTION: a brief explanation of what your agent does that's visible to users in Gemini Enterprise. For example, Extract key information from uploaded invoices for business travel.
  • ICON_URI: the public URI of an icon that displays next to your Dialogflow agent's name. You can also provide a Base64-encoded image in icon.content.
  • DIALOGFLOW_PROJECT_ID: the Google Cloud project ID that identifies the location of your Dialogflow agent.
  • DIALOGFLOW_LOCATION: the specific geographic location where your Dialogflow agent is hosted, such as global or us-central1.
  • DIALOGFLOW_AGENT_ID: the unique identifier of your Dialogflow agent.

The successful response to this command returns all fields of the newly created Dialogflow agent resource, which includes its unique resource name in the name field. This resource name can be used for future updates or references.

List agents connected to an app

The following code sample demonstrates how you can get the details of all the agents connected to your app:

curl 

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

Replace the variables with values:

  • ENDPOINT_LOCATION-: the multi-region for your API request. Assign one of the following values:
    • us- for the US multi-region
    • eu- for the EU multi-region
    • global- for the Global location
    For more information, see Specify a multi-region for your data store.
  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the multi-region of your app: global, us, or eu.
  • APP_ID: the ID of your Gemini Enterprise app.

If your agent isn't prebuilt by Google, the response includes a name field in the first few lines. The value of this field contains the Agent ID at the end of the path. For example, in the following response, the Agent ID is 12345678901234567890:

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

View details of a Dialogflow agent

The following code sample demonstrates how you can retrieve the details of an agent that was registered with Gemini Enterprise:

curl 

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Replace the variables with values:

  • ENDPOINT_LOCATION-: the multi-region for your API request. Assign one of the following values:
    • us- for the US multi-region
    • eu- for the EU multi-region
    • global- for the Global location
    For more information, see Specify a multi-region for your data store.
  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the multi-region of your app: global, us, or eu.
  • APP_ID: the ID of your Gemini Enterprise app.
  • AGENT_ID: The ID of the agent. You can find the agent ID by listing the agents connected to your app.

Update a Dialogflow agent

All of the fields that were supplied during agent registration can be updated. The following fields are mandatory during the update process:

  • displayName
  • description
  • reasoning_engine

When updating a field, all fields and their values must be redefined in the update request, even if no changes are made to a particular field.

This code sample demonstrates how you can update the registration of your Dialogflow agent:

curl 

  curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
  "https://discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "icon": {
        "uri": "ICON_URI"
      },
      "dialogflowAgentDefinition": {
        "dialogflowAgent": "projects/PROJECT_ID/locations/REASONING_ENGINE_LOCATION/agents/DIALOGFLOW_AGENT_ID"
      }
    }'

Replace the variables with values:

  • PROJECT_ID: the ID of your Google Cloud project.
  • AGENT_RESOURCE_NAME: the resource name of the agent registration to be updated.
  • DISPLAY_NAME:tThe display name of the agent.
  • DESCRIPTION: the description of the agent that's displayed in Gemini Enterprise. The description is only for the user's benefit.
  • ICON_URI: the public URI of an icon that displays next to your Dialogflow agent's name. You can also provide a Base64-encoded image in icon.content.
  • REASONING_ENGINE_LOCATION: the cloud location of the reasoning engine that you're creating an agent at.
  • DIALOGFLOW_AGENT_ID: the unique identifier of your Dialogflow agent.

Delete a Dialogflow agent

The following code sample demonstrates how you can delete an agent that is connected to your app:

curl 

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Replace the variables with values:

  • ENDPOINT_LOCATION-: the multi-region for your API request. Assign one of the following values:
    • us- for the US multi-region
    • eu- for the EU multi-region
    • global- for the Global location
    For more information, see Specify a multi-region for your data store.
  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the multi-region of your app: global, us, or eu
  • APP_ID: the ID of your Gemini Enterprise app.
  • AGENT_ID: the ID of the agent. You can find the agent ID by listing the agents connected to your app.