Create assistants

This section describes how to create assistants.

You can add a generative AI assistant to your app that's grounded with your enterprise data sources and uses the safeguards of the security, privacy, and compliance requirements of the enterprise.

When you enter queries into your search app, you can get answers from the assistant and ask follow-up questions.

Assistant features

Assistants offer the following features:

Generate answers to queries and answer follow-up questions
Ground answers in your enterprise data with citations
Provide optional grounding and citations based on external public website data
Analyze and summarize content such as PDFs and images that you upload, and answer follow-up questions about it
Generate images based on text prompts
Create reports with streamed research during the creation process

Compliance and security controls for assistant

The following regions are supported:

Global
EU
US

The following security controls are supported:

Data residency
Access transparency

Before you begin

To use an assistant, do the following:

Enable the following APIs:
- Discovery Engine API: Enable in the console
- Vertex AI API: Enable in the console
Assign users the following roles:
- Discovery Engine User
- A custom role with aiplatform.endpoints.predict permission

Create and manage assistants

You can create an assistant in the following ways:

Create a new app with an assistant
Create an assistant for an existing app

You can manage your assistant in the following ways:

View your assistant
Update an assistant display name
Delete an assistant

Create a new app with an assistant

To create a new search app with an assistant, do the following:

Run the following curl command:

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?engineId=APP_ID" \
  -d '{
    "name": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/"APP_ID",
    "displayName": "APP_DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "searchEngineConfig": {
      "required_subscription_tier": "SUBSCRIPTION_TIER_SEARCH_AND_ASSISTANT",
      "searchTier": "SEARCH_TIER_ENTERPRISE",
      "searchAddOns": ["SEARCH_ADD_ON_LLM"]
    },
    "commonConfig": {
      "companyName": "COMPANY_NAME"
    },
    "industryVertical": "GENERIC",
    "dataStoreIds": ["DATA_STORE_ID_1", "DATA_STORE_ID_2"]
  }'

Replace the following:

PROJECT_ID: the ID of your Google Cloud project.
APP_ID: the ID of the app that you want to create.
APP_DISPLAY_NAME: the display name of the app that you want to create.
DATA_STORE_ID_1, DATA_STORE_ID_2: the IDs of the data stores to attach to your app.
COMPANY_NAME: the name of your company.

Example command and response:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: 1234" \
"https://discoveryengine.googleapis.com/v1alpha/projects/1234/locations/global/collections/default_collection/engines?engineId=myapp" \
-d '{
  "name": "projects/1234/locations/global/collections/default_collection/engines/myapp",
  "displayName": "myapp",
  "solutionType": "SOLUTION_TYPE_SEARCH",
  "searchEngineConfig": {
    "required_subscription_tier": "SUBSCRIPTION_TIER_SEARCH_AND_ASSISTANT",
    "searchTier": "SEARCH_TIER_ENTERPRISE",
    "searchAddOns": ["SEARCH_ADD_ON_LLM"]
  },
  "commonConfig": {
    "companyName": "My Company"
  },
  "industryVertical": "GENERIC",
  "dataStoreIds": ["mydatastore1", "mydatastore2"]
}'
------------------
{
  "name": "projects/1234/locations/global/collections/default_collection/operations/create-engine-877224357326871179",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.Engine",
    "name": "projects/1234/locations/global/collections/default_collection/engines/myapp",
    "displayName": "myapp",
    "dataStoreIds": [
      "mydatastore1",
      "mydatastore2"
    ],
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "searchEngineConfig": {
      "searchTier": "SEARCH_TIER_ENTERPRISE",
      "searchAddOns": [
        "SEARCH_ADD_ON_LLM"
      ]
    },
    "commonConfig": {
      "companyName": "My Company"
    },
    "industryVertical": "GENERIC"
  }
}

Create an assistant for an existing app

If you already have an app with the Agentspace Enterprise Plus subscription tier enabled, then you can create an assistant for it using the following procedure.

To create an assistant for an existing app, do the following:

Run the following curl command:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID"/assistants?assistantId=ASSISTANT_ID" \
  -d '{
        "displayName": ASSISTANT_DISPLAY_NAME"
      }'

Replace the following:

PROJECT_ID: the ID of your Google Cloud project.
APP_ID: the ID of the app to attach your assistant to.
ASSISTANT_ID: the ID of the assistant that you want to create.
ASSISTANT_DISPLAY_NAME: the display name of the assistant that you want to create.

Example command and response:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"
  -H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1alpha/projects/1234/locations/global/collections/default_collection/engines/myapp/assistants?assistantId=default_assistant2" \
  -d '{
        "displayName": "Default Assistant2"
      }'
-
{
  "name": "projects/1234/locations/global/collections/default_collection/engines/myapp/assistants/default_assistant2",
  "displayName": "Default Assistant2"
}

View your assistant

To view your assistant after you've created it, do the following:

Run the following curl command:

curl -X GET   -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/ASSISTANT_ID"

Replace the following:

PROJECT_ID: the ID of your Google Cloud project.
APP_ID: the ID of the app.
ASSISTANT_ID: the ID of the assistant.

Example command and response:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: 1234" \
"https://discoveryengine.googleapis.com/v1alpha/projects/1234/locations/global/collections/default_collection/engines/myapp/assistants/default_assistant"
---------------------------
{
  "name": "projects/1234/locations/global/collections/default_collection/engines/myapp/assistants/default_assistant",
  "displayName": "Default Assistant",
}

Update an assistant display name

To update the display name for an existing assistant, do the following:

Run the following curl command:

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/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID"/assistants/ASSISTANT_ID" \
-d '{
      "displayName": ASSISTANT_DISPLAY_NAME"
    }'

Replace the following:

PROJECT_ID: the ID of your Google Cloud project.
APP_ID: the ID of the app to attach your assistant to.
ASSISTANT_ID: the ID of the assistant whose name you want to update.
ASSISTANT_DISPLAY_NAME: the new display name of the assistant.

Example command and response:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1alpha/projects/1234/locations/global/collections/default_collection/engines/myapp/assistants?assistantId=default_assistant2" \
  -d '{
    "displayName": "Default Assistant2"
  }'
------------------
{
  "name": "projects/1234/locations/global/collections/default_collection/engines/myapp/assistants/default_assistant2",
  "displayName": "Default Assistant2"
}

Delete an assistant

To delete your assistant, do the following:

Run the following curl command:

curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID"/assistants/ASSISTANT_ID"

Replace the following:

PROJECT_ID: the ID of your Google Cloud project.
APP_ID: the ID of the app.
ASSISTANT_ID: the ID of the assistant.

Example command and response:

curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json"
"https://discoveryengine.googleapis.com/v1alpha/projects/1234/locations/global/collections/default_collection/engines/myapp/assistants/default_assistant2"
-
{}