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

google/adk/a2a/converters/request_converter.py

@@ -31,42 +31,24 @@ except ImportError as e:
 from google.genai import types as genai_types
 
 from ...runners import RunConfig
-from ...utils.feature_decorator import working_in_progress
+from ...utils.feature_decorator import experimental
 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:
+def _get_user_id(request: RequestContext) -> str:
   # Get user from call context if available (auth is enabled on a2a server)
-  if request.call_context and request.call_context.user:
+  if (
+      request.call_context
+      and request.call_context.user
+      and request.call_context.user.user_name
+  ):
     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 context id
+  return f'A2A_USER_{request.context_id}'
 
-  # 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
+@experimental
 def convert_a2a_request_to_adk_run_args(
     request: RequestContext,
 ) -> dict[str, Any]:
@@ -74,11 +56,9 @@ def convert_a2a_request_to_adk_run_args(
   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,
+      'user_id': _get_user_id(request),
+      'session_id': request.context_id,
       'new_message': genai_types.Content(
           role='user',
           parts=[

google/adk/a2a/converters/utils.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 
 ADK_METADATA_KEY_PREFIX = "adk_"
 ADK_CONTEXT_ID_PREFIX = "ADK"
+ADK_CONTEXT_ID_SEPARATOR = "/"
 
 
 def _get_adk_metadata_key(key: str) -> str:
@@ -45,8 +46,17 @@ def _to_a2a_context_id(app_name: str, user_id: str, session_id: str) -> str:
 
   Returns:
     The A2A context id.
+
+  Raises:
+    ValueError: If any of the input parameters are empty or None.
   """
-  return [ADK_CONTEXT_ID_PREFIX, app_name, user_id, session_id].join("$")
+  if not all([app_name, user_id, session_id]):
+    raise ValueError(
+        "All parameters (app_name, user_id, session_id) must be non-empty"
+    )
+  return ADK_CONTEXT_ID_SEPARATOR.join(
+      [ADK_CONTEXT_ID_PREFIX, app_name, user_id, session_id]
+  )
 
 
 def _from_a2a_context_id(context_id: str) -> tuple[str, str, str]:
@@ -64,8 +74,16 @@ def _from_a2a_context_id(context_id: str) -> tuple[str, str, str]:
   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
+  try:
+    parts = context_id.split(ADK_CONTEXT_ID_SEPARATOR)
+    if len(parts) != 4:
+      return None, None, None
+
+    prefix, app_name, user_id, session_id = parts
+    if prefix == ADK_CONTEXT_ID_PREFIX and app_name and user_id and session_id:
+      return app_name, user_id, session_id
+  except ValueError:
+    # Handle any split errors gracefully
+    pass
 
   return None, None, None

google/adk/a2a/executor/__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/a2a/executor/a2a_agent_executor.py

@@ -0,0 +1,260 @@
+# 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 datetime import datetime
+from datetime import timezone
+import inspect
+import logging
+from typing import Any
+from typing import Awaitable
+from typing import Callable
+from typing import Optional
+import uuid
+
+try:
+  from a2a.server.agent_execution import AgentExecutor
+  from a2a.server.agent_execution.context import RequestContext
+  from a2a.server.events.event_queue import EventQueue
+  from a2a.types import Message
+  from a2a.types import Role
+  from a2a.types import TaskState
+  from a2a.types import TaskStatus
+  from a2a.types import TaskStatusUpdateEvent
+  from a2a.types import TextPart
+
+except ImportError as e:
+  import sys
+
+  if sys.version_info < (3, 10):
+    raise ImportError(
+        'A2A requires Python 3.10 or above. Please upgrade your Python version.'
+    ) from e
+  else:
+    raise e
+from google.adk.runners import Runner
+from pydantic import BaseModel
+from typing_extensions import override
+
+from ...utils.feature_decorator import experimental
+from ..converters.event_converter import convert_event_to_a2a_events
+from ..converters.request_converter import convert_a2a_request_to_adk_run_args
+from ..converters.utils import _get_adk_metadata_key
+from .task_result_aggregator import TaskResultAggregator
+
+logger = logging.getLogger('google_adk.' + __name__)
+
+
+@experimental
+class A2aAgentExecutorConfig(BaseModel):
+  """Configuration for the A2aAgentExecutor."""
+
+  pass
+
+
+@experimental
+class A2aAgentExecutor(AgentExecutor):
+  """An AgentExecutor that runs an ADK Agent against an A2A request and
+  publishes updates to an event queue.
+  """
+
+  def __init__(
+      self,
+      *,
+      runner: Runner | Callable[..., Runner | Awaitable[Runner]],
+      config: Optional[A2aAgentExecutorConfig] = None,
+  ):
+    super().__init__()
+    self._runner = runner
+    self._config = config
+
+  async def _resolve_runner(self) -> Runner:
+    """Resolve the runner, handling cases where it's a callable that returns a Runner."""
+    # If already resolved and cached, return it
+    if isinstance(self._runner, Runner):
+      return self._runner
+    if callable(self._runner):
+      # Call the function to get the runner
+      result = self._runner()
+
+      # Handle async callables
+      if inspect.iscoroutine(result):
+        resolved_runner = await result
+      else:
+        resolved_runner = result
+
+      # Cache the resolved runner for future calls
+      self._runner = resolved_runner
+      return resolved_runner
+
+    raise TypeError(
+        'Runner must be a Runner instance or a callable that returns a'
+        f' Runner, got {type(self._runner)}'
+    )
+
+  @override
+  async def cancel(self, context: RequestContext, event_queue: EventQueue):
+    """Cancel the execution."""
+    # TODO: Implement proper cancellation logic if needed
+    raise NotImplementedError('Cancellation is not supported')
+
+  @override
+  async def execute(
+      self,
+      context: RequestContext,
+      event_queue: EventQueue,
+  ):
+    """Executes an A2A request and publishes updates to the event queue
+    specified. It runs as following:
+    * Takes the input from the A2A request
+    * Convert the input to ADK input content, and runs the ADK agent
+    * Collects output events of the underlying ADK Agent
+    * Converts the ADK output events into A2A task updates
+    * Publishes the updates back to A2A server via event queue
+    """
+    if not context.message:
+      raise ValueError('A2A request must have a message')
+
+    # for new task, create a task submitted event
+    if not context.current_task:
+      await event_queue.enqueue_event(
+          TaskStatusUpdateEvent(
+              taskId=context.task_id,
+              status=TaskStatus(
+                  state=TaskState.submitted,
+                  message=context.message,
+                  timestamp=datetime.now(timezone.utc).isoformat(),
+              ),
+              contextId=context.context_id,
+              final=False,
+          )
+      )
+
+    # Handle the request and publish updates to the event queue
+    try:
+      await self._handle_request(context, event_queue)
+    except Exception as e:
+      logger.error('Error handling A2A request: %s', e, exc_info=True)
+      # Publish failure event
+      try:
+        await event_queue.enqueue_event(
+            TaskStatusUpdateEvent(
+                taskId=context.task_id,
+                status=TaskStatus(
+                    state=TaskState.failed,
+                    timestamp=datetime.now(timezone.utc).isoformat(),
+                    message=Message(
+                        messageId=str(uuid.uuid4()),
+                        role=Role.agent,
+                        parts=[TextPart(text=str(e))],
+                    ),
+                ),
+                contextId=context.context_id,
+                final=True,
+            )
+        )
+      except Exception as enqueue_error:
+        logger.error(
+            'Failed to publish failure event: %s', enqueue_error, exc_info=True
+        )
+
+  async def _handle_request(
+      self,
+      context: RequestContext,
+      event_queue: EventQueue,
+  ):
+    # Resolve the runner instance
+    runner = await self._resolve_runner()
+
+    # Convert the a2a request to ADK run args
+    run_args = convert_a2a_request_to_adk_run_args(context)
+
+    # ensure the session exists
+    session = await self._prepare_session(context, run_args, runner)
+
+    # create invocation context
+    invocation_context = runner._new_invocation_context(
+        session=session,
+        new_message=run_args['new_message'],
+        run_config=run_args['run_config'],
+    )
+
+    # publish the task working event
+    await event_queue.enqueue_event(
+        TaskStatusUpdateEvent(
+            taskId=context.task_id,
+            status=TaskStatus(
+                state=TaskState.working,
+                timestamp=datetime.now(timezone.utc).isoformat(),
+            ),
+            contextId=context.context_id,
+            final=False,
+            metadata={
+                _get_adk_metadata_key('app_name'): runner.app_name,
+                _get_adk_metadata_key('user_id'): run_args['user_id'],
+                _get_adk_metadata_key('session_id'): run_args['session_id'],
+            },
+        )
+    )
+
+    task_result_aggregator = TaskResultAggregator()
+    async for adk_event in runner.run_async(**run_args):
+      for a2a_event in convert_event_to_a2a_events(
+          adk_event, invocation_context, context.task_id, context.context_id
+      ):
+        task_result_aggregator.process_event(a2a_event)
+        await event_queue.enqueue_event(a2a_event)
+
+    # publish the task result event - this is final
+    await event_queue.enqueue_event(
+        TaskStatusUpdateEvent(
+            taskId=context.task_id,
+            status=TaskStatus(
+                state=(
+                    task_result_aggregator.task_state
+                    if task_result_aggregator.task_state != TaskState.working
+                    else TaskState.completed
+                ),
+                timestamp=datetime.now(timezone.utc).isoformat(),
+                message=task_result_aggregator.task_status_message,
+            ),
+            contextId=context.context_id,
+            final=True,
+        )
+    )
+
+  async def _prepare_session(
+      self, context: RequestContext, run_args: dict[str, Any], runner: Runner
+  ):
+
+    session_id = run_args['session_id']
+    # create a new session if not exists
+    user_id = run_args['user_id']
+    session = await runner.session_service.get_session(
+        app_name=runner.app_name,
+        user_id=user_id,
+        session_id=session_id,
+    )
+    if session is None:
+      session = await runner.session_service.create_session(
+          app_name=runner.app_name,
+          user_id=user_id,
+          state={},
+          session_id=session_id,
+      )
+      # Update run_args with the new session_id
+      run_args['session_id'] = session.id
+
+    return session

google/adk/a2a/executor/task_result_aggregator.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
+
+from a2a.server.events import Event
+from a2a.types import Message
+from a2a.types import TaskState
+from a2a.types import TaskStatusUpdateEvent
+
+from ...utils.feature_decorator import experimental
+
+
+@experimental
+class TaskResultAggregator:
+  """Aggregates the task status updates and provides the final task state."""
+
+  def __init__(self):
+    self._task_state = TaskState.working
+    self._task_status_message = None
+
+  def process_event(self, event: Event):
+    """Process an event from the agent run and detect signals about the task status.
+    Priority of task state:
+    - failed
+    - auth_required
+    - input_required
+    - working
+    """
+    if isinstance(event, TaskStatusUpdateEvent):
+      if event.status.state == TaskState.failed:
+        self._task_state = TaskState.failed
+        self._task_status_message = event.status.message
+      elif (
+          event.status.state == TaskState.auth_required
+          and self._task_state != TaskState.failed
+      ):
+        self._task_state = TaskState.auth_required
+        self._task_status_message = event.status.message
+      elif (
+          event.status.state == TaskState.input_required
+          and self._task_state
+          not in (TaskState.failed, TaskState.auth_required)
+      ):
+        self._task_state = TaskState.input_required
+        self._task_status_message = event.status.message
+      # final state is already recorded and make sure the intermediate state is
+      # always working because other state may terminate the event aggregation
+      # in a2a request handler
+      elif self._task_state == TaskState.working:
+        self._task_status_message = event.status.message
+      event.status.state = TaskState.working
+
+  @property
+  def task_state(self) -> TaskState:
+    return self._task_state
+
+  @property
+  def task_status_message(self) -> Message | None:
+    return self._task_status_message

google/adk/a2a/logs/__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.