Merge branch 'main' into upgrade-github-actions-node24

Author: wuliang229

src/google/adk/cli/adk_web_server.py

@@ -1347,6 +1347,24 @@ async def load_artifact(
         raise HTTPException(status_code=404, detail="Artifact not found")
       return artifact
 
+    @app.get(
+        "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{artifact_name}/versions/metadata",
+        response_model=list[ArtifactVersion],
+        response_model_exclude_none=True,
+    )
+    async def list_artifact_versions_metadata(
+        app_name: str,
+        user_id: str,
+        session_id: str,
+        artifact_name: str,
+    ) -> list[ArtifactVersion]:
+      return await self.artifact_service.list_artifact_versions(
+          app_name=app_name,
+          user_id=user_id,
+          session_id=session_id,
+          filename=artifact_name,
+      )
+
     @app.get(
         "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{artifact_name}/versions/{version_id}",
         response_model_exclude_none=True,
@@ -1416,6 +1434,31 @@ async def save_artifact(
         )
       return artifact_version
 
+    @app.get(
+        "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{artifact_name}/versions/{version_id}/metadata",
+        response_model=ArtifactVersion,
+        response_model_exclude_none=True,
+    )
+    async def get_artifact_version_metadata(
+        app_name: str,
+        user_id: str,
+        session_id: str,
+        artifact_name: str,
+        version_id: int,
+    ) -> ArtifactVersion:
+      artifact_version = await self.artifact_service.get_artifact_version(
+          app_name=app_name,
+          user_id=user_id,
+          session_id=session_id,
+          filename=artifact_name,
+          version=version_id,
+      )
+      if not artifact_version:
+        raise HTTPException(
+            status_code=404, detail="Artifact version not found"
+        )
+      return artifact_version
+
     @app.get(
         "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts",
         response_model_exclude_none=True,

src/google/adk/cli/conformance/adk_web_server_client.py

@@ -27,6 +27,7 @@
 
 import httpx
 
+from ...artifacts.base_artifact_service import ArtifactVersion
 from ...events.event import Event
 from ...sessions.session import Session
 from ..adk_web_server import RunAgentRequest
@@ -268,3 +269,38 @@ async def run_agent(
             yield Event.model_validate(event_data)
           else:
             logger.debug("Non data line received: %s", line)
+
+  async def get_artifact_version_metadata(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      session_id: str,
+      artifact_name: str,
+      version: int,
+  ) -> ArtifactVersion:
+    """Retrieve metadata for a specific artifact version."""
+    async with self._get_client() as client:
+      response = await client.get((
+          f"/apps/{app_name}/users/{user_id}/sessions/{session_id}"
+          f"/artifacts/{artifact_name}/versions/{version}/metadata"
+      ))
+      response.raise_for_status()
+      return ArtifactVersion.model_validate(response.json())
+
+  async def list_artifact_versions_metadata(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      session_id: str,
+      artifact_name: str,
+  ) -> list[ArtifactVersion]:
+    """List metadata for all versions of an artifact."""
+    async with self._get_client() as client:
+      response = await client.get((
+          f"/apps/{app_name}/users/{user_id}/sessions/{session_id}"
+          f"/artifacts/{artifact_name}/versions/metadata"
+      ))
+      response.raise_for_status()
+      return [ArtifactVersion.model_validate(item) for item in response.json()]

src/google/adk/features/_feature_registry.py

@@ -41,6 +41,7 @@ class FeatureName(str, Enum):
   PROGRESSIVE_SSE_STREAMING = "PROGRESSIVE_SSE_STREAMING"
   PUBSUB_TOOL_CONFIG = "PUBSUB_TOOL_CONFIG"
   PUBSUB_TOOLSET = "PUBSUB_TOOLSET"
+  SKILL_TOOLSET = "SKILL_TOOLSET"
   SPANNER_TOOLSET = "SPANNER_TOOLSET"
   SPANNER_TOOL_SETTINGS = "SPANNER_TOOL_SETTINGS"
   SPANNER_VECTOR_STORE = "SPANNER_VECTOR_STORE"
@@ -123,6 +124,9 @@ class FeatureConfig:
     FeatureName.PUBSUB_TOOLSET: FeatureConfig(
         FeatureStage.EXPERIMENTAL, default_on=True
     ),
+    FeatureName.SKILL_TOOLSET: FeatureConfig(
+        FeatureStage.EXPERIMENTAL, default_on=True
+    ),
     FeatureName.SPANNER_TOOLSET: FeatureConfig(
         FeatureStage.EXPERIMENTAL, default_on=True
     ),

src/google/adk/tools/skill_toolset.py

@@ -21,6 +21,8 @@
 from google.genai import types
 
 from ..agents.readonly_context import ReadonlyContext
+from ..features import experimental
+from ..features import FeatureName
 from ..models.llm_request import LlmRequest
 from ..skills import models
 from ..skills import prompt
@@ -29,6 +31,7 @@
 from .tool_context import ToolContext
 
 
+@experimental(FeatureName.SKILL_TOOLSET)
 class LoadSkillTool(BaseTool):
   """Tool to load a skill's instructions."""
 
@@ -79,6 +82,7 @@ async def run_async(
     }
 
 
+@experimental(FeatureName.SKILL_TOOLSET)
 class LoadSkillResourceTool(BaseTool):
   """Tool to load resources (references or assets) from a skill."""
 
@@ -167,6 +171,7 @@ async def run_async(
     }
 
 
+@experimental(FeatureName.SKILL_TOOLSET)
 class SkillToolset(BaseToolset):
   """A toolset for managing and interacting with agent skills."""
 

src/google/adk/utils/instructions_utils.py

@@ -79,7 +79,16 @@ async def _async_sub(pattern, repl_async_fn, string) -> str:
     return ''.join(result)
 
   async def _replace_match(match) -> str:
-    var_name = match.group().lstrip('{').rstrip('}').strip()
+    matched_text = match.group()
+    if matched_text.startswith('{{') and matched_text.endswith('}}'):
+      # Preserve escaped non-placeholder literals (e.g. JSON snippets),
+      # but keep escaped placeholders as literal placeholders.
+      escaped_value = matched_text[2:-2]
+      if _is_escaped_placeholder(escaped_value):
+        return matched_text[1:-1]
+      return matched_text
+
+    var_name = matched_text.lstrip('{').rstrip('}').strip()
     optional = False
     if var_name.endswith('?'):
       optional = True
@@ -124,6 +133,21 @@ async def _replace_match(match) -> str:
   return await _async_sub(r'{+[^{}]*}+', _replace_match, template)
 
 
+def _is_escaped_placeholder(value: str) -> bool:
+  """Checks if escaped braces contain a supported placeholder pattern."""
+  var_name = value.strip()
+  if not var_name:
+    return False
+
+  if var_name.endswith('?'):
+    var_name = var_name.removesuffix('?')
+
+  if var_name.startswith('artifact.'):
+    return True
+
+  return _is_valid_state_name(var_name)
+
+
 def _is_valid_state_name(var_name):
   """Checks if the variable name is a valid state name.
 

tests/unittests/cli/conformance/test_adk_web_server_client.py

@@ -17,6 +17,7 @@
 from unittest.mock import MagicMock
 from unittest.mock import patch
 
+from google.adk.artifacts.base_artifact_service import ArtifactVersion
 from google.adk.cli.adk_web_server import RunAgentRequest
 from google.adk.cli.conformance.adk_web_server_client import AdkWebServerClient
 from google.adk.events.event import Event
@@ -262,6 +263,84 @@ def mock_stream(*_args, **_kwargs):
         pass
 
 
+@pytest.mark.asyncio
+async def test_get_artifact_version_metadata():
+  client = AdkWebServerClient()
+  mock_response = MagicMock()
+  mock_response.json.return_value = {
+      "version": 2,
+      "canonicalUri": (
+          "artifact://apps/app/users/user/sessions/session/"
+          "artifacts/report/versions/2"
+      ),
+      "customMetadata": {"foo": "bar"},
+      "createTime": 123.4,
+      "mimeType": "text/plain",
+  }
+
+  with patch("httpx.AsyncClient") as mock_client_class:
+    mock_client = AsyncMock()
+    mock_client.get.return_value = mock_response
+    mock_client_class.return_value = mock_client
+
+    metadata = await client.get_artifact_version_metadata(
+        app_name="app",
+        user_id="user",
+        session_id="session",
+        artifact_name="report",
+        version=2,
+    )
+
+    assert isinstance(metadata, ArtifactVersion)
+    assert metadata.version == 2
+    assert metadata.custom_metadata == {"foo": "bar"}
+    mock_client.get.assert_called_once_with(
+        "/apps/app/users/user/sessions/session/artifacts/report/versions/2/metadata"
+    )
+    mock_response.raise_for_status.assert_called_once()
+
+
+@pytest.mark.asyncio
+async def test_list_artifact_versions_metadata():
+  client = AdkWebServerClient()
+  mock_response = MagicMock()
+  mock_response.json.return_value = [
+      {
+          "version": 0,
+          "canonicalUri": "artifact://.../versions/0",
+          "customMetadata": {},
+          "createTime": 100.0,
+      },
+      {
+          "version": 1,
+          "canonicalUri": "artifact://.../versions/1",
+          "customMetadata": {"foo": "bar"},
+          "createTime": 200.0,
+          "mimeType": "application/json",
+      },
+  ]
+
+  with patch("httpx.AsyncClient") as mock_client_class:
+    mock_client = AsyncMock()
+    mock_client.get.return_value = mock_response
+    mock_client_class.return_value = mock_client
+
+    metadata_list = await client.list_artifact_versions_metadata(
+        app_name="app",
+        user_id="user",
+        session_id="session",
+        artifact_name="report",
+    )
+
+    assert len(metadata_list) == 2
+    assert all(isinstance(item, ArtifactVersion) for item in metadata_list)
+    assert metadata_list[1].custom_metadata == {"foo": "bar"}
+    mock_client.get.assert_called_once_with(
+        "/apps/app/users/user/sessions/session/artifacts/report/versions/metadata"
+    )
+    mock_response.raise_for_status.assert_called_once()
+
+
 @pytest.mark.asyncio
 async def test_close():
   client = AdkWebServerClient()