googleapis/google/cloud/dialogflow/v2/generator.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.dialogflow.v2;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/dialogflow/v2/agent_coaching_instruction.proto";
import "google/cloud/dialogflow/v2/ces_app.proto";
import "google/cloud/dialogflow/v2/ces_tool.proto";
import "google/cloud/dialogflow/v2/tool_call.proto";
import "google/cloud/dialogflow/v2/toolset.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.Dialogflow.V2";
option go_package = "cloud.google.com/go/dialogflow/apiv2/dialogflowpb;dialogflowpb";
option java_multiple_files = true;
option java_outer_classname = "GeneratorProto";
option java_package = "com.google.cloud.dialogflow.v2";
option objc_class_prefix = "DF";
option (google.api.resource_definition) = {
  type: "discoveryengine.googleapis.com/Engine"
  pattern: "projects/{project}/locations/{location}/collections/{collection}/engines/{engine}"
};

// Generator Service for LLM powered Agent Assist. This service manages the
// configurations of user owned Generators, such as description, context and
// instruction, input/output format, etc. The generator resources will be used
// inside a conversation and will be triggered by TriggerEvent to query LLM for
// answers.
service Generators {
  option (google.api.default_host) = "dialogflow.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform,"
      "https://www.googleapis.com/auth/dialogflow";

  // Creates a generator.
  rpc CreateGenerator(CreateGeneratorRequest) returns (Generator) {
    option (google.api.http) = {
      post: "/v2/{parent=projects/*/locations/*}/generators"
      body: "generator"
      additional_bindings {
        post: "/v2/{parent=projects/*}/generators"
        body: "generator"
      }
    };
    option (google.api.method_signature) = "parent,generator,generator_id";
  }

  // Retrieves a generator.
  rpc GetGenerator(GetGeneratorRequest) returns (Generator) {
    option (google.api.http) = {
      get: "/v2/{name=projects/*/locations/*/generators/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Lists generators.
  rpc ListGenerators(ListGeneratorsRequest) returns (ListGeneratorsResponse) {
    option (google.api.http) = {
      get: "/v2/{parent=projects/*/locations/*}/generators"
      additional_bindings { get: "/v2/{parent=projects/*}/generators" }
    };
    option (google.api.method_signature) = "parent";
  }

  // Deletes a generator.
  rpc DeleteGenerator(DeleteGeneratorRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v2/{name=projects/*/locations/*/generators/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Updates a generator.
  rpc UpdateGenerator(UpdateGeneratorRequest) returns (Generator) {
    option (google.api.http) = {
      patch: "/v2/{generator.name=projects/*/locations/*/generators/*}"
      body: "generator"
    };
    option (google.api.method_signature) = "generator,update_mask";
  }
}

// Request message of CreateGenerator.
message CreateGeneratorRequest {
  // Required. The project/location to create generator for. Format:
  // `projects/<Project ID>/locations/<Location ID>`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudresourcemanager.googleapis.com/Project"
    }
  ];

  // Required. The generator to create.
  Generator generator = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. The ID to use for the generator, which will become the final
  // component of the generator's resource name.
  //
  // The generator ID must be compliant with the regression formula
  // `[a-zA-Z][a-zA-Z0-9_-]*` with the characters length in range of [3,64].
  // If the field is not provided, an Id will be auto-generated.
  // If the field is provided, the caller is responsible for
  // 1. the uniqueness of the ID, otherwise the request will be rejected.
  // 2. the consistency for whether to use custom ID or not under a project to
  // better ensure uniqueness.
  string generator_id = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Request message of GetGenerator.
message GetGeneratorRequest {
  // Required. The generator resource name to retrieve. Format:
  // `projects/<Project ID>/locations/<Location ID>/generators/<Generator ID>`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/Generator"
    }
  ];
}

// Request message of ListGenerators.
message ListGeneratorsRequest {
  // Required. The project/location to list generators for. Format:
  // `projects/<Project ID>/locations/<Location ID>`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudresourcemanager.googleapis.com/Project"
    }
  ];

  // Optional. Maximum number of conversation models to return in a single page.
  // Default to 10.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The next_page_token value returned from a previous list request.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Response of ListGenerators.
message ListGeneratorsResponse {
  // List of generators retrieved.
  repeated Generator generators = 1;

  // Token to retrieve the next page of results, or empty if there are no more
  // results in the list.
  string next_page_token = 2;
}

// Request of DeleteGenerator.
message DeleteGeneratorRequest {
  // Required. The generator resource name to delete. Format:
  // `projects/<Project ID>/locations/<Location ID>/generators/<Generator ID>`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/Generator"
    }
  ];
}

// Request of UpdateGenerator.
message UpdateGeneratorRequest {
  // Required. The generator to update.
  // The name field of generator is to identify the generator to update.
  Generator generator = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The list of fields to update.
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// Represents a message entry of a conversation.
message MessageEntry {
  // Enumeration of the roles a participant can play in a conversation.
  enum Role {
    // Participant role not set.
    ROLE_UNSPECIFIED = 0;

    // Participant is a human agent.
    HUMAN_AGENT = 1;

    // Participant is an automated agent, such as a Dialogflow agent.
    AUTOMATED_AGENT = 2;

    // Participant is an end user that has called or chatted with
    // Dialogflow services.
    END_USER = 3;
  }

  // Optional. Participant role of the message.
  Role role = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Transcript content of the message.
  string text = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The language of the text. See [Language
  // Support](https://cloud.google.com/dialogflow/docs/reference/language) for a
  // list of the currently supported language codes.
  string language_code = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Create time of the message entry.
  google.protobuf.Timestamp create_time = 4
      [(google.api.field_behavior) = OPTIONAL];
}

// Context of the conversation, including transcripts.
message ConversationContext {
  // Optional. List of message transcripts in the conversation.
  repeated MessageEntry message_entries = 1
      [(google.api.field_behavior) = OPTIONAL];
}

// List of summarization sections.
message SummarizationSectionList {
  // Optional. Summarization sections.
  repeated SummarizationSection summarization_sections = 1
      [(google.api.field_behavior) = OPTIONAL];
}

// Providing examples in the generator (i.e. building a few-shot generator)
// helps convey the desired format of the LLM response.
message FewShotExample {
  // Optional. Conversation transcripts.
  ConversationContext conversation_context = 3
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Key is the placeholder field name in input, value is the value of
  // the placeholder. E.g. instruction contains "@price", and ingested data has
  // <"price", "10">
  map<string, string> extra_info = 4 [(google.api.field_behavior) = OPTIONAL];

  // Instruction list of this few_shot example.
  oneof instruction_list {
    // Summarization sections.
    SummarizationSectionList summarization_section_list = 6;
  }

  // Required. Example output of the model.
  GeneratorSuggestion output = 7 [(google.api.field_behavior) = REQUIRED];
}

// The parameters of inference.
message InferenceParameter {
  // Optional. Maximum number of the output tokens for the generator.
  optional int32 max_output_tokens = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Controls the randomness of LLM predictions.
  // Low temperature = less random. High temperature = more random.
  // If unset (or 0), uses a default value of 0.
  optional double temperature = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Top-k changes how the model selects tokens for output. A top-k of
  // 1 means the selected token is the most probable among all tokens in the
  // model's vocabulary (also called greedy decoding), while a top-k of 3 means
  // that the next token is selected from among the 3 most probable tokens
  // (using temperature). For each token selection step, the top K tokens with
  // the highest probabilities are sampled. Then tokens are further filtered
  // based on topP with the final token selected using temperature sampling.
  // Specify a lower value for less random responses and a higher value for more
  // random responses. Acceptable value is [1, 40], default to 40.
  optional int32 top_k = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Top-p changes how the model selects tokens for output. Tokens are
  // selected from most K (see topK parameter) probable to least until the sum
  // of their probabilities equals the top-p value. For example, if tokens A, B,
  // and C have a probability of 0.3, 0.2, and 0.1 and the top-p value is 0.5,
  // then the model will select either A or B as the next token (using
  // temperature) and doesn't consider C. The default top-p value is 0.95.
  // Specify a lower value for less random responses and a higher value for more
  // random responses. Acceptable value is [0.0, 1.0], default to 0.95.
  optional double top_p = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Agent Coaching context that customer can configure.
message AgentCoachingContext {
  // Optional. The overarching guidance for the agent coaching. This should be
  // set only for v1.5 and later versions.
  string overarching_guidance = 7 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Customized instructions for agent coaching.
  repeated AgentCoachingInstruction instructions = 1
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Version of the feature. If not set, default to latest version.
  // Current candidates are ["1.2"].
  string version = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Output language code.
  string output_language_code = 9 [(google.api.field_behavior) = OPTIONAL];
}

// Represents the section of summarization.
message SummarizationSection {
  // Type enum of the summarization sections.
  enum Type {
    // Undefined section type, does not return anything.
    TYPE_UNSPECIFIED = 0;

    // What the customer needs help with or has question about.
    // Section name: "situation".
    SITUATION = 1;

    // What the agent does to help the customer.
    // Section name: "action".
    ACTION = 2;

    // Result of the customer service. A single word describing the result
    // of the conversation.
    // Section name: "resolution".
    RESOLUTION = 3;

    // Reason for cancellation if the customer requests for a cancellation.
    // "N/A" otherwise.
    // Section name: "reason_for_cancellation".
    REASON_FOR_CANCELLATION = 4;

    // "Unsatisfied" or "Satisfied" depending on the customer's feelings at
    // the end of the conversation.
    // Section name: "customer_satisfaction".
    CUSTOMER_SATISFACTION = 5;

    // Key entities extracted from the conversation, such as ticket number,
    // order number, dollar amount, etc.
    // Section names are prefixed by "entities/".
    ENTITIES = 6;

    // Customer defined sections.
    CUSTOMER_DEFINED = 7;

    // Concise version of the situation section. This type is only available if
    // type SITUATION is not selected.
    SITUATION_CONCISE = 9;

    // Concise version of the action section. This type is only available if
    // type ACTION is not selected.
    ACTION_CONCISE = 10;
  }

  // Optional. Name of the section, for example, "situation".
  string key = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Definition of the section, for example, "what the customer needs
  // help with or has question about."
  string definition = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Type of the summarization section.
  Type type = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Summarization context that customer can configure.
message SummarizationContext {
  // Optional. List of sections. Note it contains both predefined section sand
  // customer defined sections.
  repeated SummarizationSection summarization_sections = 1
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. List of few shot examples.
  repeated FewShotExample few_shot_examples = 2
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Version of the feature. If not set, default to latest version.
  // Current candidates are ["1.0"].
  string version = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The target language of the generated summary. The language code
  // for conversation will be used if this field is empty. Supported 2.0 and
  // later versions.
  string output_language_code = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Free form generator context that customer can configure.
message FreeFormContext {
  // Optional. Free form text input to LLM.
  string text = 1 [(google.api.field_behavior) = OPTIONAL];
}

// LLM generator.
message Generator {
  option (google.api.resource) = {
    type: "dialogflow.googleapis.com/Generator"
    pattern: "projects/{project}/locations/{location}/generators/{generator}"
    plural: "generators"
    singular: "generator"
  };

  // Output only. Identifier. The resource name of the generator. Format:
  // `projects/<Project ID>/locations/<Location ID>/generators/<Generator ID>`
  string name = 1 [
    (google.api.field_behavior) = IDENTIFIER,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];

  // Optional. Human readable description of the generator.
  string description = 2 [(google.api.field_behavior) = OPTIONAL];

  // Required. Input context of the generator.
  oneof context {
    // Input of free from generator to LLM.
    FreeFormContext free_form_context = 11;

    // Input of prebuilt Agent Coaching feature.
    AgentCoachingContext agent_coaching_context = 12;

    // Input of prebuilt Summarization feature.
    SummarizationContext summarization_context = 13;
  }

  // Optional. Inference parameters for this generator.
  InferenceParameter inference_parameter = 4
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The trigger event of the generator. It defines when the generator
  // is triggered in a conversation.
  TriggerEvent trigger_event = 5 [(google.api.field_behavior) = OPTIONAL];

  // The foundation model to use for generating suggestions. If a foundation
  // model isn't specified here, a model specifically tuned for the feature
  // type (and version when applicable) will be used.
  oneof foundation_model {
    // Optional. The published Large Language Model name.
    // * To use the latest model version, specify the model name without version
    //   number. Example: `text-bison`
    // * To use a stable model version, specify the version number as well.
    //   Example: `text-bison@002`.
    string published_model = 15 [(google.api.field_behavior) = OPTIONAL];
  }

  // Output only. Creation time of this generator.
  google.protobuf.Timestamp create_time = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Update time of this generator.
  google.protobuf.Timestamp update_time = 9
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Resource names of the tools that the generator can choose from.
  // Format: `projects/<Project ID>/locations/<Location ID>/tools/<tool ID>`.
  repeated string tools = 14 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.resource_reference) = { type: "dialogflow.googleapis.com/Tool" }
  ];

  // Optional. Configuration for suggestion deduping. This is only applicable to
  // AI Coach feature.
  SuggestionDedupingConfig suggestion_deduping_config = 23
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. List of CES toolset specs that the generator can choose from.
  repeated ToolsetTool toolset_tools = 27
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. List of CES tool specs that the generator can choose from.
  repeated CesToolSpec ces_tool_specs = 28
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. List of CES app specs that the generator can choose from.
  repeated CesAppSpec ces_app_specs = 29
      [(google.api.field_behavior) = OPTIONAL];
}

// Suggestion generated using free form generator.
message FreeFormSuggestion {
  // Required. Free form suggestion.
  string response = 1 [(google.api.field_behavior) = REQUIRED];
}

// Suggested summary of the conversation.
message SummarySuggestion {
  // A component of the generated summary.
  message SummarySection {
    // Required. Name of the section.
    string section = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. Summary text for the section.
    string summary = 2 [(google.api.field_behavior) = REQUIRED];
  }

  // Required. All the parts of generated summary.
  repeated SummarySection summary_sections = 1
      [(google.api.field_behavior) = REQUIRED];
}

// Suggestion for coaching agents.
message AgentCoachingSuggestion {
  // Sources for the suggestion.
  message Sources {
    // Output only. Source instruction indexes for the suggestion. This is the
    // index of the applicable_instructions field.
    repeated int32 instruction_indexes = 2
        [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Duplication check for the suggestion.
  message DuplicateCheckResult {
    // The duplicate suggestion details.
    // Keeping answer_record and sources together as they are identifiers for
    // duplicate suggestions.
    message DuplicateSuggestion {
      // Output only. The answer record id of the past duplicate suggestion.
      string answer_record = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. Sources for the suggestion.
      Sources sources = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. The index of the duplicate suggestion in the past
      // suggestion list.
      int32 suggestion_index = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. The similarity score of between the past and current
      // suggestion.
      float similarity_score = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
    }

    // Output only. The duplicate suggestions.
    repeated DuplicateSuggestion duplicate_suggestions = 1
        [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Actions suggested for the agent. This is based on applicable instructions.
  message AgentActionSuggestion {
    // Optional. The suggested action for the agent.
    string agent_action = 1 [(google.api.field_behavior) = OPTIONAL];

    // Output only. Sources for the agent action suggestion.
    Sources sources = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Duplicate check result for the agent action suggestion.
    DuplicateCheckResult duplicate_check_result = 3
        [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Sample response that the agent can use. This could be based on applicable
  // instructions and ingested data from other systems.
  message SampleResponse {
    // Optional. Sample response for Agent in text.
    string response_text = 1 [(google.api.field_behavior) = OPTIONAL];

    // Output only. Sources for the Sample Response.
    Sources sources = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Duplicate check result for the sample response.
    DuplicateCheckResult duplicate_check_result = 3
        [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Optional. Instructions applicable based on the current context.
  repeated AgentCoachingInstruction applicable_instructions = 1
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Suggested actions for the agent to take.
  repeated AgentActionSuggestion agent_action_suggestions = 2
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Sample response for the Agent.
  repeated SampleResponse sample_responses = 3
      [(google.api.field_behavior) = OPTIONAL];
}

// Suggestion generated using a Generator.
message GeneratorSuggestion {
  // Request and response for a tool call.
  message ToolCallInfo {
    // Required. Request for a tool call.
    ToolCall tool_call = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. Response for a tool call.
    ToolCallResult tool_call_result = 2
        [(google.api.field_behavior) = REQUIRED];
  }

  // The suggestion could be one of the many types
  oneof suggestion {
    // Optional. Free form suggestion.
    FreeFormSuggestion free_form_suggestion = 1
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Suggested summary.
    SummarySuggestion summary_suggestion = 2
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Suggestion to coach the agent.
    AgentCoachingSuggestion agent_coaching_suggestion = 3
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Optional. List of request and response for tool calls executed.
  repeated ToolCallInfo tool_call_info = 9
      [(google.api.field_behavior) = OPTIONAL];
}

// Config for suggestion deduping.
// NEXT_ID: 3
message SuggestionDedupingConfig {
  // Optional. Whether to enable suggestion deduping.
  bool enable_deduping = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The threshold for similarity between two suggestions.
  // Acceptable value is [0.0, 1.0], default to 0.8
  float similarity_threshold = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Settings for Responsible AI checks.
message RaiSettings {
  // Configuration for a specific RAI category.
  message RaiCategoryConfig {
    // Enum for RAI category.
    enum RaiCategory {
      // Default value.
      RAI_CATEGORY_UNSPECIFIED = 0;

      // Dangerous content.
      DANGEROUS_CONTENT = 1;

      // Sexually explicit content.
      SEXUALLY_EXPLICIT = 2;

      // Harassment content.
      HARASSMENT = 3;

      // Hate speech content.
      HATE_SPEECH = 4;
    }

    // Enum for user-configurable sensitivity levels.
    enum SensitivityLevel {
      // Default value.
      // If unspecified, the default behavior is:
      // - DANGEROUS_CONTENT: BLOCK_FEW
      // - SEXUALLY_EXPLICIT: BLOCK_SOME
      // - HARASSMENT: BLOCK_SOME
      // - HATE_SPEECH: BLOCK_SOME
      SENSITIVITY_LEVEL_UNSPECIFIED = 0;

      // Block most potentially sensitive responses.
      BLOCK_MOST = 1;

      // Block some potentially sensitive responses.
      BLOCK_SOME = 2;

      // Block a few potentially sensitive responses.
      BLOCK_FEW = 3;

      // No filtering for this category.
      BLOCK_NONE = 4;
    }

    // Optional. The RAI category.
    RaiCategory category = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The sensitivity level for this category.
    SensitivityLevel sensitivity_level = 2
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Configuration for a set of RAI categories.
  repeated RaiCategoryConfig rai_category_configs = 1;
}

// The event that triggers the generator and LLM execution.
enum TriggerEvent {
  // Default value for TriggerEvent.
  TRIGGER_EVENT_UNSPECIFIED = 0;

  // Triggers when each chat message or voice utterance ends.
  END_OF_UTTERANCE = 1;

  // Triggers on the conversation manually by API calls, such as
  // Conversations.GenerateStatelessSuggestion and
  // Conversations.GenerateSuggestions.
  MANUAL_CALL = 2;

  // Triggers after each customer message only.
  CUSTOMER_MESSAGE = 3;

  // Triggers after each agent message only.
  AGENT_MESSAGE = 4;
}