google-cloud-agentplatform 1.165.1.dev0__py3-none-any.whl

agentplatform/_genai/types/evals.py

@@ -0,0 +1,1031 @@
+# Copyright 2025 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.
+#
+
+# Code generated by the Google Gen AI SDK generator DO NOT EDIT.
+
+import datetime
+from typing import Any, Optional, Union
+from google.genai import _common
+from google.genai import types as genai_types
+from pydantic import Field
+from typing_extensions import TypedDict
+
+
+class Importance(_common.CaseInSensitiveEnum):
+    """Importance level of the rubric."""
+
+    IMPORTANCE_UNSPECIFIED = "IMPORTANCE_UNSPECIFIED"
+    """Importance is not specified."""
+    HIGH = "HIGH"
+    """High importance."""
+    MEDIUM = "MEDIUM"
+    """Medium importance."""
+    LOW = "LOW"
+    """Low importance."""
+
+
+class AgentConfig(_common.BaseModel):
+    """Represents configuration for an Agent."""
+
+    agent_id: Optional[str] = Field(
+        default=None,
+        description="""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.""",
+    )
+    agent_type: Optional[str] = Field(
+        default=None,
+        description="""The type or class of the agent (e.g., "LlmAgent", "RouterAgent",
+      "ToolUseAgent"). Useful for the autorater to understand the expected
+      behavior of the agent.""",
+    )
+    description: Optional[str] = Field(
+        default=None,
+        description="""A high-level description of the agent's role and responsibilities.
+      Critical for evaluating if the agent is routing tasks correctly.""",
+    )
+    instruction: Optional[str] = Field(
+        default=None,
+        description="""The 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.""",
+    )
+    tools: Optional[list[genai_types.Tool]] = Field(
+        default=None, description="""The list of tools available to this agent."""
+    )
+    sub_agents: Optional[list[str]] = Field(
+        default=None,
+        description="""The list of valid agent IDs that this agent can delegate to.
+      This defines the directed edges in the multi-agent system graph topology.""",
+    )
+
+    @staticmethod
+    def _get_tool_declarations_from_agent(agent: Any) -> genai_types.ToolListUnion:
+        """Gets tool declarations from an agent.
+
+        Args:
+          agent: The agent to get the tool declarations from. Data type is google.adk.agents.LLMAgent type.
+
+        Returns:
+          The tool declarations of the agent.
+        """
+        tool_declarations: genai_types.ToolListUnion = []
+        for tool in getattr(agent, "tools", None) or []:
+            # ADK tools (e.g. AgentTool, VertexAiSearchTool) own their declaration
+            # via _get_declaration(). A None result means the tool has no function
+            # declaration (e.g. built-in retrieval tools). In both cases, skip the
+            # plain-callable path, which calls typing.get_type_hints() on the
+            # instance and raises NameError for classes using
+            # `from __future__ import annotations`.
+            if hasattr(tool, "_get_declaration") and callable(tool._get_declaration):
+                declaration = tool._get_declaration()
+                if declaration is not None:
+                    tool_declarations.append({"function_declarations": [declaration]})
+                continue
+
+            declaration = AgentConfig._get_declaration_from_callable(tool)
+            if declaration is not None:
+                tool_declarations.append({"function_declarations": [declaration]})
+        return tool_declarations
+
+    @staticmethod
+    def _get_declaration_from_callable(
+        tool: Any,
+    ) -> Optional[genai_types.FunctionDeclaration]:
+        """Builds a function declaration for a plain callable tool.
+
+        ADK agents store plain Python functions in `agent.tools` and only wrap
+        them in `FunctionTool` lazily at runtime. Such functions often take
+        ADK-injected parameters (e.g. `tool_context: ToolContext`) that the
+        generic `google-genai` schema generator rejects. When google-adk is
+        available, wrap the callable in ADK's `FunctionTool` so its declaration
+        logic strips those injected parameters. Otherwise, fall back to the
+        generic generator.
+
+        Args:
+          tool: A plain callable tool from an agent's `tools` list.
+
+        Returns:
+          The function declaration for the tool, or None if the tool has no
+          declaration.
+        """
+        # pylint: disable=g-import-not-at-top,protected-access
+        # The returned FunctionDeclaration may populate either `parameters` or
+        # `parameters_json_schema` depending on the installed google-adk version
+        # and the JSON_SCHEMA_FOR_FUNC_DECL feature flag (default-on in adk>=2.2).
+        # A future adk major version will drop `parameters`, so downstream
+        # consumers must handle both fields.
+        try:
+            from google.adk.tools.function_tool import FunctionTool
+
+            return FunctionTool(func=tool)._get_declaration()  # type: ignore[no-any-return]
+        except ImportError:
+            pass
+        return genai_types.FunctionDeclaration.from_callable_with_api_option(
+            callable=tool
+        )
+
+    @classmethod
+    def from_agent(cls, agent: Any) -> "AgentConfig":
+        """Creates an AgentConfig from an ADK agent.
+
+        Args:
+          agent: The agent to get the agent info from, data type is google.adk.agents.LLMAgent type.
+
+        Returns:
+            An AgentConfig populated with the agent's metadata for evaluation.
+        """
+        agent_id = getattr(agent, "name", None)
+        if not agent_id:
+            raise ValueError(f"Agent {agent} must have a name.")
+        return cls(  # pytype: disable=missing-parameter
+            agent_id=agent_id,
+            agent_type=agent.__class__.__name__,
+            description=getattr(agent, "description", None),
+            instruction=getattr(agent, "instruction", None),
+            tools=AgentConfig._get_tool_declarations_from_agent(agent),
+            sub_agents=[
+                str(getattr(sub_agent, "name"))
+                for sub_agent in getattr(agent, "sub_agents", [])
+                if getattr(sub_agent, "name", None) is not None
+            ],
+        )
+
+
+class AgentConfigDict(TypedDict, total=False):
+    """Represents configuration for an Agent."""
+
+    agent_id: Optional[str]
+    """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."""
+
+    agent_type: Optional[str]
+    """The type or class of the agent (e.g., "LlmAgent", "RouterAgent",
+      "ToolUseAgent"). Useful for the autorater to understand the expected
+      behavior of the agent."""
+
+    description: Optional[str]
+    """A high-level description of the agent's role and responsibilities.
+      Critical for evaluating if the agent is routing tasks correctly."""
+
+    instruction: Optional[str]
+    """The 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."""
+
+    tools: Optional[list[genai_types.Tool]]
+    """The list of tools available to this agent."""
+
+    sub_agents: Optional[list[str]]
+    """The list of valid agent IDs that this agent can delegate to.
+      This defines the directed edges in the multi-agent system graph topology."""
+
+
+AgentConfigOrDict = Union[AgentConfig, AgentConfigDict]
+
+
+class AgentEvent(_common.BaseModel):
+    """A single event in the execution trace."""
+
+    author: Optional[str] = Field(
+        default=None,
+        description="""The ID of the agent or entity that generated this event.
+      Use "user" to denote events generated by the end-user.""",
+    )
+    content: Optional[genai_types.Content] = Field(
+        default=None, description="""The content of the event."""
+    )
+    event_time: Optional[datetime.datetime] = Field(
+        default=None, description="""The timestamp when the event occurred."""
+    )
+    state_delta: Optional[dict[str, Any]] = Field(
+        default=None,
+        description="""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.""",
+    )
+    active_tools: Optional[list[genai_types.Tool]] = Field(
+        default=None,
+        description="""The list of tools that were active/available to the agent at the
+      time of this event. This overrides the `AgentConfig.tools` if set.""",
+    )
+
+
+class AgentEventDict(TypedDict, total=False):
+    """A single event in the execution trace."""
+
+    author: Optional[str]
+    """The ID of the agent or entity that generated this event.
+      Use "user" to denote events generated by the end-user."""
+
+    content: Optional[genai_types.Content]
+    """The content of the event."""
+
+    event_time: Optional[datetime.datetime]
+    """The timestamp when the event occurred."""
+
+    state_delta: Optional[dict[str, Any]]
+    """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."""
+
+    active_tools: Optional[list[genai_types.Tool]]
+    """The list of tools that were active/available to the agent at the
+      time of this event. This overrides the `AgentConfig.tools` if set."""
+
+
+AgentEventOrDict = Union[AgentEvent, AgentEventDict]
+
+
+class ConversationTurn(_common.BaseModel):
+    """Represents a single turn/invocation in the conversation."""
+
+    turn_index: Optional[int] = Field(
+        default=None,
+        description="""The 0-based index of the turn in the conversation sequence.""",
+    )
+    turn_id: Optional[str] = Field(
+        default=None, description="""A unique identifier for the turn."""
+    )
+    events: Optional[list[AgentEvent]] = Field(
+        default=None,
+        description="""The list of events that occurred during this turn.""",
+    )
+
+
+class ConversationTurnDict(TypedDict, total=False):
+    """Represents a single turn/invocation in the conversation."""
+
+    turn_index: Optional[int]
+    """The 0-based index of the turn in the conversation sequence."""
+
+    turn_id: Optional[str]
+    """A unique identifier for the turn."""
+
+    events: Optional[list[AgentEventDict]]
+    """The list of events that occurred during this turn."""
+
+
+ConversationTurnOrDict = Union[ConversationTurn, ConversationTurnDict]
+
+
+class AgentData(_common.BaseModel):
+    """Represents data specific to multi-turn agent evaluations."""
+
+    agents: Optional[dict[str, AgentConfig]] = Field(
+        default=None,
+        description="""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.""",
+    )
+    turns: Optional[list[ConversationTurn]] = Field(
+        default=None,
+        description="""A chronological list of conversation turns.
+      Each turn represents a logical execution cycle (e.g., User Input -> Agent
+      Response).""",
+    )
+
+    @classmethod
+    def get_agents_map(cls, agent: Any) -> dict[str, AgentConfig]:
+        """Recursively gets all agent configs from an agent and its sub-agents.
+
+        Args:
+          agent: The agent to get the agent info from, data type is google.adk.agents.LLMAgent type.
+
+        Returns:
+          A dict mapping agent_id to AgentConfig.
+        """
+        agent_config = AgentConfig.from_agent(agent)
+        agent_id = agent_config.agent_id
+        if not agent_id:
+            raise ValueError(f"Agent {agent} must have a name.")
+        agents_map = {agent_id: agent_config}
+
+        for sub_agent in getattr(agent, "sub_agents", []):
+            agents_map.update(cls.get_agents_map(sub_agent))
+
+        return agents_map
+
+    @classmethod
+    def from_session(cls, agent: Any, session_history: list[Any]) -> "AgentData":
+        """Creates an AgentData object from a session history.
+
+        Segments the flat list of session events into ConversationTurns. A new turn
+        is initiated by a User message.
+
+        Args:
+            agent: The agent instance used in the session.
+            session_history: A list of raw events/messages from the session.
+
+        Returns:
+            An AgentData object containing the segmented history and agent config.
+        """
+        agents_map = cls.get_agents_map(agent)
+        agent_id = agent.name
+
+        turns: list[ConversationTurn] = []
+        current_turn_events: list[AgentEvent] = []
+
+        for event in session_history:
+            is_user = False
+            if isinstance(event, dict):
+                if event.get("role") == "user":
+                    is_user = True
+                elif (
+                    isinstance(event.get("content"), dict)
+                    and event["content"].get("role") == "user"
+                ):
+                    is_user = True
+            elif hasattr(event, "role") and event.role == "user":
+                is_user = True
+
+            if is_user and current_turn_events:
+                turns.append(
+                    ConversationTurn(  # pytype: disable=missing-parameter
+                        turn_index=len(turns),
+                        turn_id=f"turn_{len(turns)}",
+                        events=current_turn_events,
+                    )
+                )
+                current_turn_events = []
+
+            author = "user" if is_user else agent_id
+
+            content = None
+            if isinstance(event, dict):
+                if "content" in event:
+                    raw_content = event["content"]
+                    if isinstance(raw_content, genai_types.Content):
+                        content = raw_content
+                    elif isinstance(raw_content, dict):
+                        try:
+                            content = genai_types.Content.model_validate(raw_content)
+                        except Exception as e:
+                            raise ValueError(
+                                f"Failed to validate Content from dictionary in session history: {raw_content}"
+                            ) from e
+                    elif isinstance(raw_content, str):
+                        content = genai_types.Content(
+                            parts=[genai_types.Part(text=raw_content)]
+                        )
+                elif "parts" in event:
+                    try:
+                        content = genai_types.Content.model_validate(event)
+                    except Exception as e:
+                        raise ValueError(
+                            f"Failed to validate Content from event with 'parts': {event}"
+                        ) from e
+            elif hasattr(event, "content") and isinstance(
+                event.content, genai_types.Content
+            ):
+                content = event.content
+
+            agent_event = AgentEvent(  # pytype: disable=missing-parameter
+                author=author,
+                content=content,
+            )
+            current_turn_events.append(agent_event)
+
+        if current_turn_events:
+            turns.append(
+                ConversationTurn(  # pytype: disable=missing-parameter
+                    turn_index=len(turns),
+                    turn_id=f"turn_{len(turns)}",
+                    events=current_turn_events,
+                )
+            )
+
+        return cls(agents=agents_map, turns=turns)  # pytype: disable=missing-parameter
+
+
+class AgentDataDict(TypedDict, total=False):
+    """Represents data specific to multi-turn agent evaluations."""
+
+    agents: Optional[dict[str, AgentConfigDict]]
+    """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."""
+
+    turns: Optional[list[ConversationTurnDict]]
+    """A chronological list of conversation turns.
+      Each turn represents a logical execution cycle (e.g., User Input -> Agent
+      Response)."""
+
+
+AgentDataOrDict = Union[AgentData, AgentDataDict]
+
+
+class AgentInfo(_common.BaseModel):
+    """The agent info of an agent system, used for agent evaluation."""
+
+    name: Optional[str] = Field(
+        default=None, description="""Agent candidate name, used as an identifier."""
+    )
+    agents: Optional[dict[str, AgentConfig]] = Field(
+        default=None,
+        description="""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.""",
+    )
+    root_agent_id: Optional[str] = Field(
+        default=None, description="""The agent ID of the root agent."""
+    )
+
+    @classmethod
+    def load_from_agent(cls, agent: Any) -> "AgentInfo":
+        """Loads agent info from an ADK agent.
+
+        Args:
+          agent: The root agent to get the agent info from, data type is google.adk.agents.LLMAgent type.
+
+        Returns:
+          The agent info of the agent system.
+
+        Example:
+        ```
+        from agentplatform._genai import types
+
+        agent_info = types.evals.AgentInfo.load_from_agent(agent=my_agent)
+        ```
+        """
+        agent_name = getattr(agent, "name", None)
+        if not agent_name:
+            raise ValueError(f"Agent {agent} must have a name.")
+        return cls(  # pytype: disable=missing-parameter
+            name=agent_name,
+            agents=AgentData.get_agents_map(agent),
+            root_agent_id=agent_name,
+        )
+
+
+class AgentInfoDict(TypedDict, total=False):
+    """The agent info of an agent system, used for agent evaluation."""
+
+    name: Optional[str]
+    """Agent candidate name, used as an identifier."""
+
+    agents: Optional[dict[str, AgentConfigDict]]
+    """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."""
+
+    root_agent_id: Optional[str]
+    """The agent ID of the root agent."""
+
+
+AgentInfoOrDict = Union[AgentInfo, AgentInfoDict]
+
+
+class SessionInput(_common.BaseModel):
+    """Input to initialize a session and run an agent, used for agent evaluation."""
+
+    user_id: Optional[str] = Field(default=None, description="""The user id.""")
+    state: Optional[dict[str, str]] = Field(
+        default=None, description="""The state of the session."""
+    )
+    app_name: Optional[str] = Field(
+        default=None,
+        description="""The name of the app, used for local ADK agent run Runner and Session.""",
+    )
+
+
+class SessionInputDict(TypedDict, total=False):
+    """Input to initialize a session and run an agent, used for agent evaluation."""
+
+    user_id: Optional[str]
+    """The user id."""
+
+    state: Optional[dict[str, str]]
+    """The state of the session."""
+
+    app_name: Optional[str]
+    """The name of the app, used for local ADK agent run Runner and Session."""
+
+
+SessionInputOrDict = Union[SessionInput, SessionInputDict]
+
+
+class UserScenario(_common.BaseModel):
+    """User scenario to help simulate multi-turn agent run results."""
+
+    starting_prompt: Optional[str] = Field(
+        default=None,
+        description="""Starting prompt for the conversation between simulated user and agent under the test.""",
+    )
+    conversation_plan: Optional[str] = Field(
+        default=None,
+        description="""Conversation plan to drive multi-turn agent run and get simulated agent eval dataset.""",
+    )
+    test_case_title: Optional[str] = Field(
+        default=None,
+        description="""Represents a short 3-5 word title for eval test case.""",
+    )
+
+
+class UserScenarioDict(TypedDict, total=False):
+    """User scenario to help simulate multi-turn agent run results."""
+
+    starting_prompt: Optional[str]
+    """Starting prompt for the conversation between simulated user and agent under the test."""
+
+    conversation_plan: Optional[str]
+    """Conversation plan to drive multi-turn agent run and get simulated agent eval dataset."""
+
+    test_case_title: Optional[str]
+    """Represents a short 3-5 word title for eval test case."""
+
+
+UserScenarioOrDict = Union[UserScenario, UserScenarioDict]
+
+
+class UserScenarioGenerationConfig(_common.BaseModel):
+    """User scenario generation configuration."""
+
+    model_name: Optional[str] = Field(
+        default=None,
+        description="""Optional. The model name to use for generation. It can be model name, e.g. "gemini-3-pro-preview". or the fully qualified name of the publisher model or endpoint. Publisher model format: `projects/{project}/locations/{location}/publishers/*/models/*` Endpoint format: `projects/{project}/locations/{location}/endpoints/{endpoint}`""",
+    )
+    count: Optional[int] = Field(
+        default=None,
+        description="""The number of user scenarios to generate. The maximum number of scenarios that can be generated is 100.""",
+    )
+    generation_instruction: Optional[str] = Field(
+        default=None,
+        description="""Instruction to guide the conversation scenario generation.""",
+    )
+    environment_context: Optional[str] = Field(
+        default=None,
+        description="""Environment context to drive simulation. For example, for a QA agent, this could be the docs queried by the tools.""",
+    )
+    environment_data: Optional[str] = Field(
+        default=None, description="""Optional. Environment data in string type."""
+    )
+    simulation_instruction: Optional[str] = Field(
+        default=None,
+        description="""Optional. Simulation instruction to guide the user scenario generation.""",
+    )
+    user_scenario_count: Optional[int] = Field(
+        default=None,
+        description="""Required. The number of user scenarios to generate. The maximum number of scenarios that can be generated is 100.""",
+    )
+
+
+class UserScenarioGenerationConfigDict(TypedDict, total=False):
+    """User scenario generation configuration."""
+
+    model_name: Optional[str]
+    """Optional. The model name to use for generation. It can be model name, e.g. "gemini-3-pro-preview". or the fully qualified name of the publisher model or endpoint. Publisher model format: `projects/{project}/locations/{location}/publishers/*/models/*` Endpoint format: `projects/{project}/locations/{location}/endpoints/{endpoint}`"""
+
+    count: Optional[int]
+    """The number of user scenarios to generate. The maximum number of scenarios that can be generated is 100."""
+
+    generation_instruction: Optional[str]
+    """Instruction to guide the conversation scenario generation."""
+
+    environment_context: Optional[str]
+    """Environment context to drive simulation. For example, for a QA agent, this could be the docs queried by the tools."""
+
+    environment_data: Optional[str]
+    """Optional. Environment data in string type."""
+
+    simulation_instruction: Optional[str]
+    """Optional. Simulation instruction to guide the user scenario generation."""
+
+    user_scenario_count: Optional[int]
+    """Required. The number of user scenarios to generate. The maximum number of scenarios that can be generated is 100."""
+
+
+UserScenarioGenerationConfigOrDict = Union[
+    UserScenarioGenerationConfig, UserScenarioGenerationConfigDict
+]
+
+
+class UserSimulatorConfig(_common.BaseModel):
+    """Configuration for a user simulator.
+
+    Uses an LLM to generate multi-turn messages that simulate a user.
+    """
+
+    model_name: Optional[str] = Field(
+        default=None,
+        description="""The model name to get next user message for multi-turn agent run.""",
+    )
+    model_configuration: Optional[genai_types.GenerateContentConfig] = Field(
+        default=None, description="""The configuration for the model."""
+    )
+    max_turn: Optional[int] = Field(
+        default=None,
+        description="""Maximum number of invocations allowed by the multi-turn agent
+      running. This property allows us to stop a run-off conversation
+      where the agent and the user simulator get into a never ending loop.
+      The initial fixed prompt is also counted as an invocation.""",
+    )
+
+
+class UserSimulatorConfigDict(TypedDict, total=False):
+    """Configuration for a user simulator.
+
+    Uses an LLM to generate multi-turn messages that simulate a user.
+    """
+
+    model_name: Optional[str]
+    """The model name to get next user message for multi-turn agent run."""
+
+    model_configuration: Optional[genai_types.GenerateContentConfig]
+    """The configuration for the model."""
+
+    max_turn: Optional[int]
+    """Maximum number of invocations allowed by the multi-turn agent
+      running. This property allows us to stop a run-off conversation
+      where the agent and the user simulator get into a never ending loop.
+      The initial fixed prompt is also counted as an invocation."""
+
+
+UserSimulatorConfigOrDict = Union[UserSimulatorConfig, UserSimulatorConfigDict]
+
+
+class Event(_common.BaseModel):
+    """Represents an event in a conversation between agents and users.
+
+    It is used to store the content of the conversation, as well as the actions
+    taken by the agents like function calls, function responses, intermediate NL
+    responses etc.
+    """
+
+    event_id: Optional[str] = Field(
+        default=None, description="""Unique identifier for the agent event."""
+    )
+    content: Optional[genai_types.Content] = Field(
+        default=None, description="""Content of the event."""
+    )
+    creation_timestamp: Optional[datetime.datetime] = Field(
+        default=None, description="""The creation timestamp of the event."""
+    )
+    author: Optional[str] = Field(
+        default=None, description="""Name of the entity that produced the event."""
+    )
+
+
+class EventDict(TypedDict, total=False):
+    """Represents an event in a conversation between agents and users.
+
+    It is used to store the content of the conversation, as well as the actions
+    taken by the agents like function calls, function responses, intermediate NL
+    responses etc.
+    """
+
+    event_id: Optional[str]
+    """Unique identifier for the agent event."""
+
+    content: Optional[genai_types.Content]
+    """Content of the event."""
+
+    creation_timestamp: Optional[datetime.datetime]
+    """The creation timestamp of the event."""
+
+    author: Optional[str]
+    """Name of the entity that produced the event."""
+
+
+EventOrDict = Union[Event, EventDict]
+
+
+class Message(_common.BaseModel):
+    """Represents a single message turn in a conversation."""
+
+    turn_id: Optional[str] = Field(
+        default=None, description="""Unique identifier for the message turn."""
+    )
+    content: Optional[genai_types.Content] = Field(
+        default=None, description="""Content of the message, including function call."""
+    )
+    creation_timestamp: Optional[datetime.datetime] = Field(
+        default=None,
+        description="""Timestamp indicating when the message was created.""",
+    )
+    author: Optional[str] = Field(
+        default=None, description="""Name of the entity that produced the message."""
+    )
+
+
+class MessageDict(TypedDict, total=False):
+    """Represents a single message turn in a conversation."""
+
+    turn_id: Optional[str]
+    """Unique identifier for the message turn."""
+
+    content: Optional[genai_types.Content]
+    """Content of the message, including function call."""
+
+    creation_timestamp: Optional[datetime.datetime]
+    """Timestamp indicating when the message was created."""
+
+    author: Optional[str]
+    """Name of the entity that produced the message."""
+
+
+MessageOrDict = Union[Message, MessageDict]
+
+
+class Events(_common.BaseModel):
+    """This field is experimental and will be removed in future versions.
+
+    Represents a list of events for an agent.
+    """
+
+    event: Optional[list[genai_types.Content]] = Field(
+        default=None, description="""A list of events."""
+    )
+
+
+class EventsDict(TypedDict, total=False):
+    """This field is experimental and will be removed in future versions.
+
+    Represents a list of events for an agent.
+    """
+
+    event: Optional[list[genai_types.Content]]
+    """A list of events."""
+
+
+EventsOrDict = Union[Events, EventsDict]
+
+
+class InstanceDataContents(_common.BaseModel):
+    """This field is experimental and will be removed in future versions.
+
+    List of standard Content messages from Gemini API.
+    """
+
+    contents: Optional[list[genai_types.Content]] = Field(
+        default=None, description="""Repeated contents."""
+    )
+
+
+class InstanceDataContentsDict(TypedDict, total=False):
+    """This field is experimental and will be removed in future versions.
+
+    List of standard Content messages from Gemini API.
+    """
+
+    contents: Optional[list[genai_types.Content]]
+    """Repeated contents."""
+
+
+InstanceDataContentsOrDict = Union[InstanceDataContents, InstanceDataContentsDict]
+
+
+class InstanceData(_common.BaseModel):
+    """This field is experimental and will be removed in future versions.
+
+    Instance data used to populate placeholders in a metric prompt template.
+    """
+
+    text: Optional[str] = Field(default=None, description="""Text data.""")
+    contents: Optional[InstanceDataContents] = Field(
+        default=None, description="""List of Gemini content data."""
+    )
+
+
+class InstanceDataDict(TypedDict, total=False):
+    """This field is experimental and will be removed in future versions.
+
+    Instance data used to populate placeholders in a metric prompt template.
+    """
+
+    text: Optional[str]
+    """Text data."""
+
+    contents: Optional[InstanceDataContentsDict]
+    """List of Gemini content data."""
+
+
+InstanceDataOrDict = Union[InstanceData, InstanceDataDict]
+
+
+class Tools(_common.BaseModel):
+    """This field is experimental and will be removed in future versions.
+
+    Represents a list of tools for an agent.
+    """
+
+    tool: Optional[list[genai_types.Tool]] = Field(
+        default=None,
+        description="""List of tools: each tool can have multiple function declarations.""",
+    )
+
+
+class ToolsDict(TypedDict, total=False):
+    """This field is experimental and will be removed in future versions.
+
+    Represents a list of tools for an agent.
+    """
+
+    tool: Optional[list[genai_types.Tool]]
+    """List of tools: each tool can have multiple function declarations."""
+
+
+ToolsOrDict = Union[Tools, ToolsDict]
+
+
+class RubricContentProperty(_common.BaseModel):
+    """Defines criteria based on a specific property."""
+
+    description: Optional[str] = Field(
+        default=None,
+        description="""Description of the property being evaluated.
+      Example: "The model's response is grammatically correct." """,
+    )
+
+
+class RubricContentPropertyDict(TypedDict, total=False):
+    """Defines criteria based on a specific property."""
+
+    description: Optional[str]
+    """Description of the property being evaluated.
+      Example: "The model's response is grammatically correct." """
+
+
+RubricContentPropertyOrDict = Union[RubricContentProperty, RubricContentPropertyDict]
+
+
+class RubricContent(_common.BaseModel):
+    """Content of the rubric, defining the testable criteria."""
+
+    property: Optional[RubricContentProperty] = Field(
+        default=None,
+        description="""Evaluation criteria based on a specific property.""",
+    )
+
+
+class RubricContentDict(TypedDict, total=False):
+    """Content of the rubric, defining the testable criteria."""
+
+    property: Optional[RubricContentPropertyDict]
+    """Evaluation criteria based on a specific property."""
+
+
+RubricContentOrDict = Union[RubricContent, RubricContentDict]
+
+
+class Rubric(_common.BaseModel):
+    """Message representing a single testable criterion for evaluation.
+
+    One input prompt could have multiple rubrics.
+    """
+
+    rubric_id: Optional[str] = Field(
+        default=None,
+        description="""Required. Unique identifier for the rubric.
+      This ID is used to refer to this rubric, e.g., in RubricVerdict.""",
+    )
+    content: Optional[RubricContent] = Field(
+        default=None,
+        description="""Required. The actual testable criteria for the rubric.""",
+    )
+    type: Optional[str] = Field(
+        default=None,
+        description="""Optional. A type designator for the rubric, which can inform how it's
+      evaluated or interpreted by systems or users.
+      It's recommended to use consistent, well-defined, upper snake_case strings.
+      Examples: "SUMMARIZATION_QUALITY", "SAFETY_HARMFUL_CONTENT",
+      "INSTRUCTION_ADHERENCE".""",
+    )
+    importance: Optional[Importance] = Field(
+        default=None,
+        description="""Optional. The relative importance of this rubric.""",
+    )
+
+
+class RubricDict(TypedDict, total=False):
+    """Message representing a single testable criterion for evaluation.
+
+    One input prompt could have multiple rubrics.
+    """
+
+    rubric_id: Optional[str]
+    """Required. Unique identifier for the rubric.
+      This ID is used to refer to this rubric, e.g., in RubricVerdict."""
+
+    content: Optional[RubricContentDict]
+    """Required. The actual testable criteria for the rubric."""
+
+    type: Optional[str]
+    """Optional. A type designator for the rubric, which can inform how it's
+      evaluated or interpreted by systems or users.
+      It's recommended to use consistent, well-defined, upper snake_case strings.
+      Examples: "SUMMARIZATION_QUALITY", "SAFETY_HARMFUL_CONTENT",
+      "INSTRUCTION_ADHERENCE"."""
+
+    importance: Optional[Importance]
+    """Optional. The relative importance of this rubric."""
+
+
+RubricOrDict = Union[Rubric, RubricDict]
+
+
+class RubricVerdict(_common.BaseModel):
+    """Represents the verdict of an evaluation against a single rubric."""
+
+    evaluated_rubric: Optional[Rubric] = Field(
+        default=None,
+        description="""Required. The full rubric definition that was evaluated.
+      Storing this ensures the verdict is self-contained and understandable,
+      especially if the original rubric definition changes or was dynamically
+      generated.""",
+    )
+    verdict: Optional[bool] = Field(
+        default=None,
+        description="""Required. Outcome of the evaluation against the rubric, represented as a
+      boolean. `true` indicates a "Pass", `false` indicates a "Fail".""",
+    )
+    reasoning: Optional[str] = Field(
+        default=None,
+        description="""Optional. Human-readable reasoning or explanation for the verdict.
+      This can include specific examples or details from the evaluated content
+      that justify the given verdict.""",
+    )
+
+
+class RubricVerdictDict(TypedDict, total=False):
+    """Represents the verdict of an evaluation against a single rubric."""
+
+    evaluated_rubric: Optional[RubricDict]
+    """Required. The full rubric definition that was evaluated.
+      Storing this ensures the verdict is self-contained and understandable,
+      especially if the original rubric definition changes or was dynamically
+      generated."""
+
+    verdict: Optional[bool]
+    """Required. Outcome of the evaluation against the rubric, represented as a
+      boolean. `true` indicates a "Pass", `false` indicates a "Fail"."""
+
+    reasoning: Optional[str]
+    """Optional. Human-readable reasoning or explanation for the verdict.
+      This can include specific examples or details from the evaluated content
+      that justify the given verdict."""
+
+
+RubricVerdictOrDict = Union[RubricVerdict, RubricVerdictDict]
+
+
+class CandidateResult(_common.BaseModel):
+    """Result for a single candidate."""
+
+    candidate: Optional[str] = Field(
+        default=None,
+        description="""The candidate that is being evaluated. The value is the same as the candidate name in the EvaluationRequest.""",
+    )
+    metric: Optional[str] = Field(
+        default=None, description="""The metric that was evaluated."""
+    )
+    score: Optional[float] = Field(
+        default=None, description="""The score of the metric."""
+    )
+    explanation: Optional[str] = Field(
+        default=None, description="""The explanation for the metric."""
+    )
+    rubric_verdicts: Optional[list[RubricVerdict]] = Field(
+        default=None, description="""The rubric verdicts for the metric."""
+    )
+    additional_results: Optional[dict[str, Any]] = Field(
+        default=None, description="""Additional results for the metric."""
+    )
+
+
+class CandidateResultDict(TypedDict, total=False):
+    """Result for a single candidate."""
+
+    candidate: Optional[str]
+    """The candidate that is being evaluated. The value is the same as the candidate name in the EvaluationRequest."""
+
+    metric: Optional[str]
+    """The metric that was evaluated."""
+
+    score: Optional[float]
+    """The score of the metric."""
+
+    explanation: Optional[str]
+    """The explanation for the metric."""
+
+    rubric_verdicts: Optional[list[RubricVerdictDict]]
+    """The rubric verdicts for the metric."""
+
+    additional_results: Optional[dict[str, Any]]
+    """Additional results for the metric."""
+
+
+CandidateResultOrDict = Union[CandidateResult, CandidateResultDict]