agentengine-sdk-python 0.8.3__py3-none-any.whl → 0.8.4__py3-none-any.whl

ksadk/knowledge_base/client.py

@@ -86,6 +86,8 @@ class KnowledgeBaseClient(BaseModel):
     # KnowledgeBaseService.build_context 区分"后端吞错返空"与"真无结果"，
     # 避免错误伪装成"未找到"注入模型上下文。
     last_error: str = ""
+    last_request_id: str = ""
+    last_http_status: int | None = None
 
     _aicp_client: Any = None
 
@@ -140,9 +142,7 @@ class KnowledgeBaseClient(BaseModel):
                 "Ensure kingsoftcloud-sdk-python is installed and up to date."
             )
 
-        cred = credential.Credential(
-            self.access_key, self.secret_key, self.session_token or None
-        )
+        cred = credential.Credential(self.access_key, self.secret_key, self.session_token or None)
 
         http_profile = HttpProfile()
         http_profile.endpoint = self.endpoint
@@ -153,17 +153,23 @@ class KnowledgeBaseClient(BaseModel):
         client_profile = ClientProfile()
         client_profile.httpProfile = http_profile
 
-        self._aicp_client = aicp_module.AicpClient(cred, self.region, profile=client_profile)
+        owner = self
+
+        class ObservedAicpClient(aicp_module.AicpClient):
+            def _check_status(self, response):
+                # The upstream SDK discards HTTP status when raising its generic
+                # ServerNetworkError. Capture only the status before delegation;
+                # never infer authorization from exception text/response content.
+                owner.last_http_status = response.status
+                return super()._check_status(response)
+
+        self._aicp_client = ObservedAicpClient(cred, self.region, profile=client_profile)
 
         # 强制覆写 API 版本为 RetrieveKnowledge 所需的 2025-11-14
         # SDK 的 _apiVersion 由导入的模块版本决定，可能不匹配
         self._aicp_client._apiVersion = "2025-11-14"
 
-        logger.info(
-            f"KnowledgeBaseClient initialized: "
-            f"dataset_id={self.dataset_id}, region={self.region}, "
-            f"endpoint={self.endpoint}"
-        )
+        logger.debug("KnowledgeBaseClient initialized")
         return self._aicp_client
 
     def _build_params(self, query: str, top_k: Optional[int] = None) -> dict:
@@ -192,11 +198,41 @@ class KnowledgeBaseClient(BaseModel):
         try:
             data = json.loads(response) if isinstance(response, str) else response
         except (json.JSONDecodeError, TypeError):
-            self.last_error = f"Failed to parse response: {str(response)[:200]}"
-            logger.error(f"Failed to parse response: {str(response)[:200]}")
+            self.last_error = "Invalid knowledge response JSON"
+            logger.error("Invalid knowledge response JSON")
+            return []
+
+        if not isinstance(data, dict):
+            self.last_error = "Knowledge response must be an object"
+            return []
+        metadata = data.get("ResponseMetadata") or {}
+        if not isinstance(metadata, dict):
+            self.last_error = "Invalid knowledge response metadata"
+            return []
+        request_id = data.get("RequestId") or metadata.get("RequestId")
+        self.last_request_id = (
+            request_id if isinstance(request_id, str) and len(request_id) <= 256 else ""
+        )
+        code = data.get("Code")
+        if "Code" in data:
+            valid_code = (
+                (type(code) is int and code in {0, 200})
+                or (type(code) is str and code in {"0", "200"})
+            )
+            if not valid_code:
+                self.last_error = "Knowledge service rejected the request"
+                return []
+        if data.get("Error") or metadata.get("Error"):
+            self.last_error = "Knowledge service rejected the request"
             return []
 
-        records = data.get("Records", [])
+        if "Records" not in data:
+            self.last_error = "Knowledge response omitted records"
+            return []
+        records = data["Records"]
+        if not isinstance(records, list):
+            self.last_error = "Invalid knowledge records"
+            return []
         results = []
 
         for record in records:
@@ -228,24 +264,19 @@ class KnowledgeBaseClient(BaseModel):
         Returns:
             匹配的文档片段列表
         """
-        client = self._get_client()
-        params = self._build_params(query, top_k)
-
-        logger.info(
-            f"Searching knowledge base: dataset_id={self.dataset_id}, " f"query='{query[:50]}'"
-        )
-
         self.last_error = ""
+        self.last_request_id = ""
+        self.last_http_status = None
         try:
+            client = self._get_client()
+            params = self._build_params(query, top_k)
             response = client.call("RetrieveKnowledge", params, options={"IsPostJson": True})
             results = self._parse_response(response)
-            logger.info(
-                f"Knowledge base returned {len(results)} results " f"for query='{query[:50]}'"
-            )
+            logger.debug("Knowledge base returned %d results", len(results))
             return results
         except Exception as e:
             self.last_error = str(e)
-            logger.error(f"Knowledge base search failed: {e}")
+            logger.error("Knowledge base search failed (%s)", type(e).__name__)
             raise
 
     @classmethod
@@ -261,7 +292,7 @@ class KnowledgeBaseClient(BaseModel):
         dataset_id = os.environ.get("KSADK_KB_DATASET_ID", "")
         if not dataset_id:
             raise ValueError(
-                "KSADK_KB_DATASET_ID environment variable is required " "to enable knowledge base."
+                "KSADK_KB_DATASET_ID environment variable is required to enable knowledge base."
             )
 
         access_key = (
@@ -275,9 +306,8 @@ class KnowledgeBaseClient(BaseModel):
             or os.environ.get("KSYUN_SECRET_KEY")
             or os.environ.get("KSYUN_SECRET_ACCESS_KEY", "")
         )
-        session_token = (
-            os.environ.get("KSADK_KB_SESSION_TOKEN")
-            or os.environ.get("KSYUN_SESSION_TOKEN", "")
+        session_token = os.environ.get("KSADK_KB_SESSION_TOKEN") or os.environ.get(
+            "KSYUN_SESSION_TOKEN", ""
         )
 
         score_threshold_str = os.environ.get("KSADK_KB_SCORE_THRESHOLD", "")

ksadk/mcp_runtime/__init__.py

@@ -3,11 +3,12 @@ from __future__ import annotations
 import inspect
 import json
 import os
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any, Coroutine, Sequence, cast
 from urllib.parse import urlparse
 
 import httpx
+from pydantic import Field
 
 from ksadk.compat.adk_compat import (
     CheckableMcpHttpClientFactory,
@@ -21,8 +22,8 @@ MCP_TOOLSET_KEY_ATTR = "_ksadk_mcp_toolset_key"
 @dataclass(frozen=True)
 class MCPServerConfig:
     name: str
-    url: str
-    api_key: str | None = None
+    url: str = field(repr=False)
+    api_key: str | None = field(default=None, repr=False)
     tool_filter: tuple[str, ...] = ()
     tool_name_prefix: str | None = None
 
@@ -68,7 +69,14 @@ def build_connection_params(
     kwargs["httpx_client_factory"] = httpx_client_factory or _default_httpx_client_factory(
         config.url
     )
-    return StreamableHTTPConnectionParams(**kwargs)
+    return _RedactedStreamableHTTPConnectionParams(**kwargs)
+
+
+class _RedactedStreamableHTTPConnectionParams(StreamableHTTPConnectionParams):
+    """Keep process-scoped MCP connection material out of debug reprs."""
+
+    url: str = Field(repr=False)
+    headers: dict[str, Any] | None = Field(default=None, repr=False)
 
 
 def build_mcp_toolset(

ksadk/memory/adk/backends/sdk_ltm_backend.py

@@ -52,7 +52,8 @@ DEFAULT_SCENE_ID = "_sys_general"
 # "记忆不存在"识别模式（方案 §17.4：准确错误码待真实 fixture 固化，
 # 首版按保守中英文模式匹配，fixture 到位后收敛为精确匹配）。
 _NOT_EXIST_RE = re.compile(
-    r"not[ _]?exist|does not exist|memory.*不存在|记忆不存在|记忆已被删除|resourcenotfound|notfound",
+    r"not[ _]?exist|does not exist|memory.*不存在|记忆不存在|记忆已被删除|"
+    r"resourcenotfound|notfound",
     re.IGNORECASE,
 )
 
@@ -98,6 +99,7 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
     agent_id: str = ""
     scene_id: str = DEFAULT_SCENE_ID
     last_error: str = ""
+    last_http_status: int | None = None
     last_create_response: dict[str, Any] = Field(default_factory=dict)
     last_session_status: dict[str, Any] = Field(default_factory=dict)
 
@@ -176,7 +178,16 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
         client_profile = ClientProfile()
         client_profile.httpProfile = http_profile
 
-        self._aicp_client = aicp_module.AicpClient(cred, self.region, profile=client_profile)
+        owner = self
+
+        class ObservedAicpClient(aicp_module.AicpClient):
+            def _check_status(self, response):
+                # Preserve the status that the upstream SDK's generic exception
+                # otherwise discards. No response content is used as authority.
+                owner.last_http_status = response.status
+                return super()._check_status(response)
+
+        self._aicp_client = ObservedAicpClient(cred, self.region, profile=client_profile)
 
         # 强制覆写 API 版本为记忆库 API 所需的 2025-11-14
         self._aicp_client._apiVersion = "2025-11-14"
@@ -246,6 +257,7 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
 
         try:
             self.last_error = ""
+            self.last_create_response = {}
             conversation = self._build_conversation(event_strings)
             if not conversation:
                 logger.info("No valid conversation items to save")
@@ -278,6 +290,11 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
 
             response = client.call("CreateMemorySdk", params, options={"IsPostJson": True})
             self.last_create_response = self._parse_json_response(response) or {}
+            if kwargs.get("strict", False):
+                data = self.last_create_response
+                if not self._confirmed_mutation_response(data):
+                    self.last_error = "MEMORY_WRITE_RESPONSE_UNKNOWN"
+                    return False
             self.last_session_status = {
                 "SessionId": session_id,
                 "AgentUserId": user_id,
@@ -290,8 +307,8 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             return True
 
         except Exception as e:
-            self.last_error = str(e)
-            logger.error(f"CreateMemorySdk failed: {e}")
+            self.last_error = "MEMORY_WRITE_UNKNOWN" if kwargs.get("strict", False) else str(e)
+            logger.error("CreateMemorySdk did not return a confirmed acknowledgment")
             return False
 
     def search_memory(self, user_id: str, query: str, top_k: int = 5, **kwargs) -> list[str]:
@@ -379,7 +396,9 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             "SceneId": self._effective_scene_id(),
         }
         response = client.call("QueryMemorySdk", params, options={"IsPostJson": True})
-        records = self._parse_query_records_response(response, user_id=user_id)
+        records = self._parse_query_records_response(
+            response, user_id=user_id, strict=kwargs.get("strict", False)
+        )
         logger.info(
             f"QueryMemorySdk structured: user={user_id}, records={len(records)}"
         )
@@ -452,9 +471,16 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             )
 
         data = self._parse_json_response(response)
+        if kwargs.get("strict", False) and not self._confirmed_mutation_response(data):
+            return MemoryMutationResult(
+                ok=False, memory_id=memory_id, status="failed",
+                message="记忆更新结果未确认",
+            )
         response_memory_id = self._parse_new_memory_id(data)
         new_memory_id = response_memory_id
-        if not response_memory_id or response_memory_id == memory_id:
+        if not kwargs.get("strict", False) and (
+            not response_memory_id or response_memory_id == memory_id
+        ):
             # The service can merge an edited memory into another record while
             # returning no new ID (or echoing the old one).  Do not expose that
             # stale handle to callers: confirm the current handle by listing
@@ -512,7 +538,7 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             "AgentUserId": user_id,
         }
         try:
-            client.call("DeleteMemory", params, options={"IsPostJson": True})
+            response = client.call("DeleteMemory", params, options={"IsPostJson": True})
         except Exception as exc:
             if self._is_not_exist_error(exc):
                 return MemoryMutationResult(
@@ -529,6 +555,13 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
                 status="failed",
                 message="记忆删除失败",
             )
+        if kwargs.get("strict", False) and not self._confirmed_mutation_response(
+            self._parse_json_response(response)
+        ):
+            return MemoryMutationResult(
+                ok=False, memory_id=memory_id, status="failed",
+                message="记忆删除结果未确认",
+            )
         return MemoryMutationResult(
             ok=True,
             memory_id=memory_id,
@@ -536,6 +569,19 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             message="已删除",
         )
 
+    @staticmethod
+    def _confirmed_mutation_response(data: Any) -> bool:
+        metadata = data.get("ResponseMetadata", {}) if isinstance(data, dict) else {}
+        return bool(
+            isinstance(data, dict) and isinstance(metadata, dict)
+            and not data.get("Error") and not metadata.get("Error")
+            and ("Success" not in data or data["Success"] is True)
+            and type(data.get("Code")) is not bool
+            and data.get("Code") in (None, 0, "0", 200, "200")
+            and isinstance(data.get("RequestId", metadata.get("RequestId")), str)
+            and data.get("RequestId", metadata.get("RequestId"))
+        )
+
     def get_extraction_status(
         self,
         *,
@@ -547,16 +593,21 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
         State 映射 0/50/100/-50/-100；未找到 Session 返回 unknown。
         searchable 需 Service 层结合 ListMemories 确认后置位。
         """
-        item = self.get_session_status(user_id=user_id, session_id=session_id)
+        item, error_code = self._lookup_session_status(user_id=user_id, session_id=session_id)
         if not isinstance(item, dict):
             return MemoryExtractionStatus(
                 session_id=session_id,
                 state=None,
                 status="unknown",
-                message="Session 状态未知",
+                message="Session 状态查询未完成" if error_code else "Session 状态未知",
+                error_code=error_code,
             )
         state = item.get("State")
-        state_int = int(state) if isinstance(state, (int, float, str)) and str(state).lstrip("-").isdigit() else None
+        state_int = (
+            int(state)
+            if isinstance(state, (int, float, str)) and str(state).lstrip("-").isdigit()
+            else None
+        )
         status = map_session_state(state_int)
         message = {
             "queued": "排队中",
@@ -617,19 +668,29 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
         return ""
 
     def _parse_query_records_response(
-        self, response: Any, *, user_id: str
+        self, response: Any, *, user_id: str, strict: bool = False
     ) -> List[LongTermMemoryRecord]:
         """严格解析 QueryMemorySdk 结构化响应：Data[].Memories[]。"""
         try:
             data = self._parse_json_response(response)
         except (json.JSONDecodeError, TypeError):
+            if strict:
+                raise ValueError("MEMORY_SEARCH_RESPONSE_INVALID") from None
             logger.error("QueryMemorySdk records: invalid JSON response")
             return []
         if not isinstance(data, dict):
+            if strict:
+                raise ValueError("MEMORY_SEARCH_RESPONSE_INVALID")
             logger.error("QueryMemorySdk records: unexpected payload type")
             return []
         items = data.get("Data")
+        if strict and (
+            data.get("Error") or data.get("Code") not in (None, 0, "0", 200, "200")
+        ):
+            raise ValueError("MEMORY_SEARCH_RESPONSE_INVALID")
         if not isinstance(items, list):
+            if strict:
+                raise ValueError("MEMORY_SEARCH_RESPONSE_INVALID")
             logger.warning(
                 "QueryMemorySdk records: unknown schema, keys=%s; fail closed",
                 list(data.keys()),
@@ -639,11 +700,15 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
         for item in items:
             memories = item.get("Memories") if isinstance(item, dict) else None
             if not isinstance(memories, list):
+                if strict:
+                    raise ValueError("MEMORY_SEARCH_RESPONSE_INVALID")
                 continue
             for memory in memories:
                 record = self._record_from_item(memory, user_id=user_id)
                 if record is not None:
                     records.append(record)
+                elif strict:
+                    raise ValueError("MEMORY_SEARCH_RESPONSE_INVALID")
         return records
 
     def _parse_list_memories_response(
@@ -717,38 +782,93 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
         user_id: str,
         session_id: str,
         page_size: int = 20,
+        max_pages: int = 20,
     ) -> dict[str, Any] | None:
-        """Return raw AICP session status for a recently submitted memory session."""
-        if not session_id:
-            return None
-
-        client = self._get_client()
-        memory_collection_id = self._effective_memory_collection_id()
-        params = {
-            "MemoryCollectionId": memory_collection_id,
-            "AgentUserId": user_id,
-            "Page": 1,
-            "PageSize": page_size,
-        }
-
+        """Look up a session across bounded pages; preserve legacy raw return shape."""
+        item, error_code = self._lookup_session_status(
+            user_id=user_id, session_id=session_id, page_size=page_size, max_pages=max_pages
+        )
+        self.last_error = error_code
+        self.last_session_status = dict(item or {})
+        return item
+
+    def _lookup_session_status(
+        self, *, user_id: str, session_id: str, page_size: int = 20, max_pages: int = 20
+    ) -> tuple[dict[str, Any] | None, str]:
+        if (type(page_size) is not int or not 1 <= page_size <= 100
+                or type(max_pages) is not int or not 1 <= max_pages <= 1000):
+            raise ValueError("Invalid memory status pagination budget")
+        if not user_id or not session_id:
+            return None, "MEMORY_STATUS_IDENTITY_REQUIRED"
+        seen: set[str] = set()
+        previous_total = None
         try:
-            response = client.call("ListSessions", params, options={"IsPostJson": True})
-            data = self._parse_json_response(response)
-        except Exception as e:
-            self.last_error = str(e)
-            logger.warning(f"ListSessions failed while checking memory status: {e}")
-            return None
-
-        payload = data.get("Data") if isinstance(data, dict) else None
-        items = payload.get("Items") if isinstance(payload, dict) else None
-        if not isinstance(items, list):
-            return None
-
-        for item in items:
-            if isinstance(item, dict) and item.get("SessionId") == session_id:
-                self.last_session_status = item
-                return item
-        return None
+            client = self._get_client()
+            collection = self._effective_memory_collection_id()
+            for page in range(1, max_pages + 1):
+                response = client.call("ListSessions", {
+                    "MemoryCollectionId": collection, "AgentUserId": user_id,
+                    "Page": page, "PageSize": page_size,
+                }, options={"IsPostJson": True})
+                data = self._parse_json_response(response)
+                metadata = data.get("ResponseMetadata", {}) if isinstance(data, dict) else {}
+                if (
+                    not isinstance(data, dict) or data.get("Error")
+                    or not isinstance(metadata, dict) or metadata.get("Error")
+                    or type(data.get("Code")) is bool
+                    or data.get("Code") not in (None, 0, "0", 200, "200")
+                ):
+                    return None, "MEMORY_STATUS_QUERY_FAILED"
+                payload = data.get("Data")
+                items = payload.get("Items") if isinstance(payload, dict) else None
+                if not isinstance(items, list) or len(items) > page_size or any(
+                    not isinstance(item, dict) or not isinstance(item.get("SessionId"), str)
+                    or not item["SessionId"] for item in items
+                ):
+                    return None, "MEMORY_STATUS_RESPONSE_INVALID"
+                total_count = payload.get("TotalCount")
+                total_alias = payload.get("Total")
+                if total_count is not None and total_alias is not None:
+                    normalized_count = (
+                        int(total_count)
+                        if isinstance(total_count, str) and total_count.isdigit()
+                        else total_count
+                    )
+                    normalized_alias = (
+                        int(total_alias)
+                        if isinstance(total_alias, str) and total_alias.isdigit()
+                        else total_alias
+                    )
+                    if normalized_count != normalized_alias:
+                        return None, "MEMORY_STATUS_RESPONSE_INVALID"
+                total = total_count if total_count is not None else total_alias
+                if isinstance(total, str) and total.isdigit():
+                    total = int(total)
+                if total is not None and (type(total) is not int or total < 0):
+                    return None, "MEMORY_STATUS_RESPONSE_INVALID"
+                if page > 1 and total != previous_total:
+                    return None, "MEMORY_STATUS_DIRECTORY_CHANGED"
+                previous_total = total
+                ids = [item["SessionId"] for item in items]
+                if len(set(ids)) != len(ids) or seen.intersection(ids):
+                    return None, "MEMORY_STATUS_PAGINATION_REPEATED"
+                seen.update(ids)
+                for item in items:
+                    if item["SessionId"] == session_id:
+                        if (
+                            item.get("AgentUserId", user_id) != user_id
+                            or item.get("MemoryCollectionId", collection) != collection
+                        ):
+                            return None, "MEMORY_STATUS_SCOPE_MISMATCH"
+                        return dict(item), ""
+                if total is not None and len(seen) >= total:
+                    return None, "" if len(seen) == total else "MEMORY_STATUS_DIRECTORY_CHANGED"
+                if len(items) < page_size:
+                    return None, "" if total is None else "MEMORY_STATUS_DIRECTORY_INCOMPLETE"
+            return None, "MEMORY_STATUS_PAGE_BUDGET_EXHAUSTED"
+        except Exception:
+            logger.warning("ListSessions status query failed")
+            return None, "MEMORY_STATUS_QUERY_FAILED"
 
     def _parse_query_response(self, response: str) -> list[str]:
         """解析 QueryMemorySdk 响应

ksadk/memory/adk/resilient_session_service.py

@@ -38,11 +38,11 @@ class ResilientADKSessionService(BaseSessionService):
             return
         self._primary_enabled = False
         logger.error(
-            "ADK session persistence degraded; using in-memory live session: %s",
-            exc,
+            "ADK session persistence degraded; using in-memory live session",
             extra={
                 "session_backend_state": "degraded",
                 "session_backend": type(self.primary).__name__,
+                "session_backend_reason_code": "SESSION_STORE_UNREACHABLE",
             },
         )
         self._start_probe()
@@ -63,22 +63,30 @@ class ResilientADKSessionService(BaseSessionService):
             await asyncio.sleep(self._probe_interval_seconds)
             if self._primary_enabled:
                 break
-            try:
-                await self.primary.get_session(
-                    app_name="__ksadk_probe__",
-                    user_id="__ksadk_probe__",
-                    session_id="__ksadk_probe__",
-                )
-            except Exception:
-                continue
-            self._primary_enabled = True
-            logger.info(
-                "ADK session persistence recovered; durable backend re-enabled",
-                extra={
-                    "session_backend_state": "recovered",
-                    "session_backend": type(self.primary).__name__,
-                },
+            await self.refresh_persistence_capability()
+
+    async def refresh_persistence_capability(self) -> bool:
+        """Probe a degraded ADK database service without rebuilding the runner."""
+        if self._primary_enabled:
+            return True
+        try:
+            await self.primary.get_session(
+                app_name="__ksadk_probe__",
+                user_id="__ksadk_probe__",
+                session_id="__ksadk_probe__",
             )
+        except Exception:
+            return False
+        self._primary_enabled = True
+        logger.info(
+            "ADK session persistence recovered; durable backend re-enabled",
+            extra={
+                "session_backend_state": "recovered",
+                "session_backend": type(self.primary).__name__,
+                "session_backend_reason_code": "READY",
+            },
+        )
+        return True
 
     @staticmethod
     def _key(app_name: str, user_id: str, session_id: str) -> tuple[str, str, str]:

ksadk/memory/adk/short_term_memory.py

@@ -33,6 +33,7 @@ from ksadk.compat.adk_compat import (
     InMemorySessionService,
     Session,
 )
+from ksadk.sessions.topology import StorageTarget, resolve_persistence_topology
 
 logger = logging.getLogger(__name__)
 
@@ -55,14 +56,20 @@ def _normalize_backend_name(backend: str) -> str:
 
 
 def _normalize_database_url(db_url: str) -> str:
-    """Normalize sqlite URLs for google.adk DatabaseSessionService.
+    """Normalize database URLs for google.adk DatabaseSessionService.
 
-    ADK uses SQLAlchemy async engines underneath, so plain `sqlite:///...`
-    URLs fail while `sqlite+aiosqlite:///...` works.
+    ADK uses SQLAlchemy async engines underneath, so plain PostgreSQL and
+    SQLite URLs need their corresponding async driver schemes.
     """
     normalized = str(db_url or "").strip()
     if not normalized:
         return ""
+    if normalized.startswith("postgresql+asyncpg:"):
+        return normalized
+    if normalized.startswith("postgresql:"):
+        return "postgresql+asyncpg:" + normalized[len("postgresql:") :]
+    if normalized.startswith("postgres:"):
+        return "postgresql+asyncpg:" + normalized[len("postgres:") :]
     if normalized.startswith("sqlite+aiosqlite:"):
         return normalized
     if normalized.startswith("sqlite:"):
@@ -159,9 +166,7 @@ class ShortTermMemory(BaseModel):
             self._session_service = ResilientADKSessionService(
                 DatabaseSessionService(db_url=normalized_db_url, **service_kwargs)
             )
-            logger.info(
-                f"ShortTermMemory: using DatabaseSessionService " f"({normalized_db_url[:30]}...)"
-            )
+            logger.info("ShortTermMemory: using DatabaseSessionService")
         except ImportError:
             logger.warning(
                 "DatabaseSessionService not available. "
@@ -170,10 +175,11 @@ class ShortTermMemory(BaseModel):
             )
             self._session_service = InMemorySessionService()
             self.backend = "local"
-        except Exception as e:
+        except Exception as exc:
             logger.error(
-                f"Failed to create DatabaseSessionService: {e}. "
-                f"Falling back to InMemorySessionService."
+                "Failed to create DatabaseSessionService (%s); "
+                "falling back to InMemorySessionService.",
+                type(exc).__name__,
             )
             self._session_service = InMemorySessionService()
             self.backend = "local"
@@ -237,6 +243,13 @@ class ShortTermMemory(BaseModel):
             logger.error(f"Failed to create session: {e}")
             return None
 
+    @classmethod
+    def from_persistence_target(cls, target: StorageTarget) -> "ShortTermMemory":
+        """Build ADK-native state from an effective Checkpoint storage target."""
+        if target.backend == "postgres" and target.dsn:
+            return cls(backend="database", db_url=_normalize_database_url(target.dsn))
+        return cls(backend="local")
+
     @classmethod
     def from_env(cls) -> "ShortTermMemory":
         """从环境变量创建 ShortTermMemory
@@ -251,6 +264,10 @@ class ShortTermMemory(BaseModel):
             KSADK_SESSION_BACKEND: 统一 session backend fallback
             KSADK_SESSION_DSN: 统一 session DSN fallback
         """
+        topology = resolve_persistence_topology(framework="adk")
+        if topology.checkpoint.backend == "postgres" and topology.checkpoint.dsn:
+            return cls.from_persistence_target(topology.checkpoint)
+
         explicit_backend = _normalize_backend_name(
             _env_first(
                 "KSADK_ADK_SESSION_BACKEND",