google-adk 1.4.1__tar.gz → 1.4.2__tar.gz

{google_adk-1.4.1 → google_adk-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-adk
-Version: 1.4.1
+Version: 1.4.2
 Summary: Agent Development Kit
 Author-email: Google LLC <googleapis-packages@google.com>
 Requires-Python: >=3.9

google_adk-1.4.2/src/google/adk/a2a/converters/event_converter.py

@@ -0,0 +1,382 @@
+# 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
+
+import datetime
+import logging
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Optional
+import uuid
+
+from a2a.server.events import Event as A2AEvent
+from a2a.types import Artifact
+from a2a.types import DataPart
+from a2a.types import Message
+from a2a.types import Role
+from a2a.types import TaskArtifactUpdateEvent
+from a2a.types import TaskState
+from a2a.types import TaskStatus
+from a2a.types import TaskStatusUpdateEvent
+from a2a.types import TextPart
+
+from ...agents.invocation_context import InvocationContext
+from ...events.event import Event
+from ...utils.feature_decorator import working_in_progress
+from .part_converter import A2A_DATA_PART_METADATA_TYPE_FUNCTION_CALL
+from .part_converter import A2A_DATA_PART_METADATA_TYPE_KEY
+from .part_converter import convert_genai_part_to_a2a_part
+from .utils import _get_adk_metadata_key
+
+# Constants
+
+ARTIFACT_ID_SEPARATOR = "-"
+DEFAULT_ERROR_MESSAGE = "An error occurred during processing"
+
+# Logger
+logger = logging.getLogger("google_adk." + __name__)
+
+
+def _serialize_metadata_value(value: Any) -> str:
+  """Safely serializes metadata values to string format.
+
+  Args:
+    value: The value to serialize.
+
+  Returns:
+    String representation of the value.
+  """
+  if hasattr(value, "model_dump"):
+    try:
+      return value.model_dump(exclude_none=True, by_alias=True)
+    except Exception as e:
+      logger.warning("Failed to serialize metadata value: %s", e)
+      return str(value)
+  return str(value)
+
+
+def _get_context_metadata(
+    event: Event, invocation_context: InvocationContext
+) -> Dict[str, str]:
+  """Gets the context metadata for the event.
+
+  Args:
+    event: The ADK event to extract metadata from.
+    invocation_context: The invocation context containing session information.
+
+  Returns:
+    A dictionary containing the context metadata.
+
+  Raises:
+    ValueError: If required fields are missing from event or context.
+  """
+  if not event:
+    raise ValueError("Event cannot be None")
+  if not invocation_context:
+    raise ValueError("Invocation context cannot be None")
+
+  try:
+    metadata = {
+        _get_adk_metadata_key("app_name"): invocation_context.app_name,
+        _get_adk_metadata_key("user_id"): invocation_context.user_id,
+        _get_adk_metadata_key("session_id"): invocation_context.session.id,
+        _get_adk_metadata_key("invocation_id"): event.invocation_id,
+        _get_adk_metadata_key("author"): event.author,
+    }
+
+    # Add optional metadata fields if present
+    optional_fields = [
+        ("branch", event.branch),
+        ("grounding_metadata", event.grounding_metadata),
+        ("custom_metadata", event.custom_metadata),
+        ("usage_metadata", event.usage_metadata),
+        ("error_code", event.error_code),
+    ]
+
+    for field_name, field_value in optional_fields:
+      if field_value is not None:
+        metadata[_get_adk_metadata_key(field_name)] = _serialize_metadata_value(
+            field_value
+        )
+
+    return metadata
+
+  except Exception as e:
+    logger.error("Failed to create context metadata: %s", e)
+    raise
+
+
+def _create_artifact_id(
+    app_name: str, user_id: str, session_id: str, filename: str, version: int
+) -> str:
+  """Creates a unique artifact ID.
+
+  Args:
+    app_name: The application name.
+    user_id: The user ID.
+    session_id: The session ID.
+    filename: The artifact filename.
+    version: The artifact version.
+
+  Returns:
+    A unique artifact ID string.
+  """
+  components = [app_name, user_id, session_id, filename, str(version)]
+  return ARTIFACT_ID_SEPARATOR.join(components)
+
+
+def _convert_artifact_to_a2a_events(
+    event: Event,
+    invocation_context: InvocationContext,
+    filename: str,
+    version: int,
+) -> TaskArtifactUpdateEvent:
+  """Converts a new artifact version to an A2A TaskArtifactUpdateEvent.
+
+  Args:
+    event: The ADK event containing the artifact information.
+    invocation_context: The invocation context.
+    filename: The name of the artifact file.
+    version: The version number of the artifact.
+
+  Returns:
+    A TaskArtifactUpdateEvent representing the artifact update.
+
+  Raises:
+    ValueError: If required parameters are invalid.
+    RuntimeError: If artifact loading fails.
+  """
+  if not filename:
+    raise ValueError("Filename cannot be empty")
+  if version < 0:
+    raise ValueError("Version must be non-negative")
+
+  try:
+    artifact_part = invocation_context.artifact_service.load_artifact(
+        app_name=invocation_context.app_name,
+        user_id=invocation_context.user_id,
+        session_id=invocation_context.session.id,
+        filename=filename,
+        version=version,
+    )
+
+    converted_part = convert_genai_part_to_a2a_part(part=artifact_part)
+    if not converted_part:
+      raise RuntimeError(f"Failed to convert artifact part for {filename}")
+
+    artifact_id = _create_artifact_id(
+        invocation_context.app_name,
+        invocation_context.user_id,
+        invocation_context.session.id,
+        filename,
+        version,
+    )
+
+    return TaskArtifactUpdateEvent(
+        taskId=str(uuid.uuid4()),
+        append=False,
+        contextId=invocation_context.session.id,
+        lastChunk=True,
+        artifact=Artifact(
+            artifactId=artifact_id,
+            name=filename,
+            metadata={
+                "filename": filename,
+                "version": version,
+            },
+            parts=[converted_part],
+        ),
+    )
+  except Exception as e:
+    logger.error(
+        "Failed to convert artifact for %s, version %s: %s",
+        filename,
+        version,
+        e,
+    )
+    raise RuntimeError(f"Artifact conversion failed: {e}") from e
+
+
+def _process_long_running_tool(a2a_part, event: Event) -> None:
+  """Processes long-running tool metadata for an A2A part.
+
+  Args:
+    a2a_part: The A2A part to potentially mark as long-running.
+    event: The ADK event containing long-running tool information.
+  """
+  if (
+      isinstance(a2a_part.root, DataPart)
+      and event.long_running_tool_ids
+      and a2a_part.root.metadata.get(
+          _get_adk_metadata_key(A2A_DATA_PART_METADATA_TYPE_KEY)
+      )
+      == A2A_DATA_PART_METADATA_TYPE_FUNCTION_CALL
+      and a2a_part.root.metadata.get("id") in event.long_running_tool_ids
+  ):
+    a2a_part.root.metadata[_get_adk_metadata_key("is_long_running")] = True
+
+
+@working_in_progress
+def convert_event_to_a2a_status_message(
+    event: Event, invocation_context: InvocationContext
+) -> Optional[Message]:
+  """Converts an ADK event to an A2A message.
+
+  Args:
+    event: The ADK event to convert.
+    invocation_context: The invocation context.
+
+  Returns:
+    An A2A Message if the event has content, None otherwise.
+
+  Raises:
+    ValueError: If required parameters are invalid.
+  """
+  if not event:
+    raise ValueError("Event cannot be None")
+  if not invocation_context:
+    raise ValueError("Invocation context cannot be None")
+
+  if not event.content or not event.content.parts:
+    return None
+
+  try:
+    a2a_parts = []
+    for part in event.content.parts:
+      a2a_part = convert_genai_part_to_a2a_part(part)
+      if a2a_part:
+        a2a_parts.append(a2a_part)
+        _process_long_running_tool(a2a_part, event)
+
+    if a2a_parts:
+      return Message(
+          messageId=str(uuid.uuid4()), role=Role.agent, parts=a2a_parts
+      )
+
+  except Exception as e:
+    logger.error("Failed to convert event to status message: %s", e)
+    raise
+
+  return None
+
+
+def _create_error_status_event(
+    event: Event, invocation_context: InvocationContext
+) -> TaskStatusUpdateEvent:
+  """Creates a TaskStatusUpdateEvent for error scenarios.
+
+  Args:
+    event: The ADK event containing error information.
+    invocation_context: The invocation context.
+
+  Returns:
+    A TaskStatusUpdateEvent with FAILED state.
+  """
+  error_message = getattr(event, "error_message", None) or DEFAULT_ERROR_MESSAGE
+
+  return TaskStatusUpdateEvent(
+      taskId=str(uuid.uuid4()),
+      contextId=invocation_context.session.id,
+      final=False,
+      metadata=_get_context_metadata(event, invocation_context),
+      status=TaskStatus(
+          state=TaskState.failed,
+          message=Message(
+              messageId=str(uuid.uuid4()),
+              role=Role.agent,
+              parts=[TextPart(text=error_message)],
+          ),
+          timestamp=datetime.datetime.now().isoformat(),
+      ),
+  )
+
+
+def _create_running_status_event(
+    message: Message, invocation_context: InvocationContext, event: Event
+) -> TaskStatusUpdateEvent:
+  """Creates a TaskStatusUpdateEvent for running scenarios.
+
+  Args:
+    message: The A2A message to include.
+    invocation_context: The invocation context.
+    event: The ADK event.
+
+  Returns:
+    A TaskStatusUpdateEvent with RUNNING state.
+  """
+  return TaskStatusUpdateEvent(
+      taskId=str(uuid.uuid4()),
+      contextId=invocation_context.session.id,
+      final=False,
+      status=TaskStatus(
+          state=TaskState.working,
+          message=message,
+          timestamp=datetime.datetime.now().isoformat(),
+      ),
+      metadata=_get_context_metadata(event, invocation_context),
+  )
+
+
+@working_in_progress
+def convert_event_to_a2a_events(
+    event: Event, invocation_context: InvocationContext
+) -> List[A2AEvent]:
+  """Converts a GenAI event to a list of A2A events.
+
+  Args:
+    event: The ADK event to convert.
+    invocation_context: The invocation context.
+
+  Returns:
+    A list of A2A events representing the converted ADK event.
+
+  Raises:
+    ValueError: If required parameters are invalid.
+  """
+  if not event:
+    raise ValueError("Event cannot be None")
+  if not invocation_context:
+    raise ValueError("Invocation context cannot be None")
+
+  a2a_events = []
+
+  try:
+    # Handle artifact deltas
+    if event.actions.artifact_delta:
+      for filename, version in event.actions.artifact_delta.items():
+        artifact_event = _convert_artifact_to_a2a_events(
+            event, invocation_context, filename, version
+        )
+        a2a_events.append(artifact_event)
+
+    # Handle error scenarios
+    if event.error_code:
+      error_event = _create_error_status_event(event, invocation_context)
+      a2a_events.append(error_event)
+
+    # Handle regular message content
+    message = convert_event_to_a2a_status_message(event, invocation_context)
+    if message:
+      running_event = _create_running_status_event(
+          message, invocation_context, event
+      )
+      a2a_events.append(running_event)
+
+  except Exception as e:
+    logger.error("Failed to convert event to A2A events: %s", e)
+    raise
+
+  return a2a_events

{google_adk-1.4.1 → google_adk-1.4.2}/src/google/adk/a2a/converters/part_converter.py

@@ -23,6 +23,8 @@ import logging
 import sys
 from typing import Optional
 
+from .utils import _get_adk_metadata_key
+
 try:
   from a2a import types as a2a_types
 except ImportError as e:
@@ -84,7 +86,7 @@ def convert_a2a_part_to_genai_part(
     # logic accordinlgy
     if part.metadata and A2A_DATA_PART_METADATA_TYPE_KEY in part.metadata:
       if (
-          part.metadata[A2A_DATA_PART_METADATA_TYPE_KEY]
+          part.metadata[_get_adk_metadata_key(A2A_DATA_PART_METADATA_TYPE_KEY)]
           == A2A_DATA_PART_METADATA_TYPE_FUNCTION_CALL
       ):
         return genai_types.Part(
@@ -93,7 +95,7 @@ def convert_a2a_part_to_genai_part(
             )
         )
       if (
-          part.metadata[A2A_DATA_PART_METADATA_TYPE_KEY]
+          part.metadata[_get_adk_metadata_key(A2A_DATA_PART_METADATA_TYPE_KEY)]
           == A2A_DATA_PART_METADATA_TYPE_FUNCTION_RESPONSE
       ):
         return genai_types.Part(

google_adk-1.4.2/src/google/adk/a2a/converters/utils.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 __future__ import annotations
+
+ADK_METADATA_KEY_PREFIX = "adk_"
+
+
+def _get_adk_metadata_key(key: str) -> str:
+  """Gets the A2A event metadata key for the given key.
+
+  Args:
+    key: The metadata key to prefix.
+
+  Returns:
+    The prefixed metadata key.
+
+  Raises:
+    ValueError: If key is empty or None.
+  """
+  if not key:
+    raise ValueError("Metadata key cannot be empty or None")
+  return f"{ADK_METADATA_KEY_PREFIX}{key}"

{google_adk-1.4.1 → google_adk-1.4.2}/src/google/adk/sessions/vertex_ai_session_service.py

@@ -14,6 +14,7 @@
 from __future__ import annotations
 
 import asyncio
+import json
 import logging
 import re
 from typing import Any
@@ -87,6 +88,7 @@ class VertexAiSessionService(BaseSessionService):
         path=f'reasoningEngines/{reasoning_engine_id}/sessions',
         request_dict=session_json_dict,
     )
+    api_response = _convert_api_response(api_response)
     logger.info(f'Create Session response {api_response}')
 
     session_id = api_response['name'].split('/')[-3]
@@ -100,6 +102,7 @@ class VertexAiSessionService(BaseSessionService):
           path=f'operations/{operation_id}',
           request_dict={},
       )
+      lro_response = _convert_api_response(lro_response)
 
       if lro_response.get('done', None):
         break
@@ -118,6 +121,7 @@ class VertexAiSessionService(BaseSessionService):
         path=f'reasoningEngines/{reasoning_engine_id}/sessions/{session_id}',
         request_dict={},
     )
+    get_session_api_response = _convert_api_response(get_session_api_response)
 
     update_timestamp = isoparse(
         get_session_api_response['updateTime']
@@ -149,6 +153,7 @@ class VertexAiSessionService(BaseSessionService):
         path=f'reasoningEngines/{reasoning_engine_id}/sessions/{session_id}',
         request_dict={},
     )
+    get_session_api_response = _convert_api_response(get_session_api_response)
 
     session_id = get_session_api_response['name'].split('/')[-1]
     update_timestamp = isoparse(
@@ -167,9 +172,12 @@ class VertexAiSessionService(BaseSessionService):
         path=f'reasoningEngines/{reasoning_engine_id}/sessions/{session_id}/events',
         request_dict={},
     )
+    list_events_api_response = _convert_api_response(list_events_api_response)
 
     # Handles empty response case
-    if list_events_api_response.get('httpHeaders', None):
+    if not list_events_api_response or list_events_api_response.get(
+        'httpHeaders', None
+    ):
       return session
 
     session.events += [
@@ -226,9 +234,10 @@ class VertexAiSessionService(BaseSessionService):
         path=path,
         request_dict={},
     )
+    api_response = _convert_api_response(api_response)
 
     # Handles empty response case
-    if api_response.get('httpHeaders', None):
+    if not api_response or api_response.get('httpHeaders', None):
       return ListSessionsResponse()
 
     sessions = []
@@ -303,6 +312,13 @@ class VertexAiSessionService(BaseSessionService):
     return client._api_client
 
 
+def _convert_api_response(api_response):
+  """Converts the API response to a JSON object based on the type."""
+  if hasattr(api_response, 'body'):
+    return json.loads(api_response.body)
+  return api_response
+
+
 def _convert_event_to_json(event: Event) -> Dict[str, Any]:
   metadata_json = {
       'partial': event.partial,

{google_adk-1.4.1 → google_adk-1.4.2}/src/google/adk/tools/bigquery/bigquery_credentials.py

@@ -21,9 +21,10 @@ from typing import Optional
 from fastapi.openapi.models import OAuth2
 from fastapi.openapi.models import OAuthFlowAuthorizationCode
 from fastapi.openapi.models import OAuthFlows
+import google.auth.credentials
 from google.auth.exceptions import RefreshError
 from google.auth.transport.requests import Request
-from google.oauth2.credentials import Credentials
+import google.oauth2.credentials
 from pydantic import BaseModel
 from pydantic import model_validator
 
@@ -40,26 +41,35 @@ BIGQUERY_DEFAULT_SCOPE = ["https://www.googleapis.com/auth/bigquery"]
 
 @experimental
 class BigQueryCredentialsConfig(BaseModel):
-  """Configuration for Google API tools. (Experimental)"""
+  """Configuration for Google API tools (Experimental).
+
+  Please do not use this in production, as it may be deprecated later.
+  """
 
   # Configure the model to allow arbitrary types like Credentials
   model_config = {"arbitrary_types_allowed": True}
 
-  credentials: Optional[Credentials] = None
-  """the existing oauth credentials to use. If set,this credential will be used
+  credentials: Optional[google.auth.credentials.Credentials] = None
+  """The existing auth credentials to use. If set, this credential will be used
   for every end user, end users don't need to be involved in the oauthflow. This
   field is mutually exclusive with client_id, client_secret and scopes.
   Don't set this field unless you are sure this credential has the permission to
   access every end user's data.
 
-  Example usage: when the agent is deployed in Google Cloud environment and
+  Example usage 1: When the agent is deployed in Google Cloud environment and
   the service account (used as application default credentials) has access to
   all the required BigQuery resource. Setting this credential to allow user to
   access the BigQuery resource without end users going through oauth flow.
 
-  To get application default credential: `google.auth.default(...)`. See more
+  To get application default credential, use: `google.auth.default(...)`. See more
   details in https://cloud.google.com/docs/authentication/application-default-credentials.
 
+  Example usage 2: When the agent wants to access the user's BigQuery resources
+  using the service account key credentials.
+
+  To load service account key credentials, use: `google.auth.load_credentials_from_file(...)`.
+  See more details in https://cloud.google.com/iam/docs/service-account-creds#user-managed-keys.
+
   When the deployed environment cannot provide a pre-existing credential,
   consider setting below client_id, client_secret and scope for end users to go
   through oauth flow, so that agent can access the user data.
@@ -86,7 +96,9 @@ class BigQueryCredentialsConfig(BaseModel):
           " client_id/client_secret/scopes."
       )
 
-    if self.credentials:
+    if self.credentials and isinstance(
+        self.credentials, google.oauth2.credentials.Credentials
+    ):
       self.client_id = self.credentials.client_id
       self.client_secret = self.credentials.client_secret
       self.scopes = self.credentials.scopes
@@ -115,7 +127,7 @@ class BigQueryCredentialsManager:
 
   async def get_valid_credentials(
       self, tool_context: ToolContext
-  ) -> Optional[Credentials]:
+  ) -> Optional[google.auth.credentials.Credentials]:
     """Get valid credentials, handling refresh and OAuth flow as needed.
 
     Args:
@@ -127,7 +139,7 @@ class BigQueryCredentialsManager:
     # First, try to get credentials from the tool context
     creds_json = tool_context.state.get(BIGQUERY_TOKEN_CACHE_KEY, None)
     creds = (
-        Credentials.from_authorized_user_info(
+        google.oauth2.credentials.Credentials.from_authorized_user_info(
             json.loads(creds_json), self.credentials_config.scopes
         )
         if creds_json
@@ -138,6 +150,11 @@ class BigQueryCredentialsManager:
     if not creds:
       creds = self.credentials_config.credentials
 
+    # If non-oauth credentials are provided then use them as is. This helps
+    # in flows such as service account keys
+    if creds and not isinstance(creds, google.oauth2.credentials.Credentials):
+      return creds
+
     # Check if we have valid credentials
     if creds and creds.valid:
       return creds
@@ -159,7 +176,7 @@ class BigQueryCredentialsManager:
 
   async def _perform_oauth_flow(
       self, tool_context: ToolContext
-  ) -> Optional[Credentials]:
+  ) -> Optional[google.oauth2.credentials.Credentials]:
     """Perform OAuth flow to get new credentials.
 
     Args:
@@ -199,7 +216,7 @@ class BigQueryCredentialsManager:
 
     if auth_response:
       # OAuth flow completed, create credentials
-      creds = Credentials(
+      creds = google.oauth2.credentials.Credentials(
           token=auth_response.oauth2.access_token,
           refresh_token=auth_response.oauth2.refresh_token,
           token_uri=auth_scheme.flows.authorizationCode.tokenUrl,

{google_adk-1.4.1 → google_adk-1.4.2}/src/google/adk/tools/bigquery/bigquery_tool.py

@@ -19,7 +19,7 @@ from typing import Any
 from typing import Callable
 from typing import Optional
 
-from google.oauth2.credentials import Credentials
+from google.auth.credentials import Credentials
 from typing_extensions import override
 
 from ...utils.feature_decorator import experimental

{google_adk-1.4.1 → google_adk-1.4.2}/src/google/adk/tools/bigquery/client.py

@@ -15,8 +15,8 @@
 from __future__ import annotations
 
 import google.api_core.client_info
+from google.auth.credentials import Credentials
 from google.cloud import bigquery
-from google.oauth2.credentials import Credentials
 
 from ... import version
 

{google_adk-1.4.1 → google_adk-1.4.2}/src/google/adk/tools/bigquery/metadata_tool.py

@@ -12,8 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from google.auth.credentials import Credentials
 from google.cloud import bigquery
-from google.oauth2.credentials import Credentials
 
 from . import client
 

{google_adk-1.4.1 → google_adk-1.4.2}/src/google/adk/tools/bigquery/query_tool.py

@@ -16,8 +16,8 @@ import functools
 import types
 from typing import Callable
 
+from google.auth.credentials import Credentials
 from google.cloud import bigquery
-from google.oauth2.credentials import Credentials
 
 from . import client
 from .config import BigQueryToolConfig

{google_adk-1.4.1 → google_adk-1.4.2}/src/google/adk/version.py

@@ -13,4 +13,4 @@
 # limitations under the License.
 
 # version: major.minor.patch
-__version__ = "1.4.1"
+__version__ = "1.4.2"