Enable Model Armor in Google Agentspace

This document describes how to enable Model Armor for Google Agentspace. Model Armor is a Google Cloud service that enhances the security and safety of your AI applications by proactively screening the prompts and responses given by the Google Agentspace assistant. This helps protect against various risks and ensures responsible AI practices.

Model Armor's response to potential issues in user queries or responses from the Google Agentspace assistant is governed by the template's enforcement type. For more information, see Define the enforcement type.

• If the enforcement type is Inspect and block, Google Agentspace blocks the request and displays an error message. This is the default enforcement type when you create a Model Armor template using the console.

• If the enforcement type is Inspect only, Google Agentspace does not block the requests or responses.

When the Model Armor screening service is unavailable, you can configure Google Agentspace to behave in one of the following ways:

Mode	Description
Allow user interactions	In this mode, Google Agentspace allows requests and responses to pass through without proactive screening when the Model Armor screening service is unavailable, ensuring continuous communication with the end-user. However, this can occasionally expose unscreened messages or provide answers to unscreened queries.
Block all user interactions	In this mode, when the Model Armor screening service is unavailable, Google Agentspace blocks all requests and responses, including legitimate ones.

Before you begin

• Make sure you have the required roles assigned to you and the Google Agentspace service account:

  • To enable Model Armor in Google Agentspace, you need the Discovery Engine Admin (roles/discoveryengine.admin) role.

  • To create the Model Armor templates, you need the Model Armor Admin role (roles/modelarmor.admin).

  • To call the Model Armor APIs, you need the Model Armor User role (roles/modelarmor.user).

  Note: To grant multiple IAM roles to a service account, see Grant or revoke multiple IAM roles using the Google Cloud console.

• Ensure you have created an Google Agentspace app. To create one, see Create an app.

Create a Model Armor template

You can create and use the same Model Armor template for user prompts and responses from the assistant, or you can create two separate Model Armor templates. For more information, see Create a Model Armor template.

When creating a Model Armor template for Google Agentspace apps, consider these configurations:

• Select Multi-region in the Regions field. The following table shows you how to map Model Armor template regions to Google Agentspace app regions:

  Note: After a Model Armor template and an Google Agentspace app is created, the regions can't be changed.

  Google Agentspace app multi-region	Model Armor multi-region
  Global	US (multiple regions in United States) EU (multiple regions in the Europe Union)
  US (multiple regions in United States)	US (multiple regions in United States)
  EU (multiple regions in the Europe Union)	EU (multiple regions in the Europe Union)

• Google does not recommend configuring cloud logging in the Model Armor template for Google Agentspace apps. This configuration can expose sensitive data to users with the Private Logs Viewer (roles/logging.privateLogViewer) IAM role. Instead, consider the following options:

  • If you need to log the data that goes through the Model Armor template, you can reroute logs to a secure storage like BigQuery, which offers stricter access controls. For more information, see Route logs to supported destinations.

  • You can configure Data Access audit logs to analyze and report on the request and response screening verdicts generated by Model Armor. For more information, see Configure audit logs.

Configure the Google Agentspace app with the Model Armor templates

The following steps describe how to add the Model Armor templates to your Google Agentspace app.

Console

1. In the Google Cloud console, go to the Agentspace page.

   Agentspace

2. Click the name of the app that you want to configure.

3. Click Configurations > Assistant.

4. To turn on Model Armor, click Enable Model Armor.

5. For Model Armor template for user prompts and Model Armor templates for response outputs, enter the Resource name of the Model Armor templates you created.

   Note: To get the Resource name, follow the steps in the View a Model Armor template documentation, and copy the Resource name value.

6. If you want to block user interactions during Model Armor processing failures, click the Allow user interactions during Model Armor processing failure toggle to the off position. For more information, see the two modes supported by Google Agentspace when Model Armor is unavailable.

7. Click Save and publish.

REST

To add the Model Armor templates to your Google Agentspace app, run the following command :

Key Term: In Agentspace, the term app can be used interchangeably with the term engine in the context of APIs. An Agentspace engine is a generic search engine where the app_type field is set to APP_TYPE_INTRANET.

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant?update_mask=customerPolicy" \
-d '{
  "customerPolicy": {
    "modelArmorConfig": {
      "userPromptTemplate": "QUERY_PROMPT_TEMPLATE",
      "responseTemplate": "RESPONSE_PROMPT_TEMPLATE",
      "failureMode": "FAIL_MODE"
    }
  }
}'

Replace the following:

• PROJECT_ID: the ID of your project.
• 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.
• LOCATION: the multi-region of your data store: global, us or eu
• APP_ID: the ID of the app that you want to configure.
• QUERY_PROMPT_TEMPLATE: the Resource name of the Model Armor templates you created.
  To get the Resource name, follow the steps in the View a Model Armor templatedocumentation, and copy the Resource name value.
• RESPONSE_PROMPT_TEMPLATE: the Resource name of the Model Armor templates you created.
• FAIL_MODE: the operation mode when Model Armor is not available: FAIL_CLOSED or FAIL_OPEN.
  If the FAIL_MODE is not defined, FAIL_CLOSE is the default mode where all the interactions with the Google Agentspace assistant is blocked when there are Model Armor processing failures. For more information, see the two modes supported by Google Agentspace when Model Armor is unavailable

Example command and result

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: my-project-123" \
"https://us-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/us/collections/default_collection/engines/my-app/assistants/default_assistant?update_mask=customer_policy" \
-d '{
  "customer_policy": {
    "modelArmorConfig": {
      "user_prompt_template": "projects/my-project-123/locations/us/templates/123456789",
      "response_template": "projects/my-project-123/locations/us/templates/123456789",
      "failure_mode": "FAIL_OPEN"
    }
  }
}'

{
  "name": "projects/my-project-123/locations/us/collections/default_collection/engines/my-app/assistants/default_assistant",
  "displayName": "Default Assistant",
  "webGroundingType": "WEB_GROUNDING_TYPE_GOOGLE_SEARCH",
  "googleSearchGroundingEnabled": true,
  "customerPolicy": {
    "modelArmorConfig": {
      "userPromptTemplate": "projects/my-project-123/locations/us/templates/123456789",
      "responseTemplate": "projects/my-project-123/locations/us/templates/123456789",
      "failureMode": "FAIL_OPEN"
    }
  }
}

Test if the Model Armor template is enabled

After configuring the Model Armor template, test if your Google Agentspace app proactively screens and blocks user prompts and responses from the Google Agentspace assistant, according to the confidence levels set in the Model Armor filters.

When the Model Armor template is configured to Inspect and block requests that violate the policy, the following policy violation message is shown:

Console

For example, you see the policy violation message:

Model Armor policy violation message

REST

A JSON response which includes the following:

answer.state = SKIPPED
answer.assist_skipped_reasons: [CUSTOMER_POLICY_VIOLATION]

Remove the Model Armor templates from an Agentspace app

To remove the Model Armor templates from an Agentspace app, use the Google Cloud console or the REST API.

Console

To remove the Model Armor templates from your Agentspace app, follow these steps:

1. In the Google Cloud console, go to the Agentspace page.

   Agentspace

2. Click the name of the app that you want to configure.

3. Click Configurations > Assistant.

4. To turn off Model Armor, click the Enable Model Armor toggle to the off position.

5. Click Save and publish.

REST

To remove the Model Armor templates from your Agentspace app, run the following command:

Key Term: In Agentspace, the term app can be used interchangeably with the term engine in the context of APIs. An Agentspace engine is a generic search engine where the app_type field is set to APP_TYPE_INTRANET.

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant?update_mask=customerPolicy" \
-d '{
  "customerPolicy": {
    "modelArmorConfig": {
    }
  }
}'

Replace the following:

• PROJECT_ID: the ID of your project.
• PROJECT_NUMBER: the number of your Google Cloud project.
• 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.
• LOCATION: the multi-region of your data store: global, us, or eu.
• APP_ID: the ID of the app that you want to configure.

Example command and result

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: my-project-123" \
"https://discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant?update_mask=customerPolicy" \
-d '{
  "customerPolicy": {
    "modelArmorConfig": {
    }
  }
}'

{
  "name": "projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant",
  "displayName": "Default Assistant",
  "webGroundingType": "WEB_GROUNDING_TYPE_GOOGLE_SEARCH",
  "googleSearchGroundingEnabled": true,
  "customerPolicy": {
    "modelArmorConfig": {}
  },
  "generationConfig": {
    "systemInstruction": {}
  }
}

Configure audit logs

Model Armor can write Data Access audit logs, which you can use to analyze and report on the request and response screening verdicts generated by Model Armor. These logs don't contain the user queries or responses from the Google Agentspace assistant, so they are safe for reporting and analytics. For more information, see Audit logging for Model Armor.

To access these logs, you need to have the Private Logs Viewer (roles/logging.privateLogViewer) IAM role.

Enable Data Access audit logs

To enable the Data Access audit logs, follow these steps:

1. In the Google Cloud console, go to IAM & Admin > Audit Logs.

2. Select the Model Armor API.

3. In the Permission type section, select the Data read permission type.

4. Click Save.

Examine Data Access audit logs

To examine the Data Access audit logs, follow these steps:

1. In the Google Cloud console, go to Logs Explorer.

2. Search the logs for the following method names:

   • methodName: "google.cloud.modelarmor.v1.ModelArmor.SanitizeUserPrompt" to view the user requests that were screened.

   • google.cloud.modelarmor.v1.ModelArmor.SanitizeModelResponse to view the responses that were screened.

Considerations when using Model Armor

When using Model Armor with Google Agentspace, consider the following:

Tokens	The token limits for Google Agentspace apps using Model Armor are determined by the specific filters configured in Model Armor. For detailed information on these limits, see the applicable token limits in the Model Armor documentation.
Service Level Agreement	Google Agentspace provides a Service Level Agreement. When Google Agentspace is configured to use Model Armor, blocked queries don't count as SLA violations, regardless of whether the fail-open or fail-closed mode is used.
Compliance	Both Google Agentspace and Model Armor offer various compliance certifications. When used together, the effective compliance certifications are the common subset of both products. Google recommends reviewing the compliance certifications for both products to ensure that they meet your regulatory requirements.
Document screening	If a Model Armor template is configured to screen user requests, then the documents included in the request are screened. The screening happens when you add a document to the request. If a document violates the policies in the configured template, the document is discarded and isn't included in the request. For the list of supported document types, see Document screening.