google-adk 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

google/adk/tools/application_integration_tool/integration_connector_tool.py

@@ -0,0 +1,159 @@
+# 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
+from typing import Any
+from typing import Dict
+from typing import Optional
+
+from google.adk.tools.openapi_tool.openapi_spec_parser.rest_api_tool import RestApiTool
+from google.adk.tools.openapi_tool.openapi_spec_parser.rest_api_tool import to_gemini_schema
+from google.genai.types import FunctionDeclaration
+from typing_extensions import override
+
+from .. import BaseTool
+from ..tool_context import ToolContext
+
+logger = logging.getLogger(__name__)
+
+
+class IntegrationConnectorTool(BaseTool):
+  """A tool that wraps a RestApiTool to interact with a specific Application Integration endpoint.
+
+  This tool adds Application Integration specific context like connection
+  details, entity, operation, and action to the underlying REST API call
+  handled by RestApiTool. It prepares the arguments and then delegates the
+  actual API call execution to the contained RestApiTool instance.
+
+  * Generates request params and body
+  * Attaches auth credentials to API call.
+
+  Example:
+  ```
+    # Each API operation in the spec will be turned into its own tool
+    # Name of the tool is the operationId of that operation, in snake case
+    operations = OperationGenerator().parse(openapi_spec_dict)
+    tool = [RestApiTool.from_parsed_operation(o) for o in operations]
+  ```
+  """
+
+  EXCLUDE_FIELDS = [
+      'connection_name',
+      'service_name',
+      'host',
+      'entity',
+      'operation',
+      'action',
+  ]
+
+  OPTIONAL_FIELDS = [
+      'page_size',
+      'page_token',
+      'filter',
+  ]
+
+  def __init__(
+      self,
+      name: str,
+      description: str,
+      connection_name: str,
+      connection_host: str,
+      connection_service_name: str,
+      entity: str,
+      operation: str,
+      action: str,
+      rest_api_tool: RestApiTool,
+  ):
+    """Initializes the ApplicationIntegrationTool.
+
+    Args:
+        name: The name of the tool, typically derived from the API operation.
+          Should be unique and adhere to Gemini function naming conventions
+          (e.g., less than 64 characters).
+        description: A description of what the tool does, usually based on the
+          API operation's summary or description.
+        connection_name: The name of the Integration Connector connection.
+        connection_host: The hostname or IP address for the connection.
+        connection_service_name: The specific service name within the host.
+        entity: The Integration Connector entity being targeted.
+        operation: The specific operation being performed on the entity.
+        action: The action associated with the operation (e.g., 'execute').
+        rest_api_tool: An initialized RestApiTool instance that handles the
+          underlying REST API communication based on an OpenAPI specification
+          operation. This tool will be called by ApplicationIntegrationTool with
+          added connection and context arguments. tool =
+          [RestApiTool.from_parsed_operation(o) for o in operations]
+    """
+    # Gemini restrict the length of function name to be less than 64 characters
+    super().__init__(
+        name=name,
+        description=description,
+    )
+    self.connection_name = connection_name
+    self.connection_host = connection_host
+    self.connection_service_name = connection_service_name
+    self.entity = entity
+    self.operation = operation
+    self.action = action
+    self.rest_api_tool = rest_api_tool
+
+  @override
+  def _get_declaration(self) -> FunctionDeclaration:
+    """Returns the function declaration in the Gemini Schema format."""
+    schema_dict = self.rest_api_tool._operation_parser.get_json_schema()
+    for field in self.EXCLUDE_FIELDS:
+      if field in schema_dict['properties']:
+        del schema_dict['properties'][field]
+    for field in self.OPTIONAL_FIELDS + self.EXCLUDE_FIELDS:
+      if field in schema_dict['required']:
+        schema_dict['required'].remove(field)
+
+    parameters = to_gemini_schema(schema_dict)
+    function_decl = FunctionDeclaration(
+        name=self.name, description=self.description, parameters=parameters
+    )
+    return function_decl
+
+  @override
+  async def run_async(
+      self, *, args: dict[str, Any], tool_context: Optional[ToolContext]
+  ) -> Dict[str, Any]:
+    args['connection_name'] = self.connection_name
+    args['service_name'] = self.connection_service_name
+    args['host'] = self.connection_host
+    args['entity'] = self.entity
+    args['operation'] = self.operation
+    args['action'] = self.action
+    logger.info('Running tool: %s with args: %s', self.name, args)
+    return self.rest_api_tool.call(args=args, tool_context=tool_context)
+
+  def __str__(self):
+    return (
+        f'ApplicationIntegrationTool(name="{self.name}",'
+        f' description="{self.description}",'
+        f' connection_name="{self.connection_name}", entity="{self.entity}",'
+        f' operation="{self.operation}", action="{self.action}")'
+    )
+
+  def __repr__(self):
+    return (
+        f'ApplicationIntegrationTool(name="{self.name}",'
+        f' description="{self.description}",'
+        f' connection_name="{self.connection_name}",'
+        f' connection_host="{self.connection_host}",'
+        f' connection_service_name="{self.connection_service_name}",'
+        f' entity="{self.entity}", operation="{self.operation}",'
+        f' action="{self.action}", rest_api_tool={repr(self.rest_api_tool)})'
+    )

google/adk/tools/function_tool.py

@@ -59,6 +59,23 @@ class FunctionTool(BaseTool):
     if 'tool_context' in signature.parameters:
       args_to_call['tool_context'] = tool_context
 
+    # Before invoking the function, we check for if the list of args passed in
+    # has all the mandatory arguments or not.
+    # If the check fails, then we don't invoke the tool and let the Agent know
+    # that there was a missing a input parameter. This will basically help
+    # the underlying model fix the issue and retry.
+    mandatory_args = self._get_mandatory_args()
+    missing_mandatory_args = [
+        arg for arg in mandatory_args if arg not in args_to_call
+    ]
+
+    if missing_mandatory_args:
+      missing_mandatory_args_str = '\n'.join(missing_mandatory_args)
+      error_str = f"""Invoking `{self.name}()` failed as the following mandatory input parameters are not present:
+{missing_mandatory_args_str}
+You could retry calling this tool, but it is IMPORTANT for you to provide all the mandatory parameters."""
+      return {'error': error_str}
+
     if inspect.iscoroutinefunction(self.func):
       return await self.func(**args_to_call) or {}
     else:
@@ -85,3 +102,28 @@ class FunctionTool(BaseTool):
       args_to_call['tool_context'] = tool_context
     async for item in self.func(**args_to_call):
       yield item
+
+  def _get_mandatory_args(
+      self,
+  ) -> list[str]:
+    """Identifies mandatory parameters (those without default values) for a function.
+
+    Returns:
+      A list of strings, where each string is the name of a mandatory parameter.
+    """
+    signature = inspect.signature(self.func)
+    mandatory_params = []
+
+    for name, param in signature.parameters.items():
+      # A parameter is mandatory if:
+      # 1. It has no default value (param.default is inspect.Parameter.empty)
+      # 2. It's not a variable positional (*args) or variable keyword (**kwargs) parameter
+      #
+      # For more refer to: https://docs.python.org/3/library/inspect.html#inspect.Parameter.kind
+      if param.default == inspect.Parameter.empty and param.kind not in (
+          inspect.Parameter.VAR_POSITIONAL,
+          inspect.Parameter.VAR_KEYWORD,
+      ):
+        mandatory_params.append(name)
+
+    return mandatory_params

google/adk/tools/google_api_tool/google_api_tool_set.py

@@ -11,10 +11,12 @@
 # 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 __future__ import annotations
+
 import inspect
 import os
 from typing import Any
-from typing import Dict
 from typing import Final
 from typing import List
 from typing import Optional
@@ -28,6 +30,7 @@ from .googleapi_to_openapi_converter import GoogleApiToOpenApiConverter
 
 
 class GoogleApiToolSet:
+  """Google API Tool Set."""
 
   def __init__(self, tools: List[RestApiTool]):
     self.tools: Final[List[GoogleApiTool]] = [
@@ -45,10 +48,10 @@ class GoogleApiToolSet:
 
   @staticmethod
   def _load_tool_set_with_oidc_auth(
-      spec_file: str = None,
-      spec_dict: Dict[str, Any] = None,
-      scopes: list[str] = None,
-  ) -> Optional[OpenAPIToolset]:
+      spec_file: Optional[str] = None,
+      spec_dict: Optional[dict[str, Any]] = None,
+      scopes: Optional[list[str]] = None,
+  ) -> OpenAPIToolset:
     spec_str = None
     if spec_file:
       # Get the frame of the caller
@@ -90,18 +93,18 @@ class GoogleApiToolSet:
 
   @classmethod
   def load_tool_set(
-      cl: Type['GoogleApiToolSet'],
+      cls: Type[GoogleApiToolSet],
       api_name: str,
       api_version: str,
-  ) -> 'GoogleApiToolSet':
+  ) -> GoogleApiToolSet:
     spec_dict = GoogleApiToOpenApiConverter(api_name, api_version).convert()
     scope = list(
         spec_dict['components']['securitySchemes']['oauth2']['flows'][
             'authorizationCode'
         ]['scopes'].keys()
     )[0]
-    return cl(
-        cl._load_tool_set_with_oidc_auth(
+    return cls(
+        cls._load_tool_set_with_oidc_auth(
             spec_dict=spec_dict, scopes=[scope]
         ).get_tools()
     )

google/adk/tools/load_artifacts_tool.py

@@ -89,7 +89,7 @@ class LoadArtifactsTool(BaseTool):
   than the function call.
   """])
 
-    # Attache the content of the artifacts if the model requests them.
+    # Attach the content of the artifacts if the model requests them.
     # This only adds the content to the model request, instead of the session.
     if llm_request.contents and llm_request.contents[-1].parts:
       function_response = llm_request.contents[-1].parts[0].function_response

google/adk/tools/openapi_tool/auth/credential_exchangers/oauth2_exchanger.py

@@ -66,10 +66,10 @@ class OAuth2CredentialExchanger(BaseAuthCredentialExchanger):
 
     Returns:
         An AuthCredential object containing the HTTP bearer access token. If the
-        HTTO bearer token cannot be generated, return the origianl credential
+        HTTP bearer token cannot be generated, return the original credential.
     """
 
-    if "access_token" not in auth_credential.oauth2.token:
+    if not auth_credential.oauth2.access_token:
       return auth_credential
 
     # Return the access token as a bearer token.
@@ -78,7 +78,7 @@ class OAuth2CredentialExchanger(BaseAuthCredentialExchanger):
         http=HttpAuth(
             scheme="bearer",
             credentials=HttpCredentials(
-                token=auth_credential.oauth2.token["access_token"]
+                token=auth_credential.oauth2.access_token
             ),
         ),
     )
@@ -111,7 +111,7 @@ class OAuth2CredentialExchanger(BaseAuthCredentialExchanger):
       return auth_credential
 
     # If access token is exchanged, exchange a HTTPBearer token.
-    if auth_credential.oauth2.token:
+    if auth_credential.oauth2.access_token:
       return self.generate_auth_token(auth_credential)
 
     return None

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

@@ -124,7 +124,7 @@ class OpenAPIToolset:
   def _load_spec(
       self, spec_str: str, spec_type: Literal["json", "yaml"]
   ) -> Dict[str, Any]:
-    """Loads the OpenAPI spec string into adictionary."""
+    """Loads the OpenAPI spec string into a dictionary."""
     if spec_type == "json":
       return json.loads(spec_str)
     elif spec_type == "yaml":

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

@@ -14,20 +14,12 @@
 
 import inspect
 from textwrap import dedent
-from typing import Any
-from typing import Dict
-from typing import List
-from typing import Optional
-from typing import Union
+from typing import Any, Dict, List, Optional, Union
 
 from fastapi.encoders import jsonable_encoder
-from fastapi.openapi.models import Operation
-from fastapi.openapi.models import Parameter
-from fastapi.openapi.models import Schema
+from fastapi.openapi.models import Operation, Parameter, Schema
 
-from ..common.common import ApiParameter
-from ..common.common import PydocHelper
-from ..common.common import to_snake_case
+from ..common.common import ApiParameter, PydocHelper, to_snake_case
 
 
 class OperationParser:
@@ -110,7 +102,8 @@ class OperationParser:
       description = request_body.description or ''
 
       if schema and schema.type == 'object':
-        for prop_name, prop_details in schema.properties.items():
+        properties = schema.properties or {}
+        for prop_name, prop_details in properties.items():
           self.params.append(
               ApiParameter(
                   original_name=prop_name,

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

@@ -17,6 +17,7 @@ from typing import Dict
 from typing import List
 from typing import Literal
 from typing import Optional
+from typing import Sequence
 from typing import Tuple
 from typing import Union
 
@@ -59,6 +60,40 @@ def snake_to_lower_camel(snake_case_string: str):
   ])
 
 
+# TODO: Switch to Gemini `from_json_schema` util when it is released
+# in Gemini SDK.
+def normalize_json_schema_type(
+    json_schema_type: Optional[Union[str, Sequence[str]]],
+) -> tuple[Optional[str], bool]:
+  """Converts a JSON Schema Type into Gemini Schema type.
+
+  Adopted and modified from Gemini SDK. This gets the first available schema
+  type from JSON Schema, and use it to mark Gemini schema type. If JSON Schema
+  contains a list of types, the first non null type is used.
+
+  Remove this after switching to Gemini `from_json_schema`.
+  """
+  if json_schema_type is None:
+    return None, False
+  if isinstance(json_schema_type, str):
+    if json_schema_type == "null":
+      return None, True
+    return json_schema_type, False
+
+  non_null_types = []
+  nullable = False
+  # If json schema type is an array, pick the first non null type.
+  for type_value in json_schema_type:
+    if type_value == "null":
+      nullable = True
+    else:
+      non_null_types.append(type_value)
+  non_null_type = non_null_types[0] if non_null_types else None
+  return non_null_type, nullable
+
+
+# TODO: Switch to Gemini `from_json_schema` util when it is released
+# in Gemini SDK.
 def to_gemini_schema(openapi_schema: Optional[Dict[str, Any]] = None) -> Schema:
   """Converts an OpenAPI schema dictionary to a Gemini Schema object.
 
@@ -82,13 +117,6 @@ def to_gemini_schema(openapi_schema: Optional[Dict[str, Any]] = None) -> Schema:
   if not openapi_schema.get("type"):
     openapi_schema["type"] = "object"
 
-  # Adding this to avoid "properties: should be non-empty for OBJECT type" error
-  # See b/385165182
-  if openapi_schema.get("type", "") == "object" and not openapi_schema.get(
-      "properties"
-  ):
-    openapi_schema["properties"] = {"dummy_DO_NOT_GENERATE": {"type": "string"}}
-
   for key, value in openapi_schema.items():
     snake_case_key = to_snake_case(key)
     # Check if the snake_case_key exists in the Schema model's fields.
@@ -99,7 +127,17 @@ def to_gemini_schema(openapi_schema: Optional[Dict[str, Any]] = None) -> Schema:
         # Format: properties[expiration].format: only 'enum' and 'date-time' are
         # supported for STRING type
         continue
-      if snake_case_key == "properties" and isinstance(value, dict):
+      elif snake_case_key == "type":
+        schema_type, nullable = normalize_json_schema_type(
+            openapi_schema.get("type", None)
+        )
+        # Adding this to force adding a type to an empty dict
+        # This avoid "... one_of or any_of must specify a type" error
+        pydantic_schema_data["type"] = schema_type if schema_type else "object"
+        pydantic_schema_data["type"] = pydantic_schema_data["type"].upper()
+        if nullable:
+          pydantic_schema_data["nullable"] = True
+      elif snake_case_key == "properties" and isinstance(value, dict):
         pydantic_schema_data[snake_case_key] = {
             k: to_gemini_schema(v) for k, v in value.items()
         }

google/adk/version.py

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

{google_adk-0.2.0.dist-info → google_adk-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-adk
-Version: 0.2.0
+Version: 0.4.0
 Summary: Agent Development Kit
 Author-email: Google LLC <googleapis-packages@google.com>
 Requires-Python: >=3.9
@@ -27,7 +27,7 @@ Requires-Dist: google-cloud-aiplatform>=1.87.0
 Requires-Dist: google-cloud-secret-manager>=2.22.0
 Requires-Dist: google-cloud-speech>=2.30.0
 Requires-Dist: google-cloud-storage>=2.18.0, <3.0.0
-Requires-Dist: google-genai>=1.9.0
+Requires-Dist: google-genai>=1.11.0
 Requires-Dist: graphviz>=0.20.2
 Requires-Dist: mcp>=1.5.0;python_version>='3.10'
 Requires-Dist: opentelemetry-api>=1.31.0
@@ -99,11 +99,7 @@ Provides-Extra: test
     </h3>
 </html>
 
-Agent Development Kit (ADK) is designed for developers seeking fine-grained
-control and flexibility when building advanced AI agents that are tightly
-integrated with services in Google Cloud. It allows you to define agent
-behavior, orchestration, and tool use directly in code, enabling robust
-debugging, versioning, and deployment anywhere – from your laptop to the cloud.
+Agent Development Kit (ADK) is a flexible and modular framework for developing and deploying AI agents. While optimized for Gemini and the Google ecosystem, ADK is model-agnostic, deployment-agnostic, and is built for compatibility with other frameworks. ADK was designed to make agent development feel more like software development, to make it easier for developers to create, deploy, and orchestrate agentic architectures that range from simple tasks to complex workflows.
 
 
 ---
@@ -126,12 +122,27 @@ debugging, versioning, and deployment anywhere – from your laptop to the cloud
 
 ## 🚀 Installation
 
-You can install the ADK using `pip`:
+### Stable Release (Recommended)
+
+You can install the latest stable version of ADK using `pip`:
 
 ```bash
 pip install google-adk
 ```
 
+The release cadence is weekly.
+
+This version is recommended for most users as it represents the most recent official release.
+
+### Development Version
+Bug fixes and new features are merged into the main branch on GitHub first. If you need access to changes that haven't been included in an official PyPI release yet, you can install directly from the main branch:
+
+```bash
+pip install git+https://github.com/google/adk-python.git@main
+```
+
+Note: The development version is built directly from the latest code commits. While it includes the newest fixes and features, it may also contain experimental changes or bugs not present in the stable release. Use it primarily for testing upcoming changes or accessing critical fixes before they are officially released.
+
 ## 📚 Documentation
 
 Explore the full documentation for detailed guides on building, evaluating, and
@@ -193,10 +204,18 @@ adk eval \
     samples_for_testing/hello_world/hello_world_eval_set_001.evalset.json
 ```
 
+## 🤖 A2A and ADK integration
+
+For remote agent-to-agent communication, ADK integrates with the
+[A2A protocol](https://github.com/google/A2A/).
+See this [example](https://github.com/google/A2A/tree/main/samples/python/agents/google_adk)
+for how they can work together.
 
 ## 🤝 Contributing
 
-We welcome contributions from the community! Whether it's bug reports, feature requests, documentation improvements, or code contributions, please see our [**Contributing Guidelines**](./CONTRIBUTING.md) to get started.
+We welcome contributions from the community! Whether it's bug reports, feature requests, documentation improvements, or code contributions, please see our 
+- [General contribution guideline and flow](https://google.github.io/adk-docs/contributing-guide/#questions).
+- Then if you want to contribute code, please read [Code Contributing Guidelines](./CONTRIBUTING.md) to get started.
 
 ## 📄 License