// 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.aiplatform.v1beta1;

import "google/api/field_behavior.proto";
import "google/cloud/aiplatform/v1beta1/content.proto";
import "google/cloud/aiplatform/v1beta1/tool.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1";
option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb";
option java_multiple_files = true;
option java_outer_classname = "EvaluationAgentDataProto";
option java_package = "com.google.cloud.aiplatform.v1beta1";
option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1";
option ruby_package = "Google::Cloud::AIPlatform::V1beta1";

// Represents data specific to multi-turn agent evaluations.
message AgentData {
  // Optional. A map containing the static configurations for each agent in the
  // system. Key: agent_id (matches the `author` field in events). Value: The
  // static configuration of the agent.
  map<string, AgentConfig> agents = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A chronological list of conversation turns.
  // Each turn represents a logical execution cycle (e.g., User Input -> Agent
  // Response).
  repeated ConversationTurn turns = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Represents configuration for an Agent.
message AgentConfig {
  // Required. Unique identifier of the agent.
  // This ID is used to refer to this agent, e.g., in AgentEvent.author, or in
  // the `sub_agents` field. It must be unique within the `agents` map.
  optional string agent_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The type or class of the agent (e.g., "LlmAgent", "RouterAgent",
  // "ToolUseAgent"). Useful for the autorater to understand the expected
  // behavior of the agent.
  string agent_type = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A high-level description of the agent's role and
  // responsibilities. Critical for evaluating if the agent is routing tasks
  // correctly.
  string description = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Provides instructions for the LLM model, guiding the agent's
  // behavior. Can be static or dynamic. Dynamic instructions can contain
  // placeholders like {variable_name} that will be resolved at runtime using
  // the `AgentEvent.state_delta` field.
  string instruction = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The list of tools available to this agent.
  repeated Tool tools = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The list of valid agent IDs that this agent can delegate to.
  // This defines the directed edges in the multi-agent system graph topology.
  repeated string sub_agents = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Represents a single turn/invocation in the conversation.
message ConversationTurn {
  // Required. The 0-based index of the turn in the conversation sequence.
  optional int32 turn_index = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. A unique identifier for the turn.
  // Useful for referencing specific turns across systems.
  string turn_id = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The list of events that occurred during this turn.
  repeated AgentEvent events = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Represents a single event in the execution trace.
message AgentEvent {
  // Required. The ID of the agent or entity that generated this event.
  // Use "user" to denote events generated by the end-user.
  optional string author = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The content of the event (e.g., text response, tool call, tool
  // response).
  optional Content content = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. The timestamp when the event occurred.
  google.protobuf.Timestamp event_time = 3
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The change in the session state caused by this event. This is a
  // key-value map of fields that were modified or added by the event.
  google.protobuf.Struct state_delta = 4
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The list of tools that were active/available to the agent at the
  // time of this event. This overrides the `AgentConfig.tools` if set.
  repeated Tool active_tools = 5 [(google.api.field_behavior) = OPTIONAL];
}