Merge branch 'main' into fix/list-agents-filter-non-agents-dirs

Author: DeanChensj

contributing/samples/fields_output_schema/agent.py

@@ -22,9 +22,20 @@ class WeatherData(BaseModel):
   wind_speed: str
 
 
+def get_current_year() -> str:
+  """Get the current year.
+
+  Returns:
+    The current year as a string
+  """
+  from datetime import datetime
+
+  return str(datetime.now().year)
+
+
 root_agent = Agent(
     name='root_agent',
-    model='gemini-2.0-flash',
+    model='gemini-2.5-flash',
     instruction="""\
 Answer user's questions based on the data you have.
 
@@ -43,6 +54,7 @@ class WeatherData(BaseModel):
 * wind_speed: 13 mph
 
 """,
-    output_schema=WeatherData,
+    output_schema=list[WeatherData],
     output_key='weather_data',
+    tools=[get_current_year],
 )

src/google/adk/agents/llm_agent.py

@@ -56,6 +56,8 @@
 from ..tools.function_tool import FunctionTool
 from ..tools.tool_configs import ToolConfig
 from ..tools.tool_context import ToolContext
+from ..utils._schema_utils import SchemaType
+from ..utils._schema_utils import validate_schema
 from ..utils.context_utils import Aclosing
 from .base_agent import BaseAgent
 from .base_agent import BaseAgentState
@@ -318,9 +320,16 @@ class LlmAgent(BaseAgent):
   # Controlled input/output configurations - Start
   input_schema: Optional[type[BaseModel]] = None
   """The input schema when agent is used as a tool."""
-  output_schema: Optional[type[BaseModel]] = None
+  output_schema: Optional[SchemaType] = None
   """The output schema when agent replies.
 
+  Supports all schema types that the underlying Google GenAI API supports:
+    - type[BaseModel]: e.g., MySchema
+    - list[type[BaseModel]]: e.g., list[MySchema]
+    - list[primitive]: e.g., list[str], list[int]
+    - dict: Raw dict schemas
+    - Schema: Google's Schema type
+
   NOTE:
     When this is set, agent can ONLY reply and CANNOT use any tools, such as
     function tools, RAGs, agent transfer, etc.
@@ -820,12 +829,12 @@ def __maybe_save_output_to_state(self, event: Event):
           event.author,
       )
       return
-    if (
-        self.output_key
-        and event.is_final_response()
-        and event.content
-        and event.content.parts
-    ):
+
+    if not self.output_key:
+      return
+
+    # Handle text responses
+    if event.is_final_response() and event.content and event.content.parts:
 
       result = ''.join(
           part.text
@@ -838,9 +847,7 @@ def __maybe_save_output_to_state(self, event: Event):
         # Do not attempt to parse it as JSON.
         if not result.strip():
           return
-        result = self.output_schema.model_validate_json(result).model_dump(
-            exclude_none=True
-        )
+        result = validate_schema(self.output_schema, result)
       event.actions.state_delta[self.output_key] = result
 
   @model_validator(mode='after')

src/google/adk/artifacts/base_artifact_service.py

@@ -16,15 +16,19 @@
 from abc import ABC
 from abc import abstractmethod
 from datetime import datetime
+import logging
 from typing import Any
 from typing import Optional
+from typing import Union
 
 from google.genai import types
 from pydantic import alias_generators
 from pydantic import BaseModel
 from pydantic import ConfigDict
 from pydantic import Field
 
+logger = logging.getLogger("google_adk." + __name__)
+
 
 class ArtifactVersion(BaseModel):
   """Metadata describing a specific version of an artifact."""
@@ -60,6 +64,26 @@ class ArtifactVersion(BaseModel):
   )
 
 
+def ensure_part(artifact: Union[types.Part, dict[str, Any]]) -> types.Part:
+  """Normalizes an artifact to a ``types.Part`` instance.
+
+  External callers may provide artifacts as
+  plain dictionaries with camelCase keys (``inlineData``) instead of properly
+  deserialized ``types.Part`` objects.  ``model_validate`` handles both
+  camelCase and snake_case dictionaries transparently via Pydantic aliases.
+
+  Args:
+    artifact: A ``types.Part`` instance or a dictionary representation.
+
+  Returns:
+    A validated ``types.Part`` instance.
+  """
+  if isinstance(artifact, dict):
+    logger.debug("Normalizing artifact dict to types.Part: %s", list(artifact))
+    return types.Part.model_validate(artifact)
+  return artifact
+
+
 class BaseArtifactService(ABC):
   """Abstract base class for artifact services."""
 
@@ -70,7 +94,7 @@ async def save_artifact(
       app_name: str,
       user_id: str,
       filename: str,
-      artifact: types.Part,
+      artifact: Union[types.Part, dict[str, Any]],
       session_id: Optional[str] = None,
       custom_metadata: Optional[dict[str, Any]] = None,
   ) -> int:
@@ -84,10 +108,12 @@ async def save_artifact(
       app_name: The app name.
       user_id: The user ID.
       filename: The filename of the artifact.
-      artifact: The artifact to save. If the artifact consists of `file_data`,
-        the artifact service assumes its content has been uploaded separately,
-        and this method will associate the `file_data` with the artifact if
-        necessary.
+      artifact: The artifact to save. Accepts a ``types.Part`` instance or a
+        plain dictionary (camelCase or snake_case keys) which will be
+        normalized via ``ensure_part``. If the artifact consists of
+        ``file_data``, the artifact service assumes its content has been
+        uploaded separately, and this method will associate the ``file_data``
+        with the artifact if necessary.
       session_id: The session ID. If `None`, the artifact is user-scoped.
       custom_metadata: custom metadata to associate with the artifact.
 

src/google/adk/artifacts/file_artifact_service.py

@@ -22,6 +22,7 @@
 import shutil
 from typing import Any
 from typing import Optional
+from typing import Union
 from urllib.parse import unquote
 from urllib.parse import urlparse
 
@@ -35,6 +36,7 @@
 from ..errors.input_validation_error import InputValidationError
 from .base_artifact_service import ArtifactVersion
 from .base_artifact_service import BaseArtifactService
+from .base_artifact_service import ensure_part
 
 logger = logging.getLogger("google_adk." + __name__)
 
@@ -314,7 +316,7 @@ async def save_artifact(
       app_name: str,
       user_id: str,
       filename: str,
-      artifact: types.Part,
+      artifact: Union[types.Part, dict[str, Any]],
       session_id: Optional[str] = None,
       custom_metadata: Optional[dict[str, Any]] = None,
   ) -> int:
@@ -339,11 +341,12 @@ def _save_artifact_sync(
       self,
       user_id: str,
       filename: str,
-      artifact: types.Part,
+      artifact: Union[types.Part, dict[str, Any]],
       session_id: Optional[str],
       custom_metadata: Optional[dict[str, Any]],
   ) -> int:
     """Saves an artifact to disk and returns its version."""
+    artifact = ensure_part(artifact)
     artifact_dir = self._artifact_dir(
         user_id=user_id,
         session_id=session_id,

src/google/adk/artifacts/gcs_artifact_service.py

@@ -27,13 +27,15 @@
 import logging
 from typing import Any
 from typing import Optional
+from typing import Union
 
 from google.genai import types
 from typing_extensions import override
 
 from ..errors.input_validation_error import InputValidationError
 from .base_artifact_service import ArtifactVersion
 from .base_artifact_service import BaseArtifactService
+from .base_artifact_service import ensure_part
 
 logger = logging.getLogger("google_adk." + __name__)
 
@@ -61,7 +63,7 @@ async def save_artifact(
       app_name: str,
       user_id: str,
       filename: str,
-      artifact: types.Part,
+      artifact: Union[types.Part, dict[str, Any]],
       session_id: Optional[str] = None,
       custom_metadata: Optional[dict[str, Any]] = None,
   ) -> int:
@@ -198,9 +200,10 @@ def _save_artifact(
       user_id: str,
       session_id: Optional[str],
       filename: str,
-      artifact: types.Part,
+      artifact: Union[types.Part, dict[str, Any]],
       custom_metadata: Optional[dict[str, Any]] = None,
   ) -> int:
+    artifact = ensure_part(artifact)
     versions = self._list_versions(
         app_name=app_name,
         user_id=user_id,

src/google/adk/artifacts/in_memory_artifact_service.py

@@ -17,6 +17,7 @@
 import logging
 from typing import Any
 from typing import Optional
+from typing import Union
 
 from google.genai import types
 from pydantic import BaseModel
@@ -27,6 +28,7 @@
 from ..errors.input_validation_error import InputValidationError
 from .base_artifact_service import ArtifactVersion
 from .base_artifact_service import BaseArtifactService
+from .base_artifact_service import ensure_part
 
 logger = logging.getLogger("google_adk." + __name__)
 
@@ -99,10 +101,11 @@ async def save_artifact(
       app_name: str,
       user_id: str,
       filename: str,
-      artifact: types.Part,
+      artifact: Union[types.Part, dict[str, Any]],
       session_id: Optional[str] = None,
       custom_metadata: Optional[dict[str, Any]] = None,
   ) -> int:
+    artifact = ensure_part(artifact)
     path = self._artifact_path(app_name, user_id, filename, session_id)
     if path not in self.artifacts:
       self.artifacts[path] = []

src/google/adk/flows/llm_flows/_output_schema_processor.py

@@ -110,8 +110,12 @@ def get_structured_model_response(function_response_event: Event) -> str | None:
 
   for func_response in function_response_event.get_function_responses():
     if func_response.name == 'set_model_response':
-      # Convert dict to JSON string
-      return json.dumps(func_response.response, ensure_ascii=False)
+      # Extract the actual result from the wrapped response.
+      # Tool results are wrapped as {'result': ...} when not already a dict.
+      response = func_response.response
+      if isinstance(response, dict) and 'result' in response:
+        response = response['result']
+      return json.dumps(response, ensure_ascii=False)
 
   return None
 

src/google/adk/models/llm_request.py

@@ -25,6 +25,7 @@
 
 from ..agents.context_cache_config import ContextCacheConfig
 from ..tools.base_tool import BaseTool
+from ..utils._schema_utils import SchemaType
 from .cache_metadata import CacheMetadata
 
 
@@ -273,12 +274,27 @@ def append_tools(self, tools: list[BaseTool]) -> None:
         # No existing tool with function_declarations, create new one
         self.config.tools.append(types.Tool(function_declarations=declarations))
 
-  def set_output_schema(self, base_model: type[BaseModel]) -> None:
+  def set_output_schema(
+      self,
+      output_schema: Optional[SchemaType] = None,
+      *,
+      base_model: Optional[SchemaType] = None,
+  ) -> None:
     """Sets the output schema for the request.
 
     Args:
-      base_model: The pydantic base model to set the output schema to.
+      output_schema: The output schema to set. Supports all types from
+        SchemaUnion:
+        - type[BaseModel]: A pydantic model class (e.g., MySchema)
+        - list[type[BaseModel]]: A generic list type (e.g., list[MySchema])
+        - list[primitive]: e.g., list[str], list[int]
+        - dict: Raw dict schemas
+        - Schema: Google's Schema type
+      base_model: Deprecated alias for output_schema. Use output_schema instead.
     """
+    schema = output_schema or base_model
+    if schema is None:
+      raise ValueError("Either output_schema or base_model must be provided.")
 
-    self.config.response_schema = base_model
+    self.config.response_schema = schema
     self.config.response_mime_type = "application/json"