agentengine-sdk-python 0.7.0__py3-none-any.whl → 0.8.1__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"
@@ -101,9 +104,13 @@ class KnowledgeBaseClient(BaseModel):
             return self._aicp_client
 
         try:
-            from ksyun.common import credential
-            from ksyun.common.profile.client_profile import ClientProfile
-            from ksyun.common.profile.http_profile import HttpProfile
+            from ksyun.common import credential  # type: ignore[import-untyped]
+            from ksyun.common.profile.client_profile import (  # type: ignore[import-untyped]
+                ClientProfile,
+            )
+            from ksyun.common.profile.http_profile import (  # type: ignore[import-untyped]
+                HttpProfile,
+            )
         except ImportError:
             raise ImportError(
                 "kingsoftcloud-sdk-python is required for knowledge base. "
@@ -129,7 +136,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
@@ -140,9 +149,7 @@ class KnowledgeBaseClient(BaseModel):
         client_profile = ClientProfile()
         client_profile.httpProfile = http_profile
 
-        self._aicp_client = aicp_module.AicpClient(
-            cred, self.region, profile=client_profile
-        )
+        self._aicp_client = aicp_module.AicpClient(cred, self.region, profile=client_profile)
 
         # 强制覆写 API 版本为 RetrieveKnowledge 所需的 2025-11-14
         # SDK 的 _apiVersion 由导入的模块版本决定，可能不匹配
@@ -159,19 +166,20 @@ class KnowledgeBaseClient(BaseModel):
         """构建 RetrieveKnowledge 请求参数 (JSON 嵌套格式)"""
         effective_top_k = top_k if top_k is not None else self.top_k
 
-        params = {
+        retrieval_model: dict[str, Any] = {
+            "SearchMethod": self.search_method,
+            "TopK": effective_top_k,
+            "RerankingEnable": self.reranking_enable,
+        }
+        params: dict[str, Any] = {
             "DatasetId": self.dataset_id,
             "Query": query,
-            "RetrievalModel": {
-                "SearchMethod": self.search_method,
-                "TopK": effective_top_k,
-                "RerankingEnable": self.reranking_enable,
-            },
+            "RetrievalModel": retrieval_model,
         }
 
         if self.score_threshold_enabled:
-            params["RetrievalModel"]["ScoreThresholdEnabled"] = True
-            params["RetrievalModel"]["ScoreThreshold"] = self.score_threshold
+            retrieval_model["ScoreThresholdEnabled"] = True
+            retrieval_model["ScoreThreshold"] = self.score_threshold
 
         return params
 
@@ -205,9 +213,7 @@ class KnowledgeBaseClient(BaseModel):
 
         return results
 
-    def search(
-        self, query: str, top_k: Optional[int] = None
-    ) -> List[KnowledgeBaseResult]:
+    def search(self, query: str, top_k: Optional[int] = None) -> List[KnowledgeBaseResult]:
         """检索知识库
 
         Args:
@@ -221,18 +227,14 @@ class KnowledgeBaseClient(BaseModel):
         params = self._build_params(query, top_k)
 
         logger.info(
-            f"Searching knowledge base: dataset_id={self.dataset_id}, "
-            f"query='{query[:50]}'"
+            f"Searching knowledge base: dataset_id={self.dataset_id}, " f"query='{query[:50]}'"
         )
 
         try:
-            response = client.call(
-                "RetrieveKnowledge", params, options={"IsPostJson": True}
-            )
+            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]}'"
+                f"Knowledge base returned {len(results)} results " f"for query='{query[:50]}'"
             )
             return results
         except Exception as e:
@@ -252,19 +254,23 @@ 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 = (
             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", "")
@@ -279,13 +285,12 @@ 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"],
             top_k=int(os.environ.get("KSADK_KB_TOP_K", "5")),
-            search_method=os.environ.get(
-                "KSADK_KB_SEARCH_METHOD", "intelligence_search"
-            ),
+            search_method=os.environ.get("KSADK_KB_SEARCH_METHOD", "intelligence_search"),
             score_threshold=score_threshold,
             score_threshold_enabled=score_threshold_enabled,
             reranking_enable=reranking_enable,

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

@@ -0,0 +1,195 @@
+"""Managed runtime configuration and version resolution."""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as package_version
+from typing import Any
+
+
+class ManagedRuntimeError(ValueError):
+    """Raised when a managed runtime contract cannot be resolved safely."""
+
+
+@dataclass(frozen=True)
+class ResolvedRuntime:
+    name: str
+    version: str
+    source: str
+    package_requirement: str = ""
+
+
+def runtime_config(config: dict[str, Any]) -> tuple[str, str]:
+    value = config.get("runtime")
+    if not isinstance(value, dict):
+        raise ManagedRuntimeError("ManagedRuntime 项目缺少 runtime 配置")
+    name = str(value.get("name") or "").strip().lower()
+    requested_version = str(value.get("version") or "").strip()
+    if not name:
+        raise ManagedRuntimeError("ManagedRuntime 项目缺少 runtime.name")
+    return name, requested_version
+
+
+def extract_bootstrap_runtime(
+    bootstrap: dict[str, Any] | None,
+    runtime_name: str,
+) -> ResolvedRuntime | None:
+    if not isinstance(bootstrap, dict):
+        return None
+    configs = bootstrap.get("configs") or bootstrap.get("Configs")
+    if not isinstance(configs, dict):
+        return None
+    version = str(
+        configs.get("runtime.default_version")
+        or configs.get(f"runtime.{runtime_name}.default_version")
+        or ""
+    ).strip()
+    if not version:
+        return None
+    package = str(
+        configs.get("runtime.package")
+        or configs.get(f"runtime.{runtime_name}.package")
+        or ""
+    ).strip()
+    return ResolvedRuntime(
+        name=runtime_name,
+        version=version,
+        source="server",
+        package_requirement=package,
+    )
+
+
+async def resolve_managed_runtime(
+    config: dict[str, Any],
+    *,
+    region: str,
+    bootstrap: dict[str, Any] | None = None,
+) -> ResolvedRuntime:
+    name, requested_version = runtime_config(config)
+    if requested_version:
+        return ResolvedRuntime(name=name, version=requested_version, source="manifest")
+
+    resolved = extract_bootstrap_runtime(bootstrap, name)
+    if resolved is not None:
+        return resolved
+
+    if bootstrap is None:
+        from ksadk.api.client import AgentEngineClient
+        from ksadk.version import VERSION as CLI_VERSION
+
+        try:
+            async with AgentEngineClient(region=region) as client:
+                payload = await client.get_client_bootstrap_config(
+                    product="agentengine",
+                    framework=name,
+                    region=region,
+                    client_type="cli",
+                    client_version=CLI_VERSION,
+                    ignore_dry_run=True,
+                )
+        except Exception as exc:
+            raise ManagedRuntimeError(
+                "无法从 AgentEngine 获取 ManagedRuntime 默认版本；"
+                "请连接服务端或在 agentengine.yaml 中显式配置 runtime.version"
+            ) from exc
+        resolved = extract_bootstrap_runtime(payload, name)
+        if resolved is not None:
+            return resolved
+
+    raise ManagedRuntimeError(
+        f"AgentEngine 未下发 {name} 的默认 Runtime 版本；"
+        "请配置服务端 Runtime catalog 或显式设置 runtime.version"
+    )
+
+
+def installed_runtime_version(runtime_name: str) -> str:
+    package_name = {"codex": "openai-codex"}.get(runtime_name, runtime_name)
+    try:
+        return package_version(package_name)
+    except PackageNotFoundError:
+        return ""
+
+
+def validate_installed_runtime(resolved: ResolvedRuntime) -> str:
+    installed = installed_runtime_version(resolved.name)
+    if not installed:
+        raise ManagedRuntimeError(
+            f"本地缺少 {resolved.name} runtime；请安装 `pip install 'ksadk[{resolved.name}]'`"
+        )
+    if resolved.version and installed != resolved.version:
+        raise ManagedRuntimeError(
+            f"本地 {resolved.name} runtime 版本为 {installed}，"
+            f"配置要求 {resolved.version}；请安装匹配版本后重试"
+        )
+    validate_runtime_binary(resolved)
+    return installed
+
+
+def validate_runtime_binary(resolved: ResolvedRuntime) -> str:
+    if resolved.name != "codex":
+        return ""
+    try:
+        from codex_cli_bin import (  # type: ignore[import-not-found, import-untyped]
+            bundled_codex_path,
+        )
+
+        codex_bin = bundled_codex_path()
+        completed = subprocess.run(
+            [str(codex_bin), "--version"],
+            check=True,
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+    except (ImportError, OSError, subprocess.SubprocessError) as exc:
+        raise ManagedRuntimeError(
+            "本地 Codex 平台二进制不可用；请重新安装 `pip install --force-reinstall "
+            "'ksadk[codex]'`"
+        ) from exc
+    output = f"{completed.stdout}\n{completed.stderr}".strip()
+    if resolved.version and resolved.version not in output:
+        raise ManagedRuntimeError(
+            f"Codex CLI 版本输出为 {output or '(empty)'}，配置要求 {resolved.version}"
+        )
+    return output
+
+
+async def resolve_local_managed_runtime(
+    config: dict[str, Any],
+    *,
+    region: str,
+) -> ResolvedRuntime:
+    """Resolve and verify the native runtime used by ``ksadk web``."""
+    name, requested_version = runtime_config(config)
+    if requested_version:
+        explicit_runtime = ResolvedRuntime(
+            name=name,
+            version=requested_version,
+            source="manifest",
+        )
+        validate_installed_runtime(explicit_runtime)
+        return explicit_runtime
+
+    catalog_runtime: ResolvedRuntime | None = None
+    try:
+        catalog_runtime = await resolve_managed_runtime(config, region=region)
+    except ManagedRuntimeError:
+        pass
+    if catalog_runtime is not None:
+        validate_installed_runtime(catalog_runtime)
+        return catalog_runtime
+
+    installed = installed_runtime_version(name)
+    if not installed:
+        raise ManagedRuntimeError(
+            f"本地缺少 {name} runtime；请安装 `pip install 'ksadk[{name}]'`"
+        )
+    resolved = ResolvedRuntime(
+        name=name,
+        version=installed,
+        source="installed-unlocked",
+    )
+    validate_runtime_binary(resolved)
+    return resolved

ksadk/markdown.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 from typing import Any
 
-
 _FENCE_MARKER_CHARS = ("`", "~")
 _LIST_PREFIXES = ("- ", "* ", "+ ")
 
@@ -157,7 +156,11 @@ def _is_closing_fence(candidate: str, open_marker: str) -> bool:
 
 
 def _is_table_line(stripped_line: str) -> bool:
-    return stripped_line.startswith("|") and stripped_line.endswith("|") and stripped_line.count("|") >= 2
+    return (
+        stripped_line.startswith("|")
+        and stripped_line.endswith("|")
+        and stripped_line.count("|") >= 2
+    )
 
 
 def _is_list_line(stripped_line: str) -> bool:

ksadk/mcp_runtime/__init__.py

@@ -1,18 +1,19 @@
 from __future__ import annotations
 
+import inspect
 import json
 import os
-import inspect
 from dataclasses import dataclass
-from typing import Any, Sequence
+from typing import Any, Coroutine, Sequence, cast
 from urllib.parse import urlparse
 
 import httpx
-from google.adk.tools.mcp_tool.mcp_session_manager import (
+
+from ksadk.compat.adk_compat import (
     CheckableMcpHttpClientFactory,
+    McpToolset,
     StreamableHTTPConnectionParams,
 )
-from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
 
 MCP_TOOLSET_KEY_ATTR = "_ksadk_mcp_toolset_key"
 
@@ -64,7 +65,9 @@ def build_connection_params(
     httpx_client_factory: CheckableMcpHttpClientFactory | None = None,
 ) -> StreamableHTTPConnectionParams:
     kwargs: dict[str, Any] = {"url": config.url, "headers": config.headers}
-    kwargs["httpx_client_factory"] = httpx_client_factory or _default_httpx_client_factory(config.url)
+    kwargs["httpx_client_factory"] = httpx_client_factory or _default_httpx_client_factory(
+        config.url
+    )
     return StreamableHTTPConnectionParams(**kwargs)
 
 
@@ -146,7 +149,7 @@ def _mcp_toolset_tools_sync(toolset: Any) -> list[Any]:
             try:
                 asyncio.get_running_loop()
             except RuntimeError:
-                result = asyncio.run(result)
+                result = asyncio.run(cast(Coroutine[Any, Any, Any], result))
             else:
                 close = getattr(result, "close", None)
                 if callable(close):

ksadk/memory/__init__.py

@@ -13,9 +13,9 @@
 
 from typing import TYPE_CHECKING
 
-from ksadk.memory.manager import MemoryManager, get_memory_manager
 from ksadk.memory.backends.base import BaseMemoryBackend
 from ksadk.memory.backends.memory import InMemoryBackend
+from ksadk.memory.manager import MemoryManager, get_memory_manager
 
 if TYPE_CHECKING:
     from ksadk.memory.service import LongTermMemoryService

ksadk/memory/adk/__init__.py

@@ -39,10 +39,12 @@ if TYPE_CHECKING:
 def __getattr__(name):
     if name == "ShortTermMemory":
         from ksadk.memory.adk.short_term_memory import ShortTermMemory
+
         return ShortTermMemory
 
     if name == "LongTermMemory":
         from ksadk.memory.adk.long_term_memory import LongTermMemory
+
         return LongTermMemory
 
     raise AttributeError(f"module 'ksadk.memory.adk' has no attribute '{name}'")

ksadk/memory/adk/backends/base_ltm_backend.py

@@ -21,9 +21,7 @@ class BaseLongTermMemoryBackend(ABC, BaseModel):
     index: str = ""
 
     @abstractmethod
-    def save_memory(
-        self, user_id: str, event_strings: List[str], **kwargs
-    ) -> bool:
+    def save_memory(self, user_id: str, event_strings: List[str], **kwargs) -> bool:
         """保存记忆
 
         Args:
@@ -36,9 +34,7 @@ class BaseLongTermMemoryBackend(ABC, BaseModel):
         pass
 
     @abstractmethod
-    def search_memory(
-        self, user_id: str, query: str, top_k: int = 5, **kwargs
-    ) -> List[str]:
+    def search_memory(self, user_id: str, query: str, top_k: int = 5, **kwargs) -> List[str]:
         """检索记忆
 
         Args: