agentengine-sdk-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

ksadk/knowledge_base/client.py

@@ -5,8 +5,9 @@
 
 环境变量:
     KSADK_KB_DATASET_ID: 知识库 ID (必填，存在即启用)
-    KSADK_KB_ACCESS_KEY: AK (可选，默认取 KSYUN_ACCESS_KEY)
-    KSADK_KB_SECRET_KEY: SK (可选，默认取 KSYUN_SECRET_KEY)
+    KSADK_KB_ACCESS_KEY: AK (可选，默认取 KSYUN_ACCESS_KEY / KSYUN_ACCESS_KEY_ID)
+    KSADK_KB_SECRET_KEY: SK (可选，默认取 KSYUN_SECRET_KEY / KSYUN_SECRET_ACCESS_KEY)
+    KSADK_KB_SESSION_TOKEN: STS 临时会话 token (可选，默认取 KSYUN_SESSION_TOKEN)
     KSADK_KB_REGION: 区域 (默认 cn-beijing-6)
     KSADK_KB_ENDPOINT: API 端点 (默认 aicp.api.ksyun.com)
     KSADK_KB_TOP_K: 返回结果数 (默认 5)
@@ -59,6 +60,7 @@ class KnowledgeBaseClient(BaseModel):
         dataset_id: 知识库 ID (DatasetId)
         access_key: 访问密钥 ID (AK)
         secret_key: 访问密钥 (SK)
+        session_token: STS 临时会话 token
         region: API 区域
         endpoint: API 端点
         top_k: 返回结果数
@@ -71,6 +73,7 @@ class KnowledgeBaseClient(BaseModel):
     dataset_id: str
     access_key: str = ""
     secret_key: str = ""
+    session_token: str = ""
     region: str = "cn-beijing-6"
     endpoint: str = "aicp.api.ksyun.com"
     scheme: str = "https"
@@ -79,6 +82,10 @@ class KnowledgeBaseClient(BaseModel):
     score_threshold: float = 0.0
     score_threshold_enabled: bool = False
     reranking_enable: bool = False
+    # 最近一次检索失败原因（成功调用前置空，失败时填充）。供
+    # KnowledgeBaseService.build_context 区分"后端吞错返空"与"真无结果"，
+    # 避免错误伪装成"未找到"注入模型上下文。
+    last_error: str = ""
 
     _aicp_client: Any = None
 
@@ -133,7 +140,9 @@ class KnowledgeBaseClient(BaseModel):
                 "Ensure kingsoftcloud-sdk-python is installed and up to date."
             )
 
-        cred = credential.Credential(self.access_key, self.secret_key)
+        cred = credential.Credential(
+            self.access_key, self.secret_key, self.session_token or None
+        )
 
         http_profile = HttpProfile()
         http_profile.endpoint = self.endpoint
@@ -183,6 +192,7 @@ 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]}")
             return []
 
@@ -225,6 +235,7 @@ class KnowledgeBaseClient(BaseModel):
             f"Searching knowledge base: dataset_id={self.dataset_id}, " f"query='{query[:50]}'"
         )
 
+        self.last_error = ""
         try:
             response = client.call("RetrieveKnowledge", params, options={"IsPostJson": True})
             results = self._parse_response(response)
@@ -233,6 +244,7 @@ class KnowledgeBaseClient(BaseModel):
             )
             return results
         except Exception as e:
+            self.last_error = str(e)
             logger.error(f"Knowledge base search failed: {e}")
             raise
 
@@ -255,12 +267,17 @@ class KnowledgeBaseClient(BaseModel):
         access_key = (
             os.environ.get("KSADK_KB_ACCESS_KEY")
             or os.environ.get("KSYUN_ACCESS_KEY")
+            or os.environ.get("KSYUN_ACCESS_KEY_ID")
             or os.environ.get("KSYUN_SECRET_ID", "")
         )
         secret_key = (
             os.environ.get("KSADK_KB_SECRET_KEY")
             or os.environ.get("KSYUN_SECRET_KEY")
-            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", "")
         )
 
         score_threshold_str = os.environ.get("KSADK_KB_SCORE_THRESHOLD", "")
@@ -275,6 +292,7 @@ class KnowledgeBaseClient(BaseModel):
             dataset_id=dataset_id,
             access_key=access_key,
             secret_key=secret_key,
+            session_token=session_token,
             region=connection["region"],
             endpoint=connection["endpoint"],
             scheme=connection["scheme"],

ksadk/knowledge_base/service.py

@@ -44,6 +44,15 @@ class KnowledgeBaseService:
             self._client = KnowledgeBaseClient.from_env()
         return self._client
 
+    @property
+    def last_error(self) -> str:
+        """最近一次检索失败原因（成功前置空，失败填充；含响应解析失败）。
+
+        供 ``build_context`` 区分"后端吞错/解析失败返空"与"真无结果"。
+        客户端尚未懒加载时视为无错误。
+        """
+        return str(getattr(self._client, "last_error", "") or "")
+
     def search(self, query: str, top_k: Optional[int] = None) -> list[KnowledgeBaseResult]:
         return self._get_client().search(query, top_k)
 
@@ -54,13 +63,31 @@ class KnowledgeBaseService:
             logger.error("search_knowledge failed: %s", exc)
             return f"知识库检索失败: {exc}"
 
-    def build_context(self, query: str, top_k: Optional[int] = None) -> dict[str, str] | None:
+    def build_context(
+        self,
+        query: str,
+        top_k: Optional[int] = None,
+    ) -> dict[str, str] | None:
+        """构造环境知识库上下文。失败时返回 ``formatted_text=""`` + 独立 ``error`` 字段，
+        不把错误字符串塞进 ``formatted_text``（避免错误伪装成知识库正文注入模型）。
+
+        - 检索抛错（网络/鉴权失败）→ except 捕获，返 ``error`` 字段。
+        - 响应解析失败返空列表（``_parse_response``）→ client ``last_error`` 非空，
+          返回 ``error`` 字段。
+        - 真无结果（检索正常返空）→ ``formatted_text`` 为"未找到…"（语义真实，可注入）。
+        """
         normalized = str(query or "").strip()
-        if not normalized:
-            return None
-        if not self.is_configured():
+        if not normalized or not self.is_configured():
             return None
+        try:
+            results = self.search(normalized, top_k)
+        except Exception as exc:
+            logger.error("search_knowledge failed: %s", exc)
+            return {"query": normalized, "formatted_text": "", "error": str(exc)}
+        client_error = self.last_error
+        if not results and client_error:
+            return {"query": normalized, "formatted_text": "", "error": client_error}
         return {
             "query": normalized,
-            "formatted_text": self.search_text(normalized, top_k),
+            "formatted_text": format_knowledge_results(results),
         }

ksadk/managed_a2a_card.py

@@ -0,0 +1,160 @@
+"""Platform-layer discovery-only AgentCard mount for managed A2A Runtime.
+
+v1 scope (this module):
+    Mount ``GET /.well-known/agent-card.json`` only. No JSON-RPC, no identity
+    middleware, no TaskStore/ContextStore/ResumeStore. The card is available as
+    soon as the runtime starts, *before* any A2A Agent is registered, so the
+    server-side ``GetAToAAgentCard(hosted)`` probe can fetch it and break the
+    registration chicken-and-egg cycle.
+
+    The card mounts whenever ``KSADK_A2A_RUNTIME_ID`` (ar-*, available at deploy
+    time) is non-empty. It does **not** depend on ``KSADK_A2A_AGENT_ID``
+    (only known after the A2A Agent is registered). skills default to empty;
+    :func:`ksadk.a2a_card.build_agent_card` fills a ``general`` skill when none
+    are provided.
+
+v2 scope (future, not this module):
+    :class:`ksadk.a2a.bootstrap.AgentEngineA2ABootstrap` adds JSON-RPC on top
+    of the same card and the same identity env. The bootstrap replaces this
+    mount in ``RuntimeAppConfig.a2a`` once shared durable storage and a real
+    gateway-forward identity verifier are in place.
+
+Wire 1.0 conformance:
+    The card is built with :func:`build_agent_card` (same factory used by the
+    full A2A server), so ``supportedInterfaces`` / ``protocolVersion`` /
+    ``defaultInputModes`` / ``defaultOutputModes`` match wire 1.0 exactly.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+from a2a.types import AgentSkill
+from fastapi import FastAPI
+
+from ksadk.a2a_card import build_agent_card
+
+
+def _env(name: str) -> str:
+    return os.getenv(name, "").strip()
+
+
+@dataclass(frozen=True)
+class ManagedA2ACardConfig:
+    """Database-free configuration for the managed discovery-only route."""
+
+    enabled: bool = True
+    base_url: str = "http://127.0.0.1:8000"
+    agent_name: str = "agent"
+    description: str = ""
+    version: str = "0.1.0"
+    skills: Sequence[str | AgentSkill] = ()
+    streaming: bool = False
+    prefer_stream: bool = False
+
+
+@dataclass(frozen=True)
+class ManagedA2ACardMount:
+    """Discovery-only card endpoint; mounted by ``RuntimeAppConfig.a2a``.
+
+    Held as a plain dataclass so ``factory._wire_a2a_if_enabled`` can isinstance
+    it without importing the (optional) ``AgentEngineA2ABootstrap`` class.
+    """
+
+    config: ManagedA2ACardConfig
+
+    def mount(self, app: FastAPI) -> None:
+        """Mount ``GET /.well-known/agent-card.json`` into ``app``.
+
+        Directly registers a FastAPI route returning the card JSON, avoiding
+        ``a2a.server.routes`` (which pulls in the full A2A server stack and its
+        ``culsans`` dependency). The response body is the same AgentCard JSON
+        that ``create_agent_card_routes`` would produce.
+        """
+        card = build_agent_card(
+            name=self.config.agent_name,
+            base_url=self.config.base_url,
+            description=self.config.description,
+            version=self.config.version,
+            skills=self.config.skills or (),
+            streaming=self.config.streaming,
+        )
+
+        def _card_to_dict() -> dict:
+            # a2a.types.AgentCard is a protobuf message; serialize to the same
+            # camelCase JSON wire format the a2a-sdk route produces.
+            from google.protobuf.json_format import MessageToDict
+
+            return MessageToDict(
+                card,
+                preserving_proto_field_name=False,
+                use_integers_for_enums=False,
+                always_print_fields_with_no_presence=True,
+            )
+
+
+        from fastapi import Response
+        from fastapi.responses import JSONResponse
+
+        card_payload = _card_to_dict()
+
+        async def _get_agent_card() -> Response:
+            return JSONResponse(content=card_payload)
+
+        app.add_api_route(
+            "/.well-known/agent-card.json",
+            _get_agent_card,
+            methods=["GET"],
+            name="a2a_agent_card",
+            include_in_schema=False,
+        )
+
+    async def start(self) -> None:
+        """No stores/middleware to initialize in v1."""
+
+        return None
+
+    async def stop(self) -> None:
+        return None
+
+
+def build_managed_a2a_card_if_configured() -> Optional[ManagedA2ACardMount]:
+    """Read the A2A identity env vars and build a discovery-only card mount.
+
+    Returns ``None`` when the runtime is not A2A-capable
+    (``KSADK_A2A_RUNTIME_ID`` empty), so ``run_server`` skips mounting entirely.
+    Returns a mount even when ``KSADK_A2A_AGENT_ID`` is absent: the discovery
+    card is intentionally available *before* the A2A Agent is registered.
+
+    Name/version fallback chain:
+        ``KSADK_A2A_AGENT_NAME`` → ``AGENTENGINE_MANAGED_RUNTIME_NAME`` →
+        ``KSADK_A2A_RUNTIME_ID``.
+    """
+    runtime_id = _env("KSADK_A2A_RUNTIME_ID")
+    if not runtime_id:
+        return None
+
+    base_url = _env("KSADK_A2A_INTERNAL_BASE_URL") or "http://localhost:8080"
+    name = _env("KSADK_A2A_AGENT_NAME") or _env("AGENTENGINE_MANAGED_RUNTIME_NAME") or runtime_id
+    version = _env("KSADK_A2A_AGENT_VERSION") or "0.1.0"
+
+    config = ManagedA2ACardConfig(
+        enabled=True,
+        base_url=base_url,
+        agent_name=name,
+        description="",
+        version=version,
+        skills=(),
+        streaming=False,
+        prefer_stream=False,
+    )
+    return ManagedA2ACardMount(config)
+
+
+__all__ = [
+    "ManagedA2ACardConfig",
+    "ManagedA2ACardMount",
+    "build_managed_a2a_card_if_configured",
+]

ksadk/managed_runtime.py

@@ -131,7 +131,9 @@ def validate_runtime_binary(resolved: ResolvedRuntime) -> str:
     if resolved.name != "codex":
         return ""
     try:
-        from codex_cli_bin import bundled_codex_path
+        from codex_cli_bin import (  # type: ignore[import-not-found, import-untyped]
+            bundled_codex_path,
+        )
 
         codex_bin = bundled_codex_path()
         completed = subprocess.run(
@@ -162,17 +164,22 @@ async def resolve_local_managed_runtime(
     """Resolve and verify the native runtime used by ``ksadk web``."""
     name, requested_version = runtime_config(config)
     if requested_version:
-        resolved = ResolvedRuntime(name=name, version=requested_version, source="manifest")
-        validate_installed_runtime(resolved)
-        return resolved
+        explicit_runtime = ResolvedRuntime(
+            name=name,
+            version=requested_version,
+            source="manifest",
+        )
+        validate_installed_runtime(explicit_runtime)
+        return explicit_runtime
 
+    catalog_runtime: ResolvedRuntime | None = None
     try:
-        resolved = await resolve_managed_runtime(config, region=region)
+        catalog_runtime = await resolve_managed_runtime(config, region=region)
     except ManagedRuntimeError:
-        resolved = None
-    if resolved is not None:
-        validate_installed_runtime(resolved)
-        return resolved
+        pass
+    if catalog_runtime is not None:
+        validate_installed_runtime(catalog_runtime)
+        return catalog_runtime
 
     installed = installed_runtime_version(name)
     if not installed:

ksadk/memory/__init__.py

@@ -54,4 +54,65 @@ def __getattr__(name):
         from ksadk.memory.service import LongTermMemoryService
 
         return LongTermMemoryService
+    # Memory v2（方案 §10）：lazy import，避免在仅用旧 API 时强制加载 SQLite/tiktoken 依赖。
+    _v2_names = {
+        "MemoryRecord",
+        "MemoryCandidate",
+        "MemorySearchRequest",
+        "MemorySearchResult",
+        "MemoryCapabilities",
+        "CoreMemoryBlock",
+        "MemoryDeleteRequest",
+        "MemoryDeleteResult",
+        "MemoryProvider",
+        "MemoryPolicy",
+        "MemoryCoordinator",
+        "MemoryExtractor",
+        "SqliteMemoryProvider",
+        "build_search_request",
+        "recall_to_context_item",
+        "propose_memory_candidates",
+    }
+    if name in _v2_names:
+        if name in {
+            "MemoryRecord",
+            "MemoryCandidate",
+            "MemorySearchRequest",
+            "MemorySearchResult",
+            "MemoryCapabilities",
+            "CoreMemoryBlock",
+            "MemoryDeleteRequest",
+            "MemoryDeleteResult",
+        }:
+            from ksadk.memory import models as _models
+
+            return getattr(_models, name)
+        if name == "MemoryProvider":
+            from ksadk.memory.provider import MemoryProvider
+
+            return MemoryProvider
+        if name == "MemoryPolicy":
+            from ksadk.memory.policy import MemoryPolicy
+
+            return MemoryPolicy
+        if name == "MemoryCoordinator":
+            from ksadk.memory.coordinator import MemoryCoordinator
+
+            return MemoryCoordinator
+        if name in {"build_search_request", "recall_to_context_item"}:
+            from ksadk.memory import coordinator as _coord
+
+            return getattr(_coord, name)
+        if name == "MemoryExtractor":
+            from ksadk.memory.extraction import MemoryExtractor
+
+            return MemoryExtractor
+        if name == "propose_memory_candidates":
+            from ksadk.memory.extraction import propose_memory_candidates
+
+            return propose_memory_candidates
+        if name == "SqliteMemoryProvider":
+            from ksadk.memory.providers.local_sqlite import SqliteMemoryProvider
+
+            return SqliteMemoryProvider
     raise AttributeError(f"module 'ksadk.memory' has no attribute {name!r}")

ksadk/memory/adk/backends/base_ltm_backend.py

@@ -3,22 +3,48 @@
 所有长期记忆后端必须继承此类并实现 save_memory / search_memory 方法。
 
 参考 VeADK: veadk/memory/long_term_memory_backends/base_backend.py
+
+扩展协议（技术改造方案 §7.3）：
+    - search_records: 结构化检索，返回带 memory_id 的 LongTermMemoryRecord
+    - update_memory / delete_memory: 按 ID 原地更新/软删除
+    - capabilities: 声明 backend 支持的能力集合
+    基类对扩展方法提供默认实现：抛出 UnsupportedMemoryOperation 并在
+    capabilities 中不声明对应能力，旧 backend 无需改动即保持兼容。
 """
 
 from abc import ABC, abstractmethod
-from typing import List
+from typing import List, Set
 
 from pydantic import BaseModel
 
+from ksadk.memory.models import (
+    LongTermMemoryRecord,
+    MemoryExtractionStatus,
+    MemoryMutationResult,
+    UnsupportedMemoryOperation,
+)
+
+# 能力常量（§7.3）
+CAP_SEARCH = "search"
+CAP_ADD = "add"
+CAP_FLUSH = "flush"
+CAP_STRUCTURED_SEARCH = "structured_search"
+CAP_UPDATE = "update"
+CAP_DELETE = "delete"
+CAP_SESSION_STATUS = "session_status"
+
 
 class BaseLongTermMemoryBackend(ABC, BaseModel):
     """长期记忆存储后端抽象基类
 
     Attributes:
         index: 索引/集合名称，用于隔离不同应用的记忆数据
+        last_error: 最近一次 search/save 失败的原因。成功调用前置空，失败时填充。
+            上层（LongTermMemoryService.build_context）据此区分"后端吞错返空"与"真无记忆"。
     """
 
     index: str = ""
+    last_error: str = ""
 
     @abstractmethod
     def save_memory(self, user_id: str, event_strings: List[str], **kwargs) -> bool:
@@ -46,3 +72,72 @@ class BaseLongTermMemoryBackend(ABC, BaseModel):
             匹配的记忆字符串列表
         """
         pass
+
+    # ---- 扩展协议（可选能力，默认 unsupported） ----
+
+    def search_records(
+        self,
+        user_id: str,
+        query: str,
+        top_k: int = 5,
+        **kwargs,
+    ) -> List[LongTermMemoryRecord]:
+        """结构化检索：返回带服务端 memory_id 的记录列表。
+
+        不支持的 backend 抛出 UnsupportedMemoryOperation，
+        不得降级为返回正文 hash 伪造的 ID。
+        """
+        raise UnsupportedMemoryOperation(
+            f"{type(self).__name__} does not support structured search"
+        )
+
+    def update_memory(
+        self,
+        *,
+        user_id: str,
+        memory_id: str,
+        content: str,
+        **kwargs,
+    ) -> MemoryMutationResult:
+        """按 memory_id 原地更新记忆正文。
+
+        不支持的 backend 抛出 UnsupportedMemoryOperation，
+        不得静默追加一条新记忆来模拟 update。
+        """
+        raise UnsupportedMemoryOperation(f"{type(self).__name__} does not support update")
+
+    def delete_memory(
+        self,
+        *,
+        user_id: str,
+        memory_id: str,
+        **kwargs,
+    ) -> MemoryMutationResult:
+        """按 memory_id 软删除指定记忆。
+
+        不支持的 backend 抛出 UnsupportedMemoryOperation。
+        """
+        raise UnsupportedMemoryOperation(f"{type(self).__name__} does not support delete")
+
+    def get_extraction_status(
+        self,
+        *,
+        user_id: str,
+        session_id: str,
+    ) -> MemoryExtractionStatus:
+        """查询 Session 后台提取状态（写后确认，§7.7）。
+
+        不支持的 backend 抛出 UnsupportedMemoryOperation。
+        """
+        raise UnsupportedMemoryOperation(f"{type(self).__name__} does not support session status")
+
+    def capabilities(self) -> Set[str]:
+        """声明本 backend 支持的能力集合。
+
+        基类默认只声明基础读写能力；子类按真实实现覆写，
+        声明必须与实际可用方法一致（§11.1）。
+        """
+        return {CAP_SEARCH, CAP_ADD}
+
+    def has_capability(self, capability: str) -> bool:
+        return capability in self.capabilities()

ksadk/memory/adk/backends/http_ltm_backend.py

@@ -52,10 +52,10 @@ class HttpLTMBackend(BaseLongTermMemoryBackend):
     def model_post_init(self, __context) -> None:
         if not self.base_url:
             logger.warning(
-                "HttpLTMBackend: base_url is empty. " "Set KSADK_LTM_HTTP_URL environment variable."
+                "HttpLTMBackend: base_url is empty. Set KSADK_LTM_HTTP_URL environment variable."
             )
         logger.info(
-            f"HttpLTMBackend initialized: base_url={self.base_url[:50]}... " f"index={self.index}"
+            f"HttpLTMBackend initialized: base_url={self.base_url[:50]}... index={self.index}"
         )
 
     @property
@@ -101,13 +101,13 @@ class HttpLTMBackend(BaseLongTermMemoryBackend):
             response.raise_for_status()
 
             logger.info(
-                f"Saved {len(event_strings)} events to remote memory service " f"for user={user_id}"
+                f"Saved {len(event_strings)} events to remote memory service for user={user_id}"
             )
             return True
 
         except httpx.HTTPStatusError as e:
             logger.error(
-                f"HTTP error saving memory: {e.response.status_code} " f"{e.response.text[:200]}"
+                f"HTTP error saving memory: {e.response.status_code} {e.response.text[:200]}"
             )
             return False
         except Exception as e:
@@ -133,6 +133,7 @@ class HttpLTMBackend(BaseLongTermMemoryBackend):
         """
         if not self.base_url:
             logger.warning("HttpLTMBackend: base_url not configured, return empty results.")
+            self.last_error = "base_url not configured"
             return []
 
         try:
@@ -161,7 +162,7 @@ class HttpLTMBackend(BaseLongTermMemoryBackend):
 
         except httpx.HTTPStatusError as e:
             logger.error(
-                f"HTTP error searching memory: {e.response.status_code} " f"{e.response.text[:200]}"
+                f"HTTP error searching memory: {e.response.status_code} {e.response.text[:200]}"
             )
             return []
         except Exception as e:
@@ -173,3 +174,11 @@ class HttpLTMBackend(BaseLongTermMemoryBackend):
         if self._client:
             self._client.close()
             self._client = None
+
+    # ------------------------------------------------------------------
+    # 扩展协议（方案 §7.3）：HTTP backend 为框架预留，结构化能力未定。
+    # 远程 API 对接细节待提供（见 save_memory TODO），因此不声明
+    # structured/update/delete/session_status 能力；search_records 也不降级
+    # 伪造 ID，保持 base 的 UnsupportedMemoryOperation 默认行为。
+    # 远端 schema 确认后，在此接入对应端点并覆写 capabilities()。
+    # ------------------------------------------------------------------