google-adk 0.5.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py

@@ -14,7 +14,11 @@
 
 import inspect
 from textwrap import dedent
-from typing import Any, Dict, List, Optional, Union
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Optional
+from typing import Union
 
 from fastapi.encoders import jsonable_encoder
 from fastapi.openapi.models import Operation
@@ -45,14 +49,14 @@ class OperationParser:
         should_parse: Whether to parse the operation during initialization.
     """
     if isinstance(operation, dict):
-      self.operation = Operation.model_validate(operation)
+      self._operation = Operation.model_validate(operation)
     elif isinstance(operation, str):
-      self.operation = Operation.model_validate_json(operation)
+      self._operation = Operation.model_validate_json(operation)
     else:
-      self.operation = operation
+      self._operation = operation
 
-    self.params: List[ApiParameter] = []
-    self.return_value: Optional[ApiParameter] = None
+    self._params: List[ApiParameter] = []
+    self._return_value: Optional[ApiParameter] = None
     if should_parse:
       self._process_operation_parameters()
       self._process_request_body()
@@ -67,13 +71,13 @@ class OperationParser:
       return_value: Optional[ApiParameter] = None,
   ) -> 'OperationParser':
     parser = cls(operation, should_parse=False)
-    parser.params = params
-    parser.return_value = return_value
+    parser._params = params
+    parser._return_value = return_value
     return parser
 
   def _process_operation_parameters(self):
     """Processes parameters from the OpenAPI operation."""
-    parameters = self.operation.parameters or []
+    parameters = self._operation.parameters or []
     for param in parameters:
       if isinstance(param, Parameter):
         original_name = param.name
@@ -86,7 +90,7 @@ class OperationParser:
         # param.required can be None
         required = param.required if param.required is not None else False
 
-        self.params.append(
+        self._params.append(
             ApiParameter(
                 original_name=original_name,
                 param_location=location,
@@ -98,7 +102,7 @@ class OperationParser:
 
   def _process_request_body(self):
     """Processes the request body from the OpenAPI operation."""
-    request_body = self.operation.requestBody
+    request_body = self._operation.requestBody
     if not request_body:
       return
 
@@ -114,7 +118,7 @@ class OperationParser:
       if schema and schema.type == 'object':
         properties = schema.properties or {}
         for prop_name, prop_details in properties.items():
-          self.params.append(
+          self._params.append(
               ApiParameter(
                   original_name=prop_name,
                   param_location='body',
@@ -124,7 +128,7 @@ class OperationParser:
           )
 
       elif schema and schema.type == 'array':
-        self.params.append(
+        self._params.append(
             ApiParameter(
                 original_name='array',
                 param_location='body',
@@ -133,7 +137,7 @@ class OperationParser:
             )
         )
       else:
-        self.params.append(
+        self._params.append(
             # Empty name for unnamed body param
             ApiParameter(
                 original_name='',
@@ -147,7 +151,7 @@ class OperationParser:
   def _dedupe_param_names(self):
     """Deduplicates parameter names to avoid conflicts."""
     params_cnt = {}
-    for param in self.params:
+    for param in self._params:
       name = param.py_name
       if name not in params_cnt:
         params_cnt[name] = 0
@@ -157,7 +161,7 @@ class OperationParser:
 
   def _process_return_value(self) -> Parameter:
     """Returns a Parameter object representing the return type."""
-    responses = self.operation.responses or {}
+    responses = self._operation.responses or {}
     # Default to Any if no 2xx response or if schema is missing
     return_schema = Schema(type='Any')
 
@@ -174,7 +178,7 @@ class OperationParser:
           return_schema = content[mime_type].schema_
           break
 
-    self.return_value = ApiParameter(
+    self._return_value = ApiParameter(
         original_name='',
         param_location='',
         param_schema=return_schema,
@@ -182,42 +186,42 @@ class OperationParser:
 
   def get_function_name(self) -> str:
     """Returns the generated function name."""
-    operation_id = self.operation.operationId
+    operation_id = self._operation.operationId
     if not operation_id:
       raise ValueError('Operation ID is missing')
     return to_snake_case(operation_id)[:60]
 
   def get_return_type_hint(self) -> str:
     """Returns the return type hint string (like 'str', 'int', etc.)."""
-    return self.return_value.type_hint
+    return self._return_value.type_hint
 
   def get_return_type_value(self) -> Any:
     """Returns the return type value (like str, int, List[str], etc.)."""
-    return self.return_value.type_value
+    return self._return_value.type_value
 
   def get_parameters(self) -> List[ApiParameter]:
     """Returns the list of Parameter objects."""
-    return self.params
+    return self._params
 
   def get_return_value(self) -> ApiParameter:
     """Returns the list of Parameter objects."""
-    return self.return_value
+    return self._return_value
 
   def get_auth_scheme_name(self) -> str:
     """Returns the name of the auth scheme for this operation from the spec."""
-    if self.operation.security:
-      scheme_name = list(self.operation.security[0].keys())[0]
+    if self._operation.security:
+      scheme_name = list(self._operation.security[0].keys())[0]
       return scheme_name
     return ''
 
   def get_pydoc_string(self) -> str:
     """Returns the generated PyDoc string."""
-    pydoc_params = [param.to_pydoc_string() for param in self.params]
+    pydoc_params = [param.to_pydoc_string() for param in self._params]
     pydoc_description = (
-        self.operation.summary or self.operation.description or ''
+        self._operation.summary or self._operation.description or ''
     )
     pydoc_return = PydocHelper.generate_return_doc(
-        self.operation.responses or {}
+        self._operation.responses or {}
     )
     pydoc_arg_list = chr(10).join(
         f'        {param_doc}' for param_doc in pydoc_params
@@ -236,12 +240,12 @@ class OperationParser:
     """Returns the JSON schema for the function arguments."""
     properties = {
         p.py_name: jsonable_encoder(p.param_schema, exclude_none=True)
-        for p in self.params
+        for p in self._params
     }
     return {
         'properties': properties,
-        'required': [p.py_name for p in self.params if p.required],
-        'title': f"{self.operation.operationId or 'unnamed'}_Arguments",
+        'required': [p.py_name for p in self._params if p.required],
+        'title': f"{self._operation.operationId or 'unnamed'}_Arguments",
         'type': 'object',
     }
 
@@ -253,11 +257,11 @@ class OperationParser:
             inspect.Parameter.POSITIONAL_OR_KEYWORD,
             annotation=param.type_value,
         )
-        for param in self.params
+        for param in self._params
     ]
 
   def get_annotations(self) -> Dict[str, Any]:
     """Returns a dictionary of parameter annotations for the function."""
-    annotations = {p.py_name: p.type_value for p in self.params}
+    annotations = {p.py_name: p.type_value for p in self._params}
     annotations['return'] = self.get_return_type_value()
     return annotations

google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py

@@ -41,6 +41,16 @@ from .openapi_spec_parser import ParsedOperation
 from .operation_parser import OperationParser
 from .tool_auth_handler import ToolAuthHandler
 
+# Not supported by the Gemini API
+_OPENAPI_SCHEMA_IGNORE_FIELDS = (
+    "title",
+    "default",
+    "format",
+    "additional_properties",
+    "ref",
+    "def",
+)
+
 
 def snake_to_lower_camel(snake_case_string: str):
   """Converts a snake_case string to a lower_camel_case string.
@@ -121,7 +131,7 @@ def to_gemini_schema(openapi_schema: Optional[Dict[str, Any]] = None) -> Schema:
     snake_case_key = to_snake_case(key)
     # Check if the snake_case_key exists in the Schema model's fields.
     if snake_case_key in Schema.model_fields:
-      if snake_case_key in ["title", "default", "format"]:
+      if snake_case_key in _OPENAPI_SCHEMA_IGNORE_FIELDS:
         # Ignore these fields as Gemini backend doesn't recognize them, and will
         # throw exception if they appear in the schema.
         # Format: properties[expiration].format: only 'enum' and 'date-time' are

google/adk/tools/openapi_tool/openapi_spec_parser/tool_auth_handler.py

@@ -30,7 +30,7 @@ from ..auth.credential_exchangers.auto_auth_credential_exchanger import AutoAuth
 from ..auth.credential_exchangers.base_credential_exchanger import AuthCredentialMissingError
 from ..auth.credential_exchangers.base_credential_exchanger import BaseAuthCredentialExchanger
 
-logger = logging.getLogger(__name__)
+logger = logging.getLogger("google_adk." + __name__)
 
 AuthPreparationState = Literal["pending", "done"]
 

google/adk/tools/preload_memory_tool.py

@@ -14,11 +14,11 @@
 
 from __future__ import annotations
 
-from datetime import datetime
 from typing import TYPE_CHECKING
 
 from typing_extensions import override
 
+from . import _memory_entry_utils
 from .base_tool import BaseTool
 from .tool_context import ToolContext
 
@@ -27,7 +27,10 @@ if TYPE_CHECKING:
 
 
 class PreloadMemoryTool(BaseTool):
-  """A tool that preloads the memory for the current user."""
+  """A tool that preloads the memory for the current user.
+
+  NOTE: Currently this tool only uses text part from the memory.
+  """
 
   def __init__(self):
     # Name and description are not used because this tool only
@@ -41,29 +44,35 @@ class PreloadMemoryTool(BaseTool):
       tool_context: ToolContext,
       llm_request: LlmRequest,
   ) -> None:
-    parts = tool_context.user_content.parts
-    if not parts or not parts[0].text:
+    user_content = tool_context.user_content
+    if (
+        not user_content
+        or not user_content.parts
+        or not user_content.parts[0].text
+    ):
       return
-    query = parts[0].text
-    response = await tool_context.search_memory(query)
+
+    user_query: str = user_content.parts[0].text
+    response = await tool_context.search_memory(user_query)
     if not response.memories:
       return
-    memory_text = ''
+
+    memory_text_lines = []
     for memory in response.memories:
-      time_str = datetime.fromtimestamp(memory.events[0].timestamp).isoformat()
-      memory_text += f'Time: {time_str}\n'
-      for event in memory.events:
-        # TODO: support multi-part content.
-        if (
-            event.content
-            and event.content.parts
-            and event.content.parts[0].text
-        ):
-          memory_text += f'{event.author}: {event.content.parts[0].text}\n'
+      if time_str := (f'Time: {memory.timestamp}' if memory.timestamp else ''):
+        memory_text_lines.append(time_str)
+      if memory_text := _memory_entry_utils.extract_text(memory):
+        memory_text_lines.append(
+            f'{memory.author}: {memory_text}' if memory.author else memory_text
+        )
+    if not memory_text_lines:
+      return
+
+    full_memory_text = '\n'.join(memory_text_lines)
     si = f"""The following content is from your previous conversations with the user.
 They may be useful for answering the user's current query.
 <PAST_CONVERSATIONS>
-{memory_text}
+{full_memory_text}
 </PAST_CONVERSATIONS>
 """
     llm_request.append_instructions([si])

google/adk/tools/retrieval/__init__.py

@@ -29,7 +29,7 @@ try:
 except ImportError:
   import logging
 
-  logger = logging.getLogger(__name__)
+  logger = logging.getLogger('google_adk.' + __name__)
   logger.debug(
       'The Vertex sdk is not installed. If you want to use the Vertex RAG with'
       ' agents, please install it. If not, you can ignore this warning.'

google/adk/tools/retrieval/vertex_ai_rag_retrieval.py

@@ -30,7 +30,7 @@ from .base_retrieval_tool import BaseRetrievalTool
 if TYPE_CHECKING:
   from ...models.llm_request import LlmRequest
 
-logger = logging.getLogger(__name__)
+logger = logging.getLogger('google_adk.' + __name__)
 
 
 class VertexAiRagRetrieval(BaseRetrievalTool):

google/adk/tools/toolbox_toolset.py

@@ -0,0 +1,107 @@
+# 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 Any
+from typing import Callable
+from typing import List
+from typing import Mapping
+from typing import Optional
+from typing import Union
+
+import toolbox_core as toolbox
+from typing_extensions import override
+
+from ..agents.readonly_context import ReadonlyContext
+from .base_tool import BaseTool
+from .base_toolset import BaseToolset
+from .function_tool import FunctionTool
+
+
+class ToolboxToolset(BaseToolset):
+  """A class that provides access to toolbox toolsets.
+
+  Example:
+  ```python
+  toolbox_toolset = ToolboxToolset("http://127.0.0.1:5000",
+  toolset_name="my-toolset")
+  )
+  ```
+  """
+
+  def __init__(
+      self,
+      server_url: str,
+      toolset_name: Optional[str] = None,
+      tool_names: Optional[List[str]] = None,
+      auth_token_getters: Optional[dict[str, Callable[[], str]]] = None,
+      bound_params: Optional[
+          Mapping[str, Union[Callable[[], Any], Any]]
+      ] = None,
+  ):
+    """Args:
+
+      server_url: The URL of the toolbox server.
+      toolset_name: The name of the toolbox toolset to load.
+      tool_names: The names of the tools to load.
+      auth_token_getters: A mapping of authentication service names to
+        callables that return the corresponding authentication token. see:
+        https://github.com/googleapis/mcp-toolbox-sdk-python/tree/main/packages/toolbox-core#authenticating-tools
+        for details.
+      bound_params: A mapping of parameter names to bind to specific values or
+        callables that are called to produce values as needed. see:
+        https://github.com/googleapis/mcp-toolbox-sdk-python/tree/main/packages/toolbox-core#binding-parameter-values
+        for details.
+    The resulting ToolboxToolset will contain both tools loaded by tool_names
+    and toolset_name.
+    """
+    if not tool_names and not toolset_name:
+      raise ValueError("tool_names and toolset_name cannot both be None")
+    super().__init__()
+    self._server_url = server_url
+    self._toolbox_client = toolbox.ToolboxClient(server_url)
+    self._toolset_name = toolset_name
+    self._tool_names = tool_names
+    self._auth_token_getters = auth_token_getters or {}
+    self._bound_params = bound_params or {}
+
+  @override
+  async def get_tools(
+      self, readonly_context: Optional[ReadonlyContext] = None
+  ) -> list[BaseTool]:
+    tools = []
+    if self._toolset_name:
+      tools.extend([
+          FunctionTool(tool)
+          for tool in await self._toolbox_client.load_toolset(
+              self._toolset_name,
+              auth_token_getters=self._auth_token_getters,
+              bound_params=self._bound_params,
+          )
+      ])
+    if self._tool_names:
+      tools.extend([
+          FunctionTool(
+              await self._toolbox_client.load_tool(
+                  tool_name,
+                  auth_token_getters=self._auth_token_getters,
+                  bound_params=self._bound_params,
+              )
+          )
+          for tool_name in self._tool_names
+      ])
+    return tools
+
+  @override
+  async def close(self):
+    self._toolbox_client.close()

google/adk/tools/transfer_to_agent_tool.py

@@ -15,7 +15,6 @@
 from .tool_context import ToolContext
 
 
-# TODO: make this internal, since user doesn't need to use this tool directly.
 def transfer_to_agent(agent_name: str, tool_context: ToolContext):
   """Transfer the question to another agent."""
   tool_context.actions.transfer_to_agent = agent_name

google/adk/utils/__init__.py

@@ -0,0 +1,13 @@
+# 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/utils/instructions_utils.py

@@ -0,0 +1,131 @@
+# 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 re
+
+from ..agents.readonly_context import ReadonlyContext
+from ..sessions.state import State
+
+__all__ = [
+    'inject_session_state',
+]
+
+
+async def inject_session_state(
+    template: str,
+    readonly_context: ReadonlyContext,
+) -> str:
+  """Populates values in the instruction template, e.g. state, artifact, etc.
+
+  This method is intended to be used in InstructionProvider based instruction
+  and global_instruction which are called with readonly_context.
+
+  e.g.
+  ```
+  ...
+  from google.adk.utils import instructions_utils
+
+  async def build_instruction(
+      readonly_context: ReadonlyContext,
+  ) -> str:
+    return await instructions_utils.inject_session_state(
+        'You can inject a state variable like {var_name} or an artifact '
+        '{artifact.file_name} into the instruction template.',
+        readonly_context,
+    )
+
+  agent = Agent(
+      model="gemini-2.0-flash",
+      name="agent",
+      instruction=build_instruction,
+  )
+  ```
+
+  Args:
+    template: The instruction template.
+    readonly_context: The read-only context
+
+  Returns:
+    The instruction template with values populated.
+  """
+
+  invocation_context = readonly_context._invocation_context
+
+  async def _async_sub(pattern, repl_async_fn, string) -> str:
+    result = []
+    last_end = 0
+    for match in re.finditer(pattern, string):
+      result.append(string[last_end : match.start()])
+      replacement = await repl_async_fn(match)
+      result.append(replacement)
+      last_end = match.end()
+    result.append(string[last_end:])
+    return ''.join(result)
+
+  async def _replace_match(match) -> str:
+    var_name = match.group().lstrip('{').rstrip('}').strip()
+    optional = False
+    if var_name.endswith('?'):
+      optional = True
+      var_name = var_name.removesuffix('?')
+    if var_name.startswith('artifact.'):
+      var_name = var_name.removeprefix('artifact.')
+      if invocation_context.artifact_service is None:
+        raise ValueError('Artifact service is not initialized.')
+      artifact = await invocation_context.artifact_service.load_artifact(
+          app_name=invocation_context.session.app_name,
+          user_id=invocation_context.session.user_id,
+          session_id=invocation_context.session.id,
+          filename=var_name,
+      )
+      if not var_name:
+        raise KeyError(f'Artifact {var_name} not found.')
+      return str(artifact)
+    else:
+      if not _is_valid_state_name(var_name):
+        return match.group()
+      if var_name in invocation_context.session.state:
+        return str(invocation_context.session.state[var_name])
+      else:
+        if optional:
+          return ''
+        else:
+          raise KeyError(f'Context variable not found: `{var_name}`.')
+
+  return await _async_sub(r'{+[^{}]*}+', _replace_match, template)
+
+
+def _is_valid_state_name(var_name):
+  """Checks if the variable name is a valid state name.
+
+  Valid state is either:
+    - Valid identifier
+    - <Valid prefix>:<Valid identifier>
+  All the others will just return as it is.
+
+  Args:
+    var_name: The variable name to check.
+
+  Returns:
+    True if the variable name is a valid state name, False otherwise.
+  """
+  parts = var_name.split(':')
+  if len(parts) == 1:
+    return var_name.isidentifier()
+
+  if len(parts) == 2:
+    prefixes = [State.APP_PREFIX, State.USER_PREFIX, State.TEMP_PREFIX]
+    if (parts[0] + ':') in prefixes:
+      return parts[1].isidentifier()
+  return False

google/adk/version.py

@@ -13,4 +13,4 @@
 # limitations under the License.
 
 # version: date+base_cl
-__version__ = "0.5.0"
+__version__ = "1.1.0"