fix(artifacts): Support nested API names

Merge #6051

**Please ensure you have read the [contribution guide](https://github.com/google/adk-python/blob/main/CONTRIBUTING.md) before creating a pull request.**

### Link to Issue or Description of Change

**1. Link to an existing issue (if applicable):**

- Fixes: #6050

**Problem:**

Artifact services can save and list logical artifact names containing `/`, such as `reports/summary.txt`. The REST API also accepts these names through `POST /artifacts` because the filename is provided in the request body.

However, read/version/metadata/delete routes treated `artifact_name` as a single path segment. That made nested artifact names visible in the list endpoint but unreachable through the path-based endpoints.

**Solution:**

Update artifact read/version/metadata/delete routes to use FastAPI's `{artifact_name:path}` converter so nested logical artifact names can round-trip through the REST API.

Because `{artifact_name:path}` is catch-all, the version-specific routes are registered before the general artifact load route. No response schema changes are intended: endpoints that returned `types.Part` still return `types.Part`, and metadata endpoints still return `ArtifactVersion` / `list[ArtifactVersion]`.

Also update artifact URI parsing so artifact references can resolve nested filenames such as `folder/file.txt`.

### Testing Plan

**Unit Tests:**

- [x] I have added or updated unit tests for my change.
- [x] All unit tests pass locally.

Targeted artifact API tests pass locally:

```shell
uv run pytest tests/unittests/cli/test_fast_api.py -k artifact -q
```

Result:

```text
9 passed, 72 deselected
```

Artifact service and URI tests pass locally:

```shell
uv run pytest tests/unittests/artifacts/test_artifact_util.py tests/unittests/artifacts/test_artifact_service.py -q
```

Result:

```text
77 passed
```

Python 3.10 tox unit suite passes locally:

```shell
uv tool run --from tox --with tox-uv tox -e py310
```

Result:

```text
7045 passed, 21 skipped, 31 xfailed, 9 xpassed
```

Pre-commit hooks pass for changed files:

```shell
uv run pre-commit run --files src/google/adk/cli/api_server.py src/google/adk/artifacts/artifact_util.py tests/unittests/cli/test_fast_api.py tests/unittests/artifacts/test_artifact_util.py tests/unittests/artifacts/test_artifact_service.py
```

**Manual End-to-End (E2E) Tests:**

Validated a local REST API round-trip using the ADK API server route stack with `InMemoryArtifactService`:

- save `reports/summary.txt`
- list artifacts
- load with raw slash path
- load with encoded slash path
- list versions
- load version `0`
- load version metadata
- delete with encoded slash path

All requests returned `200`.

### Checklist

- [x] I have read the [CONTRIBUTING.md](https://github.com/google/adk-python/blob/main/CONTRIBUTING.md) document.
- [x] I have performed a self-review of my own code.
- [x] I have commented my code, particularly in hard-to-understand areas.
- [x] I have added tests that prove my fix is effective or that my feature works.
- [x] New and existing unit tests pass locally with my changes.
- [x] I have manually tested my changes end-to-end.
- [x] Any dependent changes have been merged and published in downstream modules.

### Additional context

No dependent changes are required.

Co-authored-by: Bo Yang <ybo@google.com>
COPYBARA_INTEGRATE_REVIEW=#6051 from spectaclehong:fix/artifact-slash-api 1c08a4f
PiperOrigin-RevId: 931342522

Author: 2 people

src/google/adk/artifacts/artifact_util.py

@@ -17,7 +17,6 @@
 
 import re
 from typing import NamedTuple
-from typing import Optional
 
 from google.genai import types
 
@@ -27,20 +26,20 @@ class ParsedArtifactUri(NamedTuple):
 
   app_name: str
   user_id: str
-  session_id: Optional[str]
+  session_id: str | None
   filename: str
   version: int
 
 
 _SESSION_SCOPED_ARTIFACT_URI_RE = re.compile(
-    r"artifact://apps/([^/]+)/users/([^/]+)/sessions/([^/]+)/artifacts/([^/]+)/versions/(\d+)"
+    r"artifact://apps/([^/]+)/users/([^/]+)/sessions/([^/]+)/artifacts/(.+)/versions/(\d+)"
 )
 _USER_SCOPED_ARTIFACT_URI_RE = re.compile(
-    r"artifact://apps/([^/]+)/users/([^/]+)/artifacts/([^/]+)/versions/(\d+)"
+    r"artifact://apps/([^/]+)/users/([^/]+)/artifacts/(.+)/versions/(\d+)"
 )
 
 
-def parse_artifact_uri(uri: str) -> Optional[ParsedArtifactUri]:
+def parse_artifact_uri(uri: str) -> ParsedArtifactUri | None:
   """Parses an artifact URI.
 
   Args:
@@ -52,7 +51,7 @@ def parse_artifact_uri(uri: str) -> Optional[ParsedArtifactUri]:
   if not uri or not uri.startswith("artifact://"):
     return None
 
-  match = _SESSION_SCOPED_ARTIFACT_URI_RE.match(uri)
+  match = _SESSION_SCOPED_ARTIFACT_URI_RE.fullmatch(uri)
   if match:
     return ParsedArtifactUri(
         app_name=match.group(1),
@@ -62,7 +61,7 @@ def parse_artifact_uri(uri: str) -> Optional[ParsedArtifactUri]:
         version=int(match.group(5)),
     )
 
-  match = _USER_SCOPED_ARTIFACT_URI_RE.match(uri)
+  match = _USER_SCOPED_ARTIFACT_URI_RE.fullmatch(uri)
   if match:
     return ParsedArtifactUri(
         app_name=match.group(1),
@@ -80,7 +79,7 @@ def get_artifact_uri(
     user_id: str,
     filename: str,
     version: int,
-    session_id: Optional[str] = None,
+    session_id: str | None = None,
 ) -> str:
   """Constructs an artifact URI.
 

src/google/adk/cli/api_server.py

@@ -1219,29 +1219,40 @@ async def update_session(
       return session
 
     @app.get(
-        "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{artifact_name}",
+        "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{artifact_name:path}/versions/{version_id}/metadata",
+        response_model=ArtifactVersion,
         response_model_exclude_none=True,
     )
-    async def load_artifact(
+    async def get_artifact_version_metadata(
         app_name: str,
         user_id: str,
         session_id: str,
         artifact_name: str,
-        version: Optional[int] = Query(None),
-    ) -> Optional[types.Part]:
-      artifact = await self.artifact_service.load_artifact(
+        version_id: str,
+    ) -> ArtifactVersion:
+      version: int | None = None
+      if version_id != "latest":
+        try:
+          version = int(version_id)
+        except ValueError:
+          raise HTTPException(
+              status_code=422, detail="Invalid version ID"
+          ) from None
+      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,
       )
-      if not artifact:
-        raise HTTPException(status_code=404, detail="Artifact not found")
-      return artifact
+      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/{artifact_name}/versions/metadata",
+        "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{artifact_name:path}/versions/metadata",
         response_model=list[ArtifactVersion],
         response_model_exclude_none=True,
     )
@@ -1258,28 +1269,6 @@ async def list_artifact_versions_metadata(
           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,
-    )
-    async def load_artifact_version(
-        app_name: str,
-        user_id: str,
-        session_id: str,
-        artifact_name: str,
-        version_id: int,
-    ) -> Optional[types.Part]:
-      artifact = await self.artifact_service.load_artifact(
-          app_name=app_name,
-          user_id=user_id,
-          session_id=session_id,
-          filename=artifact_name,
-          version=version_id,
-      )
-      if not artifact:
-        raise HTTPException(status_code=404, detail="Artifact not found")
-      return artifact
-
     @app.post(
         "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts",
         response_model=ArtifactVersion,
@@ -1329,29 +1318,34 @@ 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,
+        "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{artifact_name:path}/versions/{version_id}",
         response_model_exclude_none=True,
     )
-    async def get_artifact_version_metadata(
+    async def load_artifact_version(
         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(
+        version_id: str,
+    ) -> types.Part | None:
+      version: int | None = None
+      if version_id != "latest":
+        try:
+          version = int(version_id)
+        except ValueError:
+          raise HTTPException(
+              status_code=422, detail="Invalid version ID"
+          ) from None
+      artifact = await self.artifact_service.load_artifact(
           app_name=app_name,
           user_id=user_id,
           session_id=session_id,
           filename=artifact_name,
-          version=version_id,
+          version=version,
       )
-      if not artifact_version:
-        raise HTTPException(
-            status_code=404, detail="Artifact version not found"
-        )
-      return artifact_version
+      if not artifact:
+        raise HTTPException(status_code=404, detail="Artifact not found")
+      return artifact
 
     @app.get(
         "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts",
@@ -1365,7 +1359,7 @@ async def list_artifact_names(
       )
 
     @app.get(
-        "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{artifact_name}/versions",
+        "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{artifact_name:path}/versions",
         response_model_exclude_none=True,
     )
     async def list_artifact_versions(
@@ -1378,8 +1372,33 @@ async def list_artifact_versions(
           filename=artifact_name,
       )
 
+    # Keep this catch-all artifact route after the version-specific routes.
+    # Artifact names may contain '/', so {artifact_name:path} would otherwise
+    # capture requests for /versions/... endpoints.
+    @app.get(
+        "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{artifact_name:path}",
+        response_model_exclude_none=True,
+    )
+    async def load_artifact(
+        app_name: str,
+        user_id: str,
+        session_id: str,
+        artifact_name: str,
+        version: int | None = Query(None),
+    ) -> types.Part | None:
+      artifact = await self.artifact_service.load_artifact(
+          app_name=app_name,
+          user_id=user_id,
+          session_id=session_id,
+          filename=artifact_name,
+          version=version,
+      )
+      if not artifact:
+        raise HTTPException(status_code=404, detail="Artifact not found")
+      return artifact
+
     @app.delete(
-        "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{artifact_name}",
+        "/apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{artifact_name:path}",
     )
     async def delete_artifact(
         app_name: str, user_id: str, session_id: str, artifact_name: str

tests/unittests/artifacts/test_artifact_service.py

@@ -263,6 +263,52 @@ async def test_save_load_delete(service_type, artifact_service_factory):
   )
 
 
+@pytest.mark.asyncio
+async def test_in_memory_loads_nested_artifact_reference(
+    artifact_service_factory,
+):
+  """Tests loading an artifact reference whose target name is nested."""
+  artifact_service = artifact_service_factory(ArtifactServiceType.IN_MEMORY)
+  app_name = "app0"
+  user_id = "user0"
+  session_id = "123"
+  target_filename = "folder/file456"
+  target_artifact = types.Part.from_text(text="target")
+
+  await artifact_service.save_artifact(
+      app_name=app_name,
+      user_id=user_id,
+      session_id=session_id,
+      filename=target_filename,
+      artifact=target_artifact,
+  )
+  await artifact_service.save_artifact(
+      app_name=app_name,
+      user_id=user_id,
+      session_id=session_id,
+      filename="reference",
+      artifact=types.Part(
+          file_data=types.FileData(
+              file_uri=(
+                  "artifact://apps/app0/users/user0/sessions/123/artifacts/"
+                  "folder/file456/versions/0"
+              ),
+              mime_type="text/plain",
+          )
+      ),
+  )
+
+  assert (
+      await artifact_service.load_artifact(
+          app_name=app_name,
+          user_id=user_id,
+          session_id=session_id,
+          filename="reference",
+      )
+      == target_artifact
+  )
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
     "service_type",

tests/unittests/artifacts/test_artifact_util.py

@@ -31,6 +31,21 @@ def test_parse_session_scoped_artifact_uri():
   assert parsed.version == 123
 
 
+def test_parse_session_scoped_artifact_uri_with_nested_filename():
+  """Tests parsing a session-scoped artifact URI with a nested filename."""
+  uri = (
+      "artifact://apps/app1/users/user1/sessions/session1/artifacts/"
+      "folder/file1/versions/123"
+  )
+  parsed = artifact_util.parse_artifact_uri(uri)
+  assert parsed is not None
+  assert parsed.app_name == "app1"
+  assert parsed.user_id == "user1"
+  assert parsed.session_id == "session1"
+  assert parsed.filename == "folder/file1"
+  assert parsed.version == 123
+
+
 def test_parse_user_scoped_artifact_uri():
   """Tests parsing a valid user-scoped artifact URI."""
   uri = "artifact://apps/app2/users/user2/artifacts/file2/versions/456"
@@ -43,6 +58,18 @@ def test_parse_user_scoped_artifact_uri():
   assert parsed.version == 456
 
 
+def test_parse_user_scoped_artifact_uri_with_nested_filename():
+  """Tests parsing a user-scoped artifact URI with a nested filename."""
+  uri = "artifact://apps/app2/users/user2/artifacts/folder/file2/versions/456"
+  parsed = artifact_util.parse_artifact_uri(uri)
+  assert parsed is not None
+  assert parsed.app_name == "app2"
+  assert parsed.user_id == "user2"
+  assert parsed.session_id is None
+  assert parsed.filename == "folder/file2"
+  assert parsed.version == 456
+
+
 @pytest.mark.parametrize(
     "invalid_uri",
     [
@@ -51,6 +78,7 @@ def test_parse_user_scoped_artifact_uri():
         "artifact://app1/user1/sessions/session1/artifacts/file1",
         "artifact://apps/app1/users/user1/sessions/session1/artifacts/file1",
         "artifact://apps/app1/users/user1/artifacts/file1",
+        "artifact://apps/app1/users/user1/artifacts/file1/versions/1/extra",
     ],
 )
 def test_parse_invalid_artifact_uri(invalid_uri):