Resource: Extension
extensions are tools for large language models to access external data, run computations, etc.
name
string
Identifier. The resource name of the Extension.
displayName
string
Required. The display name of the Extension. The name can be up to 128 characters long and can consist of any UTF-8 characters.
description
string
Optional. The description of the Extension.
createTime
string (Timestamp
format)
Output only. timestamp when this Extension was created.
A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z"
and "2014-10-02T15:01:23.045123456Z"
.
updateTime
string (Timestamp
format)
Output only. timestamp when this Extension was most recently updated.
A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z"
and "2014-10-02T15:01:23.045123456Z"
.
etag
string
Optional. Used to perform consistent read-modify-write updates. If not set, a blind "overwrite" update happens.
manifest
object (ExtensionManifest
)
Required. Manifest of the Extension.
extensionOperations[]
object (ExtensionOperation
)
Output only. Supported operations.
runtimeConfig
object (RuntimeConfig
)
Optional. Runtime config controlling the runtime behavior of this Extension.
toolUseExamples[]
object (ToolUseExample
)
Optional. Examples to illustrate the usage of the extension as a tool.
privateServiceConnectConfig
object (ExtensionPrivateServiceConnectConfig
)
Optional. The PrivateServiceConnect config for the extension. If specified, the service endpoints associated with the Extension should be registered with private network access in the provided service Directory (https://cloud.google.com/service-directory/docs/configuring-private-network-access).
If the service contains more than one endpoint with a network, the service will arbitrarilty choose one of the endpoints to use for extension execution.
JSON representation |
---|
{ "name": string, "displayName": string, "description": string, "createTime": string, "updateTime": string, "etag": string, "manifest": { object ( |
ExtensionManifest
Manifest spec of an Extension needed for runtime execution.
name
string
Required. Extension name shown to the LLM. The name can be up to 128 characters long.
description
string
Required. The natural language description shown to the LLM. It should describe the usage of the extension, and is essential for the LLM to perform reasoning. e.g., if the extension is a data store, you can let the LLM know what data it contains.
apiSpec
object (ApiSpec
)
Required. Immutable. The API specification shown to the LLM.
authConfig
object (AuthConfig
)
Required. Immutable. type of auth supported by this extension.
JSON representation |
---|
{ "name": string, "description": string, "apiSpec": { object ( |
ApiSpec
The API specification shown to the LLM.
Union field api_spec
.
api_spec
can be only one of the following:
openApiYaml
string
The API spec in Open API standard and YAML format.
openApiGcsUri
string
Cloud Storage URI pointing to the OpenAPI spec.
JSON representation |
---|
{ // Union field |
AuthConfig
Auth configuration to run the extension.
authType
enum (AuthType
)
type of auth scheme.
Union field auth_config
.
auth_config
can be only one of the following:
apiKeyConfig
object (ApiKeyConfig
)
Config for API key auth.
httpBasicAuthConfig
object (HttpBasicAuthConfig
)
Config for HTTP Basic auth.
googleServiceAccountConfig
object (GoogleServiceAccountConfig
)
Config for Google service Account auth.
oauthConfig
object (OauthConfig
)
Config for user oauth.
oidcConfig
object (OidcConfig
)
Config for user OIDC auth.
JSON representation |
---|
{ "authType": enum ( |
ApiKeyConfig
Config for authentication with API key.
name
string
Required. The parameter name of the API key. E.g. If the API request is "https://example.com/act?apiKey=
apiKeySecret
string
Required. The name of the SecretManager secret version resource storing the API key. Format: projects/{project}/secrets/{secrete}/versions/{version}
- If specified, the
secretmanager.versions.access
permission should be granted to Vertex AI Extension service Agent (https://cloud.google.com/vertex-ai/docs/general/access-control#service-agents) on the specified resource.
httpElementLocation
enum (HttpElementLocation
)
Required. The location of the API key.
JSON representation |
---|
{
"name": string,
"apiKeySecret": string,
"httpElementLocation": enum ( |
HttpElementLocation
Enum of location an HTTP element can be.
Enums | |
---|---|
HTTP_IN_UNSPECIFIED |
|
HTTP_IN_QUERY |
Element is in the HTTP request query. |
HTTP_IN_HEADER |
Element is in the HTTP request header. |
HTTP_IN_PATH |
Element is in the HTTP request path. |
HTTP_IN_BODY |
Element is in the HTTP request body. |
HTTP_IN_COOKIE |
Element is in the HTTP request cookie. |
HttpBasicAuthConfig
Config for HTTP Basic Authentication.
credentialSecret
string
Required. The name of the SecretManager secret version resource storing the base64 encoded credentials. Format: projects/{project}/secrets/{secrete}/versions/{version}
- If specified, the
secretmanager.versions.access
permission should be granted to Vertex AI Extension service Agent (https://cloud.google.com/vertex-ai/docs/general/access-control#service-agents) on the specified resource.
JSON representation |
---|
{ "credentialSecret": string } |
GoogleServiceAccountConfig
Config for Google service Account Authentication.
serviceAccount
string
Optional. The service account that the extension execution service runs as.
If the service account is specified, the
iam.serviceAccounts.getAccessToken
permission should be granted to Vertex AI Extension service Agent (https://cloud.google.com/vertex-ai/docs/general/access-control#service-agents) on the specified service account.If not specified, the Vertex AI Extension service Agent will be used to execute the Extension.
JSON representation |
---|
{ "serviceAccount": string } |
OauthConfig
Config for user oauth.
Union field oauth_config
.
oauth_config
can be only one of the following:
accessToken
string
Access token for extension endpoint. Only used to propagate token from [[ExecuteExtensionRequest.runtime_auth_config]] at request time.
serviceAccount
string
The service account used to generate access tokens for executing the Extension.
- If the service account is specified, the
iam.serviceAccounts.getAccessToken
permission should be granted to Vertex AI Extension service Agent (https://cloud.google.com/vertex-ai/docs/general/access-control#service-agents) on the provided service account.
JSON representation |
---|
{ // Union field |
OidcConfig
Config for user OIDC auth.
Union field oidc_config
.
oidc_config
can be only one of the following:
idToken
string
OpenID Connect formatted id token for extension endpoint. Only used to propagate token from [[ExecuteExtensionRequest.runtime_auth_config]] at request time.
serviceAccount
string
The service account used to generate an OpenID Connect (OIDC)-compatible JWT token signed by the Google OIDC Provider (accounts.google.com) for extension endpoint (https://cloud.google.com/iam/docs/create-short-lived-credentials-direct#sa-credentials-oidc).
The audience for the token will be set to the URL in the server url defined in the OpenApi spec.
If the service account is provided, the service account should grant
iam.serviceAccounts.getOpenIdToken
permission to Vertex AI Extension service Agent (https://cloud.google.com/vertex-ai/docs/general/access-control#service-agents).
JSON representation |
---|
{ // Union field |
AuthType
type of Auth.
Enums | |
---|---|
AUTH_TYPE_UNSPECIFIED |
|
NO_AUTH |
No Auth. |
API_KEY_AUTH |
API Key Auth. |
HTTP_BASIC_AUTH |
HTTP Basic Auth. |
GOOGLE_SERVICE_ACCOUNT_AUTH |
Google service Account Auth. |
OAUTH |
OAuth auth. |
OIDC_AUTH |
OpenID Connect (OIDC) Auth. |
ExtensionOperation
Operation of an extension.
operationId
string
Operation id that uniquely identifies the operations among the extension. See: "Operation Object" in https://swagger.io/specification/.
This field is parsed from the OpenAPI spec. For HTTP extensions, if it does not exist in the spec, we will generate one from the HTTP method and path.
functionDeclaration
object (FunctionDeclaration
)
Output only. Structured representation of a function declaration as defined by the OpenAPI Spec.
JSON representation |
---|
{
"operationId": string,
"functionDeclaration": {
object ( |
RuntimeConfig
Runtime configuration to run the extension.
defaultParams
object (Struct
format)
Optional. Default parameters that will be set for all the execution of this extension. If specified, the parameter values can be overridden by values in [[ExecuteExtensionRequest.operation_params]] at request time.
The struct should be in a form of map with param name as the key and actual param value as the value. E.g. If this operation requires a param "name" to be set to "abc". you can set this to something like {"name": "abc"}.
GoogleFirstPartyExtensionConfig
. Runtime configurations for Google first party extensions. GoogleFirstPartyExtensionConfig
can be only one of the following:
codeInterpreterRuntimeConfig
object (CodeInterpreterRuntimeConfig
)
code execution runtime configurations for code interpreter extension.
vertexAiSearchRuntimeConfig
object (VertexAISearchRuntimeConfig
)
Runtime configuration for Vertex AI Search extension.
JSON representation |
---|
{ "defaultParams": { object }, // Union field |
CodeInterpreterRuntimeConfig
fileInputGcsBucket
string
Optional. The Cloud Storage bucket for file input of this Extension. If specified, support input from the Cloud Storage bucket. Vertex Extension Custom code service Agent should be granted file reader to this bucket. If not specified, the extension will only accept file contents from request body and reject Cloud Storage file inputs.
fileOutputGcsBucket
string
Optional. The Cloud Storage bucket for file output of this Extension. If specified, write all output files to the Cloud Storage bucket. Vertex Extension Custom code service Agent should be granted file writer to this bucket. If not specified, the file content will be output in response body.
JSON representation |
---|
{ "fileInputGcsBucket": string, "fileOutputGcsBucket": string } |
VertexAISearchRuntimeConfig
servingConfigName
string
Optional. Vertex AI Search serving config name. Format: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}
engineId
string
Optional. Vertex AI Search engine id. This is used to construct the search request. By setting this engineId, API will construct the serving config using the default value to call search API for the user. The engineId and servingConfigName cannot both be empty at the same time.
JSON representation |
---|
{ "servingConfigName": string, "engineId": string } |
ToolUseExample
A single example of the tool usage.
displayName
string
Required. The display name for example.
query
string
Required. Query that should be routed to this tool.
requestParams
object (Struct
format)
Request parameters used for executing this tool.
responseParams
object (Struct
format)
Response parameters generated by this tool.
responseSummary
string
Summary of the tool response to the user query.
Target
. Target tool to use. Target
can be only one of the following:
extensionOperation
object (ExtensionOperation
)
Extension operation to call.
functionName
string
Function name to call.
JSON representation |
---|
{ "displayName": string, "query": string, "requestParams": { object }, "responseParams": { object }, "responseSummary": string, // Union field |
ExtensionOperation
Identifies one operation of the extension.
extension
string
Resource name of the extension.
operationId
string
Required. Operation id of the extension.
JSON representation |
---|
{ "extension": string, "operationId": string } |
ExtensionPrivateServiceConnectConfig
PrivateExtensionConfig configuration for the extension.
serviceDirectory
string
Required. The service Directory resource name in which the service endpoints associated to the extension are registered. Format: projects/{projectId}/locations/{locationId}/namespaces/{namespace_id}/services/{serviceId}
- The Vertex AI Extension service Agent (https://cloud.google.com/vertex-ai/docs/general/access-control#service-agents) should be granted
servicedirectory.viewer
andservicedirectory.pscAuthorizedService
roles on the resource.
JSON representation |
---|
{ "serviceDirectory": string } |
Methods |
|
---|---|
|
Deletes an Extension. |
|
Executes the request against a given extension. |
|
Gets an Extension. |
|
Imports an Extension. |
|
Lists Extensions in a location. |
|
Updates an Extension. |
|
Queries an extension with a default controller. |