// 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.cx.v3beta1;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/dialogflow/cx/v3beta1/data_store_connection.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.Dialogflow.Cx.V3Beta1";
option go_package = "cloud.google.com/go/dialogflow/cx/apiv3beta1/cxpb;cxpb";
option java_multiple_files = true;
option java_outer_classname = "TraceProto";
option java_package = "com.google.cloud.dialogflow.cx.v3beta1";
option objc_class_prefix = "DF";
option ruby_package = "Google::Cloud::Dialogflow::CX::V3beta1";

// The trace block tracks a sequence of actions taken by the agent in a flow or
// a playbook.
message TraceBlock {
  // Metadata of the trace.
  oneof trace_metadata {
    // Metadata of the playbook trace.
    PlaybookTraceMetadata playbook_trace_metadata = 1;

    // Metadata of the flow trace.
    FlowTraceMetadata flow_trace_metadata = 2;

    // Metadata of the speech-to-text and speech-to-text processing.
    SpeechProcessingMetadata speech_processing_metadata = 8;
  }

  // The actions performed by the agent and the user during this session.
  repeated Action actions = 3;

  // Output only. Timestamp of the start of the trace block.
  google.protobuf.Timestamp start_time = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Timestamp of the end of the trace block.
  google.protobuf.Timestamp complete_time = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. A list of input parameters of the trace block.
  google.protobuf.Struct input_parameters = 9
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of output parameters of the trace block.
  google.protobuf.Struct output_parameters = 6
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Output only. The end state of the trace block.
  OutputState end_state = 7 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = OPTIONAL
  ];
}

// Metadata of the speech-to-text and text-to-speech processing.
message SpeechProcessingMetadata {
  // Output only. The display name of the speech processing.
  string display_name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Metadata of the playbook trace.
message PlaybookTraceMetadata {
  // Required. The unique identifier of the playbook.
  // Format:
  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/playbooks/<PlaybookID>`.
  string playbook = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/Playbook"
    }
  ];

  // Output only. The display name of the playbook.
  string display_name = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Metadata of the flow trace.
message FlowTraceMetadata {
  // Required. The unique identifier of the flow.
  // Format:
  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>`.
  string flow = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "dialogflow.googleapis.com/Flow" }
  ];

  // Output only. The display name of the flow.
  string display_name = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Action performed by end user or Dialogflow agent in the conversation.
message Action {
  // Stores metadata of the intent match action.
  message IntentMatch {
    // Stores the matched intent, which is the result of the intent match
    // action.
    message MatchedIntent {
      // The ID of the matched intent.
      string intent_id = 1;

      // The display name of the matched intent.
      string display_name = 2;

      // The score of the matched intent.
      float score = 3;

      // The generative fallback response of the matched intent.
      google.protobuf.Struct generative_fallback = 4;
    }

    // The matched intent.
    repeated MatchedIntent matched_intents = 1;
  }

  // Stores metadata of the state update action, such as a state machine
  // execution in flows.
  message FlowStateUpdate {
    // Stores the state of a page and its flow.
    message PageState {
      // The ID of the page.
      // Format:
      // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>/pages/<PageID>`.
      string page = 1;

      // The display name of the page.
      string display_name = 2;

      // The status of the page.
      string status = 3;
    }

    // Stores the metadata of a function call to execute.
    message FunctionCall {
      // The name of the function call.
      string name = 1;
    }

    // The type of the event that triggered the state update.
    string event_type = 1;

    // The updated page and flow state.
    PageState page_state = 2;

    // The updated parameters.
    google.protobuf.Struct updated_parameters = 3;

    // The destination of the transition.
    // Format:
    // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>/pages/<PageID>`
    // or
    // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/playbooks/<PlaybookId>`.
    string destination = 4;

    // The function call to execute.
    FunctionCall function_call = 5;
  }

  // Stores metadata of the Text-to-Speech action.
  message TTS {}

  // Stores metadata of the Speech-to-Text action.
  message STT {}

  // Action details.
  oneof action {
    // Optional. Agent obtained a message from the customer.
    UserUtterance user_utterance = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The agent received an event from the customer or a system event
    // is emitted.
    Event event = 7 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Action performed by the agent as a message.
    AgentUtterance agent_utterance = 2 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Action performed on behalf of the agent by calling a plugin
    // tool.
    ToolUse tool_use = 3 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Output only. LLM call performed by the agent.
    LlmCall llm_call = 14 [
      (google.api.field_behavior) = OUTPUT_ONLY,
      (google.api.field_behavior) = OPTIONAL
    ];

    // Optional. Output only. Intent Match in flows.
    IntentMatch intent_match = 17 [
      (google.api.field_behavior) = OUTPUT_ONLY,
      (google.api.field_behavior) = OPTIONAL
    ];

    // Optional. Output only. The state machine update in flows.
    FlowStateUpdate flow_state_update = 18 [
      (google.api.field_behavior) = OUTPUT_ONLY,
      (google.api.field_behavior) = OPTIONAL
    ];

    // Optional. Action performed on behalf of the agent by invoking a child
    // playbook.
    PlaybookInvocation playbook_invocation = 4
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Action performed on behalf of the agent by invoking a CX flow.
    FlowInvocation flow_invocation = 5 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Action performed on behalf of the agent by transitioning to a
    // target playbook.
    PlaybookTransition playbook_transition = 12
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Action performed on behalf of the agent by transitioning to a
    // target CX flow.
    FlowTransition flow_transition = 13
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Text-to-speech action performed by the agent.
    TTS tts = 19 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Speech-to-text action performed by the agent.
    STT stt = 20 [(google.api.field_behavior) = OPTIONAL];
  }

  // Output only. The display name of the action.
  string display_name = 15 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Timestamp of the start of the agent action.
  google.protobuf.Timestamp start_time = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Timestamp of the completion of the agent action.
  google.protobuf.Timestamp complete_time = 9
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The detailed tracing information for sub execution steps of the
  // action.
  repeated Span sub_execution_steps = 11
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Output only. The status of the action.
  Status status = 16 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];
}

// UserUtterance represents one message sent by the customer.
message UserUtterance {
  // Required. Message content in text.
  string text = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Tokens of the audio input.
  repeated int32 audio_tokens = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Audio input.
  bytes audio = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Event represents the event sent by the customer.
message Event {
  // Required. Name of the event.
  string event = 1 [(google.api.field_behavior) = REQUIRED];

  // Payload of the event.
  oneof payload {
    // Optional. Unstructured text payload of the event.
    string text = 2 [(google.api.field_behavior) = OPTIONAL];
  }
}

// AgentUtterance represents one message sent by the agent.
message AgentUtterance {
  // Required. Message content in text.
  string text = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. True if the agent utterance needs to be generated by the LLM.
  // Only used in webhook response to differentiate from empty text. Revisit
  // whether we need this field or mark `text` as optional when we expose
  // webhook interface to customer.
  bool require_generation = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Stores metadata of the invocation of an action supported by a tool.
message ToolUse {
  // The tracing information for the data store tool.
  message DataStoreToolTrace {
    // Optional. Data store connection feature output signals.
    DataStoreConnectionSignals data_store_connection_signals = 1
        [(google.api.field_behavior) = OPTIONAL];
  }

  // The tracing information for the webhook tool.
  message WebhookToolTrace {
    // Optional. The tag of the webhook.
    string webhook_tag = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The url of the webhook.
    string webhook_uri = 2 [(google.api.field_behavior) = OPTIONAL];
  }

  // Required. The [tool][google.cloud.dialogflow.cx.v3beta1.Tool] that should
  // be used. Format:
  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/tools/<ToolID>`.
  string tool = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "dialogflow.googleapis.com/Tool" }
  ];

  // Output only. The display name of the tool.
  string display_name = 8 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Name of the action to be called during the tool use.
  string action = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of input parameters for the action.
  google.protobuf.Struct input_action_parameters = 5
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of output parameters generated by the action.
  google.protobuf.Struct output_action_parameters = 6
      [(google.api.field_behavior) = OPTIONAL];

  // The tracing information for different tools.
  oneof ToolTrace {
    // Optional. Data store tool trace.
    DataStoreToolTrace data_store_tool_trace = 7
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Webhook tool trace.
    WebhookToolTrace webhook_tool_trace = 9
        [(google.api.field_behavior) = OPTIONAL];
  }
}

// Stores metadata of the call of an LLM.
message LlmCall {
  // Relevant example used for the LLM prompt.
  message RetrievedExample {
    // The id of the example.
    string example_id = 1;

    // The display name of the example.
    string example_display_name = 2;

    // Retrieval strategy of the example.
    RetrievalStrategy retrieval_strategy = 3;

    // Optional. The matched retrieval label of this LLM call.
    string matched_retrieval_label = 14
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Stores token counts of the LLM call.
  message TokenCount {
    // The total number of tokens used for the input to the LLM call.
    int64 total_input_token_count = 1;

    // The number of tokens used for the conversation history in the prompt.
    int64 conversation_context_token_count = 3;

    // The number of tokens used for the retrieved examples in the prompt.
    int64 example_token_count = 4;

    // The total number of tokens used for the output of the LLM call.
    int64 total_output_token_count = 5;
  }

  // A list of relevant examples used for the LLM prompt.
  repeated RetrievedExample retrieved_examples = 1;

  // The token counts of the LLM call.
  TokenCount token_count = 2;

  // The model of the LLM call.
  string model = 3;

  // The temperature of the LLM call.
  float temperature = 4;
}

// Stores metadata of the invocation of a child playbook. Playbook invocation
// actions enter the child playbook.
message PlaybookInvocation {
  // Required. The unique identifier of the playbook.
  // Format:
  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/playbooks/<PlaybookID>`.
  string playbook = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/Playbook"
    }
  ];

  // Output only. The display name of the playbook.
  string display_name = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Input of the child playbook invocation.
  PlaybookInput playbook_input = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Output of the child playbook invocation.
  PlaybookOutput playbook_output = 3 [(google.api.field_behavior) = OPTIONAL];

  // Required. Playbook invocation's output state.
  OutputState playbook_state = 4 [(google.api.field_behavior) = REQUIRED];
}

// Stores metadata of the invocation of a child CX flow. Flow invocation actions
// enter the child flow.
message FlowInvocation {
  // Required. The unique identifier of the flow.
  // Format:
  // `projects/<ProjectID>/locations/<LocationID>/agents/<Agentflows/<FlowID>`.
  string flow = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "dialogflow.googleapis.com/Flow" }
  ];

  // Output only. The display name of the flow.
  string display_name = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. A list of input parameters for the flow.
  google.protobuf.Struct input_action_parameters = 5
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of output parameters generated by the flow invocation.
  google.protobuf.Struct output_action_parameters = 6
      [(google.api.field_behavior) = OPTIONAL];

  // Required. Flow invocation's output state.
  OutputState flow_state = 4 [(google.api.field_behavior) = REQUIRED];
}

// Stores metadata of the transition to another target playbook. Playbook
// transition actions exit the caller playbook and enter the target playbook.
message PlaybookTransition {
  // Required. The unique identifier of the playbook.
  // Format:
  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/playbooks/<PlaybookID>`.
  string playbook = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/Playbook"
    }
  ];

  // Output only. The display name of the playbook.
  string display_name = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // A list of input parameters for the action.
  google.protobuf.Struct input_action_parameters = 2 [deprecated = true];
}

// Stores metadata of the transition to a target CX flow. Flow transition
// actions exit the caller playbook and enter the child flow.
message FlowTransition {
  // Required. The unique identifier of the flow.
  // Format:
  // `projects/<ProjectID>/locations/<LocationID>/agents/<Agentflows/<FlowID>`.
  string flow = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "dialogflow.googleapis.com/Flow" }
  ];

  // Output only. The display name of the flow.
  string display_name = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // A list of input parameters for the action.
  google.protobuf.Struct input_action_parameters = 2 [deprecated = true];
}

// Input of the playbook.
message PlaybookInput {
  // Optional. Summary string of the preceding conversation for the child
  // playbook invocation.
  string preceding_conversation_summary = 1
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of input parameters for the action.
  google.protobuf.Struct action_parameters = 3
      [(google.api.field_behavior) = OPTIONAL];
}

// Output of the playbook.
message PlaybookOutput {
  // Playbook output state.
  enum State {
    option deprecated = true;

    // Unspecified state.
    STATE_UNSPECIFIED = 0;

    // Playbook succeeded.
    OK = 1;

    // Playbook cancelled.
    CANCELLED = 2;

    // Playbook failed.
    FAILED = 3;

    // Playbook failed due to escalation.
    ESCALATED = 4;
  }

  // Optional. Summary string of the execution result of the child playbook.
  string execution_summary = 1 [(google.api.field_behavior) = OPTIONAL];

  // End state of the playbook.
  State state = 2 [deprecated = true];

  // Optional. A Struct object of output parameters for the action.
  google.protobuf.Struct action_parameters = 4
      [(google.api.field_behavior) = OPTIONAL];
}

// A span represents a sub execution step of an action.
message Span {
  // The name of the span.
  string name = 1;

  // The metadata tags of the span such as span type.
  repeated string tags = 2;

  // The unordered collection of metrics in this span.
  repeated NamedMetric metrics = 3;

  // Timestamp of the start of the span.
  google.protobuf.Timestamp start_time = 4;

  // Timestamp of the completion of the span.
  google.protobuf.Timestamp complete_time = 5;
}

// A named metric is a metric with name, value and unit.
message NamedMetric {
  // The name of the metric.
  string name = 1;

  // The value of the metric.
  google.protobuf.Value value = 2;

  // The unit in which this metric is reported. Follows [The Unified Code for
  // Units of Measure](https://unitsofmeasure.org/ucum.html) standard.
  string unit = 3;
}

// The status of the action.
message Status {
  // Optional. The exception thrown during the execution of the action.
  ExceptionDetail exception = 1 [(google.api.field_behavior) = OPTIONAL];
}

// Exception thrown during the execution of an action.
message ExceptionDetail {
  // Optional. The error message.
  string error_message = 1 [(google.api.field_behavior) = OPTIONAL];
}

// Output state.
enum OutputState {
  // Unspecified output.
  OUTPUT_STATE_UNSPECIFIED = 0;

  // Succeeded.
  OUTPUT_STATE_OK = 1;

  // Cancelled.
  OUTPUT_STATE_CANCELLED = 2;

  // Failed.
  OUTPUT_STATE_FAILED = 3;

  // Escalated.
  OUTPUT_STATE_ESCALATED = 4;

  // Pending.
  OUTPUT_STATE_PENDING = 5;
}

// Retrieval strategy on how the example is selected to be fed to the prompt.
enum RetrievalStrategy {
  // Not specified. `DEFAULT` will be used.
  RETRIEVAL_STRATEGY_UNSPECIFIED = 0;

  // Default retrieval strategy.
  DEFAULT = 1;

  // Static example will always be inserted to the prompt.
  STATIC = 2;

  // Example will never be inserted into the prompt.
  NEVER = 3;
}