REST Resource: projects.locations.apps.tools

資源：工具

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

JSON 表示法 
{
  "name": string,
  "displayName": string,
  "executionType": enum (ExecutionType),
  "timeout": string,
  "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)
  },
  "agentTool": {
    object (AgentTool)
  },
  "widgetTool": {
    object (WidgetTool)
  },
  "remoteAgentTool": {
    object (RemoteAgentTool)
  }
  // End of list of possible types for union field tool_type.
}
欄位
name

string

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)

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

string (Duration format)

選用。工具執行作業的逾時時間。如未設定，SYNCHRONOUS 工具的預設逾時時間為 30 秒，ASYNCHRONOUS 工具則為 60 秒。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。
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)

選用。系統工具。
agentTool

object (AgentTool)

選用。代理工具。
widgetTool

object (WidgetTool)

選用。小工具工具。
remoteAgentTool

object (RemoteAgentTool)

選用。遠端代理程式工具。

ClientFunction

代表代理可叫用的用戶端函式。代理選擇工具後，控制權會交給用戶端。用戶端負責執行函式，並以 ToolResponse 形式傳回結果，繼續與代理程式互動。

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

string

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

string

選用。函式說明。
parameters

object (Schema)

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

object (Schema)

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

OpenApiTool

由 OpenAPI 結構定義的遠端 API 工具。

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 預留位置，系統就會取代結構定義中的預留位置。

GoogleSearchTool

代表執行 Google 網頁搜尋以取得基礎資訊的工具。請參閱 https://cloud.google.com/customer-engagement-ai/conversational-agents/ps/tool#google-search。

JSON 表示法 
{
  "name": string,
  "description": string,
  "contextUrls": [
    string
  ],
  "preferredDomains": [
    string
  ],
  "excludeDomains": [
    string
  ],
  "promptConfig": {
    object (GoogleSearchTool.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 (GoogleSearchTool.PromptConfig)

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

GoogleSearchTool.PromptConfig

模型在處理或摘要 Google 搜尋結果時使用的提示設定。

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

string

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

string

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

ConnectorTool

ConnectorTool 可連線至不同整合服務。詳情請參閱：https://cloud.google.com/integration-connectors/docs/overview。

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。

DataStoreTool

從 Vertex AI Search 資料儲存庫或引擎擷取資料，做為回覆內容的依據。接受資料儲存庫或引擎，但不能同時接受兩者。請參閱 Vertex AI Search：https://cloud.google.com/generative-ai-app-builder/docs/enterprise-search-introduction。

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

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

string

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

string

選用。工具說明。
boostSpecs[]

object (DataStoreTool.BoostSpecs)

選用。增強規格，以提升特定文件的曝光度。
modalityConfigs[]

object (DataStoreTool.ModalityConfig)

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

enum (DataStoreTool.FilterParameterBehavior)

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

object (DataStoreTool.DataStoreSource)

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

object (DataStoreTool.EngineSource)

選用。在引擎內搜尋 (可能跨越多個資料儲存區)。

DataStoreTool.DataStoreSource

設定在特定 DataStore 中搜尋。

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

Vertex AI Search 中的 DataStore 資源。

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

string

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

enum (DataStore.DataStoreType)

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

enum (DataStore.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 (DataStore.ConnectorConfig)

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

DataStore.DataStoreType

資料儲存庫的類型。

列舉
DATA_STORE_TYPE_UNSPECIFIED 不指定。這個值表示未指定資料儲存庫類型，因此搜尋時不會使用。
PUBLIC_WEB 包含公開網頁內容的資料儲存庫。
UNSTRUCTURED 包含非結構化私人資料的資料儲存庫。
FAQ 包含結構化資料的資料儲存庫，可用做常見問題。
CONNECTOR 資料儲存庫，可做為第一方或第三方服務的連接器。

DataStore.DocumentProcessingMode

資料儲存庫的文件處理模式。

列舉
DOCUMENT_PROCESSING_MODE_UNSPECIFIED 不指定。
DOCUMENTS 文件會以文件形式處理。
CHUNKS 文件會轉換為區塊。

DataStore.ConnectorConfig

資料儲存庫連線的連接器設定。

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

string

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

string

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

string

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

DataStoreTool.EngineSource

設定在引擎內搜尋，可能指定特定資料儲存區。

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

string

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

object (DataStoreTool.DataStoreSource)

選用。用於指定 Engine 內的特定 DataStore。如果留空，搜尋範圍會涵蓋與引擎相關聯的所有資料存放區。
filter

string

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

DataStoreTool.BoostSpecs

增強規格，以提升特定文件的曝光度。詳情請參閱 https://cloud.google.com/generative-ai-app-builder/docs/boosting。

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

string

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

object (DataStoreTool.BoostSpec)

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

DataStoreTool.BoostSpec

增強規格，以提升特定文件的曝光度。

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

object (DataStoreTool.BoostSpec.ConditionBoostSpec)

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

DataStoreTool.BoostSpec.ConditionBoostSpec

增強條件的規格。

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

string

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

number

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

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

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

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

object (DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec)

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

DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec

根據顧客指定的屬性值自訂排序的規格。與上述簡單的 (條件、加成) 組合相比，這項功能提供更多控制選項，可自訂排名。

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

string

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

enum (DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.AttributeType)

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

enum (DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.InterpolationType)

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

object (DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.ControlPoint)

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

DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.AttributeType

要套用自訂排序的屬性(或函式)。

列舉
ATTRIBUTE_TYPE_UNSPECIFIED 未指定 AttributeType。
NUMERICAL 系統會根據數值欄位的值，動態更新加成金額。在這種情況下，控制點的 attributeValue (x 值) 會是指定 boostAmount 的數值欄位實際值。
FRESHNESS 如果是新鮮度用途，屬性值會是目前時間與指定 datetime 欄位中日期之間的時間長度。這個值的格式必須為 XSD dayTimeDuration 值 (ISO 8601 時間長度值的受限子集)。格式為：[nD][T[nH][nM][nS]]。例如：5D、3DT12H30M、T24H。

DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.InterpolationType

要套用的插補類型。預設為線性 (分段線性)。

列舉
INTERPOLATION_TYPE_UNSPECIFIED 未指定插補類型。在本例中，預設為「線性」。
LINEAR 系統會套用分段線性插值。

DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.ControlPoint

用來定義曲線的控制點。透過這些控制點定義的曲線只能單調遞增或遞減(可接受常數值)。

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

string

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

number

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

DataStoreTool.ModalityConfig

如有指定，系統會為指定模式套用給定的設定。

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

enum (DataStoreTool.ModalityConfig.ModalityType)

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

object (DataStoreTool.RewriterConfig)

選用。重寫器設定。
summarizationConfig

object (DataStoreTool.SummarizationConfig)

選用。摘要設定。
groundingConfig

object (DataStoreTool.GroundingConfig)

選用。基礎設定。

DataStoreTool.ModalityConfig.ModalityType

模式類型。

列舉
MODALITY_TYPE_UNSPECIFIED 未指定模態類型。
TEXT 文字模態。
AUDIO 音訊模式。

DataStoreTool.RewriterConfig

重寫器設定。

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

object (ModelSettings)

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

string

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

boolean

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

DataStoreTool.SummarizationConfig

摘要設定。

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

object (ModelSettings)

選用。LLM 模型的設定。
prompt

string

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

boolean

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

DataStoreTool.GroundingConfig

接地設定。

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

number

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

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

boolean

選用。是否停用基礎模型。

DataStoreTool.FilterParameterBehavior

篩選器參數行為。

列舉
FILTER_PARAMETER_BEHAVIOR_UNSPECIFIED 預設篩選器行為。為連接器資料存放區加入篩選器參數。如果是其餘資料儲存庫類型，則會省略篩選器輸入參數。
ALWAYS_INCLUDE 一律為所有資料儲存區類型加入篩選條件參數。
NEVER_INCLUDE 無論資料儲存區類型為何，篩選器參數一律不會納入工具參數清單。

PythonFunction

Python 函式工具。

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

string

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

string

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

string

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

McpTool

MCP 工具。詳情請參閱 https://modelcontextprotocol.io/specification/2025-06-18/server/tools。

JSON 表示法 
{
  "name": string,
  "description": string,
  "inputSchema": {
    object (Schema)
  },
  "outputSchema": {
    object (Schema)
  },
  "serverAddress": string,
  "apiAuthentication": {
    object (ApiAuthentication)
  },
  "tlsConfig": {
    object (TlsConfig)
  },
  "serviceDirectoryConfig": {
    object (ServiceDirectoryConfig)
  },
  "customHeaders": {
    string: string,
    ...
  }
}
欄位
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 中的 serverAddress 相同。詳情請參閱 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 設定，用於解析範圍內的服務名稱。
customHeaders

map (key: string, value: string)

選用。要在傳送至 MCP 伺服器的要求中加入的自訂標頭。值必須採用 $context.variables.<name_of_variable> 格式，且可在工作階段變數中設定。詳情請參閱 https://docs.cloud.google.com/customer-engagement-ai/conversational-agents/ps/tool/open-api#openapi-injection。

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

FileSearchTool

檔案搜尋工具可讓代理程式搜尋應用程式/代理程式開發人員上傳的檔案。這項功能提供預設設定，可對上傳的檔案進行相對優質的搜尋，並摘要擷取的結果。

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

enum (FileSearchTool.CorpusType)

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

string

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

string

選用。工具說明。
fileCorpus

string

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

FileSearchTool.CorpusType

Vertex RAG 語料庫的類型。

列舉
CORPUS_TYPE_UNSPECIFIED 未指定語料庫類型。
USER_OWNED 使用者建立並擁有語料庫。
FULLY_MANAGED 代理程式會建立語料庫。

SystemTool

預先定義的系統工具。

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

string

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

string

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

AgentTool

代表可讓代理呼叫其他代理的工具。

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

string

這是必要旗標，代理程式工具的名稱。
description

string

選用。工具用途說明。
rootAgent
(deprecated)

string

選用。已淘汰：請改用 agent。工具的進入點，也就是根代理程式的資源名稱。格式：projects/{project}/locations/{location}/agents/{agent}
agent

string

選用。工具的進入點代理程式資源名稱。格式：projects/{project}/locations/{location}/agents/{agent}

WidgetTool

代表代理可叫用的 Widget 工具。代理程式選擇工具後，會將小工具傳回給用戶端。用戶端負責處理小工具，並產生下一個使用者查詢，以繼續與代理程式互動。

JSON 表示法 
{
  "name": string,
  "description": string,
  "widgetType": enum (WidgetTool.WidgetType),
  "uiConfig": {
    object
  },
  "dataMapping": {
    object (WidgetTool.DataMapping)
  },
  "textResponseConfig": {
    object (WidgetTool.TextResponseConfig)
  },

  // 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 (WidgetTool.WidgetType)

選用。小工具工具的類型。如未指定，預設類型為 CUSTOMIZED。
uiConfig

object (Struct format)

選用。用於算繪小工具的設定。
dataMapping

object (WidgetTool.DataMapping)

選用。這個對應會定義來源工具的資料如何對應至小工具的輸入參數。
textResponseConfig

object (WidgetTool.TextResponseConfig)

選用。一律包含文字回覆的設定。
聯集欄位 input。小工具工具的輸入內容。input 只能是下列其中一個設定：
parameters

object (Schema)

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

WidgetTool.WidgetType

所有可用的小工具類型。日後可能會在這個列舉中新增值。

列舉
WIDGET_TYPE_UNSPECIFIED 未指定的小工具類型。
CUSTOM 自訂小工具類型。
PRODUCT_DETAILS 產品詳細資料小工具。
QUICK_ACTIONS 快速操作小工具。
PRODUCT_COMPARISON 產品比較小工具。
ADVANCED_PRODUCT_DETAILS 進階產品詳細資料小工具。
SHORT_FORM Shorts 小工具。
OVERALL_SATISFACTION 整體滿意度小工具。
ORDER_SUMMARY 訂單摘要小工具。
APPOINTMENT_DETAILS 預約詳細資料小工具。
APPOINTMENT_SCHEDULER 預約時間表小工具。
CONTACT_FORM 聯絡表單小工具。

WidgetTool.DataMapping

設定如何將來源工具的資料對應至小工具的輸入參數。

JSON 表示法 
{
  "sourceToolName": string,
  "fieldMappings": {
    string: string,
    ...
  },
  "pythonFunction": {
    object (PythonFunction)
  },
  "mode": enum (WidgetTool.DataMapping.Mode),
  "pythonScript": string
}
欄位
sourceToolName

string

選用。提供小工具資料的工具資源名稱 (例如搜尋工具或自訂函式)。格式：projects/{project}/locations/{location}/agents/{agent}/tools/{tool}
fieldMappings

map (key: string, value: string)

選用。小工具輸入參數欄位對應至來源工具相應輸出欄位的對應表。

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

object (PythonFunction)

選用。Python 函式的設定，用於將來源工具的輸出內容轉換為小工具的輸入格式。
mode

enum (WidgetTool.DataMapping.Mode)

選用。資料對應模式。
pythonScript
(deprecated)

string

已淘汰：請改用 pythonFunction。

WidgetTool.DataMapping.Mode

用來將來源工具中的資料對應至小工具的策略。

列舉
MODE_UNSPECIFIED 未指定模式。
FIELD_MAPPING 使用 fieldMappings 對應轉換資料。
PYTHON_SCRIPT 使用 pythonScript 轉換資料。

WidgetTool.TextResponseConfig

隨小工具傳回的文字回覆設定。

JSON 表示法 
{
  "type": enum (WidgetTool.TextResponseConfig.Type),
  "staticText": string,
  "textResponseInstruction": string
}
欄位
type

enum (WidgetTool.TextResponseConfig.Type)

選用。提供文字回覆的策略。
staticText

string

選用。當類型為 STATIC 時要傳回的靜態文字回應。
textResponseInstruction

string

選用。指示 LLM 如何生成文字回覆。如果類型為 LLM_GENERATED，則做為文字回應參數的說明。

WidgetTool.TextResponseConfig.Type

定義如何生成文字回覆。

列舉
TYPE_UNSPECIFIED 未指定類型。
NONE LLM 會根據對話脈絡，動態決定是否要連同小工具生成文字回覆。
LLM_GENERATED 系統明確要求 LLM 生成文字回覆。
STATIC 一律使用預先定義的靜態文字回應。

RemoteAgentTool

代表可讓代理呼叫其他遠端代理程式的工具。

JSON 表示法 
{
  "name": string,
  "description": string,
  "agentCard": {
    object (AgentCard)
  }
}
欄位
name

string

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

string

這是必要旗標，工具說明。
agentCard

object (AgentCard)

這是必要旗標，這個工具呼叫的遠端代理程式資訊卡。

AgentCard

AgentCard 會傳達遠端代理程式的重要資訊。這是 A2A 通訊協定中定義的 AgentCard 簡化版本 https://a2a-protocol.org/dev/specification/#441-agentcard

JSON 表示法 
{
  "name": string,
  "description": string,
  "supportedInterfaces": [
    {
      object (AgentInterface)
    }
  ],
  "version": string,
  "skills": [
    {
      object (AgentSkill)
    }
  ]
}
欄位
name

string

這是必要旗標，人類可讀的代理名稱。
description

string

這是必要旗標，代理程式的動作/解決方案空間說明。
supportedInterfaces[]

object (AgentInterface)

這是必要旗標，支援的介面排序清單。建議使用第一個項目。
version

string

這是必要旗標，代理程式版本。
skills[]

object (AgentSkill)

這是必要旗標，技能代表代理可執行的能力單位。這可能有點抽象，但代表代理程式極有可能成功執行的動作。

AgentInterface

宣告與代理互動的目標網址、傳輸方式和通訊協定版本組合。這項功能可讓代理程式透過多種通訊協定繫結機制，公開相同的功能。

JSON 表示法 
{
  "url": string,
  "protocolBinding": string,
  "tenant": string,
  "protocolVersion": string
}
欄位
url

string

這是必要旗標，這個介面的網址。在正式環境中，必須是有效的絕對 HTTPS 網址。例如：「https://api.example.com/a2a/v1」、「https://grpc.example.com/a2a」
protocolBinding

string

這是必要旗標，這個網址支援的通訊協定繫結。這是開放式表單字串，可輕鬆擴充其他通訊協定繫結。官方支援的核心格式為 JSONRPC、GRPC 和 HTTP+JSON。
tenant

string

呼叫代理程式時，要求中使用的租戶 ID。
protocolVersion

string

這是必要旗標，這個介面公開的 A2A 通訊協定版本。請使用每個主要版本的最新支援子版本。例如：「0.3」、「1.0」

AgentSkill

代表代理可執行的特定能力或函式。

JSON 表示法 
{
  "id": string,
  "name": string,
  "description": string,
  "tags": [
    string
  ],
  "examples": [
    string
  ],
  "inputModes": [
    string
  ],
  "outputModes": [
    string
  ]
}
欄位
id

string

這是必要旗標，專員技能的專屬 ID。
name

string

這是必要旗標，使用者可解讀的技能名稱。
description

string

這是必要旗標，技能的詳細說明。
tags[]

string

這是必要旗標，一組描述技能功能的關鍵字。
examples[]

string

這項技能可處理的提示或情境範例。
inputModes[]

string

這項技能支援的輸入媒體類型組合，會覆寫代理程式的預設值。
outputModes[]

string

這項技能支援的輸出媒體類型組合，會覆寫代理程式的預設值。

方法

create

 在指定應用程式中建立新工具。

delete

 刪除指定工具。

get

 取得指定工具的詳細資料。

list

 列出指定應用程式中的工具。

patch

 更新指定的工具。