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

google/adk/tools/application_integration_tool/clients/integration_client.py

@@ -0,0 +1,253 @@
+# 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
+from typing import Optional
+from google.adk.tools.application_integration_tool.clients.connections_client import ConnectionsClient
+import google.auth
+from google.auth import default as default_service_credential
+import google.auth.transport.requests
+from google.auth.transport.requests import Request
+from google.oauth2 import service_account
+import requests
+
+
+class IntegrationClient:
+  """A client for interacting with Google Cloud Application Integration.
+
+  This class provides methods for retrieving OpenAPI spec for an integration or
+  a connection.
+  """
+
+  def __init__(
+      self,
+      project: str,
+      location: str,
+      integration: Optional[str] = None,
+      trigger: Optional[str] = None,
+      connection: Optional[str] = None,
+      entity_operations: Optional[dict[str, list[str]]] = None,
+      actions: Optional[list[str]] = None,
+      service_account_json: Optional[str] = None,
+  ):
+    """Initializes the ApplicationIntegrationClient.
+
+    Args:
+        project: The Google Cloud project ID.
+        location: The Google Cloud location (e.g., us-central1).
+        integration: The integration name.
+        trigger: The trigger ID for the integration.
+        connection: The connection name.
+        entity_operations: A dictionary mapping entity names to a list of
+          operations (e.g., LIST, CREATE, UPDATE, DELETE, GET).
+        actions: List of actions.
+        service_account_json: The service account configuration as a dictionary.
+          Required if not using default service credential. Used for fetching
+          connection details.
+    """
+    self.project = project
+    self.location = location
+    self.integration = integration
+    self.trigger = trigger
+    self.connection = connection
+    self.entity_operations = (
+        entity_operations if entity_operations is not None else {}
+    )
+    self.actions = actions if actions is not None else []
+    self.service_account_json = service_account_json
+    self.credential_cache = None
+
+  def get_openapi_spec_for_integration(self):
+    """Gets the OpenAPI spec for the integration.
+
+    Returns:
+        dict: The OpenAPI spec as a dictionary.
+    Raises:
+        PermissionError: If there are credential issues.
+        ValueError: If there's a request error or processing error.
+        Exception: For any other unexpected errors.
+    """
+    try:
+      url = f"https://{self.location}-integrations.googleapis.com/v1/projects/{self.project}/locations/{self.location}:generateOpenApiSpec"
+      headers = {
+          "Content-Type": "application/json",
+          "Authorization": f"Bearer {self._get_access_token()}",
+      }
+      data = {
+          "apiTriggerResources": [
+              {
+                  "integrationResource": self.integration,
+                  "triggerId": [self.trigger],
+              },
+          ],
+          "fileFormat": "JSON",
+      }
+      response = requests.post(url, headers=headers, json=data)
+      response.raise_for_status()
+      spec = response.json().get("openApiSpec", {})
+      return json.loads(spec)
+    except google.auth.exceptions.DefaultCredentialsError as e:
+      raise PermissionError(f"Credentials error: {e}") from e
+    except requests.exceptions.RequestException as e:
+      if (
+          "404" in str(e)
+          or "Not found" in str(e)
+          or "400" in str(e)
+          or "Bad request" in str(e)
+      ):
+        raise ValueError(
+            "Invalid request. Please check the provided values of"
+            f" project({self.project}), location({self.location}),"
+            f" integration({self.integration}) and trigger({self.trigger})."
+        ) from e
+      raise ValueError(f"Request error: {e}") from e
+    except Exception as e:
+      raise Exception(f"An unexpected error occurred: {e}") from e
+
+  def get_openapi_spec_for_connection(self, tool_name="", tool_instructions=""):
+    """Gets the OpenAPI spec for the connection.
+
+    Returns:
+        dict: The OpenAPI spec as a dictionary.
+    Raises:
+        ValueError: If there's an error retrieving the OpenAPI spec.
+        PermissionError: If there are credential issues.
+        Exception: For any other unexpected errors.
+    """
+    # Application Integration needs to be provisioned in the same region as connection and an integration with name "ExecuteConnection" and trigger "api_trigger/ExecuteConnection" should be created as per the documentation.
+    integration_name = "ExecuteConnection"
+    connections_client = ConnectionsClient(
+        self.project,
+        self.location,
+        self.connection,
+        self.service_account_json,
+    )
+    if not self.entity_operations and not self.actions:
+      raise ValueError(
+          "No entity operations or actions provided. Please provide at least"
+          " one of them."
+      )
+    connector_spec = connections_client.get_connector_base_spec()
+    for entity, operations in self.entity_operations.items():
+      schema, supported_operations = (
+          connections_client.get_entity_schema_and_operations(entity)
+      )
+      if not operations:
+        operations = supported_operations
+      json_schema_as_string = json.dumps(schema)
+      entity_lower = entity
+      connector_spec["components"]["schemas"][
+          f"connectorInputPayload_{entity_lower}"
+      ] = connections_client.connector_payload(schema)
+      for operation in operations:
+        operation_lower = operation.lower()
+        path = f"/v2/projects/{self.project}/locations/{self.location}/integrations/{integration_name}:execute?triggerId=api_trigger/{integration_name}#{operation_lower}_{entity_lower}"
+        if operation_lower == "create":
+          connector_spec["paths"][path] = connections_client.create_operation(
+              entity_lower, tool_name, tool_instructions
+          )
+          connector_spec["components"]["schemas"][
+              f"create_{entity_lower}_Request"
+          ] = connections_client.create_operation_request(entity_lower)
+        elif operation_lower == "update":
+          connector_spec["paths"][path] = connections_client.update_operation(
+              entity_lower, tool_name, tool_instructions
+          )
+          connector_spec["components"]["schemas"][
+              f"update_{entity_lower}_Request"
+          ] = connections_client.update_operation_request(entity_lower)
+        elif operation_lower == "delete":
+          connector_spec["paths"][path] = connections_client.delete_operation(
+              entity_lower, tool_name, tool_instructions
+          )
+          connector_spec["components"]["schemas"][
+              f"delete_{entity_lower}_Request"
+          ] = connections_client.delete_operation_request()
+        elif operation_lower == "list":
+          connector_spec["paths"][path] = connections_client.list_operation(
+              entity_lower, json_schema_as_string, tool_name, tool_instructions
+          )
+          connector_spec["components"]["schemas"][
+              f"list_{entity_lower}_Request"
+          ] = connections_client.list_operation_request()
+        elif operation_lower == "get":
+          connector_spec["paths"][path] = connections_client.get_operation(
+              entity_lower, json_schema_as_string, tool_name, tool_instructions
+          )
+          connector_spec["components"]["schemas"][
+              f"get_{entity_lower}_Request"
+          ] = connections_client.get_operation_request()
+        else:
+          raise ValueError(
+              f"Invalid operation: {operation} for entity: {entity}"
+          )
+    for action in self.actions:
+      action_details = connections_client.get_action_schema(action)
+      input_schema = action_details["inputSchema"]
+      output_schema = action_details["outputSchema"]
+      action_display_name = action_details["displayName"]
+      operation = "EXECUTE_ACTION"
+      if action == "ExecuteCustomQuery":
+        connector_spec["components"]["schemas"][
+            f"{action}_Request"
+        ] = connections_client.execute_custom_query_request()
+        operation = "EXECUTE_QUERY"
+      else:
+        connector_spec["components"]["schemas"][
+            f"{action_display_name}_Request"
+        ] = connections_client.action_request(action_display_name)
+        connector_spec["components"]["schemas"][
+            f"connectorInputPayload_{action_display_name}"
+        ] = connections_client.connector_payload(input_schema)
+      connector_spec["components"]["schemas"][
+          f"connectorOutputPayload_{action_display_name}"
+      ] = connections_client.connector_payload(output_schema)
+      connector_spec["components"]["schemas"][
+          f"{action_display_name}_Response"
+      ] = connections_client.action_response(action_display_name)
+      path = f"/v2/projects/{self.project}/locations/{self.location}/integrations/{integration_name}:execute?triggerId=api_trigger/{integration_name}#{action}"
+      connector_spec["paths"][path] = connections_client.get_action_operation(
+          action, operation, action_display_name, tool_name, tool_instructions
+      )
+    return connector_spec
+
+  def _get_access_token(self) -> str:
+    """Gets the access token for the service account or using default credentials.
+
+    Returns:
+        The access token.
+    """
+    if self.credential_cache and not self.credential_cache.expired:
+      return self.credential_cache.token
+
+    if self.service_account_json:
+      credentials = service_account.Credentials.from_service_account_info(
+          json.loads(self.service_account_json),
+          scopes=["https://www.googleapis.com/auth/cloud-platform"],
+      )
+    else:
+      try:
+        credentials, _ = default_service_credential()
+      except:
+        credentials = None
+
+    if not credentials:
+      raise ValueError(
+          "Please provide a service account that has the required permissions"
+          " to access the connection."
+      )
+
+    credentials.refresh(Request())
+    self.credential_cache = credentials
+    return credentials.token

google/adk/tools/base_tool.py

@@ -0,0 +1,144 @@
+# 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 __future__ import annotations
+
+from abc import ABC
+import os
+from typing import Any
+from typing import Optional
+from typing import TYPE_CHECKING
+
+from deprecated import deprecated
+from google.genai import types
+
+from .tool_context import ToolContext
+
+if TYPE_CHECKING:
+  from ..models.llm_request import LlmRequest
+
+
+class BaseTool(ABC):
+  """The base class for all tools."""
+
+  name: str
+  """The name of the tool."""
+  description: str
+  """The description of the tool."""
+
+  is_long_running: bool = False
+  """Whether the tool is a long running operation, which typically returns a
+  resource id first and finishes the operation later."""
+
+  def __init__(self, *, name, description, is_long_running: bool = False):
+    self.name = name
+    self.description = description
+    self.is_long_running = is_long_running
+
+  def _get_declaration(self) -> Optional[types.FunctionDeclaration]:
+    """Gets the OpenAPI specification of this tool in the form of a FunctionDeclaration.
+
+    NOTE
+    - Required if subclass uses the default implementation of
+      `process_llm_request` to add function declaration to LLM request.
+    - Otherwise, can be skipped, e.g. for a built-in GoogleSearch tool for
+      Gemini.
+
+    Returns:
+      The FunctionDeclaration of this tool, or None if it doesn't need to be
+      added to LlmRequest.config.
+    """
+    return None
+
+  async def run_async(
+      self, *, args: dict[str, Any], tool_context: ToolContext
+  ) -> Any:
+    """Runs the tool with the given arguments and context.
+
+    NOTE
+    - Required if this tool needs to run at the client side.
+    - Otherwise, can be skipped, e.g. for a built-in GoogleSearch tool for
+      Gemini.
+
+    Args:
+      args: The LLM-filled arguments.
+      ctx: The context of the tool.
+
+    Returns:
+      The result of running the tool.
+    """
+    raise NotImplementedError(f'{type(self)} is not implemented')
+
+  async def process_llm_request(
+      self, *, tool_context: ToolContext, llm_request: LlmRequest
+  ) -> None:
+    """Processes the outgoing LLM request for this tool.
+
+    Use cases:
+    - Most common use case is adding this tool to the LLM request.
+    - Some tools may just preprocess the LLM request before it's sent out.
+
+    Args:
+      tool_context: The context of the tool.
+      llm_request: The outgoing LLM request, mutable this method.
+    """
+    if (function_declaration := self._get_declaration()) is None:
+      return
+
+    llm_request.tools_dict[self.name] = self
+    if tool_with_function_declarations := _find_tool_with_function_declarations(
+        llm_request
+    ):
+      if tool_with_function_declarations.function_declarations is None:
+        tool_with_function_declarations.function_declarations = []
+      tool_with_function_declarations.function_declarations.append(
+          function_declaration
+      )
+    else:
+      llm_request.config = (
+          types.GenerateContentConfig()
+          if not llm_request.config
+          else llm_request.config
+      )
+      llm_request.config.tools = (
+          [] if not llm_request.config.tools else llm_request.config.tools
+      )
+      llm_request.config.tools.append(
+          types.Tool(function_declarations=[function_declaration])
+      )
+
+  @property
+  def _api_variant(self) -> str:
+    use_vertexai = os.environ.get('GOOGLE_GENAI_USE_VERTEXAI', '0').lower() in [
+        'true',
+        '1',
+    ]
+    return 'VERTEX_AI' if use_vertexai else 'GOOGLE_AI'
+
+
+def _find_tool_with_function_declarations(
+    llm_request: LlmRequest,
+) -> Optional[types.Tool]:
+  # TODO: add individual tool with declaration and merge in google_llm.py
+  if not llm_request.config or not llm_request.config.tools:
+    return None
+
+  return next(
+      (
+          tool
+          for tool in llm_request.config.tools
+          if isinstance(tool, types.Tool) and tool.function_declarations
+      ),
+      None,
+  )

google/adk/tools/built_in_code_execution_tool.py

@@ -0,0 +1,59 @@
+# 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 __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from google.genai import types
+from typing_extensions import override
+
+from .base_tool import BaseTool
+from .tool_context import ToolContext
+
+if TYPE_CHECKING:
+  from ..models import LlmRequest
+
+
+class BuiltInCodeExecutionTool(BaseTool):
+  """A built-in code execution tool that is automatically invoked by Gemini 2 models.
+
+  This tool operates internally within the model and does not require or perform
+  local code execution.
+  """
+
+  def __init__(self):
+    # Name and description are not used because this is a model built-in tool.
+    super().__init__(name='code_execution', description='code_execution')
+
+  @override
+  async def process_llm_request(
+      self,
+      *,
+      tool_context: ToolContext,
+      llm_request: LlmRequest,
+  ) -> None:
+    if llm_request.model and llm_request.model.startswith('gemini-2'):
+      llm_request.config = llm_request.config or types.GenerateContentConfig()
+      llm_request.config.tools = llm_request.config.tools or []
+      llm_request.config.tools.append(
+          types.Tool(code_execution=types.ToolCodeExecution())
+      )
+    else:
+      raise ValueError(
+          f'Code execution tool is not supported for model {llm_request.model}'
+      )
+
+
+built_in_code_execution = BuiltInCodeExecutionTool()

google/adk/tools/crewai_tool.py

@@ -0,0 +1,72 @@
+# 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 __future__ import annotations
+
+from google.genai import types
+from typing_extensions import override
+
+from . import _automatic_function_calling_util
+from .function_tool import FunctionTool
+
+try:
+  from crewai.tools import BaseTool as CrewaiBaseTool
+except ImportError as e:
+  import sys
+
+  if sys.version_info < (3, 10):
+    raise ImportError(
+        "Crewai Tools require Python 3.10+. Please upgrade your Python version."
+    ) from e
+  else:
+    raise ImportError(
+        "Crewai Tools require pip install 'google-adk[extensions]'."
+    ) from e
+
+
+class CrewaiTool(FunctionTool):
+  """Use this class to wrap a CrewAI tool.
+
+  If the original tool name and description are not suitable, you can override
+  them in the constructor.
+  """
+
+  tool: CrewaiBaseTool
+  """The wrapped CrewAI tool."""
+
+  def __init__(self, tool: CrewaiBaseTool, *, name: str, description: str):
+    super().__init__(tool.run)
+    self.tool = tool
+    if name:
+      self.name = name
+    elif tool.name:
+      # Right now, CrewAI tool name contains white spaces. White spaces are
+      # not supported in our framework. So we replace them with "_".
+      self.name = tool.name.replace(" ", "_").lower()
+    if description:
+      self.description = description
+    elif tool.description:
+      self.description = tool.description
+
+  @override
+  def _get_declaration(self) -> types.FunctionDeclaration:
+    """Build the function declaration for the tool."""
+    function_declaration = _automatic_function_calling_util.build_function_declaration_for_params_for_crewai(
+        False,
+        self.name,
+        self.description,
+        self.func,
+        self.tool.args_schema.model_json_schema(),
+    )
+    return function_declaration

google/adk/tools/example_tool.py

@@ -0,0 +1,62 @@
+# 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 __future__ import annotations
+
+from typing import TYPE_CHECKING
+from typing import Union
+
+from pydantic import TypeAdapter
+from typing_extensions import override
+
+from ..examples import example_util
+from ..examples.base_example_provider import BaseExampleProvider
+from ..examples.example import Example
+from .base_tool import BaseTool
+from .tool_context import ToolContext
+
+if TYPE_CHECKING:
+  from ..models.llm_request import LlmRequest
+
+
+class ExampleTool(BaseTool):
+  """A tool that adds (few-shot) examples to the LLM request.
+
+  Attributes:
+    examples: The examples to add to the LLM request.
+  """
+
+  def __init__(self, examples: Union[list[Example], BaseExampleProvider]):
+    # Name and description are not used because this tool only changes
+    # llm_request.
+    super().__init__(name='example_tool', description='example tool')
+    self.examples = (
+        TypeAdapter(list[Example]).validate_python(examples)
+        if isinstance(examples, list)
+        else examples
+    )
+
+  @override
+  async def process_llm_request(
+      self, *, tool_context: ToolContext, llm_request: LlmRequest
+  ) -> None:
+    parts = tool_context.user_content.parts
+    if not parts or not parts[0].text:
+      return
+
+    llm_request.append_instructions([
+        example_util.build_example_si(
+            self.examples, parts[0].text, llm_request.model
+        )
+    ])

google/adk/tools/exit_loop_tool.py

@@ -0,0 +1,23 @@
+# 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 .tool_context import ToolContext
+
+
+def exit_loop(tool_context: ToolContext):
+  """Exits the loop.
+
+  Call this function only when you are instructed to do so.
+  """
+  tool_context.actions.escalate = True