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

google/adk/a2a/converters/event_converter.py

@@ -24,13 +24,11 @@ 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 Part as A2APart
 from a2a.types import Role
 from a2a.types import Task
-from a2a.types import TaskArtifactUpdateEvent
 from a2a.types import TaskState
 from a2a.types import TaskStatus
 from a2a.types import TaskStatusUpdateEvent
@@ -145,81 +143,6 @@ def _create_artifact_id(
   return ARTIFACT_ID_SEPARATOR.join(components)
 
 
-def _convert_artifact_to_a2a_events(
-    event: Event,
-    invocation_context: InvocationContext,
-    filename: str,
-    version: int,
-    task_id: Optional[str] = None,
-    context_id: Optional[str] = None,
-) -> 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.
-    task_id: Optional task ID to use for generated events. If not provided, new UUIDs will be generated.
-
-  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=task_id,
-        append=False,
-        contextId=context_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: A2APart, event: Event) -> None:
   """Processes long-running tool metadata for an A2A part.
 
@@ -268,7 +191,11 @@ def convert_a2a_task_to_event(
   try:
     # Extract message from task status or history
     message = None
-    if a2a_task.status and a2a_task.status.message:
+    if a2a_task.artifacts:
+      message = Message(
+          messageId="", role=Role.agent, parts=a2a_task.artifacts[-1].parts
+      )
+    elif a2a_task.status and a2a_task.status.message:
       message = a2a_task.status.message
     elif a2a_task.history:
       message = a2a_task.history[-1]
@@ -573,13 +500,6 @@ def convert_event_to_a2a_events(
   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, task_id, context_id
-        )
-        a2a_events.append(artifact_event)
 
     # Handle error scenarios
     if event.error_code:

google/adk/a2a/executor/a2a_agent_executor.py

@@ -28,8 +28,10 @@ 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 Artifact
   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
@@ -218,22 +220,49 @@ class A2aAgentExecutor(AgentExecutor):
         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,
-        )
-    )
+    if (
+        task_result_aggregator.task_state == TaskState.working
+        and task_result_aggregator.task_status_message is not None
+        and task_result_aggregator.task_status_message.parts
+    ):
+      # if task is still working properly, publish the artifact update event as
+      # the final result according to a2a protocol.
+      await event_queue.enqueue_event(
+          TaskArtifactUpdateEvent(
+              taskId=context.task_id,
+              lastChunk=True,
+              contextId=context.context_id,
+              artifact=Artifact(
+                  artifactId=str(uuid.uuid4()),
+                  parts=task_result_aggregator.task_status_message.parts,
+              ),
+          )
+      )
+      # public the final status update event
+      await event_queue.enqueue_event(
+          TaskStatusUpdateEvent(
+              taskId=context.task_id,
+              status=TaskStatus(
+                  state=TaskState.completed,
+                  timestamp=datetime.now(timezone.utc).isoformat(),
+              ),
+              contextId=context.context_id,
+              final=True,
+          )
+      )
+    else:
+      await event_queue.enqueue_event(
+          TaskStatusUpdateEvent(
+              taskId=context.task_id,
+              status=TaskStatus(
+                  state=task_result_aggregator.task_state,
+                  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

google/adk/agents/__init__.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 from .base_agent import BaseAgent
+from .invocation_context import InvocationContext
 from .live_request_queue import LiveRequest
 from .live_request_queue import LiveRequestQueue
 from .llm_agent import Agent
@@ -29,4 +30,8 @@ __all__ = [
     'LoopAgent',
     'ParallelAgent',
     'SequentialAgent',
+    'InvocationContext',
+    'LiveRequest',
+    'LiveRequestQueue',
+    'RunConfig',
 ]

google/adk/agents/agent_config.py

@@ -0,0 +1,46 @@
+# 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 Union
+
+from pydantic import RootModel
+
+from ..utils.feature_decorator import working_in_progress
+from .llm_agent import LlmAgentConfig
+from .loop_agent import LoopAgentConfig
+from .parallel_agent import ParallelAgentConfig
+from .sequential_agent import SequentialAgentConfig
+
+# A discriminated union of all possible agent configurations.
+ConfigsUnion = Union[
+    LlmAgentConfig,
+    LoopAgentConfig,
+    ParallelAgentConfig,
+    SequentialAgentConfig,
+]
+
+
+# Use a RootModel to represent the agent directly at the top level.
+# The `discriminator` is applied to the union within the RootModel.
+@working_in_progress("AgentConfig is not ready for use.")
+class AgentConfig(RootModel[ConfigsUnion]):
+  """The config for the YAML schema to create an agent."""
+
+  class Config:
+    # Pydantic v2 requires this for discriminated unions on RootModel
+    # This tells the model to look at the 'agent_class' field of the input
+    # data to decide which model from the `ConfigsUnion` to use.
+    discriminator = "agent_class"

google/adk/agents/base_agent.py

@@ -19,9 +19,13 @@ from typing import Any
 from typing import AsyncGenerator
 from typing import Awaitable
 from typing import Callable
+from typing import Dict
 from typing import final
+from typing import List
+from typing import Literal
 from typing import Mapping
 from typing import Optional
+from typing import Type
 from typing import TYPE_CHECKING
 from typing import TypeVar
 from typing import Union
@@ -32,11 +36,14 @@ from pydantic import BaseModel
 from pydantic import ConfigDict
 from pydantic import Field
 from pydantic import field_validator
+from pydantic import model_validator
 from typing_extensions import override
 from typing_extensions import TypeAlias
 
 from ..events.event import Event
+from ..utils.feature_decorator import working_in_progress
 from .callback_context import CallbackContext
+from .common_configs import CodeConfig
 
 if TYPE_CHECKING:
   from .invocation_context import InvocationContext
@@ -223,11 +230,18 @@ class BaseAgent(BaseModel):
     """
     with tracer.start_as_current_span(f'agent_run [{self.name}]'):
       ctx = self._create_invocation_context(parent_context)
-      # TODO(hangfei): support before/after_agent_callback
+
+      if event := await self.__handle_before_agent_callback(ctx):
+        yield event
+      if ctx.end_invocation:
+        return
 
       async for event in self._run_live_impl(ctx):
         yield event
 
+      if event := await self.__handle_after_agent_callback(ctx):
+        yield event
+
   async def _run_async_impl(
       self, ctx: InvocationContext
   ) -> AsyncGenerator[Event, None]:
@@ -331,73 +345,99 @@ class BaseAgent(BaseModel):
   ) -> Optional[Event]:
     """Runs the before_agent_callback if it exists.
 
+    Args:
+      ctx: InvocationContext, the invocation context for this agent.
+
     Returns:
       Optional[Event]: an event if callback provides content or changed state.
     """
-    ret_event = None
-
-    if not self.canonical_before_agent_callbacks:
-      return ret_event
-
     callback_context = CallbackContext(ctx)
 
-    for callback in self.canonical_before_agent_callbacks:
-      before_agent_callback_content = callback(
-          callback_context=callback_context
-      )
-      if inspect.isawaitable(before_agent_callback_content):
-        before_agent_callback_content = await before_agent_callback_content
-      if before_agent_callback_content:
-        ret_event = Event(
-            invocation_id=ctx.invocation_id,
-            author=self.name,
-            branch=ctx.branch,
-            content=before_agent_callback_content,
-            actions=callback_context._event_actions,
+    # Run callbacks from the plugins.
+    before_agent_callback_content = (
+        await ctx.plugin_manager.run_before_agent_callback(
+            agent=self, callback_context=callback_context
         )
-        ctx.end_invocation = True
-        return ret_event
+    )
 
-    if callback_context.state.has_delta():
+    # If no overrides are provided from the plugins, further run the canonical
+    # callbacks.
+    if (
+        not before_agent_callback_content
+        and self.canonical_before_agent_callbacks
+    ):
+      for callback in self.canonical_before_agent_callbacks:
+        before_agent_callback_content = callback(
+            callback_context=callback_context
+        )
+        if inspect.isawaitable(before_agent_callback_content):
+          before_agent_callback_content = await before_agent_callback_content
+        if before_agent_callback_content:
+          break
+
+    # Process the override content if exists, and further process the state
+    # change if exists.
+    if before_agent_callback_content:
       ret_event = Event(
+          invocation_id=ctx.invocation_id,
+          author=self.name,
+          branch=ctx.branch,
+          content=before_agent_callback_content,
+          actions=callback_context._event_actions,
+      )
+      ctx.end_invocation = True
+      return ret_event
+
+    if callback_context.state.has_delta():
+      return Event(
           invocation_id=ctx.invocation_id,
           author=self.name,
           branch=ctx.branch,
           actions=callback_context._event_actions,
       )
 
-    return ret_event
+    return None
 
   async def __handle_after_agent_callback(
       self, invocation_context: InvocationContext
   ) -> Optional[Event]:
     """Runs the after_agent_callback if it exists.
 
+    Args:
+      invocation_context: InvocationContext, the invocation context for this
+        agent.
+
     Returns:
       Optional[Event]: an event if callback provides content or changed state.
     """
-    ret_event = None
-
-    if not self.canonical_after_agent_callbacks:
-      return ret_event
 
     callback_context = CallbackContext(invocation_context)
 
-    for callback in self.canonical_after_agent_callbacks:
-      after_agent_callback_content = callback(callback_context=callback_context)
-      if inspect.isawaitable(after_agent_callback_content):
-        after_agent_callback_content = await after_agent_callback_content
-      if after_agent_callback_content:
-        ret_event = Event(
-            invocation_id=invocation_context.invocation_id,
-            author=self.name,
-            branch=invocation_context.branch,
-            content=after_agent_callback_content,
-            actions=callback_context._event_actions,
+    # Run callbacks from the plugins.
+    after_agent_callback_content = (
+        await invocation_context.plugin_manager.run_after_agent_callback(
+            agent=self, callback_context=callback_context
         )
-        return ret_event
+    )
 
-    if callback_context.state.has_delta():
+    # If no overrides are provided from the plugins, further run the canonical
+    # callbacks.
+    if (
+        not after_agent_callback_content
+        and self.canonical_after_agent_callbacks
+    ):
+      for callback in self.canonical_after_agent_callbacks:
+        after_agent_callback_content = callback(
+            callback_context=callback_context
+        )
+        if inspect.isawaitable(after_agent_callback_content):
+          after_agent_callback_content = await after_agent_callback_content
+        if after_agent_callback_content:
+          break
+
+    # Process the override content if exists, and further process the state
+    # change if exists.
+    if after_agent_callback_content:
       ret_event = Event(
           invocation_id=invocation_context.invocation_id,
           author=self.name,
@@ -405,8 +445,17 @@ class BaseAgent(BaseModel):
           content=after_agent_callback_content,
           actions=callback_context._event_actions,
       )
+      return ret_event
 
-    return ret_event
+    if callback_context.state.has_delta():
+      return Event(
+          invocation_id=invocation_context.invocation_id,
+          author=self.name,
+          branch=invocation_context.branch,
+          content=after_agent_callback_content,
+          actions=callback_context._event_actions,
+      )
+    return None
 
   @override
   def model_post_init(self, __context: Any) -> None:
@@ -439,3 +488,147 @@ class BaseAgent(BaseModel):
         )
       sub_agent.parent_agent = self
     return self
+
+  @classmethod
+  @working_in_progress('BaseAgent.from_config is not ready for use.')
+  def from_config(
+      cls: Type[SelfAgent],
+      config: BaseAgentConfig,
+      config_abs_path: str,
+  ) -> SelfAgent:
+    """Creates an agent from a config.
+
+    This method converts fields in a config to the corresponding
+    fields in an agent.
+
+    Child classes should re-implement this method to support loading from their
+    custom config types.
+
+    Args:
+      config: The config to create the agent from.
+
+    Returns:
+      The created agent.
+    """
+    from .config_agent_utils import build_sub_agent
+    from .config_agent_utils import resolve_callbacks
+
+    kwargs: Dict[str, Any] = {
+        'name': config.name,
+        'description': config.description,
+    }
+    if config.sub_agents:
+      sub_agents = []
+      for sub_agent_config in config.sub_agents:
+        sub_agent = build_sub_agent(
+            sub_agent_config, config_abs_path.rsplit('/', 1)[0]
+        )
+        sub_agents.append(sub_agent)
+      kwargs['sub_agents'] = sub_agents
+
+    if config.before_agent_callbacks:
+      kwargs['before_agent_callback'] = resolve_callbacks(
+          config.before_agent_callbacks
+      )
+    if config.after_agent_callbacks:
+      kwargs['after_agent_callback'] = resolve_callbacks(
+          config.after_agent_callbacks
+      )
+    return cls(**kwargs)
+
+
+class SubAgentConfig(BaseModel):
+  """The config for a sub-agent."""
+
+  model_config = ConfigDict(extra='forbid')
+
+  config: Optional[str] = None
+  """The YAML config file path of the sub-agent.
+
+  Only one of `config` or `code` can be set.
+
+  Example:
+
+    ```
+    sub_agents:
+      - config: search_agent.yaml
+      - config: my_library/my_custom_agent.yaml
+    ```
+  """
+
+  code: Optional[str] = None
+  """The agent instance defined in the code.
+
+  Only one of `config` or `code` can be set.
+
+  Example:
+
+    For the following agent defined in Python code:
+
+    ```
+    # my_library/custom_agents.py
+    from google.adk.agents import LlmAgent
+
+    my_custom_agent = LlmAgent(
+        name="my_custom_agent",
+        instruction="You are a helpful custom agent.",
+        model="gemini-2.0-flash",
+    )
+    ```
+
+    The yaml config should be:
+
+    ```
+    sub_agents:
+      - code: my_library.custom_agents.my_custom_agent
+    ```
+  """
+
+  @model_validator(mode='after')
+  def validate_exactly_one_field(self):
+    code_provided = self.code is not None
+    config_provided = self.config is not None
+
+    if code_provided and config_provided:
+      raise ValueError('Only one of code or config should be provided')
+    if not code_provided and not config_provided:
+      raise ValueError('Exactly one of code or config must be provided')
+
+    return self
+
+
+@working_in_progress('BaseAgentConfig is not ready for use.')
+class BaseAgentConfig(BaseModel):
+  """The config for the YAML schema of a BaseAgent.
+
+  Do not use this class directly. It's the base class for all agent configs.
+  """
+
+  model_config = ConfigDict(extra='forbid')
+
+  agent_class: Literal['BaseAgent'] = 'BaseAgent'
+  """Required. The class of the agent. The value is used to differentiate
+  among different agent classes."""
+
+  name: str
+  """Required. The name of the agent."""
+
+  description: str = ''
+  """Optional. The description of the agent."""
+
+  sub_agents: Optional[List[SubAgentConfig]] = None
+  """Optional. The sub-agents of the agent."""
+
+  before_agent_callbacks: Optional[List[CodeConfig]] = None
+  """Optional. The before_agent_callbacks of the agent.
+
+  Example:
+
+    ```
+    before_agent_callbacks:
+      - name: my_library.security_callbacks.before_agent_callback
+    ```
+  """
+
+  after_agent_callbacks: Optional[List[CodeConfig]] = None
+  """Optional. The after_agent_callbacks of the agent."""

google/adk/agents/callback_context.py

@@ -24,6 +24,8 @@ from .readonly_context import ReadonlyContext
 if TYPE_CHECKING:
   from google.genai import types
 
+  from ..auth.auth_credential import AuthCredential
+  from ..auth.auth_tool import AuthConfig
   from ..events.event_actions import EventActions
   from ..sessions.state import State
   from .invocation_context import InvocationContext
@@ -105,3 +107,42 @@ class CallbackContext(ReadonlyContext):
     )
     self._event_actions.artifact_delta[filename] = version
     return version
+
+  async def list_artifacts(self) -> list[str]:
+    """Lists the filenames of the artifacts attached to the current session."""
+    if self._invocation_context.artifact_service is None:
+      raise ValueError("Artifact service is not initialized.")
+    return await self._invocation_context.artifact_service.list_artifact_keys(
+        app_name=self._invocation_context.app_name,
+        user_id=self._invocation_context.user_id,
+        session_id=self._invocation_context.session.id,
+    )
+
+  async def save_credential(self, auth_config: AuthConfig) -> None:
+    """Saves a credential to the credential service.
+
+    Args:
+      auth_config: The authentication configuration containing the credential.
+    """
+    if self._invocation_context.credential_service is None:
+      raise ValueError("Credential service is not initialized.")
+    await self._invocation_context.credential_service.save_credential(
+        auth_config, self
+    )
+
+  async def load_credential(
+      self, auth_config: AuthConfig
+  ) -> Optional[AuthCredential]:
+    """Loads a credential from the credential service.
+
+    Args:
+      auth_config: The authentication configuration for the credential.
+
+    Returns:
+      The loaded credential, or None if not found.
+    """
+    if self._invocation_context.credential_service is None:
+      raise ValueError("Credential service is not initialized.")
+    return await self._invocation_context.credential_service.load_credential(
+        auth_config, self
+    )