googleapis/google/cloud/dialogflow/cx/v3/trace.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.cx.v3;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";

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

// 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];
}

// 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];
}

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

// Action performed by end user or Dialogflow agent in the conversation.
message Action {
  // Action details.
  oneof action {
    // Optional. Agent obtained a message from the customer.
    UserUtterance user_utterance = 1 [(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. 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];
  }
}

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

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

// Stores metadata of the invocation of an action supported by a tool.
message ToolUse {
  // Required. The [tool][google.cloud.dialogflow.cx.v3.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];
}

// Stores metadata of the invocation of a 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 CX flow.
message FlowInvocation {
  // 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 = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // 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];
}

// 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];
}

// 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;
}