MCP Tools Reference: ces.googleapis.com

工具：update_tool

更新指定的工具。請務必在輸入內容中傳遞更新遮罩。

下列範例示範如何使用 curl 叫用 update_tool MCP 工具。

Curl 要求 
                  
curl --location 'https://ces.[REGION].rep.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "update_tool",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入內容的結構定義

AgentService.UpdateTool 的要求訊息。

UpdateToolRequest

JSON 表示法 
{
  "tool": {
    object (Tool)
  },
  "updateMask": string
}
欄位
tool

object (Tool)

這是必要旗標，要更新的工具。
updateMask

string (FieldMask format)

選用。欄位遮罩用於控管要更新的欄位。如果沒有遮罩，系統會更新所有欄位。

這是以半形逗號分隔的完整欄位名稱清單，範例："user.displayName,photo"。

工具

JSON 表示法 
{
  "name": string,
  "displayName": string,
  "executionType": enum (ExecutionType),
  "createTime": string,
  "updateTime": string,
  "etag": string,
  "generatedSummary": string,
  "toolFakeConfig": {
    object (ToolFakeConfig)
  },

  // Union field tool_type can be only one of the following:
  "clientFunction": {
    object (ClientFunction)
  },
  "openApiTool": {
    object (OpenApiTool)
  },
  "googleSearchTool": {
    object (GoogleSearchTool)
  },
  "connectorTool": {
    object (ConnectorTool)
  },
  "dataStoreTool": {
    object (DataStoreTool)
  },
  "pythonFunction": {
    object (PythonFunction)
  },
  "mcpTool": {
    object (McpTool)
  },
  "fileSearchTool": {
    object (FileSearchTool)
  },
  "systemTool": {
    object (SystemTool)
  },
  "widgetTool": {
    object (WidgetTool)
  }
  // End of list of possible types for union field tool_type.
}
欄位
name

string

ID。工具的專屬 ID。格式：- projects/{project}/locations/{location}/apps/{app}/tools/{tool} 適用於

projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}/tools/{tool}，適用於從工具集擷取的工具。這些工具是動態的，且只能輸出，無法在需要工具的地方直接參照。
displayName

string

僅供輸出。工具的顯示名稱，會根據工具類型衍生而來。舉例來說，[ClientFunction][Tool.ClientFunction] 的顯示名稱是從其 name 屬性衍生而來。
executionType

enum (ExecutionType)

選用。工具的執行作業類型。
createTime

string (Timestamp format)

僅供輸出。工具的建立時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
updateTime

string (Timestamp format)

僅供輸出。上次更新工具的時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
etag

string

Etag 用於確保物件在讀取 - 修改 - 寫入作業期間未變更。如果 etag 為空，更新作業會覆寫任何並行變更。
generatedSummary

string

僅供輸出。如果工具是由 LLM 助理產生，這個欄位會包含生成內容的描述性摘要。
toolFakeConfig

object (ToolFakeConfig)

選用。模擬模式中的工具行為設定。
聯集欄位 tool_type。工具類型。tool_type 只能是下列其中一個設定：
clientFunction

object (ClientFunction)

選用。用戶端函式。
openApiTool

object (OpenApiTool)

選用。開放式 API 工具。
googleSearchTool

object (GoogleSearchTool)

選用。Google 搜尋工具。
connectorTool

object (ConnectorTool)

選用。Integration Connectors 工具。
dataStoreTool

object (DataStoreTool)

選用。資料儲存工具。
pythonFunction

object (PythonFunction)

選用。Python 函式工具。
mcpTool

object (McpTool)

選用。MCP 工具。MCP 工具無法直接建立或更新，而是由 MCP 工具集管理。
fileSearchTool

object (FileSearchTool)

選用。檔案搜尋工具。
systemTool

object (SystemTool)

選用。系統工具。
widgetTool

object (WidgetTool)

選用。小工具工具。

ClientFunction

JSON 表示法 
{
  "name": string,
  "description": string,
  "parameters": {
    object (Schema)
  },
  "response": {
    object (Schema)
  }
}
欄位
name

string

這是必要旗標，函式名稱。
description

string

選用。函式說明。
parameters

object (Schema)

選用。函式參數的結構定義。
response

object (Schema)

選用。函式回應的結構定義。

結構定義

JSON 表示法 
{
  "type": enum (Type),
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "description": string,
  "items": {
    object (Schema)
  },
  "nullable": boolean,
  "uniqueItems": boolean,
  "prefixItems": [
    {
      object (Schema)
    }
  ],
  "additionalProperties": {
    object (Schema)
  },
  "anyOf": [
    {
      object (Schema)
    }
  ],
  "enum": [
    string
  ],
  "default": value,
  "ref": string,
  "defs": {
    string: {
      object (Schema)
    },
    ...
  },
  "title": string,
  "minItems": string,
  "maxItems": string,

  // Union field _minimum can be only one of the following:
  "minimum": number
  // End of list of possible types for union field _minimum.

  // Union field _maximum can be only one of the following:
  "maximum": number
  // End of list of possible types for union field _maximum.
}
欄位
type

enum (Type)

這是必要旗標，資料類型。
properties

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

選用。Type.OBJECT 的屬性。

包含 "key": value 組合清單的物件，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
required[]

string

選用。Type.OBJECT 的必要屬性。
description

string

選用。資料說明。
items

object (Schema)

選用。Type.ARRAY 元素的結構定義。
nullable

boolean

選用。指出值是否可能為空值。
uniqueItems

boolean

選用。指出陣列中的項目不得重複。僅適用於 TYPE.ARRAY。
prefixItems[]

object (Schema)

選用。Type.ARRAY 初始元素的結構定義。
additionalProperties

object (Schema)

選用。可以是布林值或物件，可控制其他屬性的存在。
anyOf[]

object (Schema)

選用。值應根據清單中的任何 (一或多個) 子結構定義進行驗證。
enum[]

string

選用。可能的值為列舉格式的基本類型元素。範例：1. 我們可以將方向定義為：{type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]} 2. 我們可以將公寓號碼定義為：{type:INTEGER, format:enum, enum:["101", "201", "301"]}
default

value (Value format)

選用。資料的預設值。
ref

string

選用。允許架構節點之間的間接參照。此值應為根 defs 子項的有效參照。

舉例來說，下列結構定義會定義對名為「Pet」的結構節點的參照：

type: object
properties:
  pet:
    ref: #/defs/Pet
defs:
  Pet:
    type: object
    properties:
      name:
        type: string

「寵物」屬性的值是參照名為「寵物」的結構定義節點。詳情請參閱 https://json-schema.org/understanding-json-schema/structuring。
defs

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

選用。供 ref 使用的定義對應表。只能在結構定義的根層級使用。

包含 "key": value 組合清單的物件，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
title

string

選用。結構定義的標題。
minItems

string (int64 format)

選用。Type.ARRAY 的元素數量下限。
maxItems

string (int64 format)

選用。Type.ARRAY 的元素數量上限。

聯集欄位 _minimum。

_minimum 只能是下列其中一項：
minimum

number

選用。Type.INTEGER 和 Type.NUMBER 的最小值。

聯集欄位 _maximum。

_maximum 只能是下列其中一項：
maximum

number

選用。Type.INTEGER 和 Type.NUMBER 的最大值。

PropertiesEntry

JSON 表示法 
{
  "key": string,
  "value": {
    object (Schema)
  }
}
欄位
key

string
value

object (Schema)

值

JSON 表示法 
{

  // Union field kind can be only one of the following:
  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
  // End of list of possible types for union field kind.
}
欄位
聯集欄位 kind。值的類型。kind 只能是下列其中一個設定：
nullValue

null

代表空值。
numberValue

number

表示雙精度浮點數值。
stringValue

string

代表字串值。
boolValue

boolean

表示布林值。
structValue

object (Struct format)

代表結構化值。
listValue

array (ListValue format)

代表重複的 Value。

結構

JSON 表示法 
{
  "fields": {
    string: value,
    ...
  }
}
欄位
fields

map (key: string, value: value (Value format))

動態型別值的無序對應。

包含 "key": value 組合清單的物件，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

FieldsEntry

JSON 表示法 
{
  "key": string,
  "value": value
}
欄位
key

string
value

value (Value format)

ListValue

JSON 表示法 
{
  "values": [
    value
  ]
}
欄位
values[]

value (Value format)

動態型別值的重複欄位。

DefsEntry

JSON 表示法 
{
  "key": string,
  "value": {
    object (Schema)
  }
}
欄位
key

string
value

object (Schema)

OpenApiTool

JSON 表示法 
{
  "openApiSchema": string,
  "name": string,
  "description": string,
  "apiAuthentication": {
    object (ApiAuthentication)
  },
  "tlsConfig": {
    object (TlsConfig)
  },
  "serviceDirectoryConfig": {
    object (ServiceDirectoryConfig)
  },
  "ignoreUnknownFields": boolean,
  "url": string
}
欄位
openApiSchema

string

這是必要旗標，JSON 或 YAML 格式的 OpenAPI 結構定義。
name

string

選用。工具名稱。如未提供，工具名稱會從 OpenAPI 結構定義的 operation.operationId 衍生。
description

string

選用。工具說明。如未提供，工具說明會從 OpenAPI 結構定義、operation.description 或 operation.summary 衍生。
apiAuthentication

object (ApiAuthentication)

選用。API 要求的驗證資訊。
tlsConfig

object (TlsConfig)

選用。傳輸層安全標準 (TLS) 設定。包含用戶端信任的自訂伺服器憑證。
serviceDirectoryConfig

object (ServiceDirectoryConfig)

選用。Service Directory 設定。
ignoreUnknownFields

boolean

選用。如為 true，代理程式會忽略 API 回應中的不明欄位。
url

string

選用。開放式 API 結構定義的伺服器網址。如果結構定義包含伺服器網址，則只有在匯出程序期間，環境依附元件中的工具才會設定這個欄位。在匯入過程中，如果環境依附元件中存在這個網址，且結構定義含有 $env_var 預留位置，系統就會取代結構定義中的預留位置。

ApiAuthentication

JSON 表示法 
{

  // Union field auth_config can be only one of the following:
  "apiKeyConfig": {
    object (ApiKeyConfig)
  },
  "oauthConfig": {
    object (OAuthConfig)
  },
  "serviceAgentIdTokenAuthConfig": {
    object (ServiceAgentIdTokenAuthConfig)
  },
  "serviceAccountAuthConfig": {
    object (ServiceAccountAuthConfig)
  },
  "bearerTokenConfig": {
    object (BearerTokenConfig)
  }
  // End of list of possible types for union field auth_config.
}
欄位
聯集欄位 auth_config。驗證設定。auth_config 只能是下列其中一個設定：
apiKeyConfig

object (ApiKeyConfig)

選用。API 金鑰驗證的設定。
oauthConfig

object (OAuthConfig)

選用。OAuth 的設定。
serviceAgentIdTokenAuthConfig

object (ServiceAgentIdTokenAuthConfig)

選用。從 CES 服務代理程式產生的 ID 權杖驗證設定。
serviceAccountAuthConfig

object (ServiceAccountAuthConfig)

選用。服務帳戶驗證的設定。
bearerTokenConfig

object (BearerTokenConfig)

選用。不記名權杖驗證的設定。

ApiKeyConfig

JSON 表示法 
{
  "keyName": string,
  "apiKeySecretVersion": string,
  "requestLocation": enum (RequestLocation)
}
欄位
keyName

string

這是必要旗標，API 金鑰的參數名稱或標頭名稱。例如：如果 API 要求是「https://example.com/act?X-Api-Key=」，則「X-Api-Key」就是參數名稱。
apiKeySecretVersion

string

這是必要旗標，儲存 API 金鑰的 SecretManager 密鑰版本資源名稱。格式：projects/{project}/secrets/{secret}/versions/{version}

注意：您應將 roles/secretmanager.secretAccessor 角色授予 CES 服務代理人 service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com。
requestLocation

enum (RequestLocation)

這是必要旗標，要求中的金鑰位置。

OAuthConfig

JSON 表示法 
{
  "oauthGrantType": enum (OauthGrantType),
  "clientId": string,
  "clientSecretVersion": string,
  "tokenEndpoint": string,
  "scopes": [
    string
  ]
}
欄位
oauthGrantType

enum (OauthGrantType)

這是必要旗標，OAuth 授權類型。
clientId

string

這是必要旗標，OAuth 供應商提供的用戶端 ID。
clientSecretVersion

string

這是必要旗標，儲存用戶端密鑰的 SecretManager 密鑰版本資源名稱。格式：projects/{project}/secrets/{secret}/versions/{version}

注意：您應將 roles/secretmanager.secretAccessor 角色授予 CES 服務代理人 service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com。
tokenEndpoint

string

這是必要旗標，OAuth 供應商中的權杖端點，用於交換存取權杖。
scopes[]

string

選用。要授予的 OAuth 範圍。

ServiceAccountAuthConfig

JSON 表示法 
{
  "serviceAccount": string,
  "scopes": [
    string
  ]
}
欄位
serviceAccount

string

這是必要旗標，用於驗證的服務帳戶電子郵件地址。CES 會使用這個服務帳戶交換存取權杖，然後在要求的 Authorization 標頭中傳送存取權杖。

服務帳戶必須將 roles/iam.serviceAccountTokenCreator 角色授予 CES 服務代理程式 service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com。
scopes[]

string

選用。要授予的 OAuth 範圍。如未指定，則會使用預設範圍 https://www.googleapis.com/auth/cloud-platform。

BearerTokenConfig

JSON 表示法 
{
  "token": string
}
欄位
token

string

這是必要旗標，不記名權杖。格式必須為 $context.variables.<name_of_variable>。

TlsConfig

JSON 表示法 
{
  "caCerts": [
    {
      object (CaCert)
    }
  ]
}
欄位
caCerts[]

object (CaCert)

這是必要旗標，指定允許用於 HTTPS 驗證的自訂 CA 憑證清單。

CaCert

JSON 表示法 
{
  "displayName": string,
  "cert": string
}
欄位
displayName

string

這是必要旗標，允許使用的自訂 CA 憑證名稱。這可用於消除自訂 CA 憑證的歧義。
cert

string (bytes format)

這是必要旗標，用於 HTTPS 驗證的允許自訂 CA 憑證 (DER 格式)。這會覆寫預設的 SSL 信任儲存區。如為空白或未指定，CES 會使用 Google 的預設信任儲存區驗證憑證。注意：請確認 HTTPS 伺服器憑證是以「主體替代名稱」簽署。舉例來說，您可以使用下列指令自行簽署憑證： openssl x509 -req -days 200 -in example.com.csr \ -signkey example.com.key \ -out example.com.crt \ -extfile <(printf "\nsubjectAltName='DNS:www.example.com'")

Base64 編碼字串。

ServiceDirectoryConfig

JSON 表示法 
{
  "service": string
}
欄位
service

string

這是必要旗標，Service Directory 服務的名稱。格式：projects/{project}/locations/{location}/namespaces/{namespace}/services/{service}。服務目錄的位置必須與應用程式的位置相同。

GoogleSearchTool

JSON 表示法 
{
  "name": string,
  "description": string,
  "contextUrls": [
    string
  ],
  "preferredDomains": [
    string
  ],
  "excludeDomains": [
    string
  ],
  "promptConfig": {
    object (PromptConfig)
  }
}
欄位
name

string

這是必要旗標，工具名稱。
description

string

選用。工具用途說明。
contextUrls[]

string

選用。系統會直接從這些網址擷取內容，做為背景資訊和基礎。例如：「https://example.com/path.html」。最多可加入 20 個網址。
preferredDomains[]

string

選用。指定要限制搜尋結果的網域。例如：「example.com」、「another.site」。最多可指定 20 個網域。
excludeDomains[]

string

選用。要從搜尋結果中排除的網域清單。例如：「example.com」。最多可排除 2000 個網域。
promptConfig

object (PromptConfig)

選用。傳遞給規劃工具的提示指令，說明如何處理文字和語音的搜尋結果。

PromptConfig

JSON 表示法 
{
  "textPrompt": string,
  "voicePrompt": string
}
欄位
textPrompt

string

選用。定義在即時通訊對話中與代理互動時，用於系統指令的提示。如未設定，系統會使用預設提示。
voicePrompt

string

選用。定義與代理進行語音對話時，用於系統指令的提示。如未設定，系統會使用預設提示。

ConnectorTool

JSON 表示法 
{
  "connection": string,
  "action": {
    object (Action)
  },
  "authConfig": {
    object (EndUserAuthConfig)
  },
  "name": string,
  "description": string
}
欄位
connection

string

這是必要旗標，所參照 Integration Connectors 連線的完整資源名稱。格式：projects/{project}/locations/{location}/connections/{connection}
action

object (Action)

這是必要旗標，工具要執行的動作。
authConfig

object (EndUserAuthConfig)

選用。設定 Integration Connectors 的驗證處理方式。根據預設，管理員驗證會傳遞至 Integration Connectors API 要求。您可以覆寫這項設定，改用其他使用者驗證設定。注意：連線必須啟用驗證覆寫功能，才能在此指定 EUC 設定，否則 ConnectorTool 建立作業會失敗。詳情請參閱 https://cloud.google.com/application-integration/docs/configure-connectors-task#configure-authentication-override。
name

string

選用。代理可使用的工具名稱，用來決定是否呼叫這個 ConnectorTool。
description

string

選用。工具說明，代理可依據這段說明判斷是否要呼叫這個 ConnectorTool。

動作

JSON 表示法 
{
  "inputFields": [
    string
  ],
  "outputFields": [
    string
  ],

  // Union field action_spec can be only one of the following:
  "connectionActionId": string,
  "entityOperation": {
    object (EntityOperation)
  }
  // End of list of possible types for union field action_spec.
}
欄位
inputFields[]

string

選用。做為作業輸入內容的實體欄位。如未指定任何欄位，系統會使用實體的所有欄位。
outputFields[]

string

選用。要從作業傳回的實體欄位。如未指定任何欄位，系統會傳回實體的所有欄位。
聯集欄位 action_spec。工具要使用的動作設定規格。action_spec 只能是下列其中一個設定：
connectionActionId

string

工具要使用的「連線」動作 ID。
entityOperation

object (EntityOperation)

工具要使用的實體作業設定。

EntityOperation

JSON 表示法 
{
  "entityId": string,
  "operation": enum (OperationType)
}
欄位
entityId

string

這是必要旗標，實體的 ID。
operation

enum (OperationType)

這是必要旗標，要在實體上執行的作業。

EndUserAuthConfig

JSON 表示法 
{

  // Union field auth_config can be only one of the following:
  "oauth2AuthCodeConfig": {
    object (Oauth2AuthCodeConfig)
  },
  "oauth2JwtBearerConfig": {
    object (Oauth2JwtBearerConfig)
  }
  // End of list of possible types for union field auth_config.
}
欄位
聯集欄位 auth_config。驗證設定。auth_config 只能是下列其中一個設定：
oauth2AuthCodeConfig

object (Oauth2AuthCodeConfig)

Oauth 2.0 授權碼驗證。
oauth2JwtBearerConfig

object (Oauth2JwtBearerConfig)

JWT 設定檔 OAuth 2.0 授權授予驗證。

Oauth2AuthCodeConfig

JSON 表示法 
{
  "oauthToken": string
}
欄位
oauthToken

string

這是必要旗標，要傳遞的 OAuth 權杖參數名稱。格式必須為 $context.variables.<name_of_variable>。

Oauth2JwtBearerConfig

JSON 表示法 
{
  "issuer": string,
  "subject": string,
  "clientKey": string
}
欄位
issuer

string

這是必要旗標，要傳遞的發卡機構參數名稱。格式必須為 $context.variables.<name_of_variable>。
subject

string

這是必要旗標，要傳遞的主體參數名稱。格式必須為 $context.variables.<name_of_variable>。
clientKey

string

這是必要旗標，要傳遞的用戶端參數名稱。格式必須為 $context.variables.<name_of_variable>。

DataStoreTool

JSON 表示法 
{
  "name": string,
  "description": string,
  "boostSpecs": [
    {
      object (BoostSpecs)
    }
  ],
  "modalityConfigs": [
    {
      object (ModalityConfig)
    }
  ],
  "filterParameterBehavior": enum (FilterParameterBehavior),

  // Union field search_source can be only one of the following:
  "dataStoreSource": {
    object (DataStoreSource)
  },
  "engineSource": {
    object (EngineSource)
  }
  // End of list of possible types for union field search_source.
}
欄位
name

string

這是必要旗標，資料儲存庫工具名稱。
description

string

選用。工具說明。
boostSpecs[]

object (BoostSpecs)

選用。提升規格，以提升特定文件。
modalityConfigs[]

object (ModalityConfig)

選用。資料儲存庫的模態設定。
filterParameterBehavior

enum (FilterParameterBehavior)

選用。篩選器參數行為。
聯集欄位 search_source。定義搜尋來源，可以是單一資料儲存庫或引擎。search_source 只能是下列其中一個設定：
dataStoreSource

object (DataStoreSource)

選用。在單一特定 DataStore 中搜尋。
engineSource

object (EngineSource)

選用。在引擎內搜尋 (可能跨越多個 Datastore)。

DataStoreSource

JSON 表示法 
{
  "filter": string,
  "dataStore": {
    object (DataStore)
  }
}
欄位
filter

string

選用。DataStore 的篩選器規格。請參閱：https://cloud.google.com/generative-ai-app-builder/docs/filter-search-metadata
dataStore

object (DataStore)

選用。資料儲存庫。

DataStore

JSON 表示法 
{
  "name": string,
  "type": enum (DataStoreType),
  "documentProcessingMode": enum (DocumentProcessingMode),
  "displayName": string,
  "createTime": string,
  "connectorConfig": {
    object (ConnectorConfig)
  }
}
欄位
name

string

這是必要旗標，DataStore 的完整資源名稱。格式：projects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}
type

enum (DataStoreType)

僅供輸出。資料儲存庫的類型。這個欄位為唯讀，由伺服器填入。
documentProcessingMode

enum (DocumentProcessingMode)

僅供輸出。資料存放區連線的文件處理模式。僅適用於 PUBLIC_WEB 和 UNSTRUCTURED 資料儲存庫。
displayName

string

僅供輸出。資料儲存庫的顯示名稱。
createTime

string (Timestamp format)

僅供輸出。資料儲存庫的建立時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
connectorConfig

object (ConnectorConfig)

僅供輸出。資料儲存庫連線的連接器設定。

時間戳記

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
欄位
seconds

string (int64 format)

代表自 Unix 紀元 1970-01-01T00:00:00Z 起算的世界標準時間秒數。必須介於 -62135596800 和 253402300799 之間 (含)，對應至 0001-01-01T00:00:00Z 至 9999-12-31T23:59:59Z。
nanos

integer

以奈秒為單位的非負秒數小數。這個欄位是時間長度的奈秒部分，並非秒數的替代值。如果第二個值為負數，且包含分數，奈秒值仍須為非負數，且會向前計時。必須介於 0 至 999,999,999 之間 (含)。

ConnectorConfig

JSON 表示法 
{
  "collection": string,
  "collectionDisplayName": string,
  "dataSource": string
}
欄位
collection

string

資料儲存庫所屬集合的資源名稱。
collectionDisplayName

string

資料儲存庫所屬集合的顯示名稱。
dataSource

string

資料來源的名稱。例如：salesforce、jira、confluence、bigquery。

EngineSource

JSON 表示法 
{
  "engine": string,
  "dataStoreSources": [
    {
      object (DataStoreSource)
    }
  ],
  "filter": string
}
欄位
engine

string

這是必要旗標，引擎的完整資源名稱。格式：projects/{project}/locations/{location}/collections/{collection}/engines/{engine}
dataStoreSources[]

object (DataStoreSource)

選用。用於指定引擎中的特定 DataStore。如果留空，搜尋範圍會涵蓋與引擎相關聯的所有 DataStore。
filter

string

選用。套用至整個引擎搜尋的篩選器。如果提供「data_store_sources」，則不相關且不會使用。請參閱：https://cloud.google.com/generative-ai-app-builder/docs/filter-search-metadata

BoostSpecs

JSON 表示法 
{
  "dataStores": [
    string
  ],
  "spec": [
    {
      object (BoostSpec)
    }
  ]
}
欄位
dataStores[]

string

這是必要旗標，套用升幅設定的資料儲存庫。DataStore 的完整資源名稱，例如 projects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}。
spec[]

object (BoostSpec)

這是必要旗標，增強規格清單。

BoostSpec

JSON 表示法 
{
  "conditionBoostSpecs": [
    {
      object (ConditionBoostSpec)
    }
  ]
}
欄位
conditionBoostSpecs[]

object (ConditionBoostSpec)

這是必要旗標，增強規格清單。

ConditionBoostSpec

JSON 表示法 
{
  "condition": string,
  "boost": number,
  "boostControlSpec": {
    object (BoostControlSpec)
  }
}
欄位
condition

string

這是必要旗標，指定提升條件的運算式。語法與篩選運算式語法相同。目前僅支援 BCP-47 語言代碼清單。範例：如要提升英文或法文的建議：(lang_code: ANY("en", "fr"))
boost

number

選用。增幅強度，應介於 [-1, 1] 之間。如果設為負值，即代表降低排名。預設值為 0.0。

設為 1.0 可大幅提高建議的排名。不過，這並不代表經過增強的建議一定會顯示在搜尋結果頂端。

設為 -1.0 會大幅降低建議的排名。不過，系統仍可能會顯示其他相關建議。

設為 0.0 表示不套用任何增幅。系統會忽略加成條件。
boostControlSpec

object (BoostControlSpec)

選用。根據顧客定義的屬性值，為自訂排序設定複雜規格。

BoostControlSpec

JSON 表示法 
{
  "fieldName": string,
  "attributeType": enum (AttributeType),
  "interpolationType": enum (InterpolationType),
  "controlPoints": [
    {
      object (ControlPoint)
    }
  ]
}
欄位
fieldName

string

選用。系統會根據這個欄位的值決定加成金額。
attributeType

enum (AttributeType)

選用。用來決定加成金額的屬性類型。屬性值可從指定 field_name 的欄位值衍生而來。如果是數值，則很簡單，也就是 attribute_value = numerical_field_value。不過，如果是新鮮度，attribute_value = (time.now() - datetime_field_value)。
interpolationType

enum (InterpolationType)

選用。要套用的插補類型，用於連結下列控制點。
controlPoints[]

object (ControlPoint)

選用。用來定義曲線的控制點。單調函式 (透過上述 interpolation_type 定義) 會通過這裡列出的控制點。

ControlPoint

JSON 表示法 
{
  "attributeValue": string,
  "boostAmount": number
}
欄位
attributeValue

string

選用。可以是下列任一值：1. 數值欄位值。2. 新鮮度時間長度規格：值必須採用 XSD dayTimeDuration 值格式 (ISO 8601 時間長度值的受限子集)。格式為：[nD][T[nH][nM][nS]]。
boostAmount

number

選用。如果 attribute_value 評估結果為上述指定值，則分數的提升值介於 -1 到 1 之間。

ModalityConfig

JSON 表示法 
{
  "modalityType": enum (ModalityType),
  "rewriterConfig": {
    object (RewriterConfig)
  },
  "summarizationConfig": {
    object (SummarizationConfig)
  },
  "groundingConfig": {
    object (GroundingConfig)
  }
}
欄位
modalityType

enum (ModalityType)

這是必要旗標，模式類型。
rewriterConfig

object (RewriterConfig)

選用。重寫器設定。
summarizationConfig

object (SummarizationConfig)

選用。摘要設定。
groundingConfig

object (GroundingConfig)

選用。基礎設定。

RewriterConfig

JSON 表示法 
{
  "modelSettings": {
    object (ModelSettings)
  },
  "prompt": string,
  "disabled": boolean
}
欄位
modelSettings

object (ModelSettings)

這是必要旗標，LLM 模型的設定。
prompt

string

選用。提示定義。如未設定，系統會使用預設提示。
disabled

boolean

選用。重寫器是否已停用。

ModelSettings

JSON 表示法 
{
  "model": string,

  // Union field _temperature can be only one of the following:
  "temperature": number
  // End of list of possible types for union field _temperature.
}
欄位
model

string

選用。代理程式應使用的 LLM 模型。如未設定，代理程式會沿用上層代理程式的模型。

聯集欄位 _temperature。

_temperature 只能是下列其中一項：
temperature

number

選用。如果設定這項引數，LLM 模型就會使用這個溫度。溫度會控制模型回覆的隨機程度。溫度越低，生成的回覆就越容易預測。溫度越高，生成的回覆就越有創意。

SummarizationConfig

JSON 表示法 
{
  "modelSettings": {
    object (ModelSettings)
  },
  "prompt": string,
  "disabled": boolean
}
欄位
modelSettings

object (ModelSettings)

選用。LLM 模型的設定。
prompt

string

選用。提示定義。如未設定，系統會使用預設提示。
disabled

boolean

選用。摘要功能是否已停用。

GroundingConfig

JSON 表示法 
{
  "groundingLevel": number,
  "disabled": boolean
}
欄位
groundingLevel

number

選用。根據擷取的來源，答案的根據性門檻。這個值的可設定範圍為 [1, 5]。這個層級可用於設定答案的依據程度門檻，也就是說，如果答案的依據程度分數低於門檻，系統只會傳回相關的程式碼片段。

舉例來說，如果層級為 3，回應的根據事實程度分數就必須達到 3 分以上，才會傳回。
disabled

boolean

選用。是否停用接地。

PythonFunction

JSON 表示法 
{
  "name": string,
  "pythonCode": string,
  "description": string
}
欄位
name

string

選用。要執行的 Python 函式名稱。必須與 Python 程式碼中定義的 Python 函式名稱相符。區分大小寫。如未提供名稱，系統會使用 Python 程式碼中定義的第一個函式。
pythonCode

string

選用。工具要執行的 Python 程式碼。
description

string

僅供輸出。Python 函式的說明，從 Python 程式碼的 docstring 剖析而來。

McpTool

JSON 表示法 
{
  "name": string,
  "description": string,
  "inputSchema": {
    object (Schema)
  },
  "outputSchema": {
    object (Schema)
  },
  "serverAddress": string,
  "apiAuthentication": {
    object (ApiAuthentication)
  },
  "tlsConfig": {
    object (TlsConfig)
  },
  "serviceDirectoryConfig": {
    object (ServiceDirectoryConfig)
  }
}
欄位
name

string

這是必要旗標，MCP 工具的名稱。
description

string

選用。MCP 工具的說明。
inputSchema

object (Schema)

選用。MCP 工具輸入引數的結構定義。
outputSchema

object (Schema)

選用。MCP 工具輸出引數的結構定義。
serverAddress

string

這是必要旗標，MCP 伺服器的伺服器位址，例如 「https://example.com/mcp/」。如果伺服器是使用 MCP SDK 建構，網址應加上「/mcp/」後置字串。僅支援以可串流 HTTP 傳輸為基礎的伺服器。這與 McpToolset 中的 server_address 相同。詳情請參閱 https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http。
apiAuthentication

object (ApiAuthentication)

選用。執行工具時，必須提供 MCP 伺服器的驗證資訊。如果是持有人權杖驗證，權杖僅適用於工具執行，不適用於列出工具。這項功能需要工具在未經驗證的情況下也能列出。
tlsConfig

object (TlsConfig)

選用。傳輸層安全標準 (TLS) 設定。包含用戶端應信任的自訂伺服器憑證。
serviceDirectoryConfig

object (ServiceDirectoryConfig)

選用。VPC-SC 的 Service Directory 設定，用於解析範圍內的服務名稱。

FileSearchTool

JSON 表示法 
{
  "corpusType": enum (CorpusType),
  "name": string,
  "description": string,
  "fileCorpus": string
}
欄位
corpusType

enum (CorpusType)

選用。語料庫類型。預設值為 FULLY_MANAGED。
name

string

這是必要旗標，工具名稱。
description

string

選用。工具說明。
fileCorpus

string

選用。儲存檔案的語料庫。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus}

SystemTool

JSON 表示法 
{
  "name": string,
  "description": string
}
欄位
name

string

這是必要旗標，系統工具的名稱。
description

string

僅供輸出。系統工具的說明。

WidgetTool

JSON 表示法 
{
  "name": string,
  "description": string,
  "widgetType": enum (WidgetType),

  // Union field input can be only one of the following:
  "parameters": {
    object (Schema)
  }
  // End of list of possible types for union field input.
}
欄位
name

string

這是必要旗標，小工具工具的顯示名稱。
description

string

選用。小工具工具的說明。
widgetType

enum (WidgetType)

選用。小工具工具的類型。如未指定，預設類型為 CUSTOMIZED。
聯集欄位 input。小工具工具的輸入內容。input 只能是下列其中一個設定：
parameters

object (Schema)

選用。小工具工具的輸入參數。

ToolFakeConfig

JSON 表示法 
{
  "enableFakeMode": boolean,

  // Union field tool_response can be only one of the following:
  "codeBlock": {
    object (CodeBlock)
  }
  // End of list of possible types for union field tool_response.
}
欄位
enableFakeMode

boolean

選用。工具是否使用模擬模式。
聯集欄位 tool_response。回應可以是靜態，也可以由 Python 函式提供。tool_response 只能是下列其中一個設定：
codeBlock

object (CodeBlock)

選用。要執行的程式碼區塊，而非實際的工具呼叫。

CodeBlock

JSON 表示法 
{
  "pythonCode": string
}
欄位
pythonCode

string

這是必要旗標，在工具模擬模式中呼叫的 Python 程式碼。預期的 Python 函式簽章 - 如要擷取所有工具呼叫： def fake_tool_call(tool: Tool, input: dict[str, Any], callback_context: CallbackContext) -> Optional[dict[str, Any]]: 如要擷取特定工具呼叫： def fake_{tool_id}(tool: Tool, input: dict[str, Any], callback_context: CallbackContext) -> Optional[dict[str, Any]]: 如果函式傳回 None，系統會改為叫用實際工具。

FieldMask

JSON 表示法 
{
  "paths": [
    string
  ]
}
欄位
paths[]

string

一組欄位遮罩路徑。

輸出內容的結構定義

工具代表 CES 代理可採取哪些動作來達成特定目標。

工具

JSON 表示法 
{
  "name": string,
  "displayName": string,
  "executionType": enum (ExecutionType),
  "createTime": string,
  "updateTime": string,
  "etag": string,
  "generatedSummary": string,
  "toolFakeConfig": {
    object (ToolFakeConfig)
  },

  // Union field tool_type can be only one of the following:
  "clientFunction": {
    object (ClientFunction)
  },
  "openApiTool": {
    object (OpenApiTool)
  },
  "googleSearchTool": {
    object (GoogleSearchTool)
  },
  "connectorTool": {
    object (ConnectorTool)
  },
  "dataStoreTool": {
    object (DataStoreTool)
  },
  "pythonFunction": {
    object (PythonFunction)
  },
  "mcpTool": {
    object (McpTool)
  },
  "fileSearchTool": {
    object (FileSearchTool)
  },
  "systemTool": {
    object (SystemTool)
  },
  "widgetTool": {
    object (WidgetTool)
  }
  // End of list of possible types for union field tool_type.
}
欄位
name

string

ID。工具的專屬 ID。格式：- projects/{project}/locations/{location}/apps/{app}/tools/{tool} 適用於

projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}/tools/{tool}，適用於從工具集擷取的工具。這些工具是動態的，且只能輸出，無法在需要工具的地方直接參照。
displayName

string

僅供輸出。工具的顯示名稱，會根據工具類型衍生而來。舉例來說，[ClientFunction][Tool.ClientFunction] 的顯示名稱是從其 name 屬性衍生而來。
executionType

enum (ExecutionType)

選用。工具的執行作業類型。
createTime

string (Timestamp format)

僅供輸出。工具的建立時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
updateTime

string (Timestamp format)

僅供輸出。上次更新工具的時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
etag

string

Etag 用於確保物件在讀取 - 修改 - 寫入作業期間未變更。如果 etag 為空，更新作業會覆寫任何並行變更。
generatedSummary

string

僅供輸出。如果工具是由 LLM 助理產生，這個欄位會包含生成內容的描述性摘要。
toolFakeConfig

object (ToolFakeConfig)

選用。模擬模式中的工具行為設定。
聯集欄位 tool_type。工具類型。tool_type 只能是下列其中一個設定：
clientFunction

object (ClientFunction)

選用。用戶端函式。
openApiTool

object (OpenApiTool)

選用。開放式 API 工具。
googleSearchTool

object (GoogleSearchTool)

選用。Google 搜尋工具。
connectorTool

object (ConnectorTool)

選用。Integration Connectors 工具。
dataStoreTool

object (DataStoreTool)

選用。資料儲存工具。
pythonFunction

object (PythonFunction)

選用。Python 函式工具。
mcpTool

object (McpTool)

選用。MCP 工具。MCP 工具無法直接建立或更新，而是由 MCP 工具集管理。
fileSearchTool

object (FileSearchTool)

選用。檔案搜尋工具。
systemTool

object (SystemTool)

選用。系統工具。
widgetTool

object (WidgetTool)

選用。小工具工具。

ClientFunction

JSON 表示法 
{
  "name": string,
  "description": string,
  "parameters": {
    object (Schema)
  },
  "response": {
    object (Schema)
  }
}
欄位
name

string

這是必要旗標，函式名稱。
description

string

選用。函式說明。
parameters

object (Schema)

選用。函式參數的結構定義。
response

object (Schema)

選用。函式回應的結構定義。

結構定義

JSON 表示法 
{
  "type": enum (Type),
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "description": string,
  "items": {
    object (Schema)
  },
  "nullable": boolean,
  "uniqueItems": boolean,
  "prefixItems": [
    {
      object (Schema)
    }
  ],
  "additionalProperties": {
    object (Schema)
  },
  "anyOf": [
    {
      object (Schema)
    }
  ],
  "enum": [
    string
  ],
  "default": value,
  "ref": string,
  "defs": {
    string: {
      object (Schema)
    },
    ...
  },
  "title": string,
  "minItems": string,
  "maxItems": string,

  // Union field _minimum can be only one of the following:
  "minimum": number
  // End of list of possible types for union field _minimum.

  // Union field _maximum can be only one of the following:
  "maximum": number
  // End of list of possible types for union field _maximum.
}
欄位
type

enum (Type)

這是必要旗標，資料類型。
properties

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

選用。Type.OBJECT 的屬性。

包含 "key": value 組合清單的物件，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
required[]

string

選用。Type.OBJECT 的必要屬性。
description

string

選用。資料說明。
items

object (Schema)

選用。Type.ARRAY 元素的結構定義。
nullable

boolean

選用。指出值是否可能為空值。
uniqueItems

boolean

選用。指出陣列中的項目不得重複。僅適用於 TYPE.ARRAY。
prefixItems[]

object (Schema)

選用。Type.ARRAY 初始元素的結構定義。
additionalProperties

object (Schema)

選用。可以是布林值或物件，可控制其他屬性的存在。
anyOf[]

object (Schema)

選用。值應根據清單中的任何 (一或多個) 子結構定義進行驗證。
enum[]

string

選用。可能的值為列舉格式的基本類型元素。範例：1. 我們可以將方向定義為：{type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]} 2. 我們可以將公寓號碼定義為：{type:INTEGER, format:enum, enum:["101", "201", "301"]}
default

value (Value format)

選用。資料的預設值。
ref

string

選用。允許架構節點之間的間接參照。此值應為根 defs 子項的有效參照。

舉例來說，下列結構定義會定義對名為「Pet」的結構節點的參照：

type: object
properties:
  pet:
    ref: #/defs/Pet
defs:
  Pet:
    type: object
    properties:
      name:
        type: string

「寵物」屬性的值是參照名為「寵物」的結構定義節點。詳情請參閱 https://json-schema.org/understanding-json-schema/structuring。
defs

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

選用。供 ref 使用的定義對應表。只能在結構定義的根層級使用。

包含 "key": value 組合清單的物件，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
title

string

選用。結構定義的標題。
minItems

string (int64 format)

選用。Type.ARRAY 的元素數量下限。
maxItems

string (int64 format)

選用。Type.ARRAY 的元素數量上限。

聯集欄位 _minimum。

_minimum 只能是下列其中一項：
minimum

number

選用。Type.INTEGER 和 Type.NUMBER 的最小值。

聯集欄位 _maximum。

_maximum 只能是下列其中一項：
maximum

number

選用。Type.INTEGER 和 Type.NUMBER 的最大值。

PropertiesEntry

JSON 表示法 
{
  "key": string,
  "value": {
    object (Schema)
  }
}
欄位
key

string
value

object (Schema)

值

JSON 表示法 
{

  // Union field kind can be only one of the following:
  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
  // End of list of possible types for union field kind.
}
欄位
聯集欄位 kind。值的類型。kind 只能是下列其中一個設定：
nullValue

null

代表空值。
numberValue

number

表示雙精度浮點數值。
stringValue

string

代表字串值。
boolValue

boolean

表示布林值。
structValue

object (Struct format)

代表結構化值。
listValue

array (ListValue format)

代表重複的 Value。

結構

JSON 表示法 
{
  "fields": {
    string: value,
    ...
  }
}
欄位
fields

map (key: string, value: value (Value format))

動態型別值的無序對應。

包含 "key": value 組合清單的物件，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

FieldsEntry

JSON 表示法 
{
  "key": string,
  "value": value
}
欄位
key

string
value

value (Value format)

ListValue

JSON 表示法 
{
  "values": [
    value
  ]
}
欄位
values[]

value (Value format)

動態型別值的重複欄位。

DefsEntry

JSON 表示法 
{
  "key": string,
  "value": {
    object (Schema)
  }
}
欄位
key

string
value

object (Schema)

OpenApiTool

JSON 表示法 
{
  "openApiSchema": string,
  "name": string,
  "description": string,
  "apiAuthentication": {
    object (ApiAuthentication)
  },
  "tlsConfig": {
    object (TlsConfig)
  },
  "serviceDirectoryConfig": {
    object (ServiceDirectoryConfig)
  },
  "ignoreUnknownFields": boolean,
  "url": string
}
欄位
openApiSchema

string

這是必要旗標，JSON 或 YAML 格式的 OpenAPI 結構定義。
name

string

選用。工具名稱。如未提供，工具名稱會從 OpenAPI 結構定義的 operation.operationId 衍生。
description

string

選用。工具說明。如未提供，工具說明會從 OpenAPI 結構定義、operation.description 或 operation.summary 衍生。
apiAuthentication

object (ApiAuthentication)

選用。API 要求的驗證資訊。
tlsConfig

object (TlsConfig)

選用。傳輸層安全標準 (TLS) 設定。包含用戶端信任的自訂伺服器憑證。
serviceDirectoryConfig

object (ServiceDirectoryConfig)

選用。Service Directory 設定。
ignoreUnknownFields

boolean

選用。如為 true，代理程式會忽略 API 回應中的不明欄位。
url

string

選用。開放式 API 結構定義的伺服器網址。如果結構定義包含伺服器網址，則只有在匯出程序期間，環境依附元件中的工具才會設定這個欄位。在匯入過程中，如果環境依附元件中存在這個網址，且結構定義含有 $env_var 預留位置，系統就會取代結構定義中的預留位置。

ApiAuthentication

JSON 表示法 
{

  // Union field auth_config can be only one of the following:
  "apiKeyConfig": {
    object (ApiKeyConfig)
  },
  "oauthConfig": {
    object (OAuthConfig)
  },
  "serviceAgentIdTokenAuthConfig": {
    object (ServiceAgentIdTokenAuthConfig)
  },
  "serviceAccountAuthConfig": {
    object (ServiceAccountAuthConfig)
  },
  "bearerTokenConfig": {
    object (BearerTokenConfig)
  }
  // End of list of possible types for union field auth_config.
}
欄位
聯集欄位 auth_config。驗證設定。auth_config 只能是下列其中一個設定：
apiKeyConfig

object (ApiKeyConfig)

選用。API 金鑰驗證的設定。
oauthConfig

object (OAuthConfig)

選用。OAuth 的設定。
serviceAgentIdTokenAuthConfig

object (ServiceAgentIdTokenAuthConfig)

選用。從 CES 服務代理程式產生的 ID 權杖驗證設定。
serviceAccountAuthConfig

object (ServiceAccountAuthConfig)

選用。服務帳戶驗證的設定。
bearerTokenConfig

object (BearerTokenConfig)

選用。不記名權杖驗證的設定。

ApiKeyConfig

JSON 表示法 
{
  "keyName": string,
  "apiKeySecretVersion": string,
  "requestLocation": enum (RequestLocation)
}
欄位
keyName

string

這是必要旗標，API 金鑰的參數名稱或標頭名稱。例如：如果 API 要求是「https://example.com/act?X-Api-Key=」，則「X-Api-Key」就是參數名稱。
apiKeySecretVersion

string

這是必要旗標，儲存 API 金鑰的 SecretManager 密鑰版本資源名稱。格式：projects/{project}/secrets/{secret}/versions/{version}

注意：您應將 roles/secretmanager.secretAccessor 角色授予 CES 服務代理人 service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com。
requestLocation

enum (RequestLocation)

這是必要旗標，要求中的金鑰位置。

OAuthConfig

JSON 表示法 
{
  "oauthGrantType": enum (OauthGrantType),
  "clientId": string,
  "clientSecretVersion": string,
  "tokenEndpoint": string,
  "scopes": [
    string
  ]
}
欄位
oauthGrantType

enum (OauthGrantType)

這是必要旗標，OAuth 授權類型。
clientId

string

這是必要旗標，OAuth 供應商提供的用戶端 ID。
clientSecretVersion

string

這是必要旗標，儲存用戶端密鑰的 SecretManager 密鑰版本資源名稱。格式：projects/{project}/secrets/{secret}/versions/{version}

注意：您應將 roles/secretmanager.secretAccessor 角色授予 CES 服務代理人 service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com。
tokenEndpoint

string

這是必要旗標，OAuth 供應商中的權杖端點，用於交換存取權杖。
scopes[]

string

選用。要授予的 OAuth 範圍。

ServiceAccountAuthConfig

JSON 表示法 
{
  "serviceAccount": string,
  "scopes": [
    string
  ]
}
欄位
serviceAccount

string

這是必要旗標，用於驗證的服務帳戶電子郵件地址。CES 會使用這個服務帳戶交換存取權杖，然後在要求的 Authorization 標頭中傳送存取權杖。

服務帳戶必須將 roles/iam.serviceAccountTokenCreator 角色授予 CES 服務代理程式 service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com。
scopes[]

string

選用。要授予的 OAuth 範圍。如未指定，則會使用預設範圍 https://www.googleapis.com/auth/cloud-platform。

BearerTokenConfig

JSON 表示法 
{
  "token": string
}
欄位
token

string

這是必要旗標，不記名權杖。格式必須為 $context.variables.<name_of_variable>。

TlsConfig

JSON 表示法 
{
  "caCerts": [
    {
      object (CaCert)
    }
  ]
}
欄位
caCerts[]

object (CaCert)

這是必要旗標，指定允許用於 HTTPS 驗證的自訂 CA 憑證清單。

CaCert

JSON 表示法 
{
  "displayName": string,
  "cert": string
}
欄位
displayName

string

這是必要旗標，允許使用的自訂 CA 憑證名稱。這可用於消除自訂 CA 憑證的歧義。
cert

string (bytes format)

這是必要旗標，用於 HTTPS 驗證的允許自訂 CA 憑證 (DER 格式)。這會覆寫預設的 SSL 信任儲存區。如為空白或未指定，CES 會使用 Google 的預設信任儲存區驗證憑證。注意：請確認 HTTPS 伺服器憑證是以「主體替代名稱」簽署。舉例來說，您可以使用下列指令自行簽署憑證： openssl x509 -req -days 200 -in example.com.csr \ -signkey example.com.key \ -out example.com.crt \ -extfile <(printf "\nsubjectAltName='DNS:www.example.com'")

Base64 編碼字串。

ServiceDirectoryConfig

JSON 表示法 
{
  "service": string
}
欄位
service

string

這是必要旗標，Service Directory 服務的名稱。格式：projects/{project}/locations/{location}/namespaces/{namespace}/services/{service}。服務目錄的位置必須與應用程式的位置相同。

GoogleSearchTool

JSON 表示法 
{
  "name": string,
  "description": string,
  "contextUrls": [
    string
  ],
  "preferredDomains": [
    string
  ],
  "excludeDomains": [
    string
  ],
  "promptConfig": {
    object (PromptConfig)
  }
}
欄位
name

string

這是必要旗標，工具名稱。
description

string

選用。工具用途說明。
contextUrls[]

string

選用。系統會直接從這些網址擷取內容，做為背景資訊和基礎。例如：「https://example.com/path.html」。最多可加入 20 個網址。
preferredDomains[]

string

選用。指定要限制搜尋結果的網域。例如：「example.com」、「another.site」。最多可指定 20 個網域。
excludeDomains[]

string

選用。要從搜尋結果中排除的網域清單。例如：「example.com」。最多可排除 2000 個網域。
promptConfig

object (PromptConfig)

選用。傳遞給規劃工具的提示指令，說明如何處理文字和語音的搜尋結果。

PromptConfig

JSON 表示法 
{
  "textPrompt": string,
  "voicePrompt": string
}
欄位
textPrompt

string

選用。定義在即時通訊對話中與代理互動時，用於系統指令的提示。如未設定，系統會使用預設提示。
voicePrompt

string

選用。定義與代理進行語音對話時，用於系統指令的提示。如未設定，系統會使用預設提示。

ConnectorTool

JSON 表示法 
{
  "connection": string,
  "action": {
    object (Action)
  },
  "authConfig": {
    object (EndUserAuthConfig)
  },
  "name": string,
  "description": string
}
欄位
connection

string

這是必要旗標，所參照 Integration Connectors 連線的完整資源名稱。格式：projects/{project}/locations/{location}/connections/{connection}
action

object (Action)

這是必要旗標，工具要執行的動作。
authConfig

object (EndUserAuthConfig)

選用。設定 Integration Connectors 的驗證處理方式。根據預設，管理員驗證會傳遞至 Integration Connectors API 要求。您可以覆寫這項設定，改用其他使用者驗證設定。注意：連線必須啟用驗證覆寫功能，才能在此指定 EUC 設定，否則 ConnectorTool 建立作業會失敗。詳情請參閱 https://cloud.google.com/application-integration/docs/configure-connectors-task#configure-authentication-override。
name

string

選用。代理可使用的工具名稱，用來決定是否呼叫這個 ConnectorTool。
description

string

選用。工具說明，代理可依據這段說明判斷是否要呼叫這個 ConnectorTool。

動作

JSON 表示法 
{
  "inputFields": [
    string
  ],
  "outputFields": [
    string
  ],

  // Union field action_spec can be only one of the following:
  "connectionActionId": string,
  "entityOperation": {
    object (EntityOperation)
  }
  // End of list of possible types for union field action_spec.
}
欄位
inputFields[]

string

選用。做為作業輸入內容的實體欄位。如未指定任何欄位，系統會使用實體的所有欄位。
outputFields[]

string

選用。要從作業傳回的實體欄位。如未指定任何欄位，系統會傳回實體的所有欄位。
聯集欄位 action_spec。工具要使用的動作設定規格。action_spec 只能是下列其中一個設定：
connectionActionId

string

工具要使用的「連線」動作 ID。
entityOperation

object (EntityOperation)

工具要使用的實體作業設定。

EntityOperation

JSON 表示法 
{
  "entityId": string,
  "operation": enum (OperationType)
}
欄位
entityId

string

這是必要旗標，實體的 ID。
operation

enum (OperationType)

這是必要旗標，要在實體上執行的作業。

EndUserAuthConfig

JSON 表示法 
{

  // Union field auth_config can be only one of the following:
  "oauth2AuthCodeConfig": {
    object (Oauth2AuthCodeConfig)
  },
  "oauth2JwtBearerConfig": {
    object (Oauth2JwtBearerConfig)
  }
  // End of list of possible types for union field auth_config.
}
欄位
聯集欄位 auth_config。驗證設定。auth_config 只能是下列其中一個設定：
oauth2AuthCodeConfig

object (Oauth2AuthCodeConfig)

Oauth 2.0 授權碼驗證。
oauth2JwtBearerConfig

object (Oauth2JwtBearerConfig)

JWT 設定檔 OAuth 2.0 授權授予驗證。

Oauth2AuthCodeConfig

JSON 表示法 
{
  "oauthToken": string
}
欄位
oauthToken

string

這是必要旗標，要傳遞的 OAuth 權杖參數名稱。格式必須為 $context.variables.<name_of_variable>。

Oauth2JwtBearerConfig

JSON 表示法 
{
  "issuer": string,
  "subject": string,
  "clientKey": string
}
欄位
issuer

string

這是必要旗標，要傳遞的發卡機構參數名稱。格式必須為 $context.variables.<name_of_variable>。
subject

string

這是必要旗標，要傳遞的主體參數名稱。格式必須為 $context.variables.<name_of_variable>。
clientKey

string

這是必要旗標，要傳遞的用戶端參數名稱。格式必須為 $context.variables.<name_of_variable>。

DataStoreTool

JSON 表示法 
{
  "name": string,
  "description": string,
  "boostSpecs": [
    {
      object (BoostSpecs)
    }
  ],
  "modalityConfigs": [
    {
      object (ModalityConfig)
    }
  ],
  "filterParameterBehavior": enum (FilterParameterBehavior),

  // Union field search_source can be only one of the following:
  "dataStoreSource": {
    object (DataStoreSource)
  },
  "engineSource": {
    object (EngineSource)
  }
  // End of list of possible types for union field search_source.
}
欄位
name

string

這是必要旗標，資料儲存庫工具名稱。
description

string

選用。工具說明。
boostSpecs[]

object (BoostSpecs)

選用。提升規格，以提升特定文件。
modalityConfigs[]

object (ModalityConfig)

選用。資料儲存庫的模態設定。
filterParameterBehavior

enum (FilterParameterBehavior)

選用。篩選器參數行為。
聯集欄位 search_source。定義搜尋來源，可以是單一資料儲存庫或引擎。search_source 只能是下列其中一個設定：
dataStoreSource

object (DataStoreSource)

選用。在單一特定 DataStore 中搜尋。
engineSource

object (EngineSource)

選用。在引擎內搜尋 (可能跨越多個 Datastore)。

DataStoreSource

JSON 表示法 
{
  "filter": string,
  "dataStore": {
    object (DataStore)
  }
}
欄位
filter

string

選用。DataStore 的篩選器規格。請參閱：https://cloud.google.com/generative-ai-app-builder/docs/filter-search-metadata
dataStore

object (DataStore)

選用。資料儲存庫。

DataStore

JSON 表示法 
{
  "name": string,
  "type": enum (DataStoreType),
  "documentProcessingMode": enum (DocumentProcessingMode),
  "displayName": string,
  "createTime": string,
  "connectorConfig": {
    object (ConnectorConfig)
  }
}
欄位
name

string

這是必要旗標，DataStore 的完整資源名稱。格式：projects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}
type

enum (DataStoreType)

僅供輸出。資料儲存庫的類型。這個欄位為唯讀，由伺服器填入。
documentProcessingMode

enum (DocumentProcessingMode)

僅供輸出。資料存放區連線的文件處理模式。僅適用於 PUBLIC_WEB 和 UNSTRUCTURED 資料儲存庫。
displayName

string

僅供輸出。資料儲存庫的顯示名稱。
createTime

string (Timestamp format)

僅供輸出。資料儲存庫的建立時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
connectorConfig

object (ConnectorConfig)

僅供輸出。資料儲存庫連線的連接器設定。

時間戳記

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
欄位
seconds

string (int64 format)

代表自 Unix 紀元 1970-01-01T00:00:00Z 起算的世界標準時間秒數。必須介於 -62135596800 和 253402300799 之間 (含)，對應至 0001-01-01T00:00:00Z 至 9999-12-31T23:59:59Z。
nanos

integer

以奈秒為單位的非負秒數小數。這個欄位是時間長度的奈秒部分，並非秒數的替代值。如果第二個值為負數，且包含分數，奈秒值仍須為非負數，且會向前計時。必須介於 0 至 999,999,999 之間 (含)。

ConnectorConfig

JSON 表示法 
{
  "collection": string,
  "collectionDisplayName": string,
  "dataSource": string
}
欄位
collection

string

資料儲存庫所屬集合的資源名稱。
collectionDisplayName

string

資料儲存庫所屬集合的顯示名稱。
dataSource

string

資料來源的名稱。例如：salesforce、jira、confluence、bigquery。

EngineSource

JSON 表示法 
{
  "engine": string,
  "dataStoreSources": [
    {
      object (DataStoreSource)
    }
  ],
  "filter": string
}
欄位
engine

string

這是必要旗標，引擎的完整資源名稱。格式：projects/{project}/locations/{location}/collections/{collection}/engines/{engine}
dataStoreSources[]

object (DataStoreSource)

選用。用於指定引擎中的特定 DataStore。如果留空，搜尋範圍會涵蓋與引擎相關聯的所有 DataStore。
filter

string

選用。套用至整個引擎搜尋的篩選器。如果提供「data_store_sources」，則不相關且不會使用。請參閱：https://cloud.google.com/generative-ai-app-builder/docs/filter-search-metadata

BoostSpecs

JSON 表示法 
{
  "dataStores": [
    string
  ],
  "spec": [
    {
      object (BoostSpec)
    }
  ]
}
欄位
dataStores[]

string

這是必要旗標，套用升幅設定的資料儲存庫。DataStore 的完整資源名稱，例如 projects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}。
spec[]

object (BoostSpec)

這是必要旗標，增強規格清單。

BoostSpec

JSON 表示法 
{
  "conditionBoostSpecs": [
    {
      object (ConditionBoostSpec)
    }
  ]
}
欄位
conditionBoostSpecs[]

object (ConditionBoostSpec)

這是必要旗標，增強規格清單。

ConditionBoostSpec

JSON 表示法 
{
  "condition": string,
  "boost": number,
  "boostControlSpec": {
    object (BoostControlSpec)
  }
}
欄位
condition

string

這是必要旗標，指定提升條件的運算式。語法與篩選運算式語法相同。目前僅支援 BCP-47 語言代碼清單。範例：如要提升英文或法文的建議：(lang_code: ANY("en", "fr"))
boost

number

選用。增幅強度，應介於 [-1, 1] 之間。如果設為負值，即代表降低排名。預設值為 0.0。

設為 1.0 可大幅提高建議的排名。不過，這並不代表經過增強的建議一定會顯示在搜尋結果頂端。

設為 -1.0 會大幅降低建議的排名。不過，系統仍可能會顯示其他相關建議。

設為 0.0 表示不套用任何增幅。系統會忽略加成條件。
boostControlSpec

object (BoostControlSpec)

選用。根據顧客定義的屬性值，為自訂排序設定複雜規格。

BoostControlSpec

JSON 表示法 
{
  "fieldName": string,
  "attributeType": enum (AttributeType),
  "interpolationType": enum (InterpolationType),
  "controlPoints": [
    {
      object (ControlPoint)
    }
  ]
}
欄位
fieldName

string

選用。系統會根據這個欄位的值決定加成金額。
attributeType

enum (AttributeType)

選用。用來決定加成金額的屬性類型。屬性值可從指定 field_name 的欄位值衍生而來。如果是數值，則很簡單，也就是 attribute_value = numerical_field_value。不過，如果是新鮮度，attribute_value = (time.now() - datetime_field_value)。
interpolationType

enum (InterpolationType)

選用。要套用的插補類型，用於連結下列控制點。
controlPoints[]

object (ControlPoint)

選用。用來定義曲線的控制點。單調函式 (透過上述 interpolation_type 定義) 會通過這裡列出的控制點。

ControlPoint

JSON 表示法 
{
  "attributeValue": string,
  "boostAmount": number
}
欄位
attributeValue

string

選用。可以是下列任一值：1. 數值欄位值。2. 新鮮度時間長度規格：值必須採用 XSD dayTimeDuration 值格式 (ISO 8601 時間長度值的受限子集)。格式為：[nD][T[nH][nM][nS]]。
boostAmount

number

選用。如果 attribute_value 評估結果為上述指定值，則分數的提升值介於 -1 到 1 之間。

ModalityConfig

JSON 表示法 
{
  "modalityType": enum (ModalityType),
  "rewriterConfig": {
    object (RewriterConfig)
  },
  "summarizationConfig": {
    object (SummarizationConfig)
  },
  "groundingConfig": {
    object (GroundingConfig)
  }
}
欄位
modalityType

enum (ModalityType)

這是必要旗標，模式類型。
rewriterConfig

object (RewriterConfig)

選用。重寫器設定。
summarizationConfig

object (SummarizationConfig)

選用。摘要設定。
groundingConfig

object (GroundingConfig)

選用。基礎設定。

RewriterConfig

JSON 表示法 
{
  "modelSettings": {
    object (ModelSettings)
  },
  "prompt": string,
  "disabled": boolean
}
欄位
modelSettings

object (ModelSettings)

這是必要旗標，LLM 模型的設定。
prompt

string

選用。提示定義。如未設定，系統會使用預設提示。
disabled

boolean

選用。重寫器是否已停用。

ModelSettings

JSON 表示法 
{
  "model": string,

  // Union field _temperature can be only one of the following:
  "temperature": number
  // End of list of possible types for union field _temperature.
}
欄位
model

string

選用。代理程式應使用的 LLM 模型。如未設定，代理程式會沿用上層代理程式的模型。

聯集欄位 _temperature。

_temperature 只能是下列其中一項：
temperature

number

選用。如果設定這項引數，LLM 模型就會使用這個溫度。溫度會控制模型回覆的隨機程度。溫度越低，生成的回覆就越容易預測。溫度越高，生成的回覆就越有創意。

SummarizationConfig

JSON 表示法 
{
  "modelSettings": {
    object (ModelSettings)
  },
  "prompt": string,
  "disabled": boolean
}
欄位
modelSettings

object (ModelSettings)

選用。LLM 模型的設定。
prompt

string

選用。提示定義。如未設定，系統會使用預設提示。
disabled

boolean

選用。摘要功能是否已停用。

GroundingConfig

JSON 表示法 
{
  "groundingLevel": number,
  "disabled": boolean
}
欄位
groundingLevel

number

選用。根據擷取的來源，答案的根據性門檻。這個值的可設定範圍為 [1, 5]。這個層級可用於設定答案的依據程度門檻，也就是說，如果答案的依據程度分數低於門檻，系統只會傳回相關的程式碼片段。

舉例來說，如果層級為 3，回應的根據事實程度分數就必須達到 3 分以上，才會傳回。
disabled

boolean

選用。是否停用接地。

PythonFunction

JSON 表示法 
{
  "name": string,
  "pythonCode": string,
  "description": string
}
欄位
name

string

選用。要執行的 Python 函式名稱。必須與 Python 程式碼中定義的 Python 函式名稱相符。區分大小寫。如未提供名稱，系統會使用 Python 程式碼中定義的第一個函式。
pythonCode

string

選用。工具要執行的 Python 程式碼。
description

string

僅供輸出。Python 函式的說明，從 Python 程式碼的 docstring 剖析而來。

McpTool

JSON 表示法 
{
  "name": string,
  "description": string,
  "inputSchema": {
    object (Schema)
  },
  "outputSchema": {
    object (Schema)
  },
  "serverAddress": string,
  "apiAuthentication": {
    object (ApiAuthentication)
  },
  "tlsConfig": {
    object (TlsConfig)
  },
  "serviceDirectoryConfig": {
    object (ServiceDirectoryConfig)
  }
}
欄位
name

string

這是必要旗標，MCP 工具的名稱。
description

string

選用。MCP 工具的說明。
inputSchema

object (Schema)

選用。MCP 工具輸入引數的結構定義。
outputSchema

object (Schema)

選用。MCP 工具輸出引數的結構定義。
serverAddress

string

這是必要旗標，MCP 伺服器的伺服器位址，例如 「https://example.com/mcp/」。如果伺服器是使用 MCP SDK 建構，網址應加上「/mcp/」後置字串。僅支援以可串流 HTTP 傳輸為基礎的伺服器。這與 McpToolset 中的 server_address 相同。詳情請參閱 https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http。
apiAuthentication

object (ApiAuthentication)

選用。執行工具時，必須提供 MCP 伺服器的驗證資訊。如果是持有人權杖驗證，權杖僅適用於工具執行，不適用於列出工具。這項功能需要工具在未經驗證的情況下也能列出。
tlsConfig

object (TlsConfig)

選用。傳輸層安全標準 (TLS) 設定。包含用戶端應信任的自訂伺服器憑證。
serviceDirectoryConfig

object (ServiceDirectoryConfig)

選用。VPC-SC 的 Service Directory 設定，用於解析範圍內的服務名稱。

FileSearchTool

JSON 表示法 
{
  "corpusType": enum (CorpusType),
  "name": string,
  "description": string,
  "fileCorpus": string
}
欄位
corpusType

enum (CorpusType)

選用。語料庫類型。預設值為 FULLY_MANAGED。
name

string

這是必要旗標，工具名稱。
description

string

選用。工具說明。
fileCorpus

string

選用。儲存檔案的語料庫。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus}

SystemTool

JSON 表示法 
{
  "name": string,
  "description": string
}
欄位
name

string

這是必要旗標，系統工具的名稱。
description

string

僅供輸出。系統工具的說明。

WidgetTool

JSON 表示法 
{
  "name": string,
  "description": string,
  "widgetType": enum (WidgetType),

  // Union field input can be only one of the following:
  "parameters": {
    object (Schema)
  }
  // End of list of possible types for union field input.
}
欄位
name

string

這是必要旗標，小工具工具的顯示名稱。
description

string

選用。小工具工具的說明。
widgetType

enum (WidgetType)

選用。小工具工具的類型。如未指定，預設類型為 CUSTOMIZED。
聯集欄位 input。小工具工具的輸入內容。input 只能是下列其中一個設定：
parameters

object (Schema)

選用。小工具工具的輸入參數。

ToolFakeConfig

JSON 表示法 
{
  "enableFakeMode": boolean,

  // Union field tool_response can be only one of the following:
  "codeBlock": {
    object (CodeBlock)
  }
  // End of list of possible types for union field tool_response.
}
欄位
enableFakeMode

boolean

選用。工具是否使用模擬模式。
聯集欄位 tool_response。回應可以是靜態，也可以由 Python 函式提供。tool_response 只能是下列其中一個設定：
codeBlock

object (CodeBlock)

選用。要執行的程式碼區塊，而非實際的工具呼叫。

CodeBlock

JSON 表示法 
{
  "pythonCode": string
}
欄位
pythonCode

string

這是必要旗標，在工具模擬模式中呼叫的 Python 程式碼。預期的 Python 函式簽章 - 如要擷取所有工具呼叫： def fake_tool_call(tool: Tool, input: dict[str, Any], callback_context: CallbackContext) -> Optional[dict[str, Any]]: 如要擷取特定工具呼叫： def fake_{tool_id}(tool: Tool, input: dict[str, Any], callback_context: CallbackContext) -> Optional[dict[str, Any]]: 如果函式傳回 None，系統會改為叫用實際工具。

工具註解

破壞性提示：✅ | 等冪提示：❌ | 唯讀提示：❌ | 開放世界提示：❌