google--adk-python/tests/unittests/tools/test_set_model_response_tool.py

# 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.

"""Tests for SetModelResponseTool."""

import inspect
from typing import Optional

from google.adk.agents.invocation_context import InvocationContext
from google.adk.agents.llm_agent import LlmAgent
from google.adk.agents.run_config import RunConfig
from google.adk.features._feature_registry import FeatureName
from google.adk.features._feature_registry import temporary_feature_override
from google.adk.sessions.in_memory_session_service import InMemorySessionService
from google.adk.tools.set_model_response_tool import SetModelResponseTool
from google.adk.tools.tool_context import ToolContext
from google.genai import types
from pydantic import BaseModel
from pydantic import Field
from pydantic import ValidationError
import pytest


class PersonSchema(BaseModel):
  """Test schema for structured output."""

  name: str = Field(description="A person's name")
  age: int = Field(description="A person's age")
  city: str = Field(description='The city they live in')


class ComplexSchema(BaseModel):
  """More complex test schema."""

  id: int
  title: str
  tags: list[str] = Field(default_factory=list)
  metadata: dict[str, str] = Field(default_factory=dict)
  is_active: bool = True


async def _create_invocation_context(agent: LlmAgent) -> InvocationContext:
  """Helper to create InvocationContext for testing."""
  session_service = InMemorySessionService()
  session = await session_service.create_session(
      app_name='test_app', user_id='test_user'
  )
  return InvocationContext(
      invocation_id='test-id',
      agent=agent,
      session=session,
      session_service=session_service,
      run_config=RunConfig(),
  )


def test_tool_initialization_simple_schema():
  """Test tool initialization with a simple schema."""
  tool = SetModelResponseTool(PersonSchema)

  assert tool.output_schema == PersonSchema
  assert tool.name == 'set_model_response'
  assert 'Set your final response' in tool.description
  assert tool.func is not None


def test_tool_initialization_complex_schema():
  """Test tool initialization with a complex schema."""
  tool = SetModelResponseTool(ComplexSchema)

  assert tool.output_schema == ComplexSchema
  assert tool.name == 'set_model_response'
  assert tool.func is not None


def test_function_signature_generation():
  """Test that function signature is correctly generated from schema."""
  tool = SetModelResponseTool(PersonSchema)

  sig = inspect.signature(tool.func)

  # Check that parameters match schema fields
  assert 'name' in sig.parameters
  assert 'age' in sig.parameters
  assert 'city' in sig.parameters

  # All parameters should be keyword-only
  for param in sig.parameters.values():
    assert param.kind == inspect.Parameter.KEYWORD_ONLY


def test_get_declaration():
  """Test that tool declaration is properly generated."""
  tool = SetModelResponseTool(PersonSchema)

  declaration = tool._get_declaration()

  assert declaration is not None
  assert declaration.name == 'set_model_response'
  assert declaration.description is not None


@pytest.mark.asyncio
async def test_run_async_valid_data():
  """Test tool execution with valid data."""
  tool = SetModelResponseTool(PersonSchema)

  agent = LlmAgent(name='test_agent', model='gemini-2.5-flash')
  invocation_context = await _create_invocation_context(agent)
  tool_context = ToolContext(invocation_context)

  # Execute with valid data
  result = await tool.run_async(
      args={'name': 'Alice', 'age': 25, 'city': 'Seattle'},
      tool_context=tool_context,
  )

  # Verify the tool now returns dict directly
  assert result is not None
  assert result['name'] == 'Alice'
  assert result['age'] == 25
  assert result['city'] == 'Seattle'


@pytest.mark.asyncio
async def test_run_async_complex_schema():
  """Test tool execution with complex schema."""
  tool = SetModelResponseTool(ComplexSchema)

  agent = LlmAgent(name='test_agent', model='gemini-2.5-flash')
  invocation_context = await _create_invocation_context(agent)
  tool_context = ToolContext(invocation_context)

  # Execute with complex data
  result = await tool.run_async(
      args={
          'id': 123,
          'title': 'Test Item',
          'tags': ['tag1', 'tag2'],
          'metadata': {'key': 'value'},
          'is_active': False,
      },
      tool_context=tool_context,
  )

  # Verify the tool now returns dict directly
  assert result is not None
  assert result['id'] == 123
  assert result['title'] == 'Test Item'
  assert result['tags'] == ['tag1', 'tag2']
  assert result['metadata'] == {'key': 'value'}
  assert result['is_active'] is False


@pytest.mark.asyncio
async def test_run_async_validation_error():
  """Test tool execution with invalid data raises validation error."""
  tool = SetModelResponseTool(PersonSchema)

  agent = LlmAgent(name='test_agent', model='gemini-2.5-flash')
  invocation_context = await _create_invocation_context(agent)
  tool_context = ToolContext(invocation_context)

  # Execute with invalid data (wrong type for age)
  with pytest.raises(ValidationError):
    await tool.run_async(
        args={'name': 'Bob', 'age': 'not_a_number', 'city': 'Portland'},
        tool_context=tool_context,
    )


@pytest.mark.asyncio
async def test_run_async_missing_required_field():
  """Test tool execution with missing required field."""
  tool = SetModelResponseTool(PersonSchema)

  agent = LlmAgent(name='test_agent', model='gemini-2.5-flash')
  invocation_context = await _create_invocation_context(agent)
  tool_context = ToolContext(invocation_context)

  # Execute with missing required field
  with pytest.raises(ValidationError):
    await tool.run_async(
        args={'name': 'Charlie', 'city': 'Denver'},  # Missing age
        tool_context=tool_context,
    )


@pytest.mark.asyncio
async def test_session_state_storage_key():
  """Test that response is no longer stored in session state."""
  tool = SetModelResponseTool(PersonSchema)

  agent = LlmAgent(name='test_agent', model='gemini-2.5-flash')
  invocation_context = await _create_invocation_context(agent)
  tool_context = ToolContext(invocation_context)

  result = await tool.run_async(
      args={'name': 'Diana', 'age': 35, 'city': 'Miami'},
      tool_context=tool_context,
  )

  # Verify response is returned directly
  assert result is not None
  assert result['name'] == 'Diana'
  assert result['age'] == 35
  assert result['city'] == 'Miami'


@pytest.mark.asyncio
async def test_multiple_executions_return_latest():
  """Test that multiple executions return latest response independently."""
  tool = SetModelResponseTool(PersonSchema)

  agent = LlmAgent(name='test_agent', model='gemini-2.5-flash')
  invocation_context = await _create_invocation_context(agent)
  tool_context = ToolContext(invocation_context)

  # First execution
  result1 = await tool.run_async(
      args={'name': 'First', 'age': 20, 'city': 'City1'},
      tool_context=tool_context,
  )

  # Second execution should return its own response
  result2 = await tool.run_async(
      args={'name': 'Second', 'age': 30, 'city': 'City2'},
      tool_context=tool_context,
  )

  # Verify each execution returns its own dict
  assert result1['name'] == 'First'
  assert result1['age'] == 20
  assert result1['city'] == 'City1'

  assert result2['name'] == 'Second'
  assert result2['age'] == 30
  assert result2['city'] == 'City2'


def test_function_return_value_consistency():
  """Test that function return value matches run_async return value."""
  tool = SetModelResponseTool(PersonSchema)

  # Direct function call
  direct_result = tool.func()

  # Both should return the same value
  assert direct_result == 'Response set successfully.'


# Tests for list[BaseModel] schema support


class ItemSchema(BaseModel):
  """Simple item schema for list testing."""

  id: int = Field(description='Item ID')
  name: str = Field(description='Item name')


def test_tool_initialization_list_schema():
  """Test tool initialization with a list schema."""
  tool = SetModelResponseTool(list[ItemSchema])

  assert tool.output_schema == list[ItemSchema]
  assert tool._is_list_of_basemodel
  assert tool.name == 'set_model_response'
  assert 'Set your final response' in tool.description
  assert tool.func is not None


def test_function_signature_generation_list_schema():
  """Test that function signature is correctly generated for list schema."""
  tool = SetModelResponseTool(list[ItemSchema])

  sig = inspect.signature(tool.func)

  # Should have a single 'items' parameter
  assert 'items' in sig.parameters
  assert len(sig.parameters) == 1

  # Parameter should be keyword-only with correct annotation
  assert sig.parameters['items'].kind == inspect.Parameter.KEYWORD_ONLY
  assert sig.parameters['items'].annotation == list[ItemSchema]


def test_get_declaration_list_schema():
  """Test that tool declaration is properly generated for list schema."""
  tool = SetModelResponseTool(list[ItemSchema])

  declaration = tool._get_declaration()

  assert declaration is not None
  assert declaration.name == 'set_model_response'
  assert declaration.description is not None


@pytest.mark.asyncio
async def test_run_async_list_schema_valid_data():
  """Test tool execution with valid list data."""
  tool = SetModelResponseTool(list[ItemSchema])

  agent = LlmAgent(name='test_agent', model='gemini-2.5-flash')
  invocation_context = await _create_invocation_context(agent)
  tool_context = ToolContext(invocation_context)

  # Execute with valid list data
  result = await tool.run_async(
      args={
          'items': [
              {'id': 1, 'name': 'Item 1'},
              {'id': 2, 'name': 'Item 2'},
              {'id': 3, 'name': 'Item 3'},
          ]
      },
      tool_context=tool_context,
  )

  # Verify the tool returns list of dicts
  assert result is not None
  assert isinstance(result, list)
  assert len(result) == 3
  assert result[0]['id'] == 1
  assert result[0]['name'] == 'Item 1'
  assert result[1]['id'] == 2
  assert result[2]['id'] == 3


@pytest.mark.asyncio
async def test_run_async_list_schema_empty_list():
  """Test tool execution with empty list."""
  tool = SetModelResponseTool(list[ItemSchema])

  agent = LlmAgent(name='test_agent', model='gemini-2.5-flash')
  invocation_context = await _create_invocation_context(agent)
  tool_context = ToolContext(invocation_context)

  # Execute with empty list
  result = await tool.run_async(
      args={'items': []},
      tool_context=tool_context,
  )

  # Verify the tool returns empty list
  assert result is not None
  assert isinstance(result, list)
  assert len(result) == 0


@pytest.mark.asyncio
async def test_run_async_list_schema_validation_error():
  """Test tool execution with invalid list data raises validation error."""
  tool = SetModelResponseTool(list[ItemSchema])

  agent = LlmAgent(name='test_agent', model='gemini-2.5-flash')
  invocation_context = await _create_invocation_context(agent)
  tool_context = ToolContext(invocation_context)

  # Execute with invalid data (wrong type for id)
  with pytest.raises(ValidationError):
    await tool.run_async(
        args={
            'items': [
                {'id': 'not_a_number', 'name': 'Item 1'},
            ]
        },
        tool_context=tool_context,
    )


# Tests for other schema types (list[str], dict, etc.)


def test_tool_initialization_list_str_schema():
  """Test tool initialization with list[str] schema."""
  tool = SetModelResponseTool(list[str])

  assert tool.output_schema == list[str]
  assert not tool._is_basemodel
  assert not tool._is_list_of_basemodel
  assert tool.name == 'set_model_response'
  assert tool.func is not None


def test_function_signature_generation_list_str_schema():
  """Test that function signature is correctly generated for list[str] schema."""
  tool = SetModelResponseTool(list[str])

  sig = inspect.signature(tool.func)

  # Should have a single 'response' parameter with list[str] annotation
  assert 'response' in sig.parameters
  assert len(sig.parameters) == 1
  assert sig.parameters['response'].kind == inspect.Parameter.KEYWORD_ONLY
  assert sig.parameters['response'].annotation == list[str]


@pytest.mark.asyncio
async def test_run_async_list_str_schema():
  """Test tool execution with list[str] data."""
  tool = SetModelResponseTool(list[str])

  agent = LlmAgent(name='test_agent', model='gemini-2.5-flash')
  invocation_context = await _create_invocation_context(agent)
  tool_context = ToolContext(invocation_context)

  # Execute with list of strings
  result = await tool.run_async(
      args={'response': ['apple', 'banana', 'cherry']},
      tool_context=tool_context,
  )

  # Verify the tool returns the list directly
  assert result is not None
  assert isinstance(result, list)
  assert result == ['apple', 'banana', 'cherry']


def test_tool_initialization_dict_schema():
  """Test tool initialization with dict schema."""
  tool = SetModelResponseTool(dict[str, int])

  assert tool.output_schema == dict[str, int]
  assert not tool._is_basemodel
  assert not tool._is_list_of_basemodel
  assert tool.name == 'set_model_response'
  assert tool.func is not None


def test_function_signature_generation_dict_schema():
  """Test that function signature is correctly generated for dict schema."""
  tool = SetModelResponseTool(dict[str, int])

  sig = inspect.signature(tool.func)

  # Should have a single 'response' parameter with dict[str, int] annotation
  assert 'response' in sig.parameters
  assert len(sig.parameters) == 1
  assert sig.parameters['response'].kind == inspect.Parameter.KEYWORD_ONLY
  assert sig.parameters['response'].annotation == dict[str, int]


@pytest.mark.asyncio
async def test_run_async_dict_schema():
  """Test tool execution with dict data."""
  tool = SetModelResponseTool(dict[str, int])

  agent = LlmAgent(name='test_agent', model='gemini-2.5-flash')
  invocation_context = await _create_invocation_context(agent)
  tool_context = ToolContext(invocation_context)

  # Execute with dict data
  result = await tool.run_async(
      args={'response': {'a': 1, 'b': 2, 'c': 3}},
      tool_context=tool_context,
  )

  # Verify the tool returns the dict directly
  assert result is not None
  assert isinstance(result, dict)
  assert result == {'a': 1, 'b': 2, 'c': 3}


def test_tool_initialization_raw_dict_schema():
  """Raw dict output_schema must not crash and must be stored as-is."""
  raw_schema = {
      'type': 'object',
      'properties': {'result': {'type': 'string'}},
  }

  tool = SetModelResponseTool(raw_schema)

  assert tool.output_schema == raw_schema
  assert not tool._is_basemodel
  assert not tool._is_list_of_basemodel
  assert tool.name == 'set_model_response'
  assert tool.func is not None


def test_function_signature_generation_raw_dict_schema():
  """Raw dict schemas should produce a single `response: dict` parameter.

  The annotation must be the `dict` type (hashable), not the dict instance,
  so downstream `_is_builtin_primitive_or_compound` does not raise
  `TypeError: unhashable type: 'dict'`.
  """
  raw_schema = {
      'type': 'object',
      'properties': {'result': {'type': 'string'}},
  }

  tool = SetModelResponseTool(raw_schema)

  sig = inspect.signature(tool.func)

  assert 'response' in sig.parameters
  assert len(sig.parameters) == 1
  assert sig.parameters['response'].kind == inspect.Parameter.KEYWORD_ONLY
  # The annotation is the hashable `dict` type, not the dict instance.
  assert sig.parameters['response'].annotation is dict


def test_get_declaration_raw_dict_schema():
  """`_get_declaration` must not raise when given a raw dict schema."""
  raw_schema = {
      'type': 'object',
      'properties': {'result': {'type': 'string'}},
  }

  tool = SetModelResponseTool(raw_schema)

  declaration = tool._get_declaration()

  assert declaration is not None
  assert declaration.name == 'set_model_response'
  assert declaration.description is not None


@pytest.mark.asyncio
async def test_run_async_raw_dict_schema():
  """Tool execution with a raw dict schema returns the response unchanged."""
  raw_schema = {
      'type': 'object',
      'properties': {'result': {'type': 'string'}},
  }
  tool = SetModelResponseTool(raw_schema)

  agent = LlmAgent(name='test_agent', model='gemini-1.5-flash')
  invocation_context = await _create_invocation_context(agent)
  tool_context = ToolContext(invocation_context)

  result = await tool.run_async(
      args={'response': {'result': 'hello'}},
      tool_context=tool_context,
  )

  assert result == {'result': 'hello'}


def test_tool_initialization_schema_instance():
  """types.Schema instance output_schema must be converted to dict and not crash."""
  schema_instance = types.Schema(
      type=types.Type.OBJECT,
      properties={'result': types.Schema(type=types.Type.STRING)},
  )

  tool = SetModelResponseTool(schema_instance)

  # Check that it converted it to a dictionary
  assert isinstance(tool.output_schema, dict)
  assert 'result' in tool.output_schema['properties']

  sig = inspect.signature(tool.func)
  assert 'response' in sig.parameters
  assert sig.parameters['response'].annotation is dict

  # Check that get_declaration works and doesn't crash with TypeError
  declaration = tool._get_declaration()
  assert declaration is not None
  assert declaration.name == 'set_model_response'


class SubSchema(BaseModel):

  field1: str = Field(description='Field 1')
  field2: int = Field(description='Field 2')


class ConsolidatedOptionalSchema(BaseModel):

  nested: Optional[SubSchema] = Field(default=None, description='Nested model')
  nested_list: Optional[list[SubSchema]] = Field(
      default=None, description='Nested list of models'
  )
  pep604_nested: SubSchema | None = Field(
      default=None, description='PEP 604 optional nested model'
  )
  pep604_raw_list: list | None = Field(default=None, description='Raw list')


def test_get_declaration_optional_fields():
  """Test that tool declaration preserves properties for various optional fields."""
  with temporary_feature_override(FeatureName.JSON_SCHEMA_FOR_FUNC_DECL, False):
    tool = SetModelResponseTool(ConsolidatedOptionalSchema)

    declaration = tool._get_declaration()

  assert declaration is not None
  assert declaration.name == 'set_model_response'
  params_schema = declaration.parameters
  assert params_schema is not None
  assert params_schema.type == 'OBJECT'

  # 1. Optional[SubSchema]
  assert 'nested' in params_schema.properties
  nested_schema = params_schema.properties['nested']
  assert nested_schema.type == 'OBJECT'
  assert nested_schema.properties is not None
  assert nested_schema.properties['field1'].type == 'STRING'
  assert nested_schema.properties['field2'].type == 'INTEGER'

  # 2. Optional[list[SubSchema]]
  assert 'nested_list' in params_schema.properties
  nested_list_schema = params_schema.properties['nested_list']
  assert nested_list_schema.type == 'ARRAY'
  assert nested_list_schema.items is not None
  items_schema = nested_list_schema.items
  assert items_schema.type == 'OBJECT'
  assert items_schema.properties is not None
  assert items_schema.properties['field1'].type == 'STRING'
  assert items_schema.properties['field2'].type == 'INTEGER'

  # 3. SubSchema | None (PEP 604)
  assert 'pep604_nested' in params_schema.properties
  pep604_nested_schema = params_schema.properties['pep604_nested']
  assert pep604_nested_schema.type == 'OBJECT'
  assert pep604_nested_schema.properties is not None
  assert pep604_nested_schema.properties['field1'].type == 'STRING'
  assert pep604_nested_schema.properties['field2'].type == 'INTEGER'

  # 4. list | None (PEP 604)
  assert 'pep604_raw_list' in params_schema.properties
  pep604_raw_list_schema = params_schema.properties['pep604_raw_list']
  assert pep604_raw_list_schema.type == 'ARRAY'