feat: Add ability to specify mocked tool responses in ExecuteTool

Google APIs · copybara-github · commit 3035633d62f5 · 2026-04-14T12:05:50.000-07:00
feat: Add ExportEvaluation RPC
feat: Add support for app level fallback config
feat: Add evaluation run and result information to ImportEvaluationsResponse

PiperOrigin-RevId: 899708731
diff --git a/google/cloud/ces/v1beta/BUILD.bazel b/google/cloud/ces/v1beta/BUILD.bazel
@@ -52,6 +52,7 @@ proto_library(
         "guardrail.proto",
         "mcp_tool.proto",
         "mcp_toolset.proto",
+        "mocks.proto",
         "omnichannel.proto",
         "omnichannel_service.proto",
         "open_api_tool.proto",
@@ -391,6 +392,7 @@ load(
 
 csharp_proto_library(
     name = "ces_csharp_proto",
+    extra_opts = [],
     deps = [":ces_proto"],
 )
 
diff --git a/google/cloud/ces/v1beta/app.proto b/google/cloud/ces/v1beta/app.proto
@@ -424,6 +424,32 @@ message LoggingSettings {
 
 // Settings to describe how errors should be handled in the app.
 message ErrorHandlingSettings {
+  // Configuration for handling fallback responses.
+  message FallbackResponseConfig {
+    // Optional. The fallback messages in case of system errors (e.g. LLM
+    // errors), mapped by [supported language
+    // code](https://docs.cloud.google.com/customer-engagement-ai/conversational-agents/ps/reference/language).
+    map<string, string> custom_fallback_messages = 1
+        [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. The maximum number of fallback attempts to make before the
+    // agent emitting [EndSession][google.cloud.ces.v1beta.EndSession] Signal.
+    int32 max_fallback_attempts = 2 [(google.api.field_behavior) = OPTIONAL];
+  }
+
+  // Configuration for ending the session in case of system errors (e.g. LLM
+  // errors).
+  message EndSessionConfig {
+    // Optional. Whether to escalate the session in
+    // [EndSession][google.cloud.ces.v1beta.EndSession]. If session is
+    // escalated, [metadata in
+    // EndSession][google.cloud.ces.v1beta.EndSession.metadata] will contain
+    // `session_escalated = true`. See
+    // https://docs.cloud.google.com/customer-engagement-ai/conversational-agents/ps/deploy/google-telephony-platform#transfer_a_call_to_a_human_agent
+    // for details.
+    optional bool escalate_session = 1 [(google.api.field_behavior) = OPTIONAL];
+  }
+
   // Defines the strategy for handling errors.
   enum ErrorHandlingStrategy {
     // Unspecified error handling strategy.
@@ -444,6 +470,15 @@ message ErrorHandlingSettings {
   // Optional. The strategy to use for error handling.
   ErrorHandlingStrategy error_handling_strategy = 1
       [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Configuration for handling fallback responses.
+  FallbackResponseConfig fallback_response_config = 2
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Configuration for ending the session in case of system errors
+  // (e.g. LLM errors).
+  EndSessionConfig end_session_config = 3
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Threshold settings for metrics in an Evaluation.
@@ -618,6 +653,11 @@ message ConversationLoggingSettings {
   // Optional. Whether to disable conversation logging for the sessions.
   bool disable_conversation_logging = 1
       [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Controls the retention window for the conversation.
+  // If not set, the conversation will be retained for 365 days.
+  google.protobuf.Duration retention_window = 2
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Settings to describe the Cloud Logging behaviors for the app.
diff --git a/google/cloud/ces/v1beta/ces_v1beta.yaml b/google/cloud/ces/v1beta/ces_v1beta.yaml
@@ -16,6 +16,9 @@ types:
 - name: google.cloud.ces.v1beta.BatchDeleteConversationsResponse
 - name: google.cloud.ces.v1beta.DeleteEvaluationRunOperationMetadata
 - name: google.cloud.ces.v1beta.ExportAppResponse
+- name: google.cloud.ces.v1beta.ExportEvaluationResultsResponse
+- name: google.cloud.ces.v1beta.ExportEvaluationRunsResponse
+- name: google.cloud.ces.v1beta.ExportEvaluationsResponse
 - name: google.cloud.ces.v1beta.GenerateAppResourceResponse
 - name: google.cloud.ces.v1beta.GenerateEvaluationOperationMetadata
 - name: google.cloud.ces.v1beta.ImportAppResponse
diff --git a/google/cloud/ces/v1beta/evaluation.proto b/google/cloud/ces/v1beta/evaluation.proto
@@ -919,6 +919,9 @@ message EvaluationResult {
     // Evaluation/Expectation failed. In the case of an evaluation, this means
     // that at least one expectation was not met.
     FAIL = 2;
+
+    // Evaluation/Expectation was skipped.
+    SKIPPED = 3;
   }
 
   // The state of the evaluation result execution.
diff --git a/google/cloud/ces/v1beta/evaluation_service.proto b/google/cloud/ces/v1beta/evaluation_service.proto
@@ -20,6 +20,7 @@ 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/v1beta/agent_service.proto";
 import "google/cloud/ces/v1beta/conversation.proto";
 import "google/cloud/ces/v1beta/evaluation.proto";
 import "google/longrunning/operations.proto";
@@ -354,6 +355,20 @@ service EvaluationService {
     };
     option (google.api.method_signature) = "app";
   }
+
+  // Exports evaluations.
+  rpc ExportEvaluations(ExportEvaluationsRequest)
+      returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v1beta/{parent=projects/*/locations/*/apps/*}/evaluations:export"
+      body: "*"
+    };
+    option (google.api.method_signature) = "parent";
+    option (google.longrunning.operation_info) = {
+      response_type: "ExportEvaluationsResponse"
+      metadata_type: "OperationMetadata"
+    };
+  }
 }
 
 // Response message for
@@ -521,12 +536,27 @@ message ImportEvaluationsResponse {
   // The list of evaluations that were imported into the app.
   repeated Evaluation evaluations = 1;
 
+  // The list of evaluation results that were imported into the app.
+  repeated EvaluationResult evaluation_results = 4;
+
+  // The list of evaluation runs that were imported into the app.
+  repeated EvaluationRun evaluation_runs = 5;
+
   // Optional. A list of error messages associated with evaluations that failed
   // to be imported.
   repeated string error_messages = 2 [(google.api.field_behavior) = OPTIONAL];
 
-  // The number of evaluations that were not imported due to errors.
+  // The number of evaluations that either failed to import entirely or
+  // completed import with one or more errors.
   int32 import_failure_count = 3;
+
+  // The number of evaluation results that either failed to import entirely or
+  // completed import with one or more errors.
+  int32 evaluation_result_import_failure_count = 6;
+
+  // The number of evaluation runs that either failed to import entirely or
+  // completed import with one or more errors.
+  int32 evaluation_run_import_failure_count = 7;
 }
 
 // Represents the metadata of the long-running operation for
@@ -1195,3 +1225,107 @@ message ListEvaluationExpectationsResponse {
   // subsequent pages.
   string next_page_token = 2;
 }
+
+// Options for exporting CES evaluation resources.
+message ExportOptions {
+  // The format to export the items in. Defaults to JSON if not
+  // specified.
+  enum ExportFormat {
+    // Unspecified format.
+    EXPORT_FORMAT_UNSPECIFIED = 0;
+
+    // JSON format.
+    JSON = 1;
+
+    // YAML format.
+    YAML = 2;
+  }
+
+  // Optional. The format to export the evaluation results in. Defaults to JSON
+  // if not specified.
+  ExportFormat export_format = 1 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The Google Cloud Storage URI to write the exported Evaluation
+  // Results to.
+  string gcs_uri = 2 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Request message for
+// [EvaluationService.ExportEvaluations][google.cloud.ces.v1beta.EvaluationService.ExportEvaluations].
+message ExportEvaluationsRequest {
+  // Required. The resource name of the app to export evaluations from.
+  // Format: `projects/{project}/locations/{location}/apps/{app}`
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = { type: "ces.googleapis.com/App" }
+  ];
+
+  // Required. The resource names of the evaluations to export.
+  repeated string names = 2 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = { type: "ces.googleapis.com/Evaluation" }
+  ];
+
+  // Optional. The export options for the evaluations.
+  ExportOptions export_options = 3 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Includes evaluation results in the export. At least one of
+  // include_evaluation_results or include_evaluations must be set.
+  bool include_evaluation_results = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Includes evaluations in the export. At least one of
+  // include_evaluation_results or include_evaluations must be set.
+  bool include_evaluations = 5 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Response message for
+// [EvaluationService.ExportEvaluations][google.cloud.ces.v1beta.EvaluationService.ExportEvaluations].
+message ExportEvaluationsResponse {
+  // The exported evaluations.
+  oneof evaluations {
+    // The content of the exported Evaluations. This will be populated if
+    // gcs_uri was not specified in the request.
+    bytes evaluations_content = 1;
+
+    // The Google Cloud Storage URI folder where the exported evaluations were
+    // written. This will be populated if gcs_uri was specified in the request.
+    string evaluations_uri = 2;
+  }
+
+  // Output only. A map of evaluation resource names that could not be exported,
+  // to the reason why they failed.
+  map<string, string> failed_evaluations = 3
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// Response message for
+// [EvaluationService.ExportEvaluationResults][google.cloud.ces.v1beta.EvaluationService.ExportEvaluationResults].
+message ExportEvaluationResultsResponse {
+  // The exported evaluation results.
+  oneof evaluation_results {
+    // The content of the exported Evaluation Results. This will be populated if
+    // gcs_uri was not specified in the request.
+    bytes evaluation_results_content = 1;
+
+    // The Google Cloud Storage URI folder where the exported Evaluation Results
+    // were written. This will be populated if gcs_uri was specified in the
+    // request.
+    string evaluation_results_uri = 2;
+  }
+}
+
+// Response message for
+// [EvaluationService.ExportEvaluationRuns][google.cloud.ces.v1beta.EvaluationService.ExportEvaluationRuns].
+message ExportEvaluationRunsResponse {
+  // The exported evaluation runs.
+  oneof evaluation_runs {
+    // The content of the exported Evaluation Runs. This will be populated if
+    // gcs_uri was not specified in the request.
+    bytes evaluation_runs_content = 1;
+
+    // The Google Cloud Storage URI folder where the exported Evaluation Runs
+    // were written. This will be populated if gcs_uri was specified in the
+    // request.
+    string evaluation_runs_uri = 2;
+  }
+}
diff --git a/google/cloud/ces/v1beta/mocks.proto b/google/cloud/ces/v1beta/mocks.proto
@@ -0,0 +1,65 @@
+// 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.v1beta;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/cloud/ces/v1beta/toolset_tool.proto";
+import "google/protobuf/struct.proto";
+
+option go_package = "cloud.google.com/go/ces/apiv1beta/cespb;cespb";
+option java_multiple_files = true;
+option java_outer_classname = "MocksProto";
+option java_package = "com.google.cloud.ces.v1beta";
+
+// A mocked tool call.
+//
+// Expresses the target tool + a pattern to match against that tool's
+// args / inputs. If the pattern matches, then the mock response will be
+// returned.
+message MockedToolCall {
+  // The identifier of the tool to mock.
+  oneof tool_identifier {
+    // Optional. The name of the tool to mock.
+    // Format: `projects/{project}/locations/{location}/apps/{app}/tools/{tool}`
+    string tool_id = 4 [
+      (google.api.field_behavior) = OPTIONAL,
+      (google.api.resource_reference) = { type: "ces.googleapis.com/Tool" }
+    ];
+
+    // Optional. The toolset to mock.
+    ToolsetTool toolset = 5 [(google.api.field_behavior) = OPTIONAL];
+  }
+
+  // Optional. Deprecated. Use tool_identifier instead.
+  string tool = 1 [
+    deprecated = true,
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.resource_reference) = { type: "ces.googleapis.com/Tool" }
+  ];
+
+  // Required. A pattern to match against the args / inputs of all dispatched
+  // tool calls. If the tool call inputs match this pattern, then mock output
+  // will be returned.
+  google.protobuf.Struct expected_args_pattern = 2
+      [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. The mock response / output to return if the tool call args /
+  // inputs match the pattern.
+  google.protobuf.Struct mock_response = 3
+      [(google.api.field_behavior) = OPTIONAL];
+}
diff --git a/google/cloud/ces/v1beta/session_service.proto b/google/cloud/ces/v1beta/session_service.proto
@@ -22,6 +22,7 @@ import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/cloud/ces/v1beta/common.proto";
 import "google/cloud/ces/v1beta/example.proto";
+import "google/cloud/ces/v1beta/mocks.proto";
 import "google/cloud/ces/v1beta/search_suggestions.proto";
 import "google/protobuf/struct.proto";
 
@@ -148,6 +149,31 @@ enum AudioEncoding {
   ALAW = 3;
 }
 
+// Mock tool calls configuration for the session.
+message MockConfig {
+  // What to do when a tool call doesn't match any mocked tool calls.
+  enum UnmatchedToolCallBehavior {
+    // Default value. This value is unused.
+    UNMATCHED_TOOL_CALL_BEHAVIOR_UNSPECIFIED = 0;
+
+    // Throw an error for any tool calls that don't match a mock expected input
+    // pattern.
+    FAIL = 1;
+
+    // For unmatched tool calls, pass the tool call through to real tool.
+    PASS_THROUGH = 2;
+  }
+
+  // Optional. All tool calls to mock for the duration of the session.
+  repeated MockedToolCall mocked_tool_calls = 1
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Required. Beavhior for tool calls that don't match any args patterns in
+  // mocked_tool_calls.
+  UnmatchedToolCallBehavior unmatched_tool_call_behavior = 2
+      [(google.api.field_behavior) = REQUIRED];
+}
+
 // InputAudioConfig configures how the CES agent should interpret the incoming
 // audio data.
 message InputAudioConfig {
diff --git a/google/cloud/ces/v1beta/tool_service.proto b/google/cloud/ces/v1beta/tool_service.proto
@@ -21,6 +21,7 @@ import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/cloud/ces/v1beta/schema.proto";
+import "google/cloud/ces/v1beta/session_service.proto";
 import "google/cloud/ces/v1beta/tool.proto";
 import "google/cloud/ces/v1beta/toolset_tool.proto";
 import "google/protobuf/struct.proto";
@@ -105,6 +106,11 @@ message ExecuteToolRequest {
   // Optional. The input parameters and values for the tool in JSON object
   // format.
   google.protobuf.Struct args = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Mock configuration for the tool execution.
+  // If this field is set, tools that call other tools will be
+  // mocked based on the provided patterns and responses.
+  MockConfig mock_config = 7 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Response message for

Original file line number	Diff line number	Diff line change
`@@ -919,6 +919,9 @@ message EvaluationResult {`
`919`	`919`	`// Evaluation/Expectation failed. In the case of an evaluation, this means`
`920`	`920`	`// that at least one expectation was not met.`
`921`	`921`	`FAIL = 2;`
	`922`	`+`
	`923`	`+ // Evaluation/Expectation was skipped.`
	`924`	`+ SKIPPED = 3;`
`922`	`925`	`}`
`923`	`926`
`924`	`927`	`// The state of the evaluation result execution.`