google-adk 0.0.1__py3-none-any.whl → 0.0.3__py3-none-any.whl

google/adk/tests/integration/test_system_instruction.py

@@ -0,0 +1,177 @@
+# 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.
+
+import pytest
+
+# Skip until fixed.
+pytest.skip(allow_module_level=True)
+
+from google.adk.agents import InvocationContext
+from google.adk.sessions import Session
+from google.genai import types
+
+from .fixture import context_variable_agent
+from .utils import TestRunner
+
+nl_planner_si = """
+You are an intelligent tool use agent built upon the Gemini large language model. When answering the question, try to leverage the available tools to gather the information instead of your memorized knowledge.
+
+Follow this process when answering the question: (1) first come up with a plan in natural language text format; (2) Then use tools to execute the plan and provide reasoning between tool code snippets to make a summary of current state and next step. Tool code snippets and reasoning should be interleaved with each other. (3) In the end, return one final answer.
+
+Follow this format when answering the question: (1) The planning part should be under /*PLANNING*/. (2) The tool code snippets should be under /*ACTION*/, and the reasoning parts should be under /*REASONING*/. (3) The final answer part should be under /*FINAL_ANSWER*/.
+
+
+Below are the requirements for the planning:
+The plan is made to answer the user query if following the plan. The plan is coherent and covers all aspects of information from user query, and only involves the tools that are accessible by the agent. The plan contains the decomposed steps as a numbered list where each step should use one or multiple available tools. By reading the plan, you can intuitively know which tools to trigger or what actions to take.
+If the initial plan cannot be successfully executed, you should learn from previous execution results and revise your plan. The revised plan should be be under /*REPLANNING*/. Then use tools to follow the new plan.
+
+Below are the requirements for the reasoning:
+The reasoning makes a summary of the current trajectory based on the user query and tool outputs. Based on the tool outputs and plan, the reasoning also comes up with instructions to the next steps, making the trajectory closer to the final answer.
+
+
+
+Below are the requirements for the final answer:
+The final answer should be precise and follow query formatting requirements. Some queries may not be answerable with the available tools and information. In those cases, inform the user why you cannot process their query and ask for more information.
+
+
+
+Below are the requirements for the tool code:
+
+**Custom Tools:** The available tools are described in the context and can be directly used.
+- Code must be valid self-contained Python snippets with no imports and no references to tools or Python libraries that are not in the context.
+- You cannot use any parameters or fields that are not explicitly defined in the APIs in the context.
+- Use "print" to output execution results for the next step or final answer that you need for responding to the user. Never generate ```tool_outputs yourself.
+- The code snippets should be readable, efficient, and directly relevant to the user query and reasoning steps.
+- When using the tools, you should use the library name together with the function name, e.g., vertex_search.search().
+- If Python libraries are not provided in the context, NEVER write your own code other than the function calls using the provided tools.
+
+
+
+VERY IMPORTANT instruction that you MUST follow in addition to the above instructions:
+
+You should ask for clarification if you need more information to answer the question.
+You should prefer using the information available in the context instead of repeated tool use.
+
+You should ONLY generate code snippets prefixed with "```tool_code" if you need to use the tools to answer the question.
+
+If you are asked to write code by user specifically,
+- you should ALWAYS use "```python" to format the code.
+- you should NEVER put "tool_code" to format the code.
+- Good example:
+```python
+print('hello')
+```
+- Bad example:
+```tool_code
+print('hello')
+```
+"""
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{"agent": context_variable_agent.agent.state_variable_echo_agent}],
+    indirect=True,
+)
+def test_context_variable(agent_runner: TestRunner):
+  session = Session(
+      context={
+          "customerId": "1234567890",
+          "customerInt": 30,
+          "customerFloat": 12.34,
+          "customerJson": {"name": "John Doe", "age": 30, "count": 11.1},
+      }
+  )
+  si = UnitFlow()._build_system_instruction(
+      InvocationContext(
+          invocation_id="1234567890", agent=agent_runner.agent, session=session
+      )
+  )
+
+  assert (
+      "Use the echo_info tool to echo 1234567890, 30, 12.34, and {'name': 'John"
+      " Doe', 'age': 30, 'count': 11.1}. Ask for it if you need to."
+      in si
+  )
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{
+        "agent": (
+            context_variable_agent.agent.state_variable_with_complicated_format_agent
+        )
+    }],
+    indirect=True,
+)
+def test_context_variable_with_complicated_format(agent_runner: TestRunner):
+  session = Session(
+      context={"customerId": "1234567890", "customer_int": 30},
+      artifacts={"fileName": [types.Part(text="test artifact")]},
+  )
+  si = _context_formatter.populate_context_and_artifact_variable_values(
+      agent_runner.agent.instruction,
+      session.get_state(),
+      session.get_artifact_dict(),
+  )
+
+  assert (
+      si
+      == "Use the echo_info tool to echo 1234567890, 30, { "
+      " non-identifier-float}}, test artifact, {'key1': 'value1'} and"
+      " {{'key2': 'value2'}}. Ask for it if you need to."
+  )
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{
+        "agent": (
+            context_variable_agent.agent.state_variable_with_nl_planner_agent
+        )
+    }],
+    indirect=True,
+)
+def test_nl_planner(agent_runner: TestRunner):
+  session = Session(context={"customerId": "1234567890"})
+  si = UnitFlow()._build_system_instruction(
+      InvocationContext(
+          invocation_id="1234567890",
+          agent=agent_runner.agent,
+          session=session,
+      )
+  )
+
+  for line in nl_planner_si.splitlines():
+    assert line in si
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{
+        "agent": (
+            context_variable_agent.agent.state_variable_with_function_instruction_agent
+        )
+    }],
+    indirect=True,
+)
+def test_function_instruction(agent_runner: TestRunner):
+  session = Session(context={"customerId": "1234567890"})
+  si = UnitFlow()._build_system_instruction(
+      InvocationContext(
+          invocation_id="1234567890", agent=agent_runner.agent, session=session
+      )
+  )
+
+  assert "This is the plain text sub agent instruction." in si

google/adk/tests/integration/test_tools.py

@@ -0,0 +1,287 @@
+# 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.
+
+import json
+
+import pytest
+
+# Skip until fixed.
+pytest.skip(allow_module_level=True)
+
+from .fixture import tool_agent
+from .utils import TestRunner
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{"agent": tool_agent.agent.single_function_agent}],
+    indirect=True,
+)
+def test_single_function_calls_success(agent_runner: TestRunner):
+  _call_function_and_assert(
+      agent_runner,
+      "simple_function",
+      "test",
+      "success",
+  )
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{"agent": tool_agent.agent.root_agent}],
+    indirect=True,
+)
+def test_multiple_function_calls_success(agent_runner: TestRunner):
+  _call_function_and_assert(
+      agent_runner,
+      "simple_function",
+      "test",
+      "success",
+  )
+  _call_function_and_assert(
+      agent_runner,
+      "no_param_function",
+      None,
+      "Called no param function successfully",
+  )
+  _call_function_and_assert(
+      agent_runner,
+      "no_output_function",
+      "test",
+      "",
+  )
+  _call_function_and_assert(
+      agent_runner,
+      "multiple_param_types_function",
+      ["test", 1, 2.34, True],
+      "success",
+  )
+  _call_function_and_assert(
+      agent_runner,
+      "return_list_str_function",
+      "test",
+      "success",
+  )
+  _call_function_and_assert(
+      agent_runner,
+      "list_str_param_function",
+      ["test", "test2", "test3", "test4"],
+      "success",
+  )
+
+
+@pytest.mark.skip(reason="Currently failing with 400 on MLDev.")
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{"agent": tool_agent.agent.root_agent}],
+    indirect=True,
+)
+def test_complex_function_calls_success(agent_runner: TestRunner):
+  param1 = {"name": "Test", "count": 3}
+  param2 = [
+      {"name": "Function", "count": 2},
+      {"name": "Retrieval", "count": 1},
+  ]
+  _call_function_and_assert(
+      agent_runner,
+      "complex_function_list_dict",
+      [param1, param2],
+      "test",
+  )
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{"agent": tool_agent.agent.root_agent}],
+    indirect=True,
+)
+def test_repetive_call_success(agent_runner: TestRunner):
+  _call_function_and_assert(
+      agent_runner,
+      "repetive_call_1",
+      "test",
+      "test_repetive",
+  )
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{"agent": tool_agent.agent.root_agent}],
+    indirect=True,
+)
+def test_function_calls_fail(agent_runner: TestRunner):
+  _call_function_and_assert(
+      agent_runner,
+      "throw_error_function",
+      "test",
+      None,
+      ValueError,
+  )
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{"agent": tool_agent.agent.root_agent}],
+    indirect=True,
+)
+def test_agent_tools_success(agent_runner: TestRunner):
+  _call_function_and_assert(
+      agent_runner,
+      "no_schema_agent",
+      "Hi",
+      "Hi",
+  )
+  _call_function_and_assert(
+      agent_runner,
+      "schema_agent",
+      "Agent_tools",
+      "Agent_tools_success",
+  )
+  _call_function_and_assert(
+      agent_runner, "no_input_schema_agent", "Tools", "Tools_success"
+  )
+  _call_function_and_assert(agent_runner, "no_output_schema_agent", "Hi", "Hi")
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{"agent": tool_agent.agent.root_agent}],
+    indirect=True,
+)
+def test_files_retrieval_success(agent_runner: TestRunner):
+  _call_function_and_assert(
+      agent_runner,
+      "test_case_retrieval",
+      "What is the testing strategy of agent 2.0?",
+      "test",
+  )
+  # For non relevant query, the agent should still be running fine, just return
+  # response might be different for different calls, so we don't compare the
+  # response here.
+  _call_function_and_assert(
+      agent_runner,
+      "test_case_retrieval",
+      "What is the whether in bay area?",
+      "",
+  )
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{"agent": tool_agent.agent.root_agent}],
+    indirect=True,
+)
+def test_rag_retrieval_success(agent_runner: TestRunner):
+  _call_function_and_assert(
+      agent_runner,
+      "valid_rag_retrieval",
+      "What is the testing strategy of agent 2.0?",
+      "test",
+  )
+  _call_function_and_assert(
+      agent_runner,
+      "valid_rag_retrieval",
+      "What is the whether in bay area?",
+      "No",
+  )
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{"agent": tool_agent.agent.root_agent}],
+    indirect=True,
+)
+def test_rag_retrieval_fail(agent_runner: TestRunner):
+  _call_function_and_assert(
+      agent_runner,
+      "invalid_rag_retrieval",
+      "What is the testing strategy of agent 2.0?",
+      None,
+      ValueError,
+  )
+  _call_function_and_assert(
+      agent_runner,
+      "non_exist_rag_retrieval",
+      "What is the whether in bay area?",
+      None,
+      ValueError,
+  )
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{"agent": tool_agent.agent.root_agent}],
+    indirect=True,
+)
+def test_langchain_tool_success(agent_runner: TestRunner):
+  _call_function_and_assert(
+      agent_runner,
+      "terminal",
+      "Run the following shell command 'echo test!'",
+      "test",
+  )
+
+
+@pytest.mark.parametrize(
+    "agent_runner",
+    [{"agent": tool_agent.agent.root_agent}],
+    indirect=True,
+)
+def test_crewai_tool_success(agent_runner: TestRunner):
+  _call_function_and_assert(
+      agent_runner,
+      "direcotry_read_tool",
+      "Find all the file paths",
+      "file",
+  )
+
+
+def _call_function_and_assert(
+    agent_runner: TestRunner,
+    function_name: str,
+    params,
+    expected=None,
+    exception: Exception = None,
+):
+  param_section = (
+      " with params"
+      f" {params if isinstance(params, str) else json.dumps(params)}"
+      if params is not None
+      else ""
+  )
+  query = f"Call {function_name}{param_section} and show me the result"
+  if exception:
+    _assert_raises(agent_runner, query, exception)
+    return
+
+  _assert_function_output(agent_runner, query, expected)
+
+
+def _assert_raises(agent_runner: TestRunner, query: str, exception: Exception):
+  with pytest.raises(exception):
+    agent_runner.run(query)
+
+
+def _assert_function_output(agent_runner: TestRunner, query: str, expected):
+  agent_runner.run(query)
+
+  # Retrieve the latest model response event
+  model_response_event = agent_runner.get_events()[-1]
+
+  # Assert the response content
+  assert model_response_event.content.role == "model"
+  assert (
+      expected.lower()
+      in model_response_event.content.parts[0].text.strip().lower()
+  )

google/adk/tests/integration/test_with_test_file.py

@@ -0,0 +1,34 @@
+# 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.
+
+from google.adk.evaluation import AgentEvaluator
+
+
+def test_with_single_test_file():
+  """Test the agent's basic ability via session file."""
+  AgentEvaluator.evaluate(
+      agent_module="tests.integration.fixture.home_automation_agent",
+      eval_dataset_file_path_or_dir="tests/integration/fixture/home_automation_agent/simple_test.test.json",
+  )
+
+
+def test_with_folder_of_test_files_long_running():
+  """Test the agent's basic ability via a folder of session files."""
+  AgentEvaluator.evaluate(
+      agent_module="tests.integration.fixture.home_automation_agent",
+      eval_dataset_file_path_or_dir=(
+          "tests/integration/fixture/home_automation_agent/test_files"
+      ),
+      num_runs=4,
+  )

google/adk/tests/integration/tools/__init__.py

@@ -0,0 +1,14 @@
+# 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.
+

google/adk/tests/integration/utils/__init__.py

@@ -0,0 +1,16 @@
+# 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.
+
+from .asserts import *
+from .test_runner import TestRunner

google/adk/tests/integration/utils/asserts.py

@@ -0,0 +1,75 @@
+# 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.
+
+from typing import TypedDict
+
+from .test_runner import TestRunner
+
+
+class Message(TypedDict):
+  agent_name: str
+  expected_text: str
+
+
+def assert_current_agent_is(agent_name: str, *, agent_runner: TestRunner):
+  assert agent_runner.get_current_agent_name() == agent_name
+
+
+def assert_agent_says(
+    expected_text: str, *, agent_name: str, agent_runner: TestRunner
+):
+  for event in reversed(agent_runner.get_events()):
+    if event.author == agent_name and event.content.parts[0].text:
+      assert event.content.parts[0].text.strip() == expected_text
+      return
+
+
+def assert_agent_says_in_order(
+    expected_conversaction: list[Message], agent_runner: TestRunner
+):
+  expected_conversaction_idx = len(expected_conversaction) - 1
+  for event in reversed(agent_runner.get_events()):
+    if event.content.parts and event.content.parts[0].text:
+      assert (
+          event.author
+          == expected_conversaction[expected_conversaction_idx]['agent_name']
+      )
+      assert (
+          event.content.parts[0].text.strip()
+          == expected_conversaction[expected_conversaction_idx]['expected_text']
+      )
+      expected_conversaction_idx -= 1
+      if expected_conversaction_idx < 0:
+        return
+
+
+def assert_agent_transfer_path(
+    expected_path: list[str], *, agent_runner: TestRunner
+):
+  events = agent_runner.get_events()
+  idx_in_expected_path = len(expected_path) - 1
+  # iterate events in reverse order
+  for event in reversed(events):
+    function_calls = event.get_function_calls()
+    if (
+        len(function_calls) == 1
+        and function_calls[0].name == 'transfer_to_agent'
+    ):
+      assert (
+          function_calls[0].args['agent_name']
+          == expected_path[idx_in_expected_path]
+      )
+      idx_in_expected_path -= 1
+      if idx_in_expected_path < 0:
+        return

google/adk/tests/integration/utils/test_runner.py

@@ -0,0 +1,97 @@
+# 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.
+
+import importlib
+from typing import Optional
+
+from google.adk import Agent
+from google.adk import Runner
+from google.adk.artifacts import BaseArtifactService
+from google.adk.artifacts import InMemoryArtifactService
+from google.adk.events import Event
+from google.adk.sessions import BaseSessionService
+from google.adk.sessions import InMemorySessionService
+from google.adk.sessions import Session
+from google.genai import types
+
+
+class TestRunner:
+  """Agents runner for testings."""
+
+  app_name = "test_app"
+  user_id = "test_user"
+
+  def __init__(
+      self,
+      agent: Agent,
+      artifact_service: BaseArtifactService = InMemoryArtifactService(),
+      session_service: BaseSessionService = InMemorySessionService(),
+  ) -> None:
+    self.agent = agent
+    self.agent_client = Runner(
+        app_name=self.app_name,
+        agent=agent,
+        artifact_service=artifact_service,
+        session_service=session_service,
+    )
+    self.session_service = session_service
+    self.current_session_id = session_service.create_session(
+        app_name=self.app_name, user_id=self.user_id
+    ).id
+
+  def new_session(self, session_id: Optional[str] = None) -> None:
+    self.current_session_id = self.session_service.create_session(
+        app_name=self.app_name, user_id=self.user_id, session_id=session_id
+    ).id
+
+  def run(self, prompt: str) -> list[Event]:
+    current_session = self.session_service.get_session(
+        app_name=self.app_name,
+        user_id=self.user_id,
+        session_id=self.current_session_id,
+    )
+    assert current_session is not None
+
+    return list(
+        self.agent_client.run(
+            user_id=current_session.user_id,
+            session_id=current_session.id,
+            new_message=types.Content(
+                role="user",
+                parts=[types.Part.from_text(text=prompt)],
+            ),
+        )
+    )
+
+  def get_current_session(self) -> Optional[Session]:
+    return self.session_service.get_session(
+        app_name=self.app_name,
+        user_id=self.user_id,
+        session_id=self.current_session_id,
+    )
+
+  def get_events(self) -> list[Event]:
+    return self.get_current_session().events
+
+  @classmethod
+  def from_agent_name(cls, agent_name: str):
+    agent_module_path = f"tests.integration.fixture.{agent_name}"
+    agent_module = importlib.import_module(agent_module_path)
+    agent: Agent = agent_module.agent.root_agent
+    return cls(agent)
+
+  def get_current_agent_name(self) -> str:
+    return self.agent_client._find_agent_to_run(
+        self.get_current_session(), self.agent
+    ).name