REST Resource: projects.locations.apps

Resource: App

An app serves as a top-level container for a group of agents, including the root agent and its sub-agents, along with their associated configurations. These agents work together to achieve specific goals within the app's context.

JSON representation 
{
  "name": string,
  "displayName": string,
  "description": string,
  "pinned": boolean,
  "rootAgent": string,
  "languageSettings": {
    object (LanguageSettings)
  },
  "timeZoneSettings": {
    object (TimeZoneSettings)
  },
  "audioProcessingConfig": {
    object (AudioProcessingConfig)
  },
  "loggingSettings": {
    object (LoggingSettings)
  },
  "modelSettings": {
    object (ModelSettings)
  },
  "toolExecutionMode": enum (App.ToolExecutionMode),
  "evaluationMetricsThresholds": {
    object (EvaluationMetricsThresholds)
  },
  "variableDeclarations": [
    {
      object (App.VariableDeclaration)
    }
  ],
  "predefinedVariableDeclarations": [
    {
      object (App.VariableDeclaration)
    }
  ],
  "globalInstruction": string,
  "guardrails": [
    string
  ],
  "dataStoreSettings": {
    object (DataStoreSettings)
  },
  "defaultChannelProfile": {
    object (ChannelProfile)
  },
  "metadata": {
    string: string,
    ...
  },
  "createTime": string,
  "updateTime": string,
  "etag": string,
  "deploymentCount": integer,
  "clientCertificateSettings": {
    object (ClientCertificateSettings)
  },
  "evaluationSettings": {
    object (EvaluationSettings)
  }
}
Fields
name

string

Identifier. The unique identifier of the app. Format: projects/{project}/locations/{location}/apps/{app}
displayName

string

Required. Display name of the app.
description

string

Optional. Human-readable description of the app.
pinned

boolean

Optional. Whether the app is pinned in the app list.
rootAgent

string

Optional. The root agent is the entry point of the app. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
languageSettings

object (LanguageSettings)

Optional. Language settings of the app.
timeZoneSettings

object (TimeZoneSettings)

Optional. TimeZone settings of the app.
audioProcessingConfig

object (AudioProcessingConfig)

Optional. Audio processing configuration of the app.
loggingSettings

object (LoggingSettings)

Optional. Logging settings of the app.
modelSettings

object (ModelSettings)

Optional. The default LLM model settings for the app. Individual resources (e.g. agents, guardrails) can override these configurations as needed.
toolExecutionMode

enum (App.ToolExecutionMode)

Optional. The tool execution mode for the app. If not provided, will default to PARALLEL.
evaluationMetricsThresholds

object (EvaluationMetricsThresholds)

Optional. The evaluation thresholds for the app.
variableDeclarations[]

object (App.VariableDeclaration)

Optional. The declarations of the variables.
predefinedVariableDeclarations[]

object (App.VariableDeclaration)

Output only. The declarations of predefined variables for the app.
globalInstruction

string

Optional. Instructions for all the agents in the app. You can use this instruction to set up a stable identity or personality across all the agents.
guardrails[]

string

Optional. List of guardrails for the app. Format: projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}
dataStoreSettings

object (DataStoreSettings)

Optional. The data store settings for the app.
defaultChannelProfile

object (ChannelProfile)

Optional. The default channel profile used by the app.
metadata

map (key: string, value: string)

Optional. Metadata about the app. This field can be used to store additional information relevant to the app's details or intended usages.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
createTime

string (Timestamp format)

Output only. Timestamp when the app was created.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Output only. Timestamp when the app was last updated.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
etag

string

Output only. Etag used to ensure the object hasn't changed during a read-modify-write operation. If the etag is empty, the update will overwrite any concurrent changes.
deploymentCount

integer

Output only. Number of deployments in the app.
clientCertificateSettings

object (ClientCertificateSettings)

Optional. The default client certificate settings for the app.
evaluationSettings

object (EvaluationSettings)

Optional. The evaluation settings for the app.

LanguageSettings

Language settings of the app.

JSON representation 
{
  "defaultLanguageCode": string,
  "supportedLanguageCodes": [
    string
  ],
  "enableMultilingualSupport": boolean,
  "fallbackAction": string
}
Fields
defaultLanguageCode

string

Optional. The default language code of the app.
supportedLanguageCodes[]

string

Optional. List of languages codes supported by the app, in addition to the defaultLanguageCode.
enableMultilingualSupport

boolean

Optional. Enables multilingual support. If true, agents in the app will use pre-built instructions to improve handling of multilingual input.
fallbackAction

string

Optional. The action to perform when an agent receives input in an unsupported language.

This can be a predefined action or a custom tool call. Valid values are: - A tool's full resource name, which triggers a specific tool execution. - A predefined system action, such as "escalate" or "exit", which triggers an EndSession signal with corresponding metadata to terminate the conversation.

TimeZoneSettings

TimeZone settings of the app.

JSON representation 
{
  "timeZone": string
}
Fields
timeZone

string

Optional. The time zone of the app from the time zone database, e.g., America/Los_Angeles, Europe/Paris.

AudioProcessingConfig

Configuration for how the input and output audio should be processed and delivered.

JSON representation 
{
  "synthesizeSpeechConfigs": {
    string: {
      object (SynthesizeSpeechConfig)
    },
    ...
  },
  "bargeInConfig": {
    object (BargeInConfig)
  },
  "inactivityTimeout": string,
  "ambientSoundConfig": {
    object (AmbientSoundConfig)
  }
}
Fields
synthesizeSpeechConfigs

map (key: string, value: object (SynthesizeSpeechConfig))

Optional. Configuration of how the agent response should be synthesized, mapping from the language code to SynthesizeSpeechConfig.

If the configuration for the specified language code is not found, the configuration for the root language code will be used. For example, if the map contains "en-us" and "en", and the specified language code is "en-gb", then "en" configuration will be used.

Note: Language code is case-insensitive.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
bargeInConfig

object (BargeInConfig)

Optional. Configures the agent behavior for the user barge-in activities.
inactivityTimeout

string (Duration format)

Optional. The duration of user inactivity (no speech or interaction) before the agent prompts the user for reengagement. If not set, the agent will not prompt the user for reengagement.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
ambientSoundConfig

object (AmbientSoundConfig)

Optional. Configuration for the ambient sound to be played with the synthesized agent response, to enhance the naturalness of the conversation.

SynthesizeSpeechConfig

Configuration for how the agent response should be synthesized.

JSON representation 
{
  "voice": string,
  "speakingRate": number
}
Fields
voice

string

Optional. The name of the voice. If not set, the service will choose a voice based on the other parameters such as languageCode.

For the list of available voices, please refer to Supported voices and languages from Cloud Text-to-Speech.
speakingRate

number

Optional. The speaking rate/speed in the range [0.25, 2.0]. 1.0 is the normal native speed supported by the specific voice. 2.0 is twice as fast, and 0.5 is half as fast. Values outside of the range [0.25, 2.0] will return an error.

BargeInConfig

Configuration for how the user barge-in activities should be handled.

JSON representation 
{
  "disableBargeIn": boolean,
  "bargeInAwareness": boolean
}
Fields
disableBargeIn
(deprecated)

boolean

Optional. Disables user barge-in while the agent is speaking. If true, user input during agent response playback will be ignored.

Deprecated. This field is deprecated in favor of disableBargeInControl in ChannelProfile.
bargeInAwareness

boolean

Optional. If enabled, the agent will adapt its next response based on the assumption that the user hasn't heard the full preceding agent message. This should not be used in scenarios where agent responses are displayed visually.

AmbientSoundConfig

Configuration for the ambient sound to be played with the synthesized agent response, to enhance the naturalness of the conversation.

JSON representation 
{
  "volumeGainDb": number,

  // Union field source can be only one of the following:
  "prebuiltAmbientNoise": enum (AmbientSoundConfig.PrebuiltAmbientNoise),
  "gcsUri": string,
  "prebuiltAmbientSound": string
  // End of list of possible types for union field source.
}
Fields
volumeGainDb

number

Optional. Volume gain (in dB) of the normal native volume supported by ambient noise, in the range [-96.0, 16.0]. If unset, or set to a value of 0.0 (dB), will play at normal native signal amplitude. A value of -6.0 (dB) will play at approximately half the amplitude of the normal native signal amplitude. A value of +6.0 (dB) will play at approximately twice the amplitude of the normal native signal amplitude. We strongly recommend not to exceed +10 (dB) as there's usually no effective increase in loudness for any value greater than that.
Union field source. Ambient noise to be played with the synthesized agent response, to enhance the naturalness of the conversation. source can be only one of the following:
prebuiltAmbientNoise
(deprecated)

enum (AmbientSoundConfig.PrebuiltAmbientNoise)

Optional. Prebuilt ambient noise.
gcsUri

string

Optional. Ambient noise as a mono-channel, 16kHz WAV file stored in Cloud Storage.

Note: Please make sure the CES service agent service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com has storage.objects.get permission to the Cloud Storage object.
prebuiltAmbientSound

string

Optional. Name of the prebuilt ambient sound. Valid values are: - "coffee_shop" - "keyboard" - "keypad" - "hum" - "office_1" - "office_2" - "office_3" - "room_1" - "room_2" - "room_3" - "room_4" - "room_5" - "air_conditioner"

AmbientSoundConfig.PrebuiltAmbientNoise

Prebuilt ambient noise.

Enums
PREBUILT_AMBIENT_NOISE_UNSPECIFIED Not specified.
RETAIL_STORE Ambient noise of a retail store.
CONVENTION_HALL Ambient noise of a convention hall.
OUTDOOR Ambient noise of a street.

LoggingSettings

Settings to describe the logging behaviors for the app.

JSON representation 
{
  "redactionConfig": {
    object (RedactionConfig)
  },
  "audioRecordingConfig": {
    object (AudioRecordingConfig)
  },
  "bigqueryExportSettings": {
    object (BigQueryExportSettings)
  },
  "cloudLoggingSettings": {
    object (CloudLoggingSettings)
  },
  "conversationLoggingSettings": {
    object (ConversationLoggingSettings)
  },
  "evaluationAudioRecordingConfig": {
    object (AudioRecordingConfig)
  }
}
Fields
redactionConfig

object (RedactionConfig)

Optional. Configuration for how sensitive data should be redacted.
audioRecordingConfig

object (AudioRecordingConfig)

Optional. Configuration for how audio interactions should be recorded.
bigqueryExportSettings

object (BigQueryExportSettings)

Optional. Settings to describe the BigQuery export behaviors for the app. The conversation data will be exported to BigQuery tables if it is enabled.
cloudLoggingSettings

object (CloudLoggingSettings)

Optional. Settings to describe the Cloud Logging behaviors for the app.
conversationLoggingSettings

object (ConversationLoggingSettings)

Optional. Settings to describe the conversation logging behaviors for the app.
evaluationAudioRecordingConfig

object (AudioRecordingConfig)

Optional. Configuration for how audio interactions should be recorded for the evaluation. By default, audio recording is not enabled for evaluation sessions.

RedactionConfig

Configuration to instruct how sensitive data should be handled.

JSON representation 
{
  "enableRedaction": boolean,
  "inspectTemplate": string,
  "deidentifyTemplate": string
}
Fields
enableRedaction

boolean

Optional. If true, redaction will be applied in various logging scenarios, including conversation history, Cloud Logging and audio recording.
inspectTemplate

string

Optional. DLP inspect template name to configure detection of sensitive data types.

Format: projects/{project}/locations/{location}/inspectTemplates/{inspectTemplate}
deidentifyTemplate

string

Optional. DLP deidentify template name to instruct on how to de-identify content.

Format: projects/{project}/locations/{location}/deidentifyTemplates/{deidentifyTemplate}

AudioRecordingConfig

Configuration for how the audio interactions should be recorded.

JSON representation 
{
  "gcsBucket": string,
  "gcsPathPrefix": string
}
Fields
gcsBucket

string

Optional. The Cloud Storage bucket to store the session audio recordings. The URI must start with "gs://".

Please choose a bucket location that meets your data residency requirements.

Note: If the Cloud Storage bucket is in a different project from the app, you should grant storage.objects.create permission to the CES service agent service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com.
gcsPathPrefix

string

Optional. The Cloud Storage path prefix for audio recordings.

This prefix can include the following placeholders, which will be dynamically substituted at serving time: - $project: project ID - $location: app location - $app: app ID - $date: session date in YYYY-MM-DD format - $session: session ID

If the path prefix is not specified, the default prefix $project/$location/$app/$date/$session/ will be used.

BigQueryExportSettings

Settings to describe the BigQuery export behaviors for the app.

JSON representation 
{
  "enabled": boolean,
  "project": string,
  "dataset": string
}
Fields
enabled

boolean

Optional. Indicates whether the BigQuery export is enabled.
project

string

Optional. The project ID of the BigQuery dataset to export the data to.

Note: If the BigQuery dataset is in a different project from the app, you should grant roles/bigquery.admin role to the CES service agent service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com.
dataset

string

Optional. The BigQuery dataset to export the data to.

CloudLoggingSettings

Settings to describe the Cloud Logging behaviors for the app.

JSON representation 
{
  "enableCloudLogging": boolean
}
Fields
enableCloudLogging

boolean

Optional. Whether to enable Cloud Logging for the sessions.

ConversationLoggingSettings

Settings to describe the conversation logging behaviors for the app.

JSON representation 
{
  "disableConversationLogging": boolean
}
Fields
disableConversationLogging

boolean

Optional. Whether to disable conversation logging for the sessions.

App.ToolExecutionMode

Defines the tool execution behavior if there are multiple tools being selected by the agent at the same time.

Enums
TOOL_EXECUTION_MODE_UNSPECIFIED Unspecified tool execution mode. Default to PARALLEL.
PARALLEL If there are multiple tools being selected, they will be executed in parallel, with the same ToolContext.
SEQUENTIAL If there are multiple tools being selected, they will be executed sequentially. The next tool will only be executed after the previous tool completes and it can see updated ToolContext from the previous tool.

EvaluationMetricsThresholds

Threshold settings for metrics in an Evaluation.

JSON representation 
{
  "goldenEvaluationMetricsThresholds": {
    object (EvaluationMetricsThresholds.GoldenEvaluationMetricsThresholds)
  },
  "hallucinationMetricBehavior": enum (EvaluationMetricsThresholds.HallucinationMetricBehavior)
}
Fields
goldenEvaluationMetricsThresholds

object (EvaluationMetricsThresholds.GoldenEvaluationMetricsThresholds)

Optional. The golden evaluation metrics thresholds.
hallucinationMetricBehavior

enum (EvaluationMetricsThresholds.HallucinationMetricBehavior)

Optional. The hallucination metric behavior.

EvaluationMetricsThresholds.GoldenEvaluationMetricsThresholds

Settings for golden evaluations.

JSON representation 
{
  "turnLevelMetricsThresholds": {
    object (EvaluationMetricsThresholds.GoldenEvaluationMetricsThresholds.TurnLevelMetricsThresholds)
  },
  "expectationLevelMetricsThresholds": {
    object (EvaluationMetricsThresholds.GoldenEvaluationMetricsThresholds.ExpectationLevelMetricsThresholds)
  }
}
Fields
turnLevelMetricsThresholds

object (EvaluationMetricsThresholds.GoldenEvaluationMetricsThresholds.TurnLevelMetricsThresholds)

Optional. The turn level metrics thresholds.
expectationLevelMetricsThresholds

object (EvaluationMetricsThresholds.GoldenEvaluationMetricsThresholds.ExpectationLevelMetricsThresholds)

Optional. The expectation level metrics thresholds.

EvaluationMetricsThresholds.GoldenEvaluationMetricsThresholds.TurnLevelMetricsThresholds

Turn level metrics thresholds.

JSON representation 
{
  "semanticSimilaritySuccessThreshold": integer,
  "overallToolInvocationCorrectnessThreshold": number
}
Fields
semanticSimilaritySuccessThreshold

integer

Optional. The success threshold for semantic similarity. Must be an integer between 0 and 4. Default is >= 3.
overallToolInvocationCorrectnessThreshold

number

Optional. The success threshold for overall tool invocation correctness. Must be a float between 0 and 1. Default is 1.0.

EvaluationMetricsThresholds.GoldenEvaluationMetricsThresholds.ExpectationLevelMetricsThresholds

Expectation level metrics thresholds.

JSON representation 
{
  "toolInvocationParameterCorrectnessThreshold": number
}
Fields
toolInvocationParameterCorrectnessThreshold

number

Optional. The success threshold for individual tool invocation parameter correctness. Must be a float between 0 and 1. Default is 1.0.

EvaluationMetricsThresholds.HallucinationMetricBehavior

The hallucination metric behavior. Regardless of the behavior, the metric will always be calculated. The difference is that when disabled, the metric is not used to calculate the overall evaluation score.

Enums
HALLUCINATION_METRIC_BEHAVIOR_UNSPECIFIED Unspecified hallucination metric behavior.
DISABLED Disable hallucination metric.
ENABLED Enable hallucination metric.

App.VariableDeclaration

Defines the structure and metadata for a variable.

JSON representation 
{
  "name": string,
  "description": string,
  "schema": {
    object (Schema)
  }
}
Fields
name

string

Required. The name of the variable. The name must start with a letter or underscore and contain only letters, numbers, or underscores.
description

string

Required. The description of the variable.
schema

object (Schema)

Required. The schema of the variable.

DataStoreSettings

Data store related settings for the app.

JSON representation 
{
  "engines": [
    {
      object (DataStoreSettings.Engine)
    }
  ]
}
Fields
engines[]

object (DataStoreSettings.Engine)

Output only. The engines for the app.

DataStoreSettings.Engine

An engine to which the data stores are connected. See Vertex AI Search: https://cloud.google.com/generative-ai-app-builder/docs/enterprise-search-introduction.

JSON representation 
{
  "name": string,
  "type": enum (DataStoreSettings.Engine.Type)
}
Fields
name

string

Output only. The resource name of the engine. Format: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}
type

enum (DataStoreSettings.Engine.Type)

Output only. The type of the engine.

DataStoreSettings.Engine.Type

The type of the engine. See the documentation available at https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/SolutionType and https://cloud.google.com/generative-ai-app-builder/docs/create-datastore-ingest.

Enums
TYPE_UNSPECIFIED Unspecified engine type.
ENGINE_TYPE_CHAT Chat engine type. The SOLUTION_TYPE_CHAT engine for the app. All connector data stores added to the app will be added to this engine.

ClientCertificateSettings

Settings for custom client certificates.

JSON representation 
{
  "tlsCertificate": string,
  "privateKey": string,
  "passphrase": string
}
Fields
tlsCertificate

string

Required. The TLS certificate encoded in PEM format. This string must include the begin header and end footer lines.
privateKey

string

Required. The name of the SecretManager secret version resource storing the private key encoded in PEM format. Format: projects/{project}/secrets/{secret}/versions/{version}
passphrase

string

Optional. The name of the SecretManager secret version resource storing the passphrase to decrypt the private key. Should be left unset if the private key is not encrypted. Format: projects/{project}/secrets/{secret}/versions/{version}

EvaluationSettings

Settings for evaluation.

JSON representation 
{
  "scenarioConversationInitiator": enum (EvaluationSettings.ScenarioConversationInitiator)
}
Fields
scenarioConversationInitiator

enum (EvaluationSettings.ScenarioConversationInitiator)

Optional. Who starts the conversation in a scenario evaluation.

EvaluationSettings.ScenarioConversationInitiator

Determines who starts the conversation in a scenario evaluation session.

Enums
SCENARIO_CONVERSATION_INITIATOR_UNSPECIFIED Unspecified. Defaults to USER.
USER The user starts the conversation.
AGENT The agent starts the conversation.

Methods

create

 Creates a new app in the given project and location.

delete

 Deletes the specified app.

executeTool

 Executes the given tool with the given arguments.

exportApp

 Exports the specified app.

get

 Gets details of the specified app.

importApp

 Imports the specified app.

list

 Lists apps in the given project and location.

patch

 Updates the specified app.

retrieveToolSchema

 Retrieve the schema of the given tool.