google-adk 1.4.1__py3-none-any.whl → 1.5.0__py3-none-any.whl

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/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/a2a/converters/request_converter.py

@@ -0,0 +1,90 @@
+# 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 sys
+from typing import Any
+
+try:
+  from a2a.server.agent_execution import RequestContext
+except ImportError as e:
+  if sys.version_info < (3, 10):
+    raise ImportError(
+        'A2A Tool requires Python 3.10 or above. Please upgrade your Python'
+        ' version.'
+    ) from e
+  else:
+    raise e
+
+from google.genai import types as genai_types
+
+from ...runners import RunConfig
+from ...utils.feature_decorator import working_in_progress
+from .part_converter import convert_a2a_part_to_genai_part
+from .utils import _from_a2a_context_id
+from .utils import _get_adk_metadata_key
+
+
+def _get_user_id(request: RequestContext, user_id_from_context: str) -> str:
+  # Get user from call context if available (auth is enabled on a2a server)
+  if request.call_context and request.call_context.user:
+    return request.call_context.user.user_name
+
+  # Get user from context id if available
+  if user_id_from_context:
+    return user_id_from_context
+
+  # Get user from message metadata if available (client is an ADK agent)
+  if request.message.metadata:
+    user_id = request.message.metadata.get(_get_adk_metadata_key('user_id'))
+    if user_id:
+      return f'ADK_USER_{user_id}'
+
+  # Get user from task if available (client is a an ADK agent)
+  if request.current_task:
+    user_id = request.current_task.metadata.get(
+        _get_adk_metadata_key('user_id')
+    )
+    if user_id:
+      return f'ADK_USER_{user_id}'
+  return (
+      f'temp_user_{request.task_id}'
+      if request.task_id
+      else f'TEMP_USER_{request.message.messageId}'
+  )
+
+
+@working_in_progress
+def convert_a2a_request_to_adk_run_args(
+    request: RequestContext,
+) -> dict[str, Any]:
+
+  if not request.message:
+    raise ValueError('Request message cannot be None')
+
+  _, user_id, session_id = _from_a2a_context_id(request.context_id)
+
+  return {
+      'user_id': _get_user_id(request, user_id),
+      'session_id': session_id,
+      'new_message': genai_types.Content(
+          role='user',
+          parts=[
+              convert_a2a_part_to_genai_part(part)
+              for part in request.message.parts
+          ],
+      ),
+      'run_config': RunConfig(),
+  }

google/adk/a2a/converters/utils.py

@@ -0,0 +1,71 @@
+# 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_"
+ADK_CONTEXT_ID_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}"
+
+
+def _to_a2a_context_id(app_name: str, user_id: str, session_id: str) -> str:
+  """Converts app name, user id and session id to an A2A context id.
+
+  Args:
+    app_name: The app name.
+    user_id: The user id.
+    session_id: The session id.
+
+  Returns:
+    The A2A context id.
+  """
+  return [ADK_CONTEXT_ID_PREFIX, app_name, user_id, session_id].join("$")
+
+
+def _from_a2a_context_id(context_id: str) -> tuple[str, str, str]:
+  """Converts an A2A context id to app name, user id and session id.
+  if context_id is None, return None, None, None
+  if context_id is not None, but not in the format of
+  ADK$app_name$user_id$session_id, return None, None, None
+
+  Args:
+    context_id: The A2A context id.
+
+  Returns:
+    The app name, user id and session id.
+  """
+  if not context_id:
+    return None, None, None
+
+  prefix, app_name, user_id, session_id = context_id.split("$")
+  if prefix == "ADK" and app_name and user_id and session_id:
+    return app_name, user_id, session_id
+
+  return None, None, None

google/adk/agents/llm_agent.py

@@ -161,10 +161,12 @@ class LlmAgent(BaseAgent):
   # LLM-based agent transfer configs - End
 
   include_contents: Literal['default', 'none'] = 'default'
-  """Whether to include contents in the model request.
+  """Controls content inclusion in model requests.
 
-  When set to 'none', the model request will not include any contents, such as
-  user messages, tool results, etc.
+  Options:
+      default: Model receives relevant conversation history
+      none: Model receives no prior history, operates solely on current
+            instruction and input
   """
 
   # Controlled input/output configurations - Start

google/adk/artifacts/gcs_artifact_service.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 """An artifact service implementation using Google Cloud Storage (GCS)."""
+from __future__ import annotations
 
 import logging
 from typing import Optional
@@ -151,7 +152,7 @@ class GcsArtifactService(BaseArtifactService):
         self.bucket, prefix=session_prefix
     )
     for blob in session_blobs:
-      _, _, _, filename, _ = blob.name.split("/")
+      *_, filename, _ = blob.name.split("/")
       filenames.add(filename)
 
     user_namespace_prefix = f"{app_name}/{user_id}/user/"
@@ -159,7 +160,7 @@ class GcsArtifactService(BaseArtifactService):
         self.bucket, prefix=user_namespace_prefix
     )
     for blob in user_namespace_blobs:
-      _, _, _, filename, _ = blob.name.split("/")
+      *_, filename, _ = blob.name.split("/")
       filenames.add(filename)
 
     return sorted(list(filenames))

google/adk/auth/auth_tool.py

@@ -31,12 +31,12 @@ class AuthConfig(BaseModelWithConfig):
 
   auth_scheme: AuthScheme
   """The auth scheme used to collect credentials"""
-  raw_auth_credential: AuthCredential = None
+  raw_auth_credential: Optional[AuthCredential] = None
   """The raw auth credential used to collect credentials. The raw auth
   credentials are used in some auth scheme that needs to exchange auth
   credentials. e.g. OAuth2 and OIDC. For other auth scheme, it could be None.
   """
-  exchanged_auth_credential: AuthCredential = None
+  exchanged_auth_credential: Optional[AuthCredential] = None
   """The exchanged auth credential used to collect credentials. adk and client
   will work together to fill it. For those auth scheme that doesn't need to
   exchange auth credentials, e.g. API key, service account etc. It's filled by