> [!CAUTION]
> Vertex AI Extensions has been deprecated as of May 26, 2026.
> After November 26, 2026, Vertex AI Extensions will be shut down and
> no longer function. For equivalent functionality, see the
> [Extensions migration guide](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/extensions/migrate.md.txt).

<br />


> [!WARNING]
> **Preview**
>
> Vertex AI Extensions is a Preview offering, subject to the
> "Pre-GA Offerings Terms" of the
> [Google Cloud Service Specific Terms](https://cloud.google.com/terms/service-terms). Pre-GA products and features
> may have limited support, and changes to pre-GA products and features may not be compatible with
> other pre-GA versions. For more information, see the
> [launch stage descriptions](https://cloud.google.com/products#product-launch-stages). Further, by using
> Vertex AI Extensions, you agree to the Generative AI Preview
> [terms and conditions](https://cloud.google.com/trustedtester/aitos) ("Preview Terms").

<br />

This document shows you how to register and use the Google-provided
Agent Search [extension](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/extensions/overview.md.txt)
from the Google Cloud console and the Vertex AI API. This extension
lets you access and search website corpuses and unstructured data to provide
relevant responses to natural language questions, such as:

- "How did the competitive threats for the company change from Q1 of last year to Q1 of this year?"
- "What parts of the company are growing the fastest? How fast?"

The Agent Search extension uses
[Agent Search](https://docs.cloud.google.com/generative-ai-app-builder/docs/introduction#es-and-personalize)
to retrieve meaningful results from your data store. The
Agent Search extension is defined in an
[OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/README.md)
`vertex_ai_search.yaml` file.

To use the Agent Search extension, you must
[Create a data store](https://docs.cloud.google.com/generative-ai-app-builder/docs/prepare-data.md.txt) in the global
region with a specified search scope. For best search results,
enable advanced indexing for website data and the Enterprise edition for
unstructured data. See
[About advanced features](https://docs.cloud.google.com/generative-ai-app-builder/docs/about-advanced-features.md.txt)
for more information.
<button type="button" class="button-red button expand-control"> Expand Me Collapse Me </button>

```yaml
openapi: "3.0.0"
info:
  title: Vertex AI Search
  version: v1alpha
  description: >
    Performs search on user ingested data including website and unstructured data type.

    This extension is used when user wants to search or retrieve meaningful results from their ingested data in the Vertex AI Search service.

    Supported AuthTypes:
    - GOOGLE_SERVICE_ACCOUNT_AUTH: (only supports using Vertex AI Extension Service Agent).
paths:
  /search:
    get:
      operationId: search
      description: Retrieves the results from user's query by searching in the data store.
      parameters:
      - name: query
        in: query
        schema:
          type: string
        description: User natural language instructions for search.
        required: true
      responses:
        default:
          description: Search execution result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResult"

components:
  schemas:
    SearchResult:
      description: Top results from search response.
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
                description: Retrieved document title.
              display_link:
                type: string
                description: Retrieved document link to display.
              link:
                type: string
                description: Retrieved document link.
              extractive_segments:
                type: array
                description: Extractive segments from the retrieved file.
                items:
                  type: string
              extractive_answers:
                type: array
                description: Extractive answers from the retrieved file. These are generated from the extractive segments.
                items:
                  type: string

    
```

To learn about Google extensions with end-to-end tutorials, see the following
Jupyter notebooks:

- **Business analyst workflow with Vertex AI Extensions** : Use the [Code Interpreter extension](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/extensions/code-interpreter.md.txt) and the Agent Search extension to complete a housing investment opportunities research report for business stakeholders.  
  [Colab](https://art-analytics.appspot.com/r.html?uaid=G-FHXEFWTT4E&utm_source=aRT-ba_extbygoog_notebook-cloud_docs-colab&utm_medium=aRT-clicks&utm_campaign=ba_extbygoog_notebook-cloud_docs-colab&destination=ba_extbygoog_notebook-cloud_docs-colab&url=https://colab.research.google.com/github/GoogleCloudPlatform/applied-ai-engineering-samples/blob/main/genai-on-vertex-ai/vertex_ai_extensions/notebooks/business_analyst_workflow_vertexai_extensions.ipynb) \| [GitHub](https://art-analytics.appspot.com/r.html?uaid=G-FHXEFWTT4E&utm_source=aRT-ba_extbygoog_notebook-cloud_docs-github&utm_medium=aRT-clicks&utm_campaign=ba_extbygoog_notebook-cloud_docs-github&destination=ba_extbygoog_notebook-cloud_docs-github&url=https://github.com/GoogleCloudPlatform/applied-ai-engineering-samples/blob/main/genai-on-vertex-ai/vertex_ai_extensions/notebooks/business_analyst_workflow_vertexai_extensions.ipynb) \| [Vertex AI Workbench](https://art-analytics.appspot.com/r.html?uaid=G-FHXEFWTT4E&utm_source=aRT-ba_extbygoog_notebook-cloud_docs-vai_workbench&utm_medium=aRT-clicks&utm_campaign=ba_extbygoog_notebook-cloud_docs-vai_workbench&destination=ba_extbygoog_notebook-cloud_docs-vai_workbench&url=https://console.cloud.google.com/vertex-ai/workbench/deploy-notebook?download_url%3Dhttps://raw.githubusercontent.com/GoogleCloudPlatform/applied-ai-engineering-samples/main/genai-on-vertex-ai/vertex_ai_extensions/notebooks/business_analyst_workflow_vertexai_extensions.ipynb)
- **Game review analysis workflow with Vertex AI Extensions** : Use the [Code Interpreter extension](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/extensions/code-interpreter.md.txt) to analyze game reviews from [Steam](https://store.steampowered.com/). Use the Agent Search extension to summarize game reviews from websites. Use the Code Interpreter extension to build a report with all of the generated assets.  
  [Colab](https://art-analytics.appspot.com/r.html?uaid=G-FHXEFWTT4E&utm_source=aRT-gamerev_extbygoog_notebook-cloud_docs-colab&utm_medium=aRT-clicks&utm_campaign=gamerev_extbygoog_notebook-cloud_docs-colab&destination=gamerev_extbygoog_notebook-cloud_docs-colab&url=https://colab.research.google.com/github/GoogleCloudPlatform/applied-ai-engineering-samples/blob/main/genai-on-vertex-ai/vertex_ai_extensions/notebooks/game_review_analysis_vertexai_extensions.ipynb) \| [GitHub](https://art-analytics.appspot.com/r.html?uaid=G-FHXEFWTT4E&utm_source=aRT-gamerev_extbygoog_notebook-cloud_docs-github&utm_medium=aRT-clicks&utm_campaign=gamerev_extbygoog_notebook-cloud_docs-github&destination=gamerev_extbygoog_notebook-cloud_docs-github&url=https://github.com/GoogleCloudPlatform/applied-ai-engineering-samples/blob/main/genai-on-vertex-ai/vertex_ai_extensions/notebooks/game_review_analysis_vertexai_extensions.ipynb) \| [Vertex AI Workbench](https://art-analytics.appspot.com/r.html?uaid=G-FHXEFWTT4E&utm_source=aRT-gamerev_extbygoog_notebook-cloud_docs-vai_workbench&utm_medium=aRT-clicks&utm_campaign=gamerev_extbygoog_notebook-cloud_docs-vai_workbench&destination=gamerev_extbygoog_notebook-cloud_docs-vai_workbench&url=https://console.cloud.google.com/vertex-ai/workbench/deploy-notebook?download_url%3Dhttps://raw.githubusercontent.com/GoogleCloudPlatform/applied-ai-engineering-samples/blob/main/genai-on-vertex-ai/vertex_ai_extensions/notebooks/game_review_analysis_vertexai_extensions.ipynb)

## Before you begin

<br />

## Register and run the Agent Search extension

The following sections show you how to register the
Agent Search extension using the Google Cloud console
and the Vertex AI API. After registering the extension, you can
run it using the Vertex AI API.

### Console

**Register the extension**

Perform the following steps to register the Agent Search
extension using the Google Cloud console.

1. In the Google Cloud console, go to the Vertex AI
   **Extensions** page.


   [Go to Vertex AI Extensions](https://console.cloud.google.com/vertex-ai/extensions)

   <br />

2. Click **Create Extension**.

3. In the **Create a new extension** dialog, fill in the following fields:

   - **Extension name:** Enter a name for your extension, such as "vertex_search_extension".
   - **Description:** (Optional) Enter an extension description, such as "A Vertex AI search extension".
   - **Extension type:** Select `Vertex AI search`.
4. In the **OpenAPI Spec file** section that now appears, confirm that the
   following fields are set correctly:

   - **API name:** `vertex_ai_search`.
   - **API description:** `Performs search on user ingested data including website and unstructured data type...`
   - **Source:** `Cloud Storage`.
   - **OpenAPI Spec:** `vertex-extension-public/vertex_ai_search.yaml`.
   - **Authentication:** `Google service account`.
5. In the **Runtime configurations** section, provide a serving configuration
   name. The serving configuration name is specified in the
   [vertexAiSearchRuntimeConfig](https://docs.cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations.extensions#vertexaisearchruntimeconfig).
   It is formatted and completed as follows:
   `projects/PROJECT_ID/locations/global/collections/COLLECTION_NAME/engines/ENGINE/servingConfigs/SERVING_CONFIG`

   - Set <var translate="no">COLLECTION_NAME</var> to `default_collection`.
   - Set <var translate="no">ENGINE</var> to the application ID you received when you created your search application. To learn more, see [Create a search app for website data](https://docs.cloud.google.com/generative-ai-app-builder/docs/try-enterprise-search.md.txt#create_a_search_app_for_website_data).
   - Set <var translate="no">SERVING_CONFIG</var> to `default_search`.
6. Click **Create Extension**.

### REST

**Register the extension**

Submit an Vertex AI API
[`extensions.import`](https://docs.cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations.extensions/import)
request to register the Agent Search extension.


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

- <var translate="no">PROJECT_ID</var>: The ID of your Google Cloud project.
- <var translate="no">REGION</var>: A [Compute Engine region](https://docs.cloud.google.com/compute/docs/regions-zones.md.txt#available).
- <var translate="no">DISPLAY_NAME</var>: The [name](https://docs.cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations.extensions#Extension.FIELDS.display_name) extension that is displayed to users, such as "my_search_extension".
- <var translate="no">DESCRIPTION</var>: (Optional) The extension [description](https://docs.cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations.extensions#Extension.FIELDS.description) that is displayed to users, such as "A search extension".
- <var translate="no">SERVICE_ACCOUNT</var>: (Optional) The Vertex AI Search extension uses [GOOGLE_SERVICE_ACCOUNT_AUTH](https://docs.cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations.extensions#AuthConfig.FIELDS.google_service_account_config) as shown in the sample request body. If you do not specify a service account, the extension uses the default [Vertex AI Extension Service Agent](https://docs.cloud.google.com/vertex-ai/docs/general/access-control#service-agents) service account. If you specify a different service account, grant the [`iam.serviceAccounts.getAccessToken`](https://docs.cloud.google.com/iam/docs/roles-permissions/iam.md.txt#iam.serviceAccounts.getAccessToken) permission to the Vertex AI Extension Service Agent service account on the specified service account.
- <var translate="no">SERVING_CONFIG_NAME</var>: The serving configuration name is specified in the [vertexAiSearchRuntimeConfig](https://docs.cloud.google.com/vertex-ai/docs/reference/rest/v1beta1/projects.locations.extensions#vertexaisearchruntimeconfig). It is formatted and completed as follows: `
  projects/PROJECT_ID/locations/global/collections/COLLECTION_NAME/engines/ENGINE/servingConfigs/SERVING_CONFIG`.
  - <var translate="no">PROJECT_ID</var>: The ID of your Google Cloud project.
  - Set <var translate="no">COLLECTION_NAME</var> to `default_collection`.
  - <var translate="no">ENGINE</var>: The application ID you received when you created your search application. To learn more, see [Create a search app for website data](https://docs.cloud.google.com/generative-ai-app-builder/docs/try-enterprise-search.md.txt#create_a_search_app_for_website_data).
  - Set <var translate="no">SERVING_CONFIG</var> to `default_search`.


HTTP method and URL:

```
POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import
```


Request JSON body:

```
{
  "displayName":"DISPLAY_NAME",
  "description":"DESCRIPTION",
  "manifest":{
    "name":"vertex_ai_search_tool",
    "description":"A Vertex AI Search tool",
    "apiSpec":{
      "openApiGcsUri":"gs://vertex-extension-public/vertex_ai_search.yaml"
    },
    "authConfig":{
      "authType":"GOOGLE_SERVICE_ACCOUNT_AUTH",
      "googleServiceAccountConfig":{
        "serviceAccount":"SERVICE_ACCOUNT"
      }
    }
  }
  "runtimeConfig": {
     "vertexAiSearchRuntimeConfig": {
        "servingConfigName": "SERVING_CONFIG_NAME",
     }
  }
}

```

To send your request, choose one of these options:

#### curl

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) , or by using [Cloud Shell](https://docs.cloud.google.com/shell/docs.md.txt), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


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 "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import"
```

#### PowerShell

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import" | Select-Object -Expand Content
```

**Run the extension**

You can submit an `execute` operation to the Vertex AI API
to obtain meaningful results from your data store.

### Document search


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

- <var translate="no">PROJECT_ID</var>: The ID of your Google Cloud project.
- <var translate="no">REGION</var>: A [Compute Engine region](https://docs.cloud.google.com/compute/docs/regions-zones.md.txt#available).
- <var translate="no">EXTENSION_ID</var>: The ID of your Vertex AI Search extension listed in the **Extension details** in the Google Cloud console.


HTTP method and URL:

```
POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute
```


Request JSON body:

```
{
  "operation_id":"search",
  "operation_params":{
    "query":"Housing affordability since 2010",
  }
}

```

To send your request, choose one of these options:

#### curl

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) , or by using [Cloud Shell](https://docs.cloud.google.com/shell/docs.md.txt), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


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 "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute"
```

#### PowerShell

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute" | Select-Object -Expand Content
```

<br />