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

google/adk/telemetry.py

@@ -0,0 +1,189 @@
+# 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.
+
+# NOTE:
+#
+#    We expect that the underlying GenAI SDK will provide a certain
+#    level of tracing and logging telemetry aligned with Open Telemetry
+#    Semantic Conventions (such as logging prompts, respones, request
+#    properties, etc.) and so the information that is recorded by the
+#    Agent Development Kit should be focused on the higher-level
+#    constructs of the framework that are not observable by the SDK.
+
+import json
+from typing import Any
+
+from google.genai import types
+from opentelemetry import trace
+
+from .agents.invocation_context import InvocationContext
+from .events.event import Event
+from .models.llm_request import LlmRequest
+from .models.llm_response import LlmResponse
+
+
+tracer = trace.get_tracer('gcp.vertex.agent')
+
+
+def trace_tool_call(
+    args: dict[str, Any],
+):
+  """Traces tool call.
+
+  Args:
+    args: The arguments to the tool call.
+  """
+  span = trace.get_current_span()
+  span.set_attribute('gen_ai.system', 'gcp.vertex.agent')
+  span.set_attribute('gcp.vertex.agent.tool_call_args', json.dumps(args))
+
+
+def trace_tool_response(
+    invocation_context: InvocationContext,
+    event_id: str,
+    function_response_event: Event,
+):
+  """Traces tool response event.
+
+  This function records details about the tool response event as attributes on
+  the current OpenTelemetry span.
+
+  Args:
+    invocation_context: The invocation context for the current agent run.
+    event_id: The ID of the event.
+    function_response_event: The function response event which can be either
+      merged function response for parallel function calls or individual
+      function response for sequential function calls.
+  """
+  span = trace.get_current_span()
+  span.set_attribute('gen_ai.system', 'gcp.vertex.agent')
+  span.set_attribute(
+      'gcp.vertex.agent.invocation_id', invocation_context.invocation_id
+  )
+  span.set_attribute('gcp.vertex.agent.event_id', event_id)
+  span.set_attribute(
+      'gcp.vertex.agent.tool_response',
+      function_response_event.model_dump_json(exclude_none=True),
+  )
+
+  # Setting empty llm request and response (as UI expect these) while not
+  # applicable for tool_response.
+  span.set_attribute('gcp.vertex.agent.llm_request', '{}')
+  span.set_attribute(
+      'gcp.vertex.agent.llm_response',
+      '{}',
+  )
+
+
+def trace_call_llm(
+    invocation_context: InvocationContext,
+    event_id: str,
+    llm_request: LlmRequest,
+    llm_response: LlmResponse,
+):
+  """Traces a call to the LLM.
+
+  This function records details about the LLM request and response as
+  attributes on the current OpenTelemetry span.
+
+  Args:
+    invocation_context: The invocation context for the current agent run.
+    event_id: The ID of the event.
+    llm_request: The LLM request object.
+    llm_response: The LLM response object.
+  """
+  span = trace.get_current_span()
+  # Special standard Open Telemetry GenaI attributes that indicate
+  # that this is a span related to a Generative AI system.
+  span.set_attribute('gen_ai.system', 'gcp.vertex.agent')
+  span.set_attribute('gen_ai.request.model', llm_request.model)
+  span.set_attribute(
+      'gcp.vertex.agent.invocation_id', invocation_context.invocation_id
+  )
+  span.set_attribute('gcp.vertex.agent.event_id', event_id)
+  # Consider removing once GenAI SDK provides a way to record this info.
+  span.set_attribute(
+      'gcp.vertex.agent.llm_request',
+      json.dumps(_build_llm_request_for_trace(llm_request)),
+  )
+  # Consider removing once GenAI SDK provides a way to record this info.
+  span.set_attribute(
+      'gcp.vertex.agent.llm_response',
+      llm_response.model_dump_json(exclude_none=True),
+  )
+
+
+def trace_send_data(
+    invocation_context: InvocationContext,
+    event_id: str,
+    data: list[types.Content],
+):
+  """Traces the sending of data to the agent.
+
+  This function records details about the data sent to the agent as
+  attributes on the current OpenTelemetry span.
+
+  Args:
+    invocation_context: The invocation context for the current agent run.
+    event_id: The ID of the event.
+    data: A list of content objects.
+  """
+  span = trace.get_current_span()
+  span.set_attribute(
+      'gcp.vertex.agent.invocation_id', invocation_context.invocation_id
+  )
+  span.set_attribute('gcp.vertex.agent.event_id', event_id)
+  # Once instrumentation is added to the GenAI SDK, consider whether this
+  # information still needs to be recorded by the Agent Development Kit.
+  span.set_attribute(
+      'gcp.vertex.agent.data',
+      json.dumps([
+          types.Content(role=content.role, parts=content.parts).model_dump(
+              exclude_none=True
+          )
+          for content in data
+      ]),
+  )
+
+
+def _build_llm_request_for_trace(llm_request: LlmRequest) -> dict[str, Any]:
+  """Builds a dictionary representation of the LLM request for tracing.
+
+  This function prepares a dictionary representation of the LlmRequest
+  object, suitable for inclusion in a trace. It excludes fields that cannot
+  be serialized (e.g., function pointers) and avoids sending bytes data.
+
+  Args:
+    llm_request: The LlmRequest object.
+
+  Returns:
+    A dictionary representation of the LLM request.
+  """
+  # Some fields in LlmRequest are function pointers and can not be serialized.
+  result = {
+      'model': llm_request.model,
+      'config': llm_request.config.model_dump(
+          exclude_none=True, exclude='response_schema'
+      ),
+      'contents': [],
+  }
+  # We do not want to send bytes data to the trace.
+  for content in llm_request.contents:
+    parts = [part for part in content.parts if not part.inline_data]
+    result['contents'].append(
+        types.Content(role=content.role, parts=parts).model_dump(
+            exclude_none=True
+        )
+    )
+  return result

google/adk/tests/__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/.env.example

@@ -0,0 +1,10 @@
+# Copy as .env file and fill your values below to run integration tests.
+
+# Choose Backend: GOOGLE_AI_ONLY | VERTEX_ONLY | BOTH (default)
+TEST_BACKEND=BOTH
+
+# ML Dev backend config
+GOOGLE_API_KEY=YOUR_VALUE_HERE
+# Vertex backend config
+GOOGLE_CLOUD_PROJECT=YOUR_VALUE_HERE
+GOOGLE_CLOUD_LOCATION=YOUR_VALUE_HERE

google/adk/tests/integration/__init__.py

@@ -0,0 +1,18 @@
+# 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
+
+# This allows pytest to show the values of the asserts.
+pytest.register_assert_rewrite('tests.integration.utils')

google/adk/tests/integration/conftest.py

@@ -0,0 +1,119 @@
+# 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 logging
+import os
+from typing import Literal
+import warnings
+
+from dotenv import load_dotenv
+from google.adk import Agent
+from pytest import fixture
+from pytest import FixtureRequest
+from pytest import hookimpl
+from pytest import Metafunc
+
+from .utils import TestRunner
+
+logger = logging.getLogger(__name__)
+
+
+def load_env_for_tests():
+  dotenv_path = os.path.join(os.path.dirname(__file__), '.env')
+  if not os.path.exists(dotenv_path):
+    warnings.warn(
+        f'Missing .env file at {dotenv_path}. See dotenv.sample for an example.'
+    )
+  else:
+    load_dotenv(dotenv_path, override=True, verbose=True)
+  if 'GOOGLE_API_KEY' not in os.environ:
+    warnings.warn(
+        'Missing GOOGLE_API_KEY in the environment variables. GOOGLE_AI backend'
+        ' integration tests will fail.'
+    )
+  for env_var in [
+      'GOOGLE_CLOUD_PROJECT',
+      'GOOGLE_CLOUD_LOCATION',
+  ]:
+    if env_var not in os.environ:
+      warnings.warn(
+          f'Missing {env_var} in the environment variables. Vertex backend'
+          ' integration tests will fail.'
+      )
+
+
+load_env_for_tests()
+
+BackendType = Literal['GOOGLE_AI', 'VERTEX']
+
+
+@fixture
+def agent_runner(request: FixtureRequest) -> TestRunner:
+  assert isinstance(request.param, dict)
+
+  if 'agent' in request.param:
+    assert isinstance(request.param['agent'], Agent)
+    return TestRunner(request.param['agent'])
+  elif 'agent_name' in request.param:
+    assert isinstance(request.param['agent_name'], str)
+    return TestRunner.from_agent_name(request.param['agent_name'])
+
+  raise NotImplementedError('Must provide agent or agent_name.')
+
+
+@fixture(autouse=True)
+def llm_backend(request: FixtureRequest):
+  # Set backend environment value.
+  original_val = os.environ.get('GOOGLE_GENAI_USE_VERTEXAI')
+  backend_type = request.param
+  if backend_type == 'GOOGLE_AI':
+    os.environ['GOOGLE_GENAI_USE_VERTEXAI'] = '0'
+  else:
+    os.environ['GOOGLE_GENAI_USE_VERTEXAI'] = '1'
+
+  yield  # Run the test
+
+  # Restore the environment
+  if original_val is None:
+    os.environ.pop('GOOGLE_GENAI_USE_VERTEXAI', None)
+  else:
+    os.environ['GOOGLE_GENAI_USE_VERTEXAI'] = original_val
+
+
+@hookimpl(tryfirst=True)
+def pytest_generate_tests(metafunc: Metafunc):
+  if llm_backend.__name__ in metafunc.fixturenames:
+    if not _is_explicitly_marked(llm_backend.__name__, metafunc):
+      test_backend = os.environ.get('TEST_BACKEND', 'BOTH')
+      if test_backend == 'GOOGLE_AI_ONLY':
+        metafunc.parametrize(llm_backend.__name__, ['GOOGLE_AI'], indirect=True)
+      elif test_backend == 'VERTEX_ONLY':
+        metafunc.parametrize(llm_backend.__name__, ['VERTEX'], indirect=True)
+      elif test_backend == 'BOTH':
+        metafunc.parametrize(
+            llm_backend.__name__, ['GOOGLE_AI', 'VERTEX'], indirect=True
+        )
+      else:
+        raise ValueError(
+            f'Invalid TEST_BACKEND value: {test_backend}, should be one of'
+            ' [GOOGLE_AI_ONLY, VERTEX_ONLY, BOTH]'
+        )
+
+
+def _is_explicitly_marked(mark_name: str, metafunc: Metafunc) -> bool:
+  if hasattr(metafunc.function, 'pytestmark'):
+    for mark in metafunc.function.pytestmark:
+      if mark.name == 'parametrize' and mark.args[0] == mark_name:
+        return True
+  return False

google/adk/tests/integration/fixture/__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/fixture/agent_with_config/__init__.py

@@ -0,0 +1,15 @@
+# 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 . import agent

google/adk/tests/integration/fixture/agent_with_config/agent.py

@@ -0,0 +1,88 @@
+# 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 import Agent
+from google.genai import types
+
+new_message = types.Content(
+    role="user",
+    parts=[types.Part.from_text(text="Count a number")],
+)
+
+google_agent_1 = Agent(
+    model="gemini-1.5-flash",
+    name="agent_1",
+    description="The first agent in the team.",
+    instruction="Just say 1",
+    generate_content_config=types.GenerateContentConfig(
+        temperature=0.1,
+    ),
+)
+
+google_agent_2 = Agent(
+    model="gemini-1.5-flash",
+    name="agent_2",
+    description="The second agent in the team.",
+    instruction="Just say 2",
+    generate_content_config=types.GenerateContentConfig(
+        temperature=0.2,
+        safety_settings=[{
+            "category": "HARM_CATEGORY_HATE_SPEECH",
+            "threshold": "BLOCK_ONLY_HIGH",
+        }],
+    ),
+)
+
+google_agent_3 = Agent(
+    model="gemini-1.5-flash",
+    name="agent_3",
+    description="The third agent in the team.",
+    instruction="Just say 3",
+    generate_content_config=types.GenerateContentConfig(
+        temperature=0.5,
+        safety_settings=[{
+            "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
+            "threshold": "BLOCK_NONE",
+        }],
+    ),
+)
+
+google_agent_with_instruction_in_config = Agent(
+    model="gemini-1.5-flash",
+    name="agent",
+    generate_content_config=types.GenerateContentConfig(
+        temperature=0.5, system_instruction="Count 1"
+    ),
+)
+
+
+def function():
+  pass
+
+
+google_agent_with_tools_in_config = Agent(
+    model="gemini-1.5-flash",
+    name="agent",
+    generate_content_config=types.GenerateContentConfig(
+        temperature=0.5, tools=[function]
+    ),
+)
+
+google_agent_with_response_schema_in_config = Agent(
+    model="gemini-1.5-flash",
+    name="agent",
+    generate_content_config=types.GenerateContentConfig(
+        temperature=0.5, response_schema={"key": "value"}
+    ),
+)

google/adk/tests/integration/fixture/callback_agent/__init__.py

@@ -0,0 +1,15 @@
+# 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 . import agent

google/adk/tests/integration/fixture/callback_agent/agent.py

@@ -0,0 +1,105 @@
+# 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 Optional
+
+from google.adk import Agent
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.agents.invocation_context import InvocationContext
+from google.adk.models import LlmRequest
+from google.adk.models import LlmResponse
+from google.genai import types
+
+
+def before_agent_call_end_invocation(
+    callback_context: CallbackContext,
+) -> types.Content:
+  return types.Content(
+      role='model',
+      parts=[types.Part(text='End invocation event before agent call.')],
+  )
+
+
+def before_agent_call(
+    invocation_context: InvocationContext,
+) -> types.Content:
+  return types.Content(
+      role='model',
+      parts=[types.Part.from_text(text='Plain text event before agent call.')],
+  )
+
+
+def before_model_call_end_invocation(
+    callback_context: CallbackContext, llm_request: LlmRequest
+) -> LlmResponse:
+  return LlmResponse(
+      content=types.Content(
+          role='model',
+          parts=[
+              types.Part.from_text(
+                  text='End invocation event before model call.'
+              )
+          ],
+      )
+  )
+
+
+def before_model_call(
+    invocation_context: InvocationContext, request: LlmRequest
+) -> LlmResponse:
+  request.config.system_instruction = 'Just return 999 as response.'
+  return LlmResponse(
+      content=types.Content(
+          role='model',
+          parts=[
+              types.Part.from_text(
+                  text='Update request event before model call.'
+              )
+          ],
+      )
+  )
+
+
+def after_model_call(
+    callback_context: CallbackContext,
+    llm_response: LlmResponse,
+) -> Optional[LlmResponse]:
+  content = llm_response.content
+  if not content or not content.parts or not content.parts[0].text:
+    return
+
+  content.parts[0].text += 'Update response event after model call.'
+  return llm_response
+
+
+before_agent_callback_agent = Agent(
+    model='gemini-1.5-flash',
+    name='before_agent_callback_agent',
+    instruction='echo 1',
+    before_agent_callback=before_agent_call_end_invocation,
+)
+
+before_model_callback_agent = Agent(
+    model='gemini-1.5-flash',
+    name='before_model_callback_agent',
+    instruction='echo 2',
+    before_model_callback=before_model_call_end_invocation,
+)
+
+after_model_callback_agent = Agent(
+    model='gemini-1.5-flash',
+    name='after_model_callback_agent',
+    instruction='Say hello',
+    after_model_callback=after_model_call,
+)

google/adk/tests/integration/fixture/context_update_test/OWNERS

@@ -0,0 +1 @@
+gkcng

google/adk/tests/integration/fixture/context_update_test/__init__.py

@@ -0,0 +1,15 @@
+# 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 . import agent

google/adk/tests/integration/fixture/context_update_test/agent.py

@@ -0,0 +1,43 @@
+# 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 List
+from typing import Union
+
+from google.adk import Agent
+from google.adk.tools import ToolContext
+from pydantic import BaseModel
+
+
+def update_fc(
+    data_one: str,
+    data_two: Union[int, float, str],
+    data_three: list[str],
+    data_four: List[Union[int, float, str]],
+    tool_context: ToolContext,
+):
+  """Simply ask to update these variables in the context"""
+  tool_context.actions.update_state("data_one", data_one)
+  tool_context.actions.update_state("data_two", data_two)
+  tool_context.actions.update_state("data_three", data_three)
+  tool_context.actions.update_state("data_four", data_four)
+
+
+root_agent = Agent(
+    model="gemini-1.5-flash",
+    name="root_agent",
+    instruction="Call tools",
+    flow="auto",
+    tools=[update_fc],
+)