google-adk 0.5.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

google/adk/agents/base_agent.py

@@ -15,12 +15,14 @@
 from __future__ import annotations
 
 import inspect
-from typing import Any, Awaitable, Union
+from typing import Any
 from typing import AsyncGenerator
+from typing import Awaitable
 from typing import Callable
 from typing import final
 from typing import Optional
 from typing import TYPE_CHECKING
+from typing import Union
 
 from google.genai import types
 from opentelemetry import trace
@@ -29,6 +31,7 @@ from pydantic import ConfigDict
 from pydantic import Field
 from pydantic import field_validator
 from typing_extensions import override
+from typing_extensions import TypeAlias
 
 from ..events.event import Event
 from .callback_context import CallbackContext
@@ -38,14 +41,19 @@ if TYPE_CHECKING:
 
 tracer = trace.get_tracer('gcp.vertex.agent')
 
-BeforeAgentCallback = Callable[
+_SingleAgentCallback: TypeAlias = Callable[
     [CallbackContext],
     Union[Awaitable[Optional[types.Content]], Optional[types.Content]],
 ]
 
-AfterAgentCallback = Callable[
-    [CallbackContext],
-    Union[Awaitable[Optional[types.Content]], Optional[types.Content]],
+BeforeAgentCallback: TypeAlias = Union[
+    _SingleAgentCallback,
+    list[_SingleAgentCallback],
+]
+
+AfterAgentCallback: TypeAlias = Union[
+    _SingleAgentCallback,
+    list[_SingleAgentCallback],
 ]
 
 
@@ -85,7 +93,10 @@ class BaseAgent(BaseModel):
   """The sub-agents of this agent."""
 
   before_agent_callback: Optional[BeforeAgentCallback] = None
-  """Callback signature that is invoked before the agent run.
+  """Callback or list of callbacks to be invoked before the agent run.
+
+  When a list of callbacks is provided, the callbacks will be called in the
+  order they are listed until a callback does not return None.
 
   Args:
     callback_context: MUST be named 'callback_context' (enforced).
@@ -96,7 +107,10 @@ class BaseAgent(BaseModel):
       provided content will be returned to user.
   """
   after_agent_callback: Optional[AfterAgentCallback] = None
-  """Callback signature that is invoked after the agent run.
+  """Callback or list of callbacks to be invoked after the agent run.
+
+  When a list of callbacks is provided, the callbacks will be called in the
+  order they are listed until a callback does not return None.
 
   Args:
     callback_context: MUST be named 'callback_context' (enforced).
@@ -236,6 +250,30 @@ class BaseAgent(BaseModel):
       invocation_context.branch = f'{parent_context.branch}.{self.name}'
     return invocation_context
 
+  @property
+  def canonical_before_agent_callbacks(self) -> list[_SingleAgentCallback]:
+    """The resolved self.before_agent_callback field as a list of _SingleAgentCallback.
+
+    This method is only for use by Agent Development Kit.
+    """
+    if not self.before_agent_callback:
+      return []
+    if isinstance(self.before_agent_callback, list):
+      return self.before_agent_callback
+    return [self.before_agent_callback]
+
+  @property
+  def canonical_after_agent_callbacks(self) -> list[_SingleAgentCallback]:
+    """The resolved self.after_agent_callback field as a list of _SingleAgentCallback.
+
+    This method is only for use by Agent Development Kit.
+    """
+    if not self.after_agent_callback:
+      return []
+    if isinstance(self.after_agent_callback, list):
+      return self.after_agent_callback
+    return [self.after_agent_callback]
+
   async def __handle_before_agent_callback(
       self, ctx: InvocationContext
   ) -> Optional[Event]:
@@ -246,27 +284,27 @@ class BaseAgent(BaseModel):
     """
     ret_event = None
 
-    if not isinstance(self.before_agent_callback, Callable):
+    if not self.canonical_before_agent_callbacks:
       return ret_event
 
     callback_context = CallbackContext(ctx)
-    before_agent_callback_content = self.before_agent_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,
+    for callback in self.canonical_before_agent_callbacks:
+      before_agent_callback_content = callback(
+          callback_context=callback_context
       )
-      ctx.end_invocation = True
-      return ret_event
+      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,
+        )
+        ctx.end_invocation = True
+        return ret_event
 
     if callback_context.state.has_delta():
       ret_event = Event(
@@ -288,18 +326,26 @@ class BaseAgent(BaseModel):
     """
     ret_event = None
 
-    if not isinstance(self.after_agent_callback, Callable):
+    if not self.canonical_after_agent_callbacks:
       return ret_event
 
     callback_context = CallbackContext(invocation_context)
-    after_agent_callback_content = self.after_agent_callback(
-        callback_context=callback_context
-    )
 
-    if inspect.isawaitable(after_agent_callback_content):
-      after_agent_callback_content = await after_agent_callback_content
+    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,
+        )
+        return ret_event
 
-    if after_agent_callback_content or callback_context.state.has_delta():
+    if callback_context.state.has_delta():
       ret_event = Event(
           invocation_id=invocation_context.invocation_id,
           author=self.name,

google/adk/agents/callback_context.py

@@ -14,7 +14,8 @@
 
 from __future__ import annotations
 
-from typing import Optional, TYPE_CHECKING
+from typing import Optional
+from typing import TYPE_CHECKING
 
 from typing_extensions import override
 
@@ -60,11 +61,6 @@ class CallbackContext(ReadonlyContext):
     """
     return self._state
 
-  @property
-  def user_content(self) -> Optional[types.Content]:
-    """The user content that started this invocation. READONLY field."""
-    return self._invocation_context.user_content
-
   async def load_artifact(
       self, filename: str, version: Optional[int] = None
   ) -> Optional[types.Part]:

google/adk/agents/llm_agent.py

@@ -14,8 +14,15 @@
 
 from __future__ import annotations
 
+import inspect
 import logging
-from typing import Any, AsyncGenerator, Awaitable, Callable, Literal, Optional, Union
+from typing import Any
+from typing import AsyncGenerator
+from typing import Awaitable
+from typing import Callable
+from typing import Literal
+from typing import Optional
+from typing import Union
 
 from google.genai import types
 from pydantic import BaseModel
@@ -38,6 +45,7 @@ from ..models.llm_response import LlmResponse
 from ..models.registry import LLMRegistry
 from ..planners.base_planner import BasePlanner
 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 .base_agent import BaseAgent
@@ -45,7 +53,7 @@ from .callback_context import CallbackContext
 from .invocation_context import InvocationContext
 from .readonly_context import ReadonlyContext
 
-logger = logging.getLogger(__name__)
+logger = logging.getLogger('google_adk.' + __name__)
 
 _SingleBeforeModelCallback: TypeAlias = Callable[
     [CallbackContext, LlmRequest],
@@ -67,29 +75,43 @@ AfterModelCallback: TypeAlias = Union[
     list[_SingleAfterModelCallback],
 ]
 
-BeforeToolCallback: TypeAlias = Callable[
+_SingleBeforeToolCallback: TypeAlias = Callable[
     [BaseTool, dict[str, Any], ToolContext],
     Union[Awaitable[Optional[dict]], Optional[dict]],
 ]
-AfterToolCallback: TypeAlias = Callable[
+
+BeforeToolCallback: TypeAlias = Union[
+    _SingleBeforeToolCallback,
+    list[_SingleBeforeToolCallback],
+]
+
+_SingleAfterToolCallback: TypeAlias = Callable[
     [BaseTool, dict[str, Any], ToolContext, dict],
     Union[Awaitable[Optional[dict]], Optional[dict]],
 ]
 
-InstructionProvider: TypeAlias = Callable[[ReadonlyContext], str]
+AfterToolCallback: TypeAlias = Union[
+    _SingleAfterToolCallback,
+    list[_SingleAfterToolCallback],
+]
 
-ToolUnion: TypeAlias = Union[Callable, BaseTool]
+InstructionProvider: TypeAlias = Callable[
+    [ReadonlyContext], Union[str, Awaitable[str]]
+]
+
+ToolUnion: TypeAlias = Union[Callable, BaseTool, BaseToolset]
 ExamplesUnion = Union[list[Example], BaseExampleProvider]
 
 
-def _convert_tool_union_to_tool(
-    tool_union: ToolUnion,
-) -> BaseTool:
-  return (
-      tool_union
-      if isinstance(tool_union, BaseTool)
-      else FunctionTool(tool_union)
-  )
+async def _convert_tool_union_to_tools(
+    tool_union: ToolUnion, ctx: ReadonlyContext
+) -> list[BaseTool]:
+  if isinstance(tool_union, BaseTool):
+    return [tool_union]
+  if isinstance(tool_union, Callable):
+    return [FunctionTool(func=tool_union)]
+
+  return await tool_union.get_tools(ctx)
 
 
 class LlmAgent(BaseAgent):
@@ -128,7 +150,12 @@ class LlmAgent(BaseAgent):
 
   # LLM-based agent transfer configs - Start
   disallow_transfer_to_parent: bool = False
-  """Disallows LLM-controlled transferring to the parent agent."""
+  """Disallows LLM-controlled transferring to the parent agent.
+
+  NOTE: Setting this as True also prevents this agent to continue reply to the
+  end-user. This behavior prevents one-way transfer, in which end-user may be
+  stuck with one agent that cannot transfer to other agents in the agent tree.
+  """
   disallow_transfer_to_peers: bool = False
   """Disallows LLM-controlled transferring to the peer agents."""
   # LLM-based agent transfer configs - End
@@ -173,8 +200,7 @@ class LlmAgent(BaseAgent):
 
   Check out available code executions in `google.adk.code_executor` package.
 
-  NOTE: to use model's built-in code executor, don't set this field, add
-  `google.adk.tools.built_in_code_execution` to tools instead.
+  NOTE: to use model's built-in code executor, use the `BuiltInCodeExecutor`.
   """
   # Advance features - End
 
@@ -214,7 +240,10 @@ class LlmAgent(BaseAgent):
     will be ignored and the provided content will be returned to user.
   """
   before_tool_callback: Optional[BeforeToolCallback] = None
-  """Called before the tool is called.
+  """Callback or list of callbacks to be called before calling the tool.
+
+  When a list of callbacks is provided, the callbacks will be called in the
+  order they are listed until a callback does not return None.
 
   Args:
     tool: The tool to be called.
@@ -226,7 +255,10 @@ class LlmAgent(BaseAgent):
     the framework will skip calling the actual tool.
   """
   after_tool_callback: Optional[AfterToolCallback] = None
-  """Called after the tool is called.
+  """Callback or list of callbacks to be called after calling the tool.
+
+  When a list of callbacks is provided, the callbacks will be called in the
+  order they are listed until a callback does not return None.
 
   Args:
     tool: The tool to be called.
@@ -275,33 +307,65 @@ class LlmAgent(BaseAgent):
         ancestor_agent = ancestor_agent.parent_agent
       raise ValueError(f'No model found for {self.name}.')
 
-  def canonical_instruction(self, ctx: ReadonlyContext) -> str:
+  async def canonical_instruction(
+      self, ctx: ReadonlyContext
+  ) -> tuple[str, bool]:
     """The resolved self.instruction field to construct instruction for this agent.
 
     This method is only for use by Agent Development Kit.
+
+    Args:
+      ctx: The context to retrieve the session state.
+
+    Returns:
+      A tuple of (instruction, bypass_state_injection).
+      instruction: The resolved self.instruction field.
+      bypass_state_injection: Whether the instruction is based on
+      InstructionProvider.
     """
     if isinstance(self.instruction, str):
-      return self.instruction
+      return self.instruction, False
     else:
-      return self.instruction(ctx)
-
-  def canonical_global_instruction(self, ctx: ReadonlyContext) -> str:
+      instruction = self.instruction(ctx)
+      if inspect.isawaitable(instruction):
+        instruction = await instruction
+      return instruction, True
+
+  async def canonical_global_instruction(
+      self, ctx: ReadonlyContext
+  ) -> tuple[str, bool]:
     """The resolved self.instruction field to construct global instruction.
 
     This method is only for use by Agent Development Kit.
+
+    Args:
+      ctx: The context to retrieve the session state.
+
+    Returns:
+      A tuple of (instruction, bypass_state_injection).
+      instruction: The resolved self.global_instruction field.
+      bypass_state_injection: Whether the instruction is based on
+      InstructionProvider.
     """
     if isinstance(self.global_instruction, str):
-      return self.global_instruction
+      return self.global_instruction, False
     else:
-      return self.global_instruction(ctx)
+      global_instruction = self.global_instruction(ctx)
+      if inspect.isawaitable(global_instruction):
+        global_instruction = await global_instruction
+      return global_instruction, True
 
-  @property
-  def canonical_tools(self) -> list[BaseTool]:
-    """The resolved self.tools field as a list of BaseTool.
+  async def canonical_tools(
+      self, ctx: ReadonlyContext = None
+  ) -> list[BaseTool]:
+    """The resolved self.tools field as a list of BaseTool based on the context.
 
     This method is only for use by Agent Development Kit.
     """
-    return [_convert_tool_union_to_tool(tool) for tool in self.tools]
+    resolved_tools = []
+    for tool_union in self.tools:
+      resolved_tools.extend(await _convert_tool_union_to_tools(tool_union, ctx))
+    return resolved_tools
 
   @property
   def canonical_before_model_callbacks(
@@ -329,6 +393,34 @@ class LlmAgent(BaseAgent):
       return self.after_model_callback
     return [self.after_model_callback]
 
+  @property
+  def canonical_before_tool_callbacks(
+      self,
+  ) -> list[BeforeToolCallback]:
+    """The resolved self.before_tool_callback field as a list of BeforeToolCallback.
+
+    This method is only for use by Agent Development Kit.
+    """
+    if not self.before_tool_callback:
+      return []
+    if isinstance(self.before_tool_callback, list):
+      return self.before_tool_callback
+    return [self.before_tool_callback]
+
+  @property
+  def canonical_after_tool_callbacks(
+      self,
+  ) -> list[AfterToolCallback]:
+    """The resolved self.after_tool_callback field as a list of AfterToolCallback.
+
+    This method is only for use by Agent Development Kit.
+    """
+    if not self.after_tool_callback:
+      return []
+    if isinstance(self.after_tool_callback, list):
+      return self.after_tool_callback
+    return [self.after_tool_callback]
+
   @property
   def _llm_flow(self) -> BaseLlmFlow:
     if (

google/adk/agents/loop_agent.py

@@ -58,5 +58,5 @@ class LoopAgent(BaseAgent):
   async def _run_live_impl(
       self, ctx: InvocationContext
   ) -> AsyncGenerator[Event, None]:
-    raise NotImplementedError('The behavior for run_live is not defined yet.')
+    raise NotImplementedError('This is not supported yet for LoopAgent.')
     yield  # AsyncGenerator requires having at least one yield statement

google/adk/agents/parallel_agent.py

@@ -94,3 +94,10 @@ class ParallelAgent(BaseAgent):
     agent_runs = [agent.run_async(ctx) for agent in self.sub_agents]
     async for event in _merge_agent_run(agent_runs):
       yield event
+
+  @override
+  async def _run_live_impl(
+      self, ctx: InvocationContext
+  ) -> AsyncGenerator[Event, None]:
+    raise NotImplementedError("This is not supported yet for ParallelAgent.")
+    yield  # AsyncGenerator requires having at least one yield statement

google/adk/agents/readonly_context.py

@@ -16,9 +16,12 @@ from __future__ import annotations
 
 from types import MappingProxyType
 from typing import Any
+from typing import Optional
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+  from google.genai import types
+
   from .invocation_context import InvocationContext
 
 
@@ -30,6 +33,11 @@ class ReadonlyContext:
   ) -> None:
     self._invocation_context = invocation_context
 
+  @property
+  def user_content(self) -> Optional[types.Content]:
+    """The user content that started this invocation. READONLY field."""
+    return self._invocation_context.user_content
+
   @property
   def invocation_id(self) -> str:
     """The current invocation id."""

google/adk/agents/run_config.py

@@ -22,7 +22,7 @@ from pydantic import BaseModel
 from pydantic import ConfigDict
 from pydantic import field_validator
 
-logger = logging.getLogger(__name__)
+logger = logging.getLogger('google_adk.' + __name__)
 
 
 class StreamingMode(Enum):

google/adk/agents/sequential_agent.py

@@ -23,6 +23,7 @@ from typing_extensions import override
 from ..agents.invocation_context import InvocationContext
 from ..events.event import Event
 from .base_agent import BaseAgent
+from .llm_agent import LlmAgent
 
 
 class SequentialAgent(BaseAgent):
@@ -40,6 +41,36 @@ class SequentialAgent(BaseAgent):
   async def _run_live_impl(
       self, ctx: InvocationContext
   ) -> AsyncGenerator[Event, None]:
+    """Implementation for live SequentialAgent.
+
+    Compared to non-live case, live agents process a continous streams of audio
+    or video, so it doesn't have a way to tell if it's finished and should pass
+    to next agent or not. So we introduce a task_compelted() function so the
+    model can call this function to signal that it's finished the task and we
+    can move on to next agent.
+
+    Args:
+      ctx: The invocation context of the agent.
+    """
+    # There is no way to know if it's using live during init phase so we have to init it here
+    for sub_agent in self.sub_agents:
+      # add tool
+      def task_completed():
+        """
+        Signals that the model has successfully completed the user's question
+        or task.
+        """
+        return "Task completion signaled."
+
+      if isinstance(sub_agent, LlmAgent):
+        # Use function name to dedupe.
+        if task_completed.__name__ not in sub_agent.tools:
+          sub_agent.tools.append(task_completed)
+          sub_agent.instruction += f"""If you finished the user' request
+          according to its description, call {task_completed.__name__} function
+          to exit so the next agents can take over. When calling this function,
+          do not generate any text other than the function call.'"""
+
     for sub_agent in self.sub_agents:
       async for event in sub_agent.run_live(ctx):
         yield event

google/adk/agents/transcription_entry.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from typing import Optional
 from typing import Union
 
 from google.genai import types
@@ -28,8 +29,9 @@ class TranscriptionEntry(BaseModel):
   )
   """The pydantic model config."""
 
-  role: str
-  """The role that created this data, typically "user" or "model"""
+  role: Optional[str] = None
+  """The role that created this data, typically "user" or "model". For function 
+  call, this is None."""
 
   data: Union[types.Blob, types.Content]
   """The data that can be used for transcription"""

google/adk/artifacts/gcs_artifact_service.py

@@ -23,7 +23,7 @@ from typing_extensions import override
 
 from .base_artifact_service import BaseArtifactService
 
-logger = logging.getLogger(__name__)
+logger = logging.getLogger("google_adk." + __name__)
 
 
 class GcsArtifactService(BaseArtifactService):

google/adk/artifacts/in_memory_artifact_service.py

@@ -24,7 +24,7 @@ from typing_extensions import override
 
 from .base_artifact_service import BaseArtifactService
 
-logger = logging.getLogger(__name__)
+logger = logging.getLogger("google_adk." + __name__)
 
 
 class InMemoryArtifactService(BaseArtifactService, BaseModel):

google/adk/auth/auth_credential.py

@@ -13,15 +13,23 @@
 # limitations under the License.
 
 from enum import Enum
-from typing import Any, Dict, List, Optional
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Optional
 
+from pydantic import alias_generators
 from pydantic import BaseModel
 from pydantic import ConfigDict
 from pydantic import Field
 
 
 class BaseModelWithConfig(BaseModel):
-  model_config = ConfigDict(extra="allow")
+  model_config = ConfigDict(
+      extra="allow",
+      alias_generator=alias_generators.to_camel,
+      populate_by_name=True,
+  )
   """The pydantic model config."""
 
 

google/adk/auth/auth_preprocessor.py

@@ -20,6 +20,7 @@ from typing import TYPE_CHECKING
 from typing_extensions import override
 
 from ..agents.invocation_context import InvocationContext
+from ..agents.readonly_context import ReadonlyContext
 from ..events.event import Event
 from ..flows.llm_flows import functions
 from ..flows.llm_flows._base_llm_processor import BaseLlmRequestProcessor
@@ -105,7 +106,12 @@ class _AuthLlmRequestProcessor(BaseLlmRequestProcessor):
             function_response_event = await functions.handle_function_calls_async(
                 invocation_context,
                 event,
-                {tool.name: tool for tool in agent.canonical_tools},
+                {
+                    tool.name: tool
+                    for tool in await agent.canonical_tools(
+                        ReadonlyContext(invocation_context)
+                    )
+                },
                 # there could be parallel function calls that require auth
                 # auth response would be a dict keyed by function call id
                 tools_to_resume,

google/adk/auth/auth_tool.py

@@ -12,13 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from pydantic import BaseModel
-
 from .auth_credential import AuthCredential
+from .auth_credential import BaseModelWithConfig
 from .auth_schemes import AuthScheme
 
 
-class AuthConfig(BaseModel):
+class AuthConfig(BaseModelWithConfig):
   """The auth config sent by tool asking client to collect auth credentials and
 
   adk and client will help to fill in the response
@@ -45,7 +44,7 @@ class AuthConfig(BaseModel):
   this field"""
 
 
-class AuthToolArguments(BaseModel):
+class AuthToolArguments(BaseModelWithConfig):
   """the arguments for the special long running function tool that is used to
 
   request end user credentials.