From 7870cbd33d27900081e3747b184779603d6c53d1 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Tue, 26 Mar 2024 10:19:48 -0700 Subject: [PATCH] feat: add Vertex AI extension registry and execution related API and services to v1beta1 client docs: Update comment for `name` and `parameters` in message `.google.cloud.aiplatform.v1beta1.FunctionDeclaration` PiperOrigin-RevId: 619232581 --- google/cloud/aiplatform/v1beta1/BUILD.bazel | 3 + .../v1beta1/aiplatform_v1beta1.yaml | 15 + .../cloud/aiplatform/v1beta1/extension.proto | 386 ++++++++++++++++++ .../v1beta1/extension_execution_service.proto | 135 ++++++ .../v1beta1/extension_registry_service.proto | 212 ++++++++++ google/cloud/aiplatform/v1beta1/tool.proto | 53 ++- 6 files changed, 800 insertions(+), 4 deletions(-) create mode 100644 google/cloud/aiplatform/v1beta1/extension.proto create mode 100644 google/cloud/aiplatform/v1beta1/extension_execution_service.proto create mode 100644 google/cloud/aiplatform/v1beta1/extension_registry_service.proto diff --git a/google/cloud/aiplatform/v1beta1/BUILD.bazel b/google/cloud/aiplatform/v1beta1/BUILD.bazel index 6f2f5d5ca99a2..e3b262dcd4cce 100644 --- a/google/cloud/aiplatform/v1beta1/BUILD.bazel +++ b/google/cloud/aiplatform/v1beta1/BUILD.bazel @@ -47,6 +47,9 @@ proto_library( "evaluated_annotation.proto", "evaluation_service.proto", "event.proto", + "extension.proto", + "extension_execution_service.proto", + "extension_registry_service.proto", "execution.proto", "explanation.proto", "explanation_metadata.proto", diff --git a/google/cloud/aiplatform/v1beta1/aiplatform_v1beta1.yaml b/google/cloud/aiplatform/v1beta1/aiplatform_v1beta1.yaml index fa49005e56633..e5d600e4e105d 100644 --- a/google/cloud/aiplatform/v1beta1/aiplatform_v1beta1.yaml +++ b/google/cloud/aiplatform/v1beta1/aiplatform_v1beta1.yaml @@ -8,6 +8,8 @@ apis: - name: google.cloud.aiplatform.v1beta1.DeploymentResourcePoolService - name: google.cloud.aiplatform.v1beta1.EndpointService - name: google.cloud.aiplatform.v1beta1.EvaluationService +- name: google.cloud.aiplatform.v1beta1.ExtensionExecutionService +- name: google.cloud.aiplatform.v1beta1.ExtensionRegistryService - name: google.cloud.aiplatform.v1beta1.FeatureOnlineStoreAdminService - name: google.cloud.aiplatform.v1beta1.FeatureOnlineStoreService - name: google.cloud.aiplatform.v1beta1.FeatureRegistryService @@ -85,6 +87,7 @@ types: - name: google.cloud.aiplatform.v1beta1.FeatureView - name: google.cloud.aiplatform.v1beta1.ImportDataOperationMetadata - name: google.cloud.aiplatform.v1beta1.ImportDataResponse +- name: google.cloud.aiplatform.v1beta1.ImportExtensionOperationMetadata - name: google.cloud.aiplatform.v1beta1.ImportFeatureValuesOperationMetadata - name: google.cloud.aiplatform.v1beta1.ImportFeatureValuesResponse - name: google.cloud.aiplatform.v1beta1.MutateDeployedIndexOperationMetadata @@ -718,6 +721,18 @@ authentication: oauth: canonical_scopes: |- https://www.googleapis.com/auth/cloud-platform + - selector: google.cloud.aiplatform.v1beta1.ExtensionExecutionService.ExecuteExtension + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform + - selector: google.cloud.aiplatform.v1beta1.ExtensionExecutionService.QueryExtension + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform + - selector: 'google.cloud.aiplatform.v1beta1.ExtensionRegistryService.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform - selector: 'google.cloud.aiplatform.v1beta1.FeatureOnlineStoreAdminService.*' oauth: canonical_scopes: |- diff --git a/google/cloud/aiplatform/v1beta1/extension.proto b/google/cloud/aiplatform/v1beta1/extension.proto new file mode 100644 index 0000000000000..59505d4cf4061 --- /dev/null +++ b/google/cloud/aiplatform/v1beta1/extension.proto @@ -0,0 +1,386 @@ +// Copyright 2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.cloud.aiplatform.v1beta1; + +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; +import "google/cloud/aiplatform/v1beta1/tool.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1"; +option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb"; +option java_multiple_files = true; +option java_outer_classname = "ExtensionProto"; +option java_package = "com.google.cloud.aiplatform.v1beta1"; +option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1"; +option ruby_package = "Google::Cloud::AIPlatform::V1beta1"; +option (google.api.resource_definition) = { + type: "secretmanager.googleapis.com/SecretVersion" + pattern: "projects/{project}/secrets/{secret}/versions/{secret_version}" + pattern: "projects/{project}/locations/{location}/secrets/{secret}/versions/{secret_version}" +}; +option (google.api.resource_definition) = { + type: "servicedirectory.googleapis.com/Service" + pattern: "projects/{project}/locations/{location}/namespaces/{namespace}/services/{service}" +}; + +// Enum of location an HTTP element can be. +enum HttpElementLocation { + HTTP_IN_UNSPECIFIED = 0; + + // Element is in the HTTP request query. + HTTP_IN_QUERY = 1; + + // Element is in the HTTP request header. + HTTP_IN_HEADER = 2; + + // Element is in the HTTP request path. + HTTP_IN_PATH = 3; + + // Element is in the HTTP request body. + HTTP_IN_BODY = 4; + + // Element is in the HTTP request cookie. + HTTP_IN_COOKIE = 5; +} + +// Type of Auth. +enum AuthType { + AUTH_TYPE_UNSPECIFIED = 0; + + // No Auth. + NO_AUTH = 1; + + // API Key Auth. + API_KEY_AUTH = 2; + + // HTTP Basic Auth. + HTTP_BASIC_AUTH = 3; + + // Google Service Account Auth. + GOOGLE_SERVICE_ACCOUNT_AUTH = 4; + + // OAuth auth. + OAUTH = 6; + + // OpenID Connect (OIDC) Auth. + OIDC_AUTH = 8; +} + +// Extensions are tools for large language models to access external data, run +// computations, etc. +message Extension { + option (google.api.resource) = { + type: "aiplatform.googleapis.com/Extension" + pattern: "projects/{project}/locations/{location}/extensions/{extension}" + plural: "extensions" + singular: "extension" + }; + + // Identifier. The resource name of the Extension. + string name = 1 [(google.api.field_behavior) = IDENTIFIER]; + + // Required. The display name of the Extension. + // The name can be up to 128 characters long and can consist of any UTF-8 + // characters. + string display_name = 3 [(google.api.field_behavior) = REQUIRED]; + + // Optional. The description of the Extension. + string description = 4 [(google.api.field_behavior) = OPTIONAL]; + + // Output only. Timestamp when this Extension was created. + google.protobuf.Timestamp create_time = 5 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. Timestamp when this Extension was most recently updated. + google.protobuf.Timestamp update_time = 6 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Optional. Used to perform consistent read-modify-write updates. If not set, + // a blind "overwrite" update happens. + string etag = 7 [(google.api.field_behavior) = OPTIONAL]; + + // Required. Manifest of the Extension. + ExtensionManifest manifest = 9 [(google.api.field_behavior) = REQUIRED]; + + // Output only. Supported operations. + repeated ExtensionOperation extension_operations = 11 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Optional. Runtime config controlling the runtime behavior of this + // Extension. + RuntimeConfig runtime_config = 13 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Examples to illustrate the usage of the extension as a tool. + repeated ToolUseExample tool_use_examples = 15 + [(google.api.field_behavior) = OPTIONAL]; + + // Optional. The PrivateServiceConnect config for the extension. + // If specified, the service endpoints associated with the Extension should be + // registered in the provided Service Directory + // (https://cloud.google.com/service-directory/docs/configuring-private-network-access). + ExtensionPrivateServiceConnectConfig private_service_connect_config = 16 + [(google.api.field_behavior) = OPTIONAL]; +} + +// Manifest spec of an Extension needed for runtime execution. +message ExtensionManifest { + // The API specification shown to the LLM. + message ApiSpec { + oneof api_spec { + // The API spec in Open API standard and YAML format. + string open_api_yaml = 1; + + // Cloud Storage URI pointing to the OpenAPI spec. + string open_api_gcs_uri = 2; + } + } + + // Required. Extension name shown to the LLM. + // The name can be up to 128 characters long. + string name = 1 [(google.api.field_behavior) = REQUIRED]; + + // 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. + string description = 2 [(google.api.field_behavior) = REQUIRED]; + + // Required. Immutable. The API specification shown to the LLM. + ApiSpec api_spec = 3 [ + (google.api.field_behavior) = IMMUTABLE, + (google.api.field_behavior) = REQUIRED + ]; + + // Required. Immutable. Type of auth supported by this extension. + AuthConfig auth_config = 5 [ + (google.api.field_behavior) = IMMUTABLE, + (google.api.field_behavior) = REQUIRED + ]; +} + +// Operation of an extension. +message ExtensionOperation { + // 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. + string operation_id = 1; + + // Output only. Structured representation of a function declaration as defined + // by the OpenAPI Spec. + FunctionDeclaration function_declaration = 3 + [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// Auth configuration to run the extension. +message AuthConfig { + // Empty message, used to indicate no authentication for an endpoint. + message NoAuth {} + + // Config for authentication with API key. + message ApiKeyConfig { + // Required. The parameter name of the API key. + // E.g. If the API request is "https://example.com/act?api_key=", + // "api_key" would be the parameter name. + string name = 1 [(google.api.field_behavior) = REQUIRED]; + + // 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. + string api_key_secret = 2 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "secretmanager.googleapis.com/SecretVersion" + } + ]; + + // Required. The location of the API key. + HttpElementLocation http_element_location = 3 + [(google.api.field_behavior) = REQUIRED]; + } + + // Config for HTTP Basic Authentication. + message HttpBasicAuthConfig { + // 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. + string credential_secret = 2 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "secretmanager.googleapis.com/SecretVersion" + } + ]; + } + + // Config for Google Service Account Authentication. + message GoogleServiceAccountConfig { + // 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. + string service_account = 1 [(google.api.field_behavior) = OPTIONAL]; + } + + // Config for user oauth. + message OauthConfig { + oneof oauth_config { + // Access token for extension endpoint. + // Only used to propagate token from + // [[ExecuteExtensionRequest.runtime_auth_config]] at request time. + string access_token = 1; + + // 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. + string service_account = 2; + } + } + + // Config for user OIDC auth. + message OidcConfig { + oneof oidc_config { + // OpenID Connect formatted ID token for extension endpoint. + // Only used to propagate token from + // [[ExecuteExtensionRequest.runtime_auth_config]] at request time. + string id_token = 1; + + // 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). + string service_account = 2; + } + } + + oneof auth_config { + // Config for API key auth. + ApiKeyConfig api_key_config = 2; + + // Config for HTTP Basic auth. + HttpBasicAuthConfig http_basic_auth_config = 3; + + // Config for Google Service Account auth. + GoogleServiceAccountConfig google_service_account_config = 4; + + // Config for user oauth. + OauthConfig oauth_config = 5; + + // Config for user OIDC auth. + OidcConfig oidc_config = 7; + } + + // Type of auth scheme. + AuthType auth_type = 101; +} + +// Runtime configuration to run the extension. +message RuntimeConfig { + message CodeInterpreterRuntimeConfig { + // Optional. The GCS bucket for file input of this Extension. + // If specified, support input from the GCS 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 GCS file inputs. + string file_input_gcs_bucket = 1 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. The GCS bucket for file output of this Extension. + // If specified, write all output files to the GCS 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. + string file_output_gcs_bucket = 2 [(google.api.field_behavior) = OPTIONAL]; + } + + message VertexAISearchRuntimeConfig { + // Required. Vertext AI Search serving config name. Format: + // `projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}` + // or + // `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/servingConfigs/{serving_config}` + string serving_config_name = 1 [(google.api.field_behavior) = REQUIRED]; + } + + // Runtime configurations for Google first party extensions. + oneof GoogleFirstPartyExtensionConfig { + // Code execution runtime configurations for code interpreter extension. + CodeInterpreterRuntimeConfig code_interpreter_runtime_config = 2; + + // Runtime configuration for Vertext AI Search extension. + VertexAISearchRuntimeConfig vertex_ai_search_runtime_config = 6; + } + + // 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"}. + google.protobuf.Struct default_params = 4 + [(google.api.field_behavior) = OPTIONAL]; +} + +// PrivateExtensionConfig configuration for the extension. +message ExtensionPrivateServiceConnectConfig { + // Required. The Service Directory resource name in which the service + // endpoints associated to the extension are registered. Format: + // `projects/{project_id}/locations/{location_id}/namespaces/{namespace_id}/services/{service_id}` + // + // - The Vertex AI Extension Service Agent + // (https://cloud.google.com/vertex-ai/docs/general/access-control#service-agents) + // should be granted `servicedirectory.viewer` and + // `servicedirectory.pscAuthorizedService` roles on the resource. + string service_directory = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "servicedirectory.googleapis.com/Service" + } + ]; +} diff --git a/google/cloud/aiplatform/v1beta1/extension_execution_service.proto b/google/cloud/aiplatform/v1beta1/extension_execution_service.proto new file mode 100644 index 0000000000000..bf4693d077fa2 --- /dev/null +++ b/google/cloud/aiplatform/v1beta1/extension_execution_service.proto @@ -0,0 +1,135 @@ +// Copyright 2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.cloud.aiplatform.v1beta1; + +import "google/api/annotations.proto"; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; +import "google/cloud/aiplatform/v1beta1/content.proto"; +import "google/cloud/aiplatform/v1beta1/extension.proto"; +import "google/protobuf/struct.proto"; + +option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1"; +option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb"; +option java_multiple_files = true; +option java_outer_classname = "ExtensionExecutionServiceProto"; +option java_package = "com.google.cloud.aiplatform.v1beta1"; +option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1"; +option ruby_package = "Google::Cloud::AIPlatform::V1beta1"; + +// A service for Extension execution. +service ExtensionExecutionService { + option (google.api.default_host) = "aiplatform.googleapis.com"; + option (google.api.oauth_scopes) = + "https://www.googleapis.com/auth/cloud-platform"; + + // Executes the request against a given extension. + rpc ExecuteExtension(ExecuteExtensionRequest) + returns (ExecuteExtensionResponse) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/extensions/*}:execute" + body: "*" + }; + option (google.api.method_signature) = "name,operation_id"; + } + + // Queries an extension with a default controller. + rpc QueryExtension(QueryExtensionRequest) returns (QueryExtensionResponse) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/extensions/*}:query" + body: "*" + }; + option (google.api.method_signature) = "name,contents"; + } +} + +// Request message for +// [ExtensionExecutionService.ExecuteExtension][google.cloud.aiplatform.v1beta1.ExtensionExecutionService.ExecuteExtension]. +message ExecuteExtensionRequest { + // Required. Name (identifier) of the extension; + // Format: + // `projects/{project}/locations/{location}/extensions/{extension}` + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "aiplatform.googleapis.com/Extension" + } + ]; + + // Required. The desired ID of the operation to be executed in this extension + // as defined in + // [ExtensionOperation.operation_id][google.cloud.aiplatform.v1beta1.ExtensionOperation.operation_id]. + string operation_id = 2 [(google.api.field_behavior) = REQUIRED]; + + // Optional. Request parameters that will be used for executing this + // operation. + // + // 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"}. + google.protobuf.Struct operation_params = 3 + [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Auth config provided at runtime to override the default value in + // [Extension.manifest.auth_config][]. + // The AuthConfig.auth_type should match the value in + // [Extension.manifest.auth_config][]. + AuthConfig runtime_auth_config = 4 [(google.api.field_behavior) = OPTIONAL]; +} + +// Response message for +// [ExtensionExecutionService.ExecuteExtension][google.cloud.aiplatform.v1beta1.ExtensionExecutionService.ExecuteExtension]. +message ExecuteExtensionResponse { + // Response content from the extension. The content should be conformant to + // the response.content schema in the extension's manifest/OpenAPI spec. + string content = 2; +} + +// Request message for +// [ExtensionExecutionService.QueryExtension][google.cloud.aiplatform.v1beta1.ExtensionExecutionService.QueryExtension]. +message QueryExtensionRequest { + // Required. Name (identifier) of the extension; + // Format: + // `projects/{project}/locations/{location}/extensions/{extension}` + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "aiplatform.googleapis.com/Extension" + } + ]; + + // Required. The content of the current conversation with the model. + // + // For single-turn queries, this is a single instance. For multi-turn queries, + // this is a repeated field that contains conversation history + latest + // request. + repeated Content contents = 2 [(google.api.field_behavior) = REQUIRED]; +} + +// Response message for +// [ExtensionExecutionService.QueryExtension][google.cloud.aiplatform.v1beta1.ExtensionExecutionService.QueryExtension]. +message QueryExtensionResponse { + // Steps of extension or LLM interaction, can contain function call, + // function response, or text response. The last step contains the final + // response to the query. + repeated Content steps = 1; + + // Failure message if any. + string failure_message = 2; +} diff --git a/google/cloud/aiplatform/v1beta1/extension_registry_service.proto b/google/cloud/aiplatform/v1beta1/extension_registry_service.proto new file mode 100644 index 0000000000000..41bd1318685cc --- /dev/null +++ b/google/cloud/aiplatform/v1beta1/extension_registry_service.proto @@ -0,0 +1,212 @@ +// Copyright 2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.cloud.aiplatform.v1beta1; + +import "google/api/annotations.proto"; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; +import "google/cloud/aiplatform/v1beta1/extension.proto"; +import "google/cloud/aiplatform/v1beta1/operation.proto"; +import "google/longrunning/operations.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/field_mask.proto"; + +option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1"; +option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb"; +option java_multiple_files = true; +option java_outer_classname = "ExtensionRegistryServiceProto"; +option java_package = "com.google.cloud.aiplatform.v1beta1"; +option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1"; +option ruby_package = "Google::Cloud::AIPlatform::V1beta1"; + +// A service for managing Vertex AI's Extension registry. +service ExtensionRegistryService { + option (google.api.default_host) = "aiplatform.googleapis.com"; + option (google.api.oauth_scopes) = + "https://www.googleapis.com/auth/cloud-platform"; + + // Imports an Extension. + rpc ImportExtension(ImportExtensionRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/locations/*}/extensions:import" + body: "extension" + }; + option (google.api.method_signature) = "parent,extension"; + option (google.longrunning.operation_info) = { + response_type: "Extension" + metadata_type: "ImportExtensionOperationMetadata" + }; + } + + // Gets an Extension. + rpc GetExtension(GetExtensionRequest) returns (Extension) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/locations/*/extensions/*}" + }; + option (google.api.method_signature) = "name"; + } + + // Lists Extensions in a location. + rpc ListExtensions(ListExtensionsRequest) returns (ListExtensionsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/locations/*}/extensions" + }; + option (google.api.method_signature) = "parent"; + } + + // Updates an Extension. + rpc UpdateExtension(UpdateExtensionRequest) returns (Extension) { + option (google.api.http) = { + patch: "/v1beta1/{extension.name=projects/*/locations/*/extensions/*}" + body: "extension" + }; + option (google.api.method_signature) = "extension,update_mask"; + } + + // Deletes an Extension. + rpc DeleteExtension(DeleteExtensionRequest) + returns (google.longrunning.Operation) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/locations/*/extensions/*}" + }; + option (google.api.method_signature) = "name"; + option (google.longrunning.operation_info) = { + response_type: "google.protobuf.Empty" + metadata_type: "DeleteOperationMetadata" + }; + } +} + +// Request message for +// [ExtensionRegistryService.ImportExtension][google.cloud.aiplatform.v1beta1.ExtensionRegistryService.ImportExtension]. +message ImportExtensionRequest { + // Required. The resource name of the Location to import the Extension in. + // Format: `projects/{project}/locations/{location}` + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "locations.googleapis.com/Location" + } + ]; + + // Required. The Extension to import. + Extension extension = 2 [(google.api.field_behavior) = REQUIRED]; +} + +// Details of +// [ExtensionRegistryService.ImportExtension][google.cloud.aiplatform.v1beta1.ExtensionRegistryService.ImportExtension] +// operation. +message ImportExtensionOperationMetadata { + // The common part of the operation metadata. + GenericOperationMetadata generic_metadata = 1; +} + +// Request message for +// [ExtensionRegistryService.GetExtension][google.cloud.aiplatform.v1beta1.ExtensionRegistryService.GetExtension]. +message GetExtensionRequest { + // Required. The name of the Extension resource. + // Format: + // `projects/{project}/locations/{location}/extensions/{extension}` + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "aiplatform.googleapis.com/Extension" + } + ]; +} + +// Request message for +// [ExtensionRegistryService.UpdateExtension][google.cloud.aiplatform.v1beta1.ExtensionRegistryService.UpdateExtension]. +message UpdateExtensionRequest { + // Required. The Extension which replaces the resource on the server. + Extension extension = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. Mask specifying which fields to update. + // Supported fields: + // + // * `display_name` + // * `description` + // * `tool_use_examples` + google.protobuf.FieldMask update_mask = 2 + [(google.api.field_behavior) = REQUIRED]; +} + +// Request message for +// [ExtensionRegistryService.ListExtensions][google.cloud.aiplatform.v1beta1.ExtensionRegistryService.ListExtensions]. +message ListExtensionsRequest { + // Required. The resource name of the Location to list the Extensions from. + // Format: `projects/{project}/locations/{location}` + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "locations.googleapis.com/Location" + } + ]; + + // Optional. The standard list filter. + // Supported fields: + // * `display_name` + // * `create_time` + // * `update_time` + // + // More detail in [AIP-160](https://google.aip.dev/160). + string filter = 2 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. The standard list page size. + int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. The standard list page token. + string page_token = 4 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. A comma-separated list of fields to order by, sorted in ascending + // order. Use "desc" after a field name for descending. Supported fields: + // * `display_name` + // * `create_time` + // * `update_time` + // + // Example: `display_name, create_time desc`. + string order_by = 6 [(google.api.field_behavior) = OPTIONAL]; +} + +// Response message for +// [ExtensionRegistryService.ListExtensions][google.cloud.aiplatform.v1beta1.ExtensionRegistryService.ListExtensions] +message ListExtensionsResponse { + // List of Extension in the requested page. + repeated Extension extensions = 1; + + // A token to retrieve the next page of results. + // Pass to + // [ListExtensionsRequest.page_token][google.cloud.aiplatform.v1beta1.ListExtensionsRequest.page_token] + // to obtain that page. + string next_page_token = 2; +} + +// Request message for +// [ExtensionRegistryService.DeleteExtension][google.cloud.aiplatform.v1beta1.ExtensionRegistryService.DeleteExtension]. +message DeleteExtensionRequest { + // Required. The name of the Extension resource to be deleted. + // Format: + // `projects/{project}/locations/{location}/extensions/{extension}` + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "aiplatform.googleapis.com/Extension" + } + ]; +} diff --git a/google/cloud/aiplatform/v1beta1/tool.proto b/google/cloud/aiplatform/v1beta1/tool.proto index 641d066c2a088..67572b314bd94 100644 --- a/google/cloud/aiplatform/v1beta1/tool.proto +++ b/google/cloud/aiplatform/v1beta1/tool.proto @@ -60,6 +60,44 @@ message Tool { [(google.api.field_behavior) = OPTIONAL]; } +// A single example of the tool usage. +message ToolUseExample { + // Identifies one operation of the extension. + message ExtensionOperation { + // Resource name of the extension. + string extension = 1 [(google.api.resource_reference) = { + type: "aiplatform.googleapis.com/Extension" + }]; + + // Required. Operation ID of the extension. + string operation_id = 2 [(google.api.field_behavior) = REQUIRED]; + } + + // Target tool to use. + oneof Target { + // Extension operation to call. + ExtensionOperation extension_operation = 10; + + // Function name to call. + string function_name = 11; + } + + // Required. The display name for example. + string display_name = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. Query that should be routed to this tool. + string query = 2 [(google.api.field_behavior) = REQUIRED]; + + // Request parameters used for executing this tool. + google.protobuf.Struct request_params = 3; + + // Response parameters generated by this tool. + google.protobuf.Struct response_params = 4; + + // Summary of the tool response to the user query. + string response_summary = 5; +} + // Structured representation of a function declaration as defined by the // [OpenAPI 3.0 specification](https://spec.openapis.org/oas/v3.0.3). Included // in this declaration are the function name and parameters. This @@ -68,8 +106,8 @@ message Tool { message FunctionDeclaration { // Required. The name of the function to call. // Must start with a letter or an underscore. - // Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum - // length of 64. + // Must be a-z, A-Z, 0-9, or contain underscores, dots and dashes, with a + // maximum length of 64. string name = 1 [(google.api.field_behavior) = REQUIRED]; // Optional. Description and purpose of the function. @@ -80,8 +118,10 @@ message FunctionDeclaration { // format. Reflects the Open API 3.03 Parameter Object. string Key: the name // of the parameter. Parameter names are case sensitive. Schema Value: the // Schema defining the type used for the parameter. For function with no - // parameters, this can be left unset. Example with 1 required and 1 optional - // parameter: type: OBJECT properties: + // parameters, this can be left unset. Parameter names must start with a + // letter or an underscore and must only contain chars a-z, A-Z, 0-9, or + // underscores with a maximum length of 64. Example with 1 required and 1 + // optional parameter: type: OBJECT properties: // param1: // type: STRING // param2: @@ -89,6 +129,11 @@ message FunctionDeclaration { // required: // - param1 Schema parameters = 3 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Describes the output from this function in JSON Schema format. + // Reflects the Open API 3.03 Response Object. The Schema defines the type + // used for the response value of the function. + Schema response = 4 [(google.api.field_behavior) = OPTIONAL]; } // A predicted [FunctionCall] returned from the model that contains a string