googleapis/google/cloud/ces/v1/tool_service.proto

// Copyright 2026 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.ces.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/ces/v1/schema.proto";
import "google/cloud/ces/v1/tool.proto";
import "google/cloud/ces/v1/toolset_tool.proto";
import "google/protobuf/struct.proto";

option go_package = "cloud.google.com/go/ces/apiv1/cespb;cespb";
option java_multiple_files = true;
option java_outer_classname = "ToolServiceProto";
option java_package = "com.google.cloud.ces.v1";

// Tool service provides APIs for interacting with CES tools.
service ToolService {
  option (google.api.default_host) = "ces.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/ces,"
      "https://www.googleapis.com/auth/cloud-platform";

  // Executes the given tool with the given arguments.
  rpc ExecuteTool(ExecuteToolRequest) returns (ExecuteToolResponse) {
    option (google.api.http) = {
      post: "/v1/{parent=projects/*/locations/*/apps/*}:executeTool"
      body: "*"
    };
  }

  // Retrieve the schema of the given tool. The schema is computed on the fly
  // for the given instance of the tool.
  rpc RetrieveToolSchema(RetrieveToolSchemaRequest)
      returns (RetrieveToolSchemaResponse) {
    option (google.api.http) = {
      post: "/v1/{parent=projects/*/locations/*/apps/*}:retrieveToolSchema"
      body: "*"
    };
  }

  // Retrieve the list of tools included in the specified toolset.
  rpc RetrieveTools(RetrieveToolsRequest) returns (RetrieveToolsResponse) {
    option (google.api.http) = {
      post: "/v1/{toolset=projects/*/locations/*/apps/*/toolsets/*}:retrieveTools"
      body: "*"
    };
  }
}

// Request message for
// [ToolService.ExecuteTool][google.cloud.ces.v1.ToolService.ExecuteTool].
message ExecuteToolRequest {
  // The identifier of the tool to execute. It could be either a persisted tool
  // or a tool from a toolset.
  oneof tool_identifier {
    // Optional. The name of the tool to execute.
    // Format:
    // projects/{project}/locations/{location}/apps/{app}/tools/{tool}
    string tool = 1 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.resource_reference) = { type: "ces.googleapis.com/Tool" }
    ];

    // Optional. The toolset tool to execute. Only one tool should match the
    // predicate from the toolset. Otherwise, an error will be returned.
    ToolsetTool toolset_tool = 3 [(google.api.field_behavior) = OPTIONAL];
  }

  // Additional context to be provided for the tool execution
  oneof tool_execution_context {
    // Optional. The variables that are available for the tool execution.
    google.protobuf.Struct variables = 5
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. The
    // [ToolCallContext](https://docs.cloud.google.com/customer-engagement-ai/conversational-agents/ps/tool/python#environment
    // for details) to be passed to the Python tool.
    google.protobuf.Struct context = 6 [(google.api.field_behavior) = OPTIONAL];
  }

  // Required. The resource name of the app which the tool/toolset belongs to.
  // Format: `projects/{project}/locations/{location}/apps/{app}`
  string parent = 4 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "ces.googleapis.com/App" }
  ];

  // Optional. The input parameters and values for the tool in JSON object
  // format.
  google.protobuf.Struct args = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [ToolService.ExecuteTool][google.cloud.ces.v1.ToolService.ExecuteTool].
message ExecuteToolResponse {
  // The identifier of the tool that got executed.
  oneof tool_identifier {
    // The name of the tool that got executed.
    // Format: `projects/{project}/locations/{location}/apps/{app}/tools/{tool}`
    string tool = 1
        [(google.api.resource_reference) = { type: "ces.googleapis.com/Tool" }];

    // The toolset tool that got executed.
    ToolsetTool toolset_tool = 3;
  }

  // The tool execution result in JSON object format.
  // Use "output" key to specify tool response and "error" key to specify
  // error details (if any). If "output" and "error" keys are not specified,
  // then whole "response" is treated as tool execution result.
  google.protobuf.Struct response = 2;

  // The variable values at the end of the tool execution.
  google.protobuf.Struct variables = 4;
}

// Request message for
// [ToolService.RetrieveToolSchema][google.cloud.ces.v1.ToolService.RetrieveToolSchema].
message RetrieveToolSchemaRequest {
  // The identifier of the tool to retrieve the schema for. It could be either a
  // persisted tool or a tool from a toolset.
  oneof tool_identifier {
    // Optional. The name of the tool to retrieve the schema for.
    // Format:
    // projects/{project}/locations/{location}/apps/{app}/tools/{tool}
    string tool = 1 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.resource_reference) = { type: "ces.googleapis.com/Tool" }
    ];

    // Optional. The toolset tool to retrieve the schema for. Only one tool
    // should match the predicate from the toolset. Otherwise, an error will be
    // returned.
    ToolsetTool toolset_tool = 2 [(google.api.field_behavior) = OPTIONAL];
  }

  // Required. The resource name of the app which the tool/toolset belongs to.
  // Format: `projects/{project}/locations/{location}/apps/{app}`
  string parent = 3 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "ces.googleapis.com/App" }
  ];
}

// Response message for
// [ToolService.RetrieveToolSchema][google.cloud.ces.v1.ToolService.RetrieveToolSchema].
message RetrieveToolSchemaResponse {
  // The identifier of the tool that the schema is for.
  oneof tool_identifier {
    // The name of the tool that the schema is for.
    // Format: `projects/{project}/locations/{location}/apps/{app}/tools/{tool}`
    string tool = 1
        [(google.api.resource_reference) = { type: "ces.googleapis.com/Tool" }];

    // The toolset tool that the schema is for.
    ToolsetTool toolset_tool = 2;
  }

  // The schema of the tool input parameters.
  Schema input_schema = 3;

  // The schema of the tool output parameters.
  Schema output_schema = 4;
}

// Request message for
// [ToolService.RetrieveTools][google.cloud.ces.v1.ToolService.RetrieveTools].
message RetrieveToolsRequest {
  // Required. The name of the toolset to retrieve the tools for.
  // Format:
  // `projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}`
  string toolset = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "ces.googleapis.com/Toolset" }
  ];

  // Optional. The identifiers of the tools to retrieve from the toolset.
  // If empty, all tools in the toolset will be returned.
  repeated string tool_ids = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [ToolService.RetrieveTools][google.cloud.ces.v1.ToolService.RetrieveTools].
message RetrieveToolsResponse {
  // The list of tools that are included in the specified toolset.
  repeated Tool tools = 1;
}