Integrating AlloyDB for PostgreSQL with Gemini Enterprise Agent Platform
lets you run SQL queries that pass your database data directly to
Agent Platform models for embeddings
generation and online predictions.

These instructions are specific to using AlloyDB, and not
AlloyDB Omni. To instead integrate a local installation of
AlloyDB Omni using Agent Platform, see
[Install AlloyDB Omni with AlloyDB AI](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/install-with-alloydb-ai.md.txt).

For more information about using ML models with AlloyDB, see
[Build generative AI applications using AlloyDB AI](https://docs.cloud.google.com/alloydb/docs/ai.md.txt).

For more information about Agent Platform, see
[Agent Platform overview](https://docs.cloud.google.com/gemini-enterprise-agent-platform/overview.md.txt).

## Before you begin

<br />

## About the AlloyDB service agent

When you use AlloyDB with other Google Cloud services, AlloyDB uses an Identity and Access Management (IAM) service agent to authenticate to those services. This service agent is an IAM principal that AlloyDB controls. You grant IAM roles to this service agent to let it access other Google Cloud services on your behalf.

## Grant the `Vertex AI User` role to the AlloyDB service agent

To enable database integration with Agent Platform, you grant the AlloyDB service agent the `Vertex AI User` role. This lets the AlloyDB service agent access Agent Platform on your behalf.

> [!NOTE]
> **Note:** To grant IAM roles, you must have the `resourcemanager.projects.setiamPolicy` permission. The Owner and Project IAM Admin roles include this permission. The AlloyDB Admin role also includes the permissions required to grant the Vertex AI User role to the service agent. If you don't have the necessary permissions, contact your organization's administrator.

Follow these steps to grant the AlloyDB service agent the `Vertex AI User` role:

Add Agent Platform permissions to the AlloyDB service
agent for the project where the AlloyDB database's cluster is
located:

### Console

1. Go to the **Welcome** page in the Google Cloud console, and copy the project number of the project that has AlloyDB clusters or instances. You will use this project number in the next steps.

   [Go to Welcome](https://console.cloud.google.com/welcome)

   <br />

2. In the Google Cloud console, go to the **IAM** page.

   [Go to IAM](https://console.cloud.google.com/projectselector2/iam-admin/iam)

   <br />

3. Select the project that needs to call Agent Platform endpoints.

4. Enable **Include Google-provided role grants**.

5. Click **Grant Access**.

6. In the **New principals** field, enter the following:

   <br />

   ```
       service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
       
   ```

   <br />

   Replace `PROJECT_NUMBER` with the project number.
7. In the **Role** field, enter **Vertex AI User**.

8. Click **Save**.

### gcloud


To use the gcloud CLI, you can
[install and initialize](https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt) the Google Cloud CLI, or you
can use [Cloud Shell](https://docs.cloud.google.com/shell/docs/using-cloud-shell.md.txt).

<br />

<br />

```
        gcloud projects add-iam-policy-binding PROJECT_ID 

        --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com" 

        --role="roles/aiplatform.user"
  
```

<br />

Replace the following:

- `PROJECT_ID`: the ID of the project that has the Agent Platform endpoint.
- `PROJECT_NUMBER`: the project number of the project that has AlloyDB clusters or instances.

> [!NOTE]
> **Note:** The policy change takes effect within 60 seconds to 7 minutes.

## Verify installed extension

Verify if the `google_ml_integration` is installed in the database
that contains the data that you want to run predictions on:

### Console

1. In the Google Cloud console, go to the **Clusters** page.

   [Go to Clusters](https://console.cloud.google.com/alloydb/clusters)
2. To display the cluster **Overview** page, click the name of the AlloyDB cluster in the **Resource name** column.

3. In the navigation menu, click **AlloyDB Studio**.

4. On the **Sign in to AlloyDB Studio** page, authenticate using the name of your database, username, and password.

   > [!NOTE]
   > **Note:** AlloyDB Studio connects to the primary instance of your cluster, which is where extension management and initial predictions are handled, even if you intend to invoke predictions from read pool instances later.

5. In the **Editor 1** tab, complete the following:

   1. Verify the `google_ml_integration` extension version 1.4.2 or later is installed:

      ```sql
      SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
      ```
   2. Click **Run** . Wait for the extension version to display in the **Results** pane.

### psql

1. Connect a `psql` client to the cluster's primary instance, as
   described in [Connect a `psql` client to an instance](https://docs.cloud.google.com/alloydb/docs/connect-psql.md.txt).

   > [!NOTE]
   > **Note:** You must connect to the primary instance even if you intend to invoke predictions while connected to a read pool instance.

2. At the `psql` command prompt, connect to the database:

   ```sql
   \c DB_NAME
   ```

   Replace `DB_NAME` with the name of the database on which you want
   to install the extension.

   <br />

3. Verify the `google_ml_integration` extension version 1.4.2 or later is installed:

   ```sql
   SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
   ```

   <br />

## What's next

- [Work with embeddings](https://docs.cloud.google.com/alloydb/docs/ai/work-with-embeddings.md.txt)

- [Invoke predictions](https://docs.cloud.google.com/alloydb/docs/ai/invoke-predictions.md.txt)

- [Agent Platform quotas and limits](https://docs.cloud.google.com/gemini-enterprise-agent-platform/machine-learning/quotas.md.txt)

- [Call remote model endpoints](https://docs.cloud.google.com/alloydb/docs/ai/model-endpoint-overview.md.txt)