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

google/adk/agents/llm_agent.py

@@ -14,14 +14,17 @@
 
 from __future__ import annotations
 
+import importlib
 import inspect
 import logging
 from typing import Any
 from typing import AsyncGenerator
 from typing import Awaitable
 from typing import Callable
+from typing import List
 from typing import Literal
 from typing import Optional
+from typing import Type
 from typing import Union
 
 from google.genai import types
@@ -48,8 +51,11 @@ from ..tools.base_tool import BaseTool
 from ..tools.base_toolset import BaseToolset
 from ..tools.function_tool import FunctionTool
 from ..tools.tool_context import ToolContext
+from ..utils.feature_decorator import working_in_progress
 from .base_agent import BaseAgent
+from .base_agent import BaseAgentConfig
 from .callback_context import CallbackContext
+from .common_configs import CodeConfig
 from .invocation_context import InvocationContext
 from .readonly_context import ReadonlyContext
 
@@ -164,9 +170,9 @@ class LlmAgent(BaseAgent):
   """Controls content inclusion in model requests.
 
   Options:
-      default: Model receives relevant conversation history
-      none: Model receives no prior history, operates solely on current
-            instruction and input
+    default: Model receives relevant conversation history
+    none: Model receives no prior history, operates solely on current
+    instruction and input
   """
 
   # Controlled input/output configurations - Start
@@ -175,8 +181,9 @@ class LlmAgent(BaseAgent):
   output_schema: Optional[type[BaseModel]] = None
   """The output schema when agent replies.
 
-  NOTE: when this is set, agent can ONLY reply and CANNOT use any tools, such as
-  function tools, RAGs, agent transfer, etc.
+  NOTE:
+    When this is set, agent can ONLY reply and CANNOT use any tools, such as
+    function tools, RAGs, agent transfer, etc.
   """
   output_key: Optional[str] = None
   """The key in session state to store the output of the agent.
@@ -191,9 +198,9 @@ class LlmAgent(BaseAgent):
   planner: Optional[BasePlanner] = None
   """Instructs the agent to make a plan and execute it step by step.
 
-  NOTE: to use model's built-in thinking features, set the `thinking_config`
-  field in `google.adk.planners.built_in_planner`.
-
+  NOTE:
+    To use model's built-in thinking features, set the `thinking_config`
+    field in `google.adk.planners.built_in_planner`.
   """
 
   code_executor: Optional[BaseCodeExecutor] = None
@@ -202,7 +209,8 @@ class LlmAgent(BaseAgent):
 
   Check out available code executions in `google.adk.code_executor` package.
 
-  NOTE: to use model's built-in code executor, use the `BuiltInCodeExecutor`.
+  NOTE:
+    To use model's built-in code executor, use the `BuiltInCodeExecutor`.
   """
   # Advance features - End
 
@@ -516,5 +524,178 @@ class LlmAgent(BaseAgent):
       )
     return generate_content_config
 
+  @classmethod
+  @working_in_progress('LlmAgent._resolve_tools is not ready for use.')
+  def _resolve_tools(cls, tools_config: list[CodeConfig]) -> list[Any]:
+    """Resolve tools from configuration.
+
+    Args:
+      tools_config: List of tool configurations (CodeConfig objects).
+
+    Returns:
+      List of resolved tool objects.
+    """
+
+    resolved_tools = []
+    for tool_config in tools_config:
+      if '.' not in tool_config.name:
+        module = importlib.import_module('google.adk.tools')
+        obj = getattr(module, tool_config.name)
+        if isinstance(obj, ToolUnion):
+          resolved_tools.append(obj)
+        else:
+          raise ValueError(
+              f'Invalid tool name: {tool_config.name} is not a built-in tool.'
+          )
+      else:
+        from .config_agent_utils import resolve_code_reference
+
+        resolved_tools.append(resolve_code_reference(tool_config))
+
+    return resolved_tools
+
+  @classmethod
+  @override
+  @working_in_progress('LlmAgent.from_config is not ready for use.')
+  def from_config(
+      cls: Type[LlmAgent],
+      config: LlmAgentConfig,
+      config_abs_path: str,
+  ) -> LlmAgent:
+    from .config_agent_utils import resolve_callbacks
+
+    agent = super().from_config(config, config_abs_path)
+    if config.model:
+      agent.model = config.model
+    if config.instruction:
+      agent.instruction = config.instruction
+    if config.disallow_transfer_to_parent:
+      agent.disallow_transfer_to_parent = config.disallow_transfer_to_parent
+    if config.disallow_transfer_to_peers:
+      agent.disallow_transfer_to_peers = config.disallow_transfer_to_peers
+    if config.include_contents != 'default':
+      agent.include_contents = config.include_contents
+    if config.output_key:
+      agent.output_key = config.output_key
+    if config.tools:
+      agent.tools = cls._resolve_tools(config.tools)
+    if config.before_model_callbacks:
+      agent.before_model_callback = resolve_callbacks(
+          config.before_model_callbacks
+      )
+    if config.after_model_callbacks:
+      agent.after_model_callback = resolve_callbacks(
+          config.after_model_callbacks
+      )
+    if config.before_tool_callbacks:
+      agent.before_tool_callback = resolve_callbacks(
+          config.before_tool_callbacks
+      )
+    if config.after_tool_callbacks:
+      agent.after_tool_callback = resolve_callbacks(config.after_tool_callbacks)
+    return agent
+
 
 Agent: TypeAlias = LlmAgent
+
+
+class LlmAgentConfig(BaseAgentConfig):
+  """The config for the YAML schema of a LlmAgent."""
+
+  agent_class: Literal['LlmAgent', ''] = 'LlmAgent'
+  """The value is used to uniquely identify the LlmAgent class. If it is
+  empty, it is by default an LlmAgent."""
+
+  model: Optional[str] = None
+  """Optional. LlmAgent.model. If not set, the model will be inherited from
+  the ancestor."""
+
+  instruction: str
+  """Required. LlmAgent.instruction."""
+
+  disallow_transfer_to_parent: Optional[bool] = None
+  """Optional. LlmAgent.disallow_transfer_to_parent."""
+
+  disallow_transfer_to_peers: Optional[bool] = None
+  """Optional. LlmAgent.disallow_transfer_to_peers."""
+
+  output_key: Optional[str] = None
+  """Optional. LlmAgent.output_key."""
+
+  include_contents: Literal['default', 'none'] = 'default'
+  """Optional. LlmAgent.include_contents."""
+
+  tools: Optional[list[CodeConfig]] = None
+  """Optional. LlmAgent.tools.
+
+  Examples:
+
+    For ADK built-in tools in `google.adk.tools` package, they can be referenced
+    directly with the name:
+
+      ```
+      tools:
+        - name: google_search
+        - name: load_memory
+      ```
+
+    For user-defined tools, they can be referenced with fully qualified name:
+
+      ```
+      tools:
+        - name: my_library.my_tools.my_tool
+      ```
+
+    For tools that needs to be created via functions:
+
+      ```
+      tools:
+        - name: my_library.my_tools.create_tool
+          args:
+            - name: param1
+              value: value1
+            - name: param2
+              value: value2
+      ```
+
+    For more advanced tools, instead of specifying arguments in config, it's
+    recommended to define them in Python files and reference them. E.g.,
+
+      ```
+      # tools.py
+      my_mcp_toolset = MCPToolset(
+          connection_params=StdioServerParameters(
+              command="npx",
+              args=["-y", "@notionhq/notion-mcp-server"],
+              env={"OPENAPI_MCP_HEADERS": NOTION_HEADERS},
+          )
+      )
+      ```
+
+    Then, reference the toolset in config:
+
+    ```
+    tools:
+      - name: tools.my_mcp_toolset
+    ```
+  """
+
+  before_model_callbacks: Optional[List[CodeConfig]] = None
+  """Optional. LlmAgent.before_model_callbacks.
+
+  Example:
+
+    ```
+    before_model_callbacks:
+      - name: my_library.callbacks.before_model_callback
+    ```
+  """
+
+  after_model_callbacks: Optional[List[CodeConfig]] = None
+  """Optional. LlmAgent.after_model_callbacks."""
+
+  before_tool_callbacks: Optional[List[CodeConfig]] = None
+  """Optional. LlmAgent.before_tool_callbacks."""
+
+  after_tool_callbacks: Optional[List[CodeConfig]] = None
+  """Optional. LlmAgent.after_tool_callbacks."""

google/adk/agents/loop_agent.py

@@ -16,14 +16,20 @@
 
 from __future__ import annotations
 
+from typing import Any
 from typing import AsyncGenerator
+from typing import Dict
+from typing import Literal
 from typing import Optional
+from typing import Type
 
 from typing_extensions import override
 
 from ..agents.invocation_context import InvocationContext
 from ..events.event import Event
+from ..utils.feature_decorator import working_in_progress
 from .base_agent import BaseAgent
+from .base_agent import BaseAgentConfig
 
 
 class LoopAgent(BaseAgent):
@@ -60,3 +66,26 @@ class LoopAgent(BaseAgent):
   ) -> AsyncGenerator[Event, None]:
     raise NotImplementedError('This is not supported yet for LoopAgent.')
     yield  # AsyncGenerator requires having at least one yield statement
+
+  @classmethod
+  @override
+  @working_in_progress('LoopAgent.from_config is not ready for use.')
+  def from_config(
+      cls: Type[LoopAgent],
+      config: LoopAgentConfig,
+      config_abs_path: str,
+  ) -> LoopAgent:
+    agent = super().from_config(config, config_abs_path)
+    if config.max_iterations:
+      agent.max_iterations = config.max_iterations
+    return agent
+
+
+@working_in_progress('LoopAgentConfig is not ready for use.')
+class LoopAgentConfig(BaseAgentConfig):
+  """The config for the YAML schema of a LoopAgent."""
+
+  agent_class: Literal['LoopAgent'] = 'LoopAgent'
+
+  max_iterations: Optional[int] = None
+  """Optional. LoopAgent.max_iterations."""

google/adk/agents/parallel_agent.py

@@ -18,9 +18,13 @@ from __future__ import annotations
 
 import asyncio
 from typing import AsyncGenerator
+from typing import Literal
+from typing import Type
 
 from typing_extensions import override
 
+from ..agents.base_agent import BaseAgentConfig
+from ..agents.base_agent import working_in_progress
 from ..agents.invocation_context import InvocationContext
 from ..events.event import Event
 from .base_agent import BaseAgent
@@ -33,9 +37,9 @@ def _create_branch_ctx_for_sub_agent(
 ) -> InvocationContext:
   """Create isolated branch for every sub-agent."""
   invocation_context = invocation_context.model_copy()
-  branch_suffix = f"{agent.name}.{sub_agent.name}"
+  branch_suffix = f'{agent.name}.{sub_agent.name}'
   invocation_context.branch = (
-      f"{invocation_context.branch}.{branch_suffix}"
+      f'{invocation_context.branch}.{branch_suffix}'
       if invocation_context.branch
       else branch_suffix
   )
@@ -109,5 +113,22 @@ class ParallelAgent(BaseAgent):
   async def _run_live_impl(
       self, ctx: InvocationContext
   ) -> AsyncGenerator[Event, None]:
-    raise NotImplementedError("This is not supported yet for ParallelAgent.")
+    raise NotImplementedError('This is not supported yet for ParallelAgent.')
     yield  # AsyncGenerator requires having at least one yield statement
+
+  @classmethod
+  @override
+  @working_in_progress('ParallelAgent.from_config is not ready for use.')
+  def from_config(
+      cls: Type[ParallelAgent],
+      config: ParallelAgentConfig,
+      config_abs_path: str,
+  ) -> ParallelAgent:
+    return super().from_config(config, config_abs_path)
+
+
+@working_in_progress('ParallelAgentConfig is not ready for use.')
+class ParallelAgentConfig(BaseAgentConfig):
+  """The config for the YAML schema of a ParallelAgent."""
+
+  agent_class: Literal['ParallelAgent'] = 'ParallelAgent'

google/adk/agents/remote_a2a_agent.py

@@ -26,7 +26,7 @@ import uuid
 
 try:
   from a2a.client import A2AClient
-  from a2a.client.client import A2ACardResolver  # Import A2ACardResolver
+  from a2a.client.client import A2ACardResolver
   from a2a.types import AgentCard
   from a2a.types import Message as A2AMessage
   from a2a.types import MessageSendParams as A2AMessageSendParams
@@ -35,7 +35,6 @@ try:
   from a2a.types import SendMessageRequest
   from a2a.types import SendMessageSuccessResponse
   from a2a.types import Task as A2ATask
-
 except ImportError as e:
   import sys
 
@@ -46,6 +45,12 @@ except ImportError as e:
   else:
     raise e
 
+try:
+  from a2a.utils.constants import AGENT_CARD_WELL_KNOWN_PATH
+except ImportError:
+  # Fallback for older versions of a2a-sdk.
+  AGENT_CARD_WELL_KNOWN_PATH = "/.well-known/agent.json"
+
 from google.genai import types as genai_types
 import httpx
 
@@ -63,11 +68,18 @@ from ..flows.llm_flows.functions import find_matching_function_call
 from ..utils.feature_decorator import experimental
 from .base_agent import BaseAgent
 
+__all__ = [
+    "A2AClientError",
+    "AGENT_CARD_WELL_KNOWN_PATH",
+    "AgentCardResolutionError",
+    "RemoteA2aAgent",
+]
+
+
 # Constants
 A2A_METADATA_PREFIX = "a2a:"
 DEFAULT_TIMEOUT = 600.0
 
-
 logger = logging.getLogger("google_adk." + __name__)
 
 

google/adk/agents/sequential_agent.py

@@ -17,9 +17,13 @@
 from __future__ import annotations
 
 from typing import AsyncGenerator
+from typing import Literal
+from typing import Type
 
 from typing_extensions import override
 
+from ..agents.base_agent import BaseAgentConfig
+from ..agents.base_agent import working_in_progress
 from ..agents.invocation_context import InvocationContext
 from ..events.event import Event
 from .base_agent import BaseAgent
@@ -60,7 +64,7 @@ class SequentialAgent(BaseAgent):
         Signals that the model has successfully completed the user's question
         or task.
         """
-        return "Task completion signaled."
+        return 'Task completion signaled.'
 
       if isinstance(sub_agent, LlmAgent):
         # Use function name to dedupe.
@@ -74,3 +78,20 @@ class SequentialAgent(BaseAgent):
     for sub_agent in self.sub_agents:
       async for event in sub_agent.run_live(ctx):
         yield event
+
+  @classmethod
+  @override
+  @working_in_progress('SequentialAgent.from_config is not ready for use.')
+  def from_config(
+      cls: Type[SequentialAgent],
+      config: SequentialAgentConfig,
+      config_abs_path: str,
+  ) -> SequentialAgent:
+    return super().from_config(config, config_abs_path)
+
+
+@working_in_progress('SequentialAgentConfig is not ready for use.')
+class SequentialAgentConfig(BaseAgentConfig):
+  """The config for the YAML schema of a SequentialAgent."""
+
+  agent_class: Literal['SequentialAgent'] = 'SequentialAgent'

google/adk/artifacts/gcs_artifact_service.py

@@ -12,7 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""An artifact service implementation using Google Cloud Storage (GCS)."""
+"""An artifact service implementation using Google Cloud Storage (GCS).
+
+The blob name format used depends on whether the filename has a user namespace:
+  - For files with user namespace (starting with "user:"):
+    {app_name}/{user_id}/user/{filename}/{version}
+  - For regular session-scoped files:
+    {app_name}/{user_id}/{session_id}/{filename}/{version}
+"""
 from __future__ import annotations
 
 import logging
@@ -187,10 +194,25 @@ class GcsArtifactService(BaseArtifactService):
   async def list_versions(
       self, *, app_name: str, user_id: str, session_id: str, filename: str
   ) -> list[int]:
+    """Lists all available versions of an artifact.
+
+    This method retrieves all versions of a specific artifact by querying GCS blobs
+    that match the constructed blob name prefix.
+
+    Args:
+        app_name: The name of the application.
+        user_id: The ID of the user who owns the artifact.
+        session_id: The ID of the session (ignored for user-namespaced files).
+        filename: The name of the artifact file.
+
+    Returns:
+        A list of version numbers (integers) available for the specified artifact.
+        Returns an empty list if no versions are found.
+    """
     prefix = self._get_blob_name(app_name, user_id, session_id, filename, "")
     blobs = self.storage_client.list_blobs(self.bucket, prefix=prefix)
     versions = []
     for blob in blobs:
-      _, _, _, _, version = blob.name.split("/")
+      *_, version = blob.name.split("/")
       versions.append(int(version))
     return versions

google/adk/auth/auth_handler.py

@@ -30,9 +30,9 @@ if TYPE_CHECKING:
 try:
   from authlib.integrations.requests_client import OAuth2Session
 
-  AUTHLIB_AVIALABLE = True
+  AUTHLIB_AVAILABLE = True
 except ImportError:
-  AUTHLIB_AVIALABLE = False
+  AUTHLIB_AVAILABLE = False
 
 
 class AuthHandler:
@@ -146,7 +146,7 @@ class AuthHandler:
         ValueError: If the authorization endpoint is not configured in the auth
             scheme.
     """
-    if not AUTHLIB_AVIALABLE:
+    if not AUTHLIB_AVAILABLE:
       return (
           self.auth_config.raw_auth_credential.model_copy(deep=True)
           if self.auth_config.raw_auth_credential

google/adk/auth/credential_manager.py

@@ -16,7 +16,7 @@ from __future__ import annotations
 
 from typing import Optional
 
-from ..tools.tool_context import ToolContext
+from ..agents.callback_context import CallbackContext
 from ..utils.feature_decorator import experimental
 from .auth_credential import AuthCredential
 from .auth_credential import AuthCredentialTypes
@@ -63,7 +63,7 @@ class CredentialManager:
       )
 
       # Load and prepare credential
-      credential = await manager.load_auth_credential(tool_context)
+      credential = await manager.load_auth_credential(callback_context)
       ```
   """
 
@@ -100,11 +100,11 @@ class CredentialManager:
     """
     self._exchanger_registry.register(credential_type, exchanger_instance)
 
-  async def request_credential(self, tool_context: ToolContext) -> None:
-    tool_context.request_credential(self._auth_config)
+  async def request_credential(self, callback_context: CallbackContext) -> None:
+    callback_context.request_credential(self._auth_config)
 
   async def get_auth_credential(
-      self, tool_context: ToolContext
+      self, callback_context: CallbackContext
   ) -> Optional[AuthCredential]:
     """Load and prepare authentication credential through a structured workflow."""
 
@@ -116,14 +116,14 @@ class CredentialManager:
       return self._auth_config.raw_auth_credential
 
     # Step 3: Try to load existing processed credential
-    credential = await self._load_existing_credential(tool_context)
+    credential = await self._load_existing_credential(callback_context)
 
     # Step 4: If no existing credential, load from auth response
     # TODO instead of load from auth response, we can store auth response in
     # credential service.
     was_from_auth_response = False
     if not credential:
-      credential = await self._load_from_auth_response(tool_context)
+      credential = await self._load_from_auth_response(callback_context)
       was_from_auth_response = True
 
     # Step 5: If still no credential available, return None
@@ -134,22 +134,23 @@ class CredentialManager:
     credential, was_exchanged = await self._exchange_credential(credential)
 
     # Step 7: Refresh credential if expired
+    was_refreshed = False
     if not was_exchanged:
       credential, was_refreshed = await self._refresh_credential(credential)
 
     # Step 8: Save credential if it was modified
     if was_from_auth_response or was_exchanged or was_refreshed:
-      await self._save_credential(tool_context, credential)
+      await self._save_credential(callback_context, credential)
 
     return credential
 
   async def _load_existing_credential(
-      self, tool_context: ToolContext
+      self, callback_context: CallbackContext
   ) -> Optional[AuthCredential]:
     """Load existing credential from credential service or cached exchanged credential."""
 
     # Try loading from credential service first
-    credential = await self._load_from_credential_service(tool_context)
+    credential = await self._load_from_credential_service(callback_context)
     if credential:
       return credential
 
@@ -160,23 +161,21 @@ class CredentialManager:
     return None
 
   async def _load_from_credential_service(
-      self, tool_context: ToolContext
+      self, callback_context: CallbackContext
   ) -> Optional[AuthCredential]:
     """Load credential from credential service if available."""
-    credential_service = tool_context._invocation_context.credential_service
+    credential_service = callback_context._invocation_context.credential_service
     if credential_service:
       # Note: This should be made async in a future refactor
       # For now, assuming synchronous operation
-      return await credential_service.load_credential(
-          self._auth_config, tool_context
-      )
+      return await callback_context.load_credential(self._auth_config)
     return None
 
   async def _load_from_auth_response(
-      self, tool_context: ToolContext
+      self, callback_context: CallbackContext
   ) -> Optional[AuthCredential]:
-    """Load credential from auth response in tool context."""
-    return tool_context.get_auth_response(self._auth_config)
+    """Load credential from auth response in callback context."""
+    return callback_context.get_auth_response(self._auth_config)
 
   async def _exchange_credential(
       self, credential: AuthCredential
@@ -251,11 +250,12 @@ class CredentialManager:
         # Additional validation can be added here
 
   async def _save_credential(
-      self, tool_context: ToolContext, credential: AuthCredential
+      self, callback_context: CallbackContext, credential: AuthCredential
   ) -> None:
     """Save credential to credential service if available."""
-    credential_service = tool_context._invocation_context.credential_service
+    # Update the exchanged credential in config
+    self._auth_config.exchanged_auth_credential = credential
+
+    credential_service = callback_context._invocation_context.credential_service
     if credential_service:
-      # Update the exchanged credential in config
-      self._auth_config.exchanged_auth_credential = credential
-      await credential_service.save_credential(self._auth_config, tool_context)
+      await callback_context.save_credential(self._auth_config)

google/adk/auth/credential_service/base_credential_service.py

@@ -18,7 +18,7 @@ from abc import ABC
 from abc import abstractmethod
 from typing import Optional
 
-from ...tools.tool_context import ToolContext
+from ...agents.callback_context import CallbackContext
 from ...utils.feature_decorator import experimental
 from ..auth_credential import AuthCredential
 from ..auth_tool import AuthConfig
@@ -33,10 +33,10 @@ class BaseCredentialService(ABC):
   async def load_credential(
       self,
       auth_config: AuthConfig,
-      tool_context: ToolContext,
+      callback_context: CallbackContext,
   ) -> Optional[AuthCredential]:
     """
-    Loads the credential by auth config and current tool context from the
+    Loads the credential by auth config and current callback context from the
     backend credential store.
 
     Args:
@@ -44,7 +44,7 @@ class BaseCredentialService(ABC):
         credential information. auth_config.get_credential_key will be used to
         build the key to load the credential.
 
-        tool_context: The context of the current invocation when the tool is
+        callback_context: The context of the current invocation when the tool is
         trying to load the credential.
 
     Returns:
@@ -56,7 +56,7 @@ class BaseCredentialService(ABC):
   async def save_credential(
       self,
       auth_config: AuthConfig,
-      tool_context: ToolContext,
+      callback_context: CallbackContext,
   ) -> None:
     """
     Saves the exchanged_auth_credential in auth config to the backend credential
@@ -67,7 +67,7 @@ class BaseCredentialService(ABC):
         credential information. auth_config.get_credential_key will be used to
         build the key to save the credential.
 
-        tool_context: The context of the current invocation when the tool is
+        callback_context: The context of the current invocation when the tool is
         trying to save the credential.
 
     Returns: