agentengine-sdk-python 0.7.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

ksadk/common/aicp_env.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 import os
 import socket
 
-
 DEFAULT_AICP_REGION = "cn-beijing-6"
 DEFAULT_AICP_ENDPOINT = "aicp.api.ksyun.com"
 INTERNAL_AICP_ENDPOINT = "aicp.internal.api.ksyun.com"

ksadk/common/auth.py

@@ -22,11 +22,11 @@ AWS Signature V4 签名认证
     response = requests.post(url, auth=auth.get_auth(), headers=headers)
 """
 
-import os
 import logging
+import os
 from typing import Dict, Optional
 
-from requests_aws4auth import AWS4Auth
+from requests_aws4auth import AWS4Auth  # type: ignore[import-untyped]
 
 logger = logging.getLogger(__name__)
 

ksadk/common/constants.py

@@ -3,9 +3,7 @@
 """
 
 # Serverless Endpoint (默认内网预发环境)
-DEFAULT_SERVERLESS_ENDPOINT = (
-    "http://kmr.pre-online.inner.api.ksyun.com"
-)
+DEFAULT_SERVERLESS_ENDPOINT = "http://kmr.pre-online.inner.api.ksyun.com"
 
 # KS3 Region 映射表
 # 用户输入的 region (如 cn-beijing-6) -> (外网endpoint, 内网endpoint, region_code)

ksadk/common/kop_client.py

@@ -0,0 +1,232 @@
+"""KOP (Kingsoft Open Protocol) client — 公共 AICP 控制面调用层。
+
+skill / a2a / mcp 等运行时模块通过本层访问 agentengine-server 对外 Action
+（KOP 协议：`{base}/?Action=xxx&Version=xxx` + AWS V4 签名），避免每个模块
+各自实现一遍鉴权 + URL 构造 + header 装配。
+
+本层是同步（基于 requests + requests-aws4auth）；async 调用方用
+``asyncio.to_thread`` 包裹。AICP 控制面是低频调用，同步足够。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, Mapping, Optional
+from urllib.parse import urlsplit
+
+import requests
+
+from ksadk.common.auth import AWSV4Auth
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_API_VERSION = "2024-06-12"
+DEFAULT_REGION = "cn-beijing-6"
+DEFAULT_SERVICE = "aicp"
+
+# 精确匹配 AICP 控制面域名（公网 + 内网 + internal），不接受用户自定义 URL 走签名。
+_AICP_HOSTS = {
+    "aicp.api.ksyun.com",
+    "aicp.inner.api.ksyun.com",
+    "aicp.internal.api.ksyun.com",
+}
+
+
+def is_kop_endpoint(base_url: str) -> bool:
+    """Return True only for exact AICP control-plane hosts.
+
+    User-controlled URLs must never receive KOP signing headers.
+    """
+    host = (urlsplit(base_url or "").hostname or "").lower()
+    return host in _AICP_HOSTS
+
+
+class KOPError(RuntimeError):
+    """KOP action 失败（非 2xx 或 Code != 0/200）。"""
+
+    def __init__(self, *, code: int, message: str, request_id: str = "", action: str = "") -> None:
+        super().__init__(f"KOP {action} failed: code={code} message={message}")
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.action = action
+
+
+class KOPClient:
+    """AICP KOP 控制面调用客户端。
+
+    凭证优先级：构造参数 > KSADK_*_ACCESS_KEY/SECRET_KEY > KSYUN_ACCESS_KEY/SECRET_KEY。
+    base_url 为空时按 region 探测默认 AICP（inner 优先,回落 public）。
+    非 AICP base_url（如本地 server 直连）走普通 POST，不签名。
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: Optional[str] = None,
+        access_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        region: Optional[str] = None,
+        service: Optional[str] = None,
+        api_version: Optional[str] = None,
+        account_id: Optional[str] = None,
+        service_token: Optional[str] = None,
+        timeout: float = 15.0,
+    ) -> None:
+        self.base_url = (base_url or os.getenv("KSADK_A2A_SERVICE_URL") or "").strip().rstrip("/")
+        if not self.base_url:
+            inner = os.getenv("KSADK_A2A_SERVICE_ENDPOINT", "").strip()
+            if inner:
+                scheme = os.getenv("KSADK_A2A_SERVICE_SCHEME", "https").strip() or "https"
+                self.base_url = f"{scheme}://{inner}".rstrip("/")
+        if not self.base_url:
+            # 默认探测：内网 inner 优先（runtime 在集群内），回落公网 public。
+            self.base_url = self._detect_default_base_url()
+        self.region = (
+            region
+            or os.getenv("KSADK_A2A_SERVICE_REGION")
+            or os.getenv("KSYUN_REGION")
+            or DEFAULT_REGION
+        ).strip()
+        self.service = (service or DEFAULT_SERVICE).strip()
+        self.api_version = (api_version or DEFAULT_API_VERSION).strip()
+        self.account_id = (
+            account_id
+            or os.getenv("KSADK_A2A_ACCOUNT_ID")
+            or os.getenv("KSYUN_ACCOUNT_ID")
+            or ""
+        ).strip()
+        self.service_token = (
+            service_token or os.getenv("KSADK_A2A_SERVICE_TOKEN") or ""
+        ).strip()
+        self.timeout = timeout
+        self._kop_mode = is_kop_endpoint(self.base_url)
+        ak = (
+            access_key
+            or os.getenv("KSADK_A2A_ACCESS_KEY")
+            or os.getenv("KSYUN_ACCESS_KEY")
+            or ""
+        ).strip()
+        sk = (
+            secret_key
+            or os.getenv("KSADK_A2A_SECRET_KEY")
+            or os.getenv("KSYUN_SECRET_KEY")
+            or ""
+        ).strip()
+        self._auth = AWSV4Auth(
+            access_key_id=ak,
+            secret_access_key=sk,
+            region=self.region,
+            service=self.service,
+        )
+        self._session: Optional[requests.Session] = None
+
+    @property
+    def is_kop_mode(self) -> bool:
+        return self._kop_mode
+
+    def _session_obj(self) -> requests.Session:
+        if self._session is None:
+            self._session = requests.Session()
+        return self._session
+
+    def _headers(self, action: str) -> dict[str, str]:
+        import uuid
+
+        headers = {"Accept": "application/json", "Content-Type": "application/json"}
+        if self.account_id:
+            headers["X-Ksc-Account-Id"] = self.account_id
+        if self.service_token:
+            headers["Authorization"] = f"Bearer {self.service_token}"
+        if self._kop_mode:
+            headers["Host"] = urlsplit(self.base_url).netloc
+            headers["X-Ksc-Request-Id"] = str(uuid.uuid4())
+            headers["X-Ksc-Region"] = self.region
+            headers["X-Ksc-Source"] = "ksadk-runtime"
+            # 预发环境路由：AICP 据此把请求转发到预发 server（线上 KOP 默认路由到线上 server）。
+            logical_region = (os.getenv("KSYUN_REGION") or "").strip().lower()
+            if logical_region == "pre-online":
+                headers["X-KSC-CUSTOM-SOURCE"] = os.getenv("AGENTENGINE_PRE_CUSTOM_SOURCE", "pre")
+            if action:
+                headers["X-Action"] = action
+                headers["X-Version"] = self.api_version
+        return headers
+
+    def _build_url(self, action: str) -> str:
+        if self._kop_mode:
+            return f"{self.base_url}/?Action={action}&Version={self.api_version}"
+        return f"{self.base_url}/agentengine/api/v1/{action}"
+
+    def post_action(
+        self, action: str, payload: Optional[Mapping[str, Any]] = None
+    ) -> dict[str, Any]:
+        """POST 一个 KOP Action，返回 Data 字段（已解包信封）。
+
+        非KOP 模式走 ``/agentengine/api/v1/{action}``；KOP 模式走 ``?Action=&Version=`` + 签名。
+        """
+        url = self._build_url(action)
+        headers = self._headers(action)
+        body = json.dumps(dict(payload or {}), ensure_ascii=False)
+        auth = (
+            self._auth.get_auth()
+            if self._kop_mode and self._auth.is_enabled and not self.service_token
+            else None
+        )
+        try:
+            response = self._session_obj().post(
+                url,
+                data=body.encode("utf-8"),
+                headers=headers,
+                auth=auth,
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise KOPError(
+                code=503,
+                message=f"KOP control plane unavailable: {exc}",
+                action=action,
+            ) from exc
+        if not 200 <= response.status_code < 300:
+            raise KOPError(
+                code=response.status_code,
+                message=f"KOP HTTP error: {response.text[:200]}",
+                action=action,
+            )
+        try:
+            envelope = response.json()
+        except ValueError as exc:
+            raise KOPError(
+                code=response.status_code or 502,
+                message="non-JSON response",
+                action=action,
+            ) from exc
+        if not isinstance(envelope, dict):
+            raise KOPError(
+                code=response.status_code or 502,
+                message="response not an object",
+                action=action,
+            )
+        code = int(envelope.get("Code") or 0)
+        if code and code != 200:
+            raise KOPError(
+                code=code,
+                message=str(envelope.get("Message") or "KOP error"),
+                request_id=str(envelope.get("RequestId") or ""),
+                action=action,
+            )
+        data = envelope.get("Data")
+        return data if isinstance(data, dict) else {}
+
+    def _detect_default_base_url(self) -> str:
+        """默认 AICP 地址探测：内网 inner 优先，失败回落公网 public。"""
+        inner = "http://aicp.inner.api.ksyun.com"
+        public = "https://aicp.api.ksyun.com"
+        try:
+            import socket
+            host = urlsplit(inner).hostname or ""
+            socket.create_connection((host, 80), timeout=1).close()
+            return inner
+        except OSError:
+            return public

ksadk/common/llm_utils.py

@@ -1,7 +1,7 @@
 """LLM Utilities"""
 
-import os
 import logging
+import os
 
 logger = logging.getLogger(__name__)
 
@@ -10,28 +10,32 @@ PUBLIC_ENDPOINT = "https://kspmas.ksyun.com/v1/"
 
 # Internal Endpoint (Auto-injected by Platform)
 # Note: In most cases, we don't need to hardcode this because the platform injects it.
-# But for the purpose of "smart switching based on public URL", we might need to know what to switch TO, 
+# But for "smart switching based on public URL", we might need to know
+# what to switch TO,
 # or simply rely on leaving it empty so the platform default takes over?
-# 
+#
 # According to user: "OPENAI_BASE_URL 不填会自动选择的" (If empty, it auto-selects).
-# So our strategy: If Public URL + Internal Env -> Unset OPENAI_BASE_URL (letting it fall back to platform default).
+# Strategy: If Public URL + Internal Env -> Unset OPENAI_BASE_URL,
+# letting it fall back to the platform default.
+
 
 def get_smart_openai_env() -> None:
     """Smartly configure OpenAI Environment Variables.
-    
+
     If it detects that the code is running in a Ksyun Internal Environment (Serverless/KCE)
     AND the OPENAI_BASE_URL is set to the Public Endpoint, it will unset OPENAI_BASE_URL
     to allow the platform's automatic internal endpoint injection to take effect.
-    
-    This prevents network hangs caused by accessing public endpoints from internal-only environments.
+
+    This prevents network hangs caused by accessing public endpoints from
+    internal-only environments.
     """
     base_url = os.environ.get("OPENAI_BASE_URL", "").strip()
-    
+
     # logic 1: Check if it is the Public Endpoint
     # Normalize by removing trailing slash for comparison
     normalized_url = base_url.rstrip("/")
     normalized_public = PUBLIC_ENDPOINT.rstrip("/")
-    
+
     if normalized_url != normalized_public:
         return
 
@@ -41,11 +45,11 @@ def get_smart_openai_env() -> None:
     # - K_SERVICE (Injected by Knative/Serverless)
     # - KUBERNETES_SERVICE_HOST (Injected by K8s)
     is_internal = (
-        "KSYUN_REGION" in os.environ 
+        "KSYUN_REGION" in os.environ
         or "K_SERVICE" in os.environ
         or "KUBERNETES_SERVICE_HOST" in os.environ
     )
-    
+
     if is_internal:
         logger.warning(
             f"Detected Public OPENAI_BASE_URL ({base_url}) in Internal Environment. "
@@ -55,7 +59,7 @@ def get_smart_openai_env() -> None:
         # Or explicitly set it to internal generic address if known?
         # User said: "OPENAI_BASE_URL 不填会自动选择". So we unset it.
         del os.environ["OPENAI_BASE_URL"]
-        
+
         # Verify if successful removal
         if "OPENAI_BASE_URL" not in os.environ:
-             logger.info("Successfully switched to Internal Endpoint mode.")
+            logger.info("Successfully switched to Internal Endpoint mode.")

ksadk/compat/__init__.py

@@ -0,0 +1,5 @@
+"""兼容层包 (goal-00)。"""
+
+from ksadk.compat import adk_compat
+
+__all__ = ["adk_compat", "copilotkit_a2ui"]

ksadk/compat/adk_compat.py

@@ -0,0 +1,200 @@
+"""Google ADK 多版本兼容层 (goal-00)。
+
+ksadk 业务代码**不直接** ``import google.adk``;统一从本模块取符号。
+``google-adk`` 的版本差异只在兼容层内消化,业务代码对版本无感知。
+
+版本窗口
+--------
+依赖约束 ``google-adk>=1.34.0,<3.0.0``:
+
+- **1.34.x** 是最低支持锚点(不承诺 1.x 全系;1.0 缺 ``google.adk.apps`` 等,代价过大)。
+- **2.x**(当前 2.5.x)是上界内最新主线。
+
+实测(2026-07-21, goal-00 探测,解包对比 1.34.3 vs 2.5.0):ksadk 用到的
+全部符号在两个版本**都存在**,差异仅为 2.x 的**向后兼容可选新增**:
+
+- ``Runner.run_async`` 2.x 新增可选 ``yield_user_message``(默认 False)。
+- ``RunConfig`` 2.x 新增若干可选字段(``http_options`` / ``telemetry`` /
+  ``model_input_context`` 等),均为可选,不传不影响。
+- ``App.root_agent`` 2.x 变为可选(1.34 必填);ksadk 始终显式传,两版皆可。
+- ``DatabaseSessionService`` 2.x 新增可选 ``db_engine``(``db_url`` 变可选);
+  ksadk 始终传 ``db_url``,两版皆可。
+- ``McpToolset.header_provider`` 2.x 支持 awaitable;ksadk 未用该参数。
+
+ksadk 现有调用**不依赖任何 2.x-only 参数**,因此 1.34 与 2.x 对 ksadk 能力对等,
+无需降级 shim。能力降级矩阵的完整文字版见
+``docs/adk-multi-version-compat.md``。
+
+使用 2.x-only 新能力的纪律
+--------------------------
+若未来要用某个 2.x 才有的可选参数/符号,**必须**在本层用
+:func:`adk_version_at_least` 判断后再下发,并对 1.34 做显式降级;不允许业务
+代码自行 ``import google.adk`` 探测。
+
+加载语义
+--------
+本模块 import 自身**不触发** ``google.adk`` 导入(惰性,PEP 562
+``__getattr__``)。只有真正访问某个符号时才导入对应 ``google.adk`` 子模块;
+未安装 ``google-adk`` 时抛出带安装提示的 :class:`ImportError`,便于
+``memory/adk_tool`` 等调用方捕获并降级为原函数。
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover - 仅供 mypy 静态检查,运行时不执行
+    pass
+
+#: 导出符号名 -> 提供该符号的 google.adk 子模块路径。
+#: 这是 ksadk 全部 google.adk 依赖的唯一登记表;新增依赖先在这里登记。
+_LAZY_SYMBOLS: dict[str, str] = {
+    # agents
+    "Agent": "google.adk.agents",
+    "RunConfig": "google.adk.agents.run_config",
+    "StreamingMode": "google.adk.agents.run_config",
+    # apps
+    "App": "google.adk.apps",
+    "ResumabilityConfig": "google.adk.apps",
+    # events
+    "Event": "google.adk.events.event",
+    # memory
+    "BaseMemoryService": "google.adk.memory.base_memory_service",
+    "SearchMemoryResponse": "google.adk.memory.base_memory_service",
+    "MemoryEntry": "google.adk.memory.memory_entry",
+    # models
+    "LlmResponse": "google.adk.models",
+    "LiteLlm": "google.adk.models.lite_llm",
+    # runners
+    "Runner": "google.adk.runners",
+    # sessions
+    "BaseSessionService": "google.adk.sessions",
+    "InMemorySessionService": "google.adk.sessions",
+    "Session": "google.adk.sessions",
+    "DatabaseSessionService": "google.adk.sessions",
+    "InvocationContext": "google.adk.agents",
+    "ToolContext": "google.adk.tools",
+    "GetSessionConfig": "google.adk.sessions.base_session_service",
+    "ListSessionsResponse": "google.adk.sessions.base_session_service",
+    # tools
+    "FunctionTool": "google.adk.tools",
+    "load_memory": "google.adk.tools",
+    "McpTool": "google.adk.tools.mcp_tool.mcp_tool",
+    "McpToolset": "google.adk.tools.mcp_tool.mcp_toolset",
+    "CheckableMcpHttpClientFactory": "google.adk.tools.mcp_tool.mcp_session_manager",
+    "StreamableHTTPConnectionParams": "google.adk.tools.mcp_tool.mcp_session_manager",
+}
+
+#: 以模块形式导出的名字 -> 模块路径(如 genai types、需要 monkeypatch 的 lite_llm)。
+_LAZY_MODULES: dict[str, str] = {
+    "genai_types": "google.genai.types",
+}
+
+_INSTALL_HINT = (
+    "google-adk 未安装或版本不在支持窗口 (>=1.34.0,<3.0.0)。" "安装: pip install 'ksadk[adk]'"
+)
+
+_ADK_NOT_FOUND = "google-adk 未安装"
+
+
+def _raise_missing(name: str, exc: BaseException) -> None:
+    raise ImportError(f"无法导入 google.adk 符号 {name!r}。{_INSTALL_HINT}") from exc
+
+
+def __getattr__(name: str) -> Any:
+    """PEP 562 惰性解析:首次访问符号时才导入对应 google.adk 子模块。"""
+    if name in _LAZY_SYMBOLS:
+        module_path = _LAZY_SYMBOLS[name]
+        try:
+            module = import_module(module_path)
+        except ImportError as exc:
+            _raise_missing(name, exc)
+        try:
+            value = getattr(module, name)
+        except AttributeError as exc:
+            raise ImportError(
+                f"google.adk 已安装但 {module_path} 缺少 {name!r};"
+                f"当前版本 {adk_version() or '未知'} 可能不在支持窗口 (>=1.34.0,<3.0.0)。"
+            ) from exc
+        # 注意: 刻意不缓存到 globals()。测试常 monkeypatch ``google.adk.*``
+        # 子模块符号(如把 Runner 换成 FakeRunner);若在此缓存,会把某次 patch
+        # 后的值泄漏给后续解析,造成跨测试污染。每次经 getattr 重新解析,
+        # 让既有 ``google.adk.*`` patch 点继续生效。开销可忽略(import_module
+        # 命中 sys.modules 缓存)。
+        return value
+    if name in _LAZY_MODULES:
+        module_path = _LAZY_MODULES[name]
+        try:
+            value = import_module(module_path)
+        except ImportError as exc:
+            _raise_missing(name, exc)
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY_SYMBOLS) | set(_LAZY_MODULES))
+
+
+def is_adk_available() -> bool:
+    """google-adk 是否可导入(不关心版本)。"""
+    try:
+        import_module("google.adk")
+    except ImportError:
+        return False
+    return True
+
+
+def adk_version() -> str | None:
+    """返回已安装的 google-adk 版本;未安装返回 None。"""
+    try:
+        return _dist_version("google-adk")
+    except PackageNotFoundError:
+        return None
+
+
+def adk_version_at_least(min_version: str) -> bool:
+    """已安装 google-adk 版本是否 >= ``min_version``;未安装或无法解析返回 False。
+
+    用于下发 2.x-only 能力前的版本门禁,例如::
+
+        if adk_version_at_least("2.0.0"):
+            kwargs["yield_user_message"] = True
+    """
+    ver = adk_version()
+    if ver is None:
+        return False
+    try:
+        from packaging.version import Version
+
+        return bool(Version(ver) >= Version(min_version))
+    except Exception:
+        return False
+
+
+def lite_llm_module() -> Any:
+    """返回 ``google.adk.models.lite_llm`` 模块对象。
+
+    adk_runner 的 JSON 容错 patch 需要 MonkeyPatch 该模块内的
+    ``_message_to_generate_content_response``(私有函数),因此需要模块本身
+    而非单个符号。未安装 litellm/google-adk 时抛 :class:`ImportError`。
+    """
+    try:
+        return import_module("google.adk.models.lite_llm")
+    except ImportError as exc:
+        _raise_missing("google.adk.models.lite_llm", exc)
+
+
+__all__ = [
+    # 版本/能力探测
+    "is_adk_available",
+    "adk_version",
+    "adk_version_at_least",
+    "lite_llm_module",
+    # 惰性符号
+    *_LAZY_SYMBOLS.keys(),
+    *_LAZY_MODULES.keys(),
+]