Merge branch 'main' into fix/temp-state-output-key

Author: DeanChensj

contributing/samples/agent_engine_code_execution/README

@@ -7,9 +7,9 @@ This sample data science agent uses Agent Engine Code Execution Sandbox to execu
 
 ## How to use
 
-* 1. Follow https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/code-execution/overview to create a code execution sandbox environment.
+* 1. Follow https://docs.cloud.google.com/agent-builder/agent-engine/code-execution/quickstart#create-an-agent-engine-instance to create an agent engine instance. Replace the AGENT_ENGINE_RESOURCE_NAME with the one you just created. A new sandbox environment under this agent engine instance will be created for each session with TTL of 1 year. But sandbox can only main its state for up to 14 days. This is the recommended usage for production environments.
 
-* 2. Replace the SANDBOX_RESOURCE_NAME with the one you just created. If you dont want to create a new sandbox environment directly, the Agent Engine Code Execution Sandbox will create one for you by default using the AGENT_ENGINE_RESOURCE_NAME you specified, however, please ensure to clean up sandboxes after use; otherwise, it will consume quotas.
+* 2. For testing or protyping purposes, create a sandbox environment by following this guide: https://docs.cloud.google.com/agent-builder/agent-engine/code-execution/quickstart#create_a_sandbox. Replace the SANDBOX_RESOURCE_NAME with the one you just created. This will be used as the default sandbox environment for all the code executions throughout the lifetime of the agent. As the sandbox is re-used across sessions, all sessions will share the same Python environment and variable values."
 
 
 ## Sample prompt

contributing/samples/agent_engine_code_execution/agent.py

@@ -85,11 +85,10 @@ def base_system_instruction():
 
 """,
     code_executor=AgentEngineSandboxCodeExecutor(
-        # Replace with your sandbox resource name if you already have one.
-        sandbox_resource_name="SANDBOX_RESOURCE_NAME",
+        # Replace with your sandbox resource name if you already have one. Only use it for testing or prototyping purposes, because this will use the same sandbox for all requests.
         # "projects/vertex-agent-loadtest/locations/us-central1/reasoningEngines/6842889780301135872/sandboxEnvironments/6545148628569161728",
-        # Replace with agent engine resource name used for creating sandbox if
-        # sandbox_resource_name is not set.
+        sandbox_resource_name=None,
+        # Replace with agent engine resource name used for creating sandbox environment.
         agent_engine_resource_name="AGENT_ENGINE_RESOURCE_NAME",
     ),
 )

contributing/samples/authn-adk-all-in-one/requirements.txt

@@ -1,5 +1,5 @@
 google-adk==1.12
-Flask==3.1.1
+Flask==3.1.3
 flask-cors==6.0.1
 python-dotenv==1.1.1
 PyJWT[crypto]==2.10.1

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],
 )

pyproject.toml

@@ -56,7 +56,7 @@ dependencies = [
   "opentelemetry-resourcedetector-gcp>=1.9.0a0, <2.0.0",
   "opentelemetry-sdk>=1.36.0, <1.39.0",
   "pyarrow>=14.0.0",
-  "pydantic>=2.7.0, <3.0.0",                                 # For data validation/models
+  "pydantic>=2.12.0, <3.0.0",                                 # For data validation/models
   "python-dateutil>=2.9.0.post0, <3.0.0",                    # For Vertext AI Session Service
   "python-dotenv>=1.0.0, <2.0.0",                            # To manage environment variables
   "requests>=2.32.4, <3.0.0",
@@ -109,6 +109,7 @@ community = [
 eval = [
   # go/keep-sorted start
   "Jinja2>=3.1.4,<4.0.0",                         # For eval template rendering
+  "gepa>=0.1.0",
   "google-cloud-aiplatform[evaluation]>=1.100.0",
   "pandas>=2.2.3",
   "rouge-score>=0.1.2",
@@ -155,6 +156,7 @@ extensions = [
   "crewai[tools];python_version>='3.11' and python_version<'3.12'",       # For CrewaiTool; chromadb/pypika fail on 3.12+
   "docker>=7.0.0",                              # For ContainerCodeExecutor
   "kubernetes>=29.0.0",                         # For GkeCodeExecutor
+  "k8s-agent-sandbox>=0.1.1.post2",             # For GkeCodeExecutor sandbox mode
   "langgraph>=0.2.60, <0.4.8",                  # For LangGraphAgent
   "litellm>=1.75.5, <2.0.0",                    # For LiteLlm class. Currently has OpenAI limitations. TODO: once LiteLlm fix it
   "llama-index-readers-file>=0.4.0",            # For retrieval using LlamaIndex.

src/google/adk/a2a/converters/event_converter.py

@@ -370,7 +370,7 @@ def convert_a2a_message_to_event(
 @a2a_experimental
 def convert_event_to_a2a_message(
     event: Event,
-    invocation_context: InvocationContext,
+    invocation_context: InvocationContext | None = None,
     role: Role = Role.agent,
     part_converter: GenAIPartToA2APartConverter = convert_genai_part_to_a2a_part,
 ) -> Optional[Message]:
@@ -390,8 +390,6 @@ def convert_event_to_a2a_message(
   """
   if not event:
     raise ValueError("Event cannot be None")
-  if not invocation_context:
-    raise ValueError("Invocation context cannot be None")
 
   if not event.content or not event.content.parts:
     return None

src/google/adk/a2a/converters/part_converter.py

@@ -70,7 +70,9 @@ def convert_a2a_part_to_genai_part(
     if isinstance(part.file, a2a_types.FileWithUri):
       return genai_types.Part(
           file_data=genai_types.FileData(
-              file_uri=part.file.uri, mime_type=part.file.mime_type
+              file_uri=part.file.uri,
+              mime_type=part.file.mime_type,
+              display_name=part.file.name,
           )
       )
 
@@ -79,6 +81,7 @@ def convert_a2a_part_to_genai_part(
           inline_data=genai_types.Blob(
               data=base64.b64decode(part.file.bytes),
               mime_type=part.file.mime_type,
+              display_name=part.file.name,
           )
       )
     else:
@@ -104,10 +107,25 @@ def convert_a2a_part_to_genai_part(
           part.metadata[_get_adk_metadata_key(A2A_DATA_PART_METADATA_TYPE_KEY)]
           == A2A_DATA_PART_METADATA_TYPE_FUNCTION_CALL
       ):
+        # Restore thought_signature if present
+        thought_signature = None
+        thought_sig_key = _get_adk_metadata_key('thought_signature')
+        if thought_sig_key in part.metadata:
+          sig_value = part.metadata[thought_sig_key]
+          if isinstance(sig_value, bytes):
+            thought_signature = sig_value
+          elif isinstance(sig_value, str):
+            try:
+              thought_signature = base64.b64decode(sig_value)
+            except Exception:
+              logger.warning(
+                  'Failed to decode thought_signature: %s', sig_value
+              )
         return genai_types.Part(
             function_call=genai_types.FunctionCall.model_validate(
                 part.data, by_alias=True
-            )
+            ),
+            thought_signature=thought_signature,
         )
       if (
           part.metadata[_get_adk_metadata_key(A2A_DATA_PART_METADATA_TYPE_KEY)]
@@ -173,6 +191,7 @@ def convert_genai_part_to_a2a_part(
             file=a2a_types.FileWithUri(
                 uri=part.file_data.file_uri,
                 mime_type=part.file_data.mime_type,
+                name=part.file_data.display_name,
             )
         )
     )
@@ -196,6 +215,7 @@ def convert_genai_part_to_a2a_part(
         file=a2a_types.FileWithBytes(
             bytes=base64.b64encode(part.inline_data.data).decode('utf-8'),
             mime_type=part.inline_data.mime_type,
+            name=part.inline_data.display_name,
         )
     )
 
@@ -214,16 +234,22 @@ def convert_genai_part_to_a2a_part(
   # TODO once A2A defined how to service such information, migrate below
   # logic accordingly
   if part.function_call:
+    fc_metadata = {
+        _get_adk_metadata_key(
+            A2A_DATA_PART_METADATA_TYPE_KEY
+        ): A2A_DATA_PART_METADATA_TYPE_FUNCTION_CALL
+    }
+    # Preserve thought_signature if present
+    if part.thought_signature is not None:
+      fc_metadata[_get_adk_metadata_key('thought_signature')] = (
+          base64.b64encode(part.thought_signature).decode('utf-8')
+      )
     return a2a_types.Part(
         root=a2a_types.DataPart(
             data=part.function_call.model_dump(
                 by_alias=True, exclude_none=True
             ),
-            metadata={
-                _get_adk_metadata_key(
-                    A2A_DATA_PART_METADATA_TYPE_KEY
-                ): A2A_DATA_PART_METADATA_TYPE_FUNCTION_CALL
-            },
+            metadata=fc_metadata,
         )
     )
 

src/google/adk/a2a/experimental.py

@@ -23,7 +23,7 @@
     default_message=(
         "ADK Implementation for A2A support (A2aAgentExecutor, RemoteA2aAgent "
         "and corresponding supporting components etc.) is in experimental mode "
-        "and is subjected to breaking changes. A2A protocol and SDK are"
+        "and is subject to breaking changes. A2A protocol and SDK are "
         "themselves not experimental. Once it's stable enough the experimental "
         "mode will be removed. Your feedback is welcome."
     ),

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.