agentengine-sdk-python 0.8.5__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/api/client.py

@@ -23,6 +23,9 @@ import urllib3
 
 from ksadk.api.environment import environment_variables_payload
 from ksadk.common.auth import AWSV4Auth
+from ksadk.common.cloud_headers import build_cloud_headers
+
+from ksadk.api.sse_stream import AgentEngineSSEStream, _next_stream_chunk
 
 logger = logging.getLogger(__name__)
 
@@ -37,69 +40,6 @@ class AttachmentContent:
     display_name: str
 
 
-def _next_stream_chunk(iterator: Iterator[bytes]) -> bytes | None:
-    """Read one non-empty requests chunk without leaking StopIteration to asyncio."""
-
-    while True:
-        try:
-            chunk = next(iterator)
-        except StopIteration:
-            return None
-        if chunk:
-            return chunk
-
-
-class AgentEngineSSEStream(AsyncIterator[bytes]):
-    """Async owner for one dedicated blocking requests SSE connection."""
-
-    def __init__(self, response: requests.Response, session: requests.Session) -> None:
-        self._response: requests.Response | None = response
-        self._session: requests.Session | None = session
-        # Read SSE as logical lines with the smallest requests read size.  A
-        # fixed 8 KiB ``iter_content`` block makes short runs appear
-        # non-streaming, while ``chunk_size=None`` waits for EOF on urllib3.
-        # ``iter_lines`` performs the byte-at-a-time buffering inside the
-        # blocking worker and yields complete lines, avoiding one thread hop
-        # per byte.  Re-add the delimiter so downstream SSE parsers keep their
-        # normal framing, including the blank line between events.
-        self._chunks = (line + b"\n" for line in response.iter_lines(chunk_size=1))
-        self._closed = False
-
-    def __aiter__(self) -> "AgentEngineSSEStream":
-        return self
-
-    async def __anext__(self) -> bytes:
-        if self._closed:
-            raise StopAsyncIteration
-        try:
-            chunk = await asyncio.to_thread(_next_stream_chunk, self._chunks)
-        except BaseException:
-            await self.aclose()
-            raise
-        if chunk is None:
-            await self.aclose()
-            raise StopAsyncIteration
-        return chunk
-
-    async def aclose(self) -> None:
-        if self._closed:
-            return
-        self._closed = True
-        response, session = self._response, self._session
-        self._response = None
-        self._session = None
-
-        def close_transport() -> None:
-            try:
-                if response is not None:
-                    response.close()
-            finally:
-                if session is not None:
-                    session.close()
-
-        await asyncio.to_thread(close_transport)
-
-
 class DryRunExit(Exception):
     """DryRun 模式退出异常。"""
 
@@ -590,7 +530,7 @@ class AgentEngineClient:
             account_id = self._resolve_account_id()
             if account_id:
                 headers["X-Ksc-Account-Id"] = account_id
-        return headers
+        return build_cloud_headers(headers)
 
     def _resolve_user_uuid(self) -> Optional[str]:
         """解析子账号 user uuid（X-Ksc-User-uuid 值）。
@@ -1055,7 +995,7 @@ class AgentEngineClient:
         response = self._get_session().request(
             method="POST",
             url=f"{endpoint}/agentengine/api/v1/{action}",
-            headers={"Authorization": f"Bearer {api_key}"},
+            headers=build_cloud_headers({"Authorization": f"Bearer {api_key}"}),
             json=params,
             timeout=self.timeout,
             verify=self._request_ssl_verify(),
@@ -1246,7 +1186,7 @@ class AgentEngineClient:
         response = self._get_session().request(
             method=method,
             url=url,
-            headers=headers or None,
+            headers=build_cloud_headers(headers),
             params=params,
             files=files,
             stream=False,
@@ -1313,6 +1253,7 @@ class AgentEngineClient:
         params: Optional[Dict[str, Any]] = None,
         *,
         ignore_dry_run: bool = False,
+        preserve_case: bool = False,
     ) -> Dict[str, Any]:
         """通用 Action API 调用"""
         body = params or {}
@@ -1336,7 +1277,7 @@ class AgentEngineClient:
 
         # 提取 Data 并统一转换为 snake_case
         data = result.get("Data") if result.get("Data") is not None else result
-        data = self._to_snake_case(data)
+        data = data if preserve_case else self._to_snake_case(data)
 
         # 预发环境 endpoint 协议归一化: https -> http
         if self.logical_region and self.logical_region.strip().lower() == "pre-online":
@@ -1584,6 +1525,7 @@ class AgentEngineClient:
                 "Bucket": ks3.get("bucket"),
                 "Command": data.get("code_command"),
                 "Checksum": data.get("code_checksum"),
+                "AgentKernelContractDigest": data.get("agent_kernel_contract_digest"),
             }
         elif params["DeploymentType"] == "ManagedRuntime":
             params["ManagedRuntimeConfig"] = self._managed_runtime_config_payload(data)
@@ -1888,7 +1830,7 @@ class AgentEngineClient:
         return True
 
     async def update_agent(self, agent_id: str, data: Dict[str, Any]) -> Dict[str, Any]:
-        """更新 Agent (热更新)"""
+        """提交 Agent 更新并直接返回响应；Code 更新由服务端后台执行。"""
         params: Dict[str, Any] = {"AgentId": agent_id}
         artifact_type = data.get("artifact_type")
         if artifact_type:
@@ -1916,6 +1858,7 @@ class AgentEngineClient:
                     "Bucket": ks3.get("bucket"),
                     "Command": data.get("code_command"),
                     "Checksum": data.get("code_checksum"),
+                    "AgentKernelContractDigest": data.get("agent_kernel_contract_digest"),
                 }
 
         if data.get("resources"):
@@ -1933,7 +1876,14 @@ class AgentEngineClient:
 
         envs = data.get("env_vars") or data.get("environment_variables")
         if envs:
-            params["EnvironmentVariables"] = environment_variables_payload(envs)
+            env_payload = environment_variables_payload(envs)
+            if data.get("environment_variables_is_patch"):
+                params["EnvironmentVariablePatch"] = {
+                    "Upsert": env_payload,
+                    "Delete": [],
+                }
+            else:
+                params["EnvironmentVariables"] = env_payload
 
         network_payload = self._normalize_network_payload(data.get("network"))
         if network_payload:
@@ -1978,7 +1928,7 @@ class AgentEngineClient:
         if advanced:
             params["Advanced"] = advanced
 
-        return self._action("UpdateAgent", params)
+        return await self._action_async("UpdateAgent", params)
 
     # ===== Session Actions =====
 
@@ -2593,16 +2543,18 @@ class AgentEngineClient:
             params["Metadata"] = {"agentengine": execution_metadata}
         return await self._action_async("RunAgent", params)
 
-    def _open_chat_stream(self, params: Dict[str, Any]) -> AgentEngineSSEStream:
+    def _open_chat_stream(
+        self, params: Dict[str, Any], *, action: str = "RunAgent", method: str = "POST"
+    ) -> AgentEngineSSEStream:
         """Open RunAgent SSE synchronously in a worker-owned requests session."""
 
-        path = "/agentengine/api/v1/RunAgent"
-        _kop_mode, headers, full_url = self._build_action_request_target(path, "RunAgent")
+        path = f"/agentengine/api/v1/{action}"
+        _kop_mode, headers, full_url = self._build_action_request_target(path, action)
         body_str = json.dumps(params, ensure_ascii=False)
         if self.dry_run:
             # Reuse the established dry-run contract, which raises DryRunExit
             # with the signed request rather than opening a socket.
-            self._request("POST", path, params)
+            self._request(method, path, params)
             raise AssertionError("dry-run request unexpectedly returned")
 
         session = requests.Session()
@@ -2612,9 +2564,10 @@ class AgentEngineClient:
         try:
             while True:
                 response = session.request(
-                    method="POST",
+                    method=method,
                     url=full_url,
-                    data=body_str.encode("utf-8"),
+                    data=body_str.encode("utf-8") if method == "POST" else None,
+                    params=params if method == "GET" else None,
                     headers=headers,
                     auth=self._auth.get_auth(),
                     # A foreground Agent turn can legitimately spend minutes
@@ -2650,7 +2603,7 @@ class AgentEngineClient:
                         str(
                             details.get("remote_error_message") or details.get("message") or ""
                         ).strip()
-                        or "RunAgent stream did not return text/event-stream"
+                        or f"{action} stream did not return text/event-stream"
                     )
                     raise AgentEngineAPIError(
                         error_code,
@@ -2663,12 +2616,12 @@ class AgentEngineClient:
                     response = None
                     self._switch_to_inner_aicp_endpoint()
                     _kop_mode, headers, full_url = self._build_action_request_target(
-                        path, "RunAgent"
+                        path, action
                     )
                     continue
 
                 self._log_http_error(
-                    method="POST",
+                    method=method,
                     full_url=full_url,
                     status_code=response.status_code,
                     details=details,

ksadk/api/sse_stream.py

@@ -0,0 +1,96 @@
+"""Own a cancellable blocking HTTP SSE connection from asyncio."""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+from typing import AsyncIterator, Iterator
+
+import requests
+
+
+def _next_stream_chunk(iterator: Iterator[bytes]) -> bytes | None:
+    """Read one non-empty requests chunk without leaking StopIteration to asyncio."""
+
+    while True:
+        try:
+            chunk = next(iterator)
+        except StopIteration:
+            return None
+        if chunk:
+            return chunk
+
+
+class AgentEngineSSEStream(AsyncIterator[bytes]):
+    """Async owner for one dedicated blocking requests SSE connection."""
+
+    def __init__(self, response: requests.Response, session: requests.Session) -> None:
+        self._response: requests.Response | None = response
+        self._session: requests.Session | None = session
+        # Read SSE as logical lines with the smallest requests read size.  A
+        # fixed 8 KiB ``iter_content`` block makes short runs appear
+        # non-streaming, while ``chunk_size=None`` waits for EOF on urllib3.
+        # ``iter_lines`` performs the byte-at-a-time buffering inside the
+        # blocking worker and yields complete lines, avoiding one thread hop
+        # per byte.  Re-add the delimiter so downstream SSE parsers keep their
+        # normal framing, including the blank line between events.
+        self._chunks = (line + b"\n" for line in response.iter_lines(chunk_size=1))
+        self._closed = False
+        # requests/urllib3 close() waits for the buffered reader's lock. A
+        # worker blocked in an unlimited SSE read holds that lock, so closing
+        # from another thread must first wake the socket. Capture it before
+        # EOF can clear urllib3's connection reference. Connection: close
+        # responses may only retain it through HTTPResponse's buffered file.
+        raw = getattr(response, "raw", None)
+        connection = getattr(raw, "_connection", None)
+        transport_socket = getattr(connection, "sock", None)
+        if not isinstance(transport_socket, socket.socket):
+            response_file = getattr(getattr(raw, "_fp", None), "fp", None)
+            transport_socket = getattr(getattr(response_file, "raw", None), "_sock", None)
+        self._socket = transport_socket if isinstance(transport_socket, socket.socket) else None
+
+    def __aiter__(self) -> "AgentEngineSSEStream":
+        return self
+
+    async def __anext__(self) -> bytes:
+        if self._closed:
+            raise StopAsyncIteration
+        try:
+            chunk = await asyncio.to_thread(_next_stream_chunk, self._chunks)
+        except Exception:
+            if self._closed:
+                raise StopAsyncIteration from None
+            await self.aclose()
+            raise
+        except BaseException:
+            await self.aclose()
+            raise
+        if chunk is None or self._closed:
+            await self.aclose()
+            raise StopAsyncIteration
+        return chunk
+
+    async def aclose(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        response, session = self._response, self._session
+        self._response = None
+        self._session = None
+        transport_socket, self._socket = self._socket, None
+
+        def close_transport() -> None:
+            try:
+                if transport_socket is not None:
+                    try:
+                        transport_socket.shutdown(socket.SHUT_RDWR)
+                    except OSError:
+                        # EOF or a simultaneous peer disconnect already closed it.
+                        pass
+                if response is not None:
+                    response.close()
+            finally:
+                if session is not None:
+                    session.close()
+
+        await asyncio.to_thread(close_transport)

ksadk/builders/code_builder.py

@@ -41,8 +41,46 @@ from ksadk.builders.requirements_utils import (
     parse_requirements_text,
 )
 
+from ksadk.builders.source_provenance import _git_provenance, _package_provenance as _read_package_provenance
+
+
+def _package_provenance(package_name: str, package_root: Path) -> dict:
+    return _read_package_provenance(package_name, package_root, git_reader=_git_provenance)
+
 BUILD_INFO_SCHEMA = "ksadk-build-info/v1"
 BUILD_INFO_ARCNAME = "ksadk/BUILD-INFO.json"
+DEPLOYMENT_CONTRACT_ARCNAME = "ksadk/DEPLOYMENT-CONTRACT.json"
+HOSTED_CODE_COMMAND = [
+    "ksadk", "web", "/app/code", "--port", "8080", "--host", "0.0.0.0", "--no-open",
+]
+
+
+def read_code_deployment_contract(zip_path: Path) -> dict[str, Any] | None:
+    """Read the declaration from this exact built ZIP; never infer it from the caller's SDK."""
+    try:
+        with zipfile.ZipFile(zip_path) as archive:
+            return json.loads(archive.read(DEPLOYMENT_CONTRACT_ARCNAME))
+    except (OSError, KeyError, ValueError, zipfile.BadZipFile):
+        return None
+
+
+def _bundled_kernel_contract_digest(files) -> str | None:
+    for package_name, relative, file_path in files:
+        if package_name != "ksadk" or relative != "kernel/contract_fingerprints.py":
+            continue
+        try:
+            tree = ast.parse(file_path.read_text(encoding="utf-8"))
+            for node in tree.body:
+                if isinstance(node, ast.Assign) and any(
+                    isinstance(target, ast.Name) and target.id == "AGENT_KERNEL_V1_AGGREGATE_DIGEST"
+                    for target in node.targets
+                ):
+                    value = ast.literal_eval(node.value)
+                    if isinstance(value, str) and re.fullmatch(r"[0-9a-f]{64}", value):
+                        return value
+        except (OSError, SyntaxError, ValueError, TypeError):
+            return None
+    return None
 
 
 def _sha256_file(path: Path) -> str:
@@ -70,84 +108,6 @@ def _bundled_content_fingerprint(files: List[Any]) -> str:
     return digest.hexdigest()
 
 
-def _git_provenance(start: Path) -> Optional[dict]:
-    """返回 start 所在 git 仓库的提交信息;非 git 目录返回 None。"""
-
-    def _git(*args: str) -> Optional[str]:
-        try:
-            proc = subprocess.run(
-                ["git", "-C", str(start), *args],
-                capture_output=True,
-                text=True,
-                timeout=10,
-            )
-        except Exception:
-            return None
-        if proc.returncode != 0:
-            return None
-        return proc.stdout.strip()
-
-    toplevel = _git("rev-parse", "--show-toplevel")
-    if not toplevel:
-        return None
-    commit = _git("rev-parse", "HEAD")
-    branch = _git("rev-parse", "--abbrev-ref", "HEAD")
-    status = _git("status", "--porcelain")
-    return {
-        "repo_root": toplevel,
-        "commit": commit,
-        "branch": branch or None,
-        "dirty": bool(status),
-    }
-
-
-def _package_provenance(package_name: str, package_root: Path) -> dict:
-    """采集被 vendored 包的安装来源:dist 元信息 / 本地路径 / git 提交。"""
-
-    info: dict[str, Any] = {
-        "source_dir": str(package_root),
-        "dist_version": None,
-        "installer": None,
-        "direct_url": None,
-        "source_type": "unknown",
-        "git": None,
-    }
-    try:
-        dist = importlib_metadata.distribution(package_name)
-    except Exception:
-        dist = None
-    if dist is not None:
-        info["dist_version"] = dist.version
-        installer = (dist.read_text("INSTALLER") or "").strip()
-        info["installer"] = installer or None
-        raw_direct_url = dist.read_text("direct_url.json")
-        if raw_direct_url:
-            try:
-                direct_url = json.loads(raw_direct_url)
-            except ValueError:
-                direct_url = None
-            if isinstance(direct_url, dict):
-                info["direct_url"] = direct_url.get("url")
-                url = str(direct_url.get("url") or "")
-                dir_info = direct_url.get("dir_info") or {}
-                archive_info = direct_url.get("archive_info") or {}
-                if url.startswith("file://"):
-                    if dir_info.get("editable"):
-                        info["source_type"] = "editable-install"
-                    elif url.endswith(".whl"):
-                        info["source_type"] = "local-wheel"
-                    else:
-                        info["source_type"] = "local-path"
-                elif archive_info:
-                    info["source_type"] = "remote-dist"
-    if info["direct_url"] is None and info["dist_version"] is not None:
-        # pip 从 index 安装的常规 dist 通常不写 direct_url.json
-        info["source_type"] = "installed-dist"
-    if info["source_type"] in {"editable-install", "local-path", "unknown"}:
-        info["git"] = _git_provenance(package_root)
-    return info
-
-
 def build_bundled_source_manifest(
     package_roots: dict,
     bundled_files: List[Any],
@@ -249,6 +209,7 @@ class CodeBuilder(BaseBuilder):
         ".yaml",
         ".yml",
         ".json",
+        ".sql",
         ".jinja2",
         ".j2",
         ".txt",
@@ -270,6 +231,9 @@ class CodeBuilder(BaseBuilder):
     }
     BUNDLED_KSADK_CORE_RUNTIME_REQUIREMENTS = (
         "a2a-sdk>=0.3.22",
+        # Code archives run `ksadk web` in the plain Runtime image as well as
+        # the Kernel Host image.  ksadk.cli imports rich during startup.
+        "rich>=13.0.0",
         "culsans>=0.11.0",
         "httpx-sse>=0.4.0",
         "sse-starlette>=2.1.0",
@@ -281,8 +245,10 @@ class CodeBuilder(BaseBuilder):
         "requests-aws4auth>=1.2.0",
         "kingsoftcloud-sdk-python>=1.5.8.94",
         "cryptography>=44.0.0",
+        "rfc8785==0.1.4",
         "websockets>=12.0,<16.0",
         "qrcode>=7.4.0",
+        "rfc8785>=0.1.4",
     )
     BUNDLED_KSADK_MCP_RUNTIME_REQUIREMENTS = (
         "mcp>=1.1.0",
@@ -344,11 +310,17 @@ class CodeBuilder(BaseBuilder):
 
     def build(self) -> BuildResult:
         """执行 Code 模式构建"""
+        from ksadk.a2a.build_validation import validate_a2a_exposure_sources
         from ksadk.detection import FrameworkDetector
 
         self._load_dotenv()
         config = self._load_config()
 
+        try:
+            validate_a2a_exposure_sources(self.project_dir)
+        except ValueError as exc:
+            return BuildResult(success=False, error_message=str(exc))
+
         # 检测框架
         detector = FrameworkDetector(str(self.project_dir))
         detection_result = detector.detect()
@@ -891,7 +863,10 @@ class CodeBuilder(BaseBuilder):
 
     def _should_skip_ksadk_relative_path(self, relative_path: Path) -> bool:
         parts = relative_path.parts
-        return len(parts) >= 2 and parts[0] == "server" and parts[1] == "web-ui"
+        return len(parts) >= 2 and parts[:2] in {
+            ("server", "web-ui"),
+            ("studio", "react-ui"),
+        }
 
     def _warn_on_nonrelease_bundled_source(self, build_info: dict) -> None:
         """vendored ksadk 源码来自本地路径/editable/来源不明时给出醒目提示。
@@ -1012,6 +987,13 @@ class CodeBuilder(BaseBuilder):
             )
             final_deps = merge_requirement_lists(final_deps, user_deps)
 
+        # User pins may narrow the supported framework window, but an unpinned
+        # template dependency must not erase it. Keeping both requirements lets
+        # pip intersect constraints and reject incompatible pins at build time.
+        for requirement in code_requirements_for_framework(detection_result.type.value):
+            if requirement not in final_deps:
+                final_deps.append(requirement)
+
         return final_deps
 
     def _bundled_ksadk_extra_requirements(self, requirements: List[str]) -> tuple[str, ...]:
@@ -1869,6 +1851,17 @@ class CodeBuilder(BaseBuilder):
                 BUILD_INFO_ARCNAME,
                 json.dumps(build_info, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
             )
+            zf.writestr(
+                DEPLOYMENT_CONTRACT_ARCNAME,
+                json.dumps({
+                    "schema": "ksadk-code-deployment/v1",
+                    "framework": detection_result.type.value,
+                    "command": HOSTED_CODE_COMMAND,
+                    "agentKernelContractDigest": _bundled_kernel_contract_digest(
+                        bundled_source_files
+                    ),
+                }, sort_keys=True, separators=(",", ":")) + "\n",
+            )
             self._warn_on_nonrelease_bundled_source(build_info)
 
             click.echo(f"   ✓ 打包运行时源码: {bundled_source_count} 个文件")
@@ -2212,43 +2205,27 @@ runtime_context = RuntimeLaunchContext(
     detection=detection_result,
     config=dict(runtime_build_config),
 )
-# managed A2A:KSADK_A2A_RUNTIME_ID 非空时挂 discovery card + 完整数据面 route。
-_managed_a2a_card = None
-_a2a_config = None
+# Runtime identity is available before registration for discovery.  Operator
+# enables the complete composition only after every Secret projection exists.
+_managed_a2a_bootstrap = None
 _a2a_adapter = None
 if os.environ.get("KSADK_A2A_RUNTIME_ID", "").strip():
-    from ksadk.managed_a2a_card import build_managed_a2a_card_if_configured
-
-    _managed_a2a_card = build_managed_a2a_card_if_configured()
-    try:
-        from ksadk.a2a.routes import A2AConfig
+    if os.environ.get("KSADK_A2A_MANAGED_BOOTSTRAP_ENABLED", "").strip().lower() == "true":
+        from ksadk.a2a.platform import build_managed_a2a_bootstrap_from_env
         from ksadk.runtime.factory import create_runtime_adapter
 
         _a2a_adapter = create_runtime_adapter(runtime_context)
-        _base = (
-            os.environ.get("KSADK_A2A_INTERNAL_BASE_URL", "").strip()
-            or "http://localhost:8080"
-        )
-        _a2a_config = A2AConfig(
-            enabled=True,
-            base_url=_base,
-            agent_name=(
-                os.environ.get("KSADK_A2A_AGENT_NAME", "").strip()
-                or os.environ.get("KSADK_A2A_RUNTIME_ID", "").strip()
-            ),
-            streaming=True,
-            task_store_dsn="sqlite+aiosqlite:///.agentengine/a2a_tasks.db",
-        )
-    except Exception as _e:
-        logger.warning(f"managed A2A 数据面装配失败,回退 discovery-only: {{_e}}")
-        _a2a_config = None
-        _a2a_adapter = None
+        _managed_a2a_bootstrap = build_managed_a2a_bootstrap_from_env()
+    else:
+        from ksadk.managed_a2a_card import build_managed_a2a_card_if_configured
+
+        _managed_a2a_bootstrap = build_managed_a2a_card_if_configured()
 app = create_runtime_app(
     RuntimeAppConfig(
         runtime_type=detection_result.type.value,
         runtime_executor=RuntimeExecutor(build_default_runtime_registry()),
         launch_context=runtime_context,
-        a2a=_a2a_config or _managed_a2a_card,
+        a2a=_managed_a2a_bootstrap,
         a2a_runtime_adapter=_a2a_adapter,
     ),
     configure_runtime_app,

ksadk/builders/container_builder.py

@@ -561,45 +561,27 @@ runtime_context = RuntimeLaunchContext(
     detection=detection_result,
     config=dict(runtime_build_config),
 )
-# managed A2A:KSADK_A2A_RUNTIME_ID 非空时挂 discovery card + 完整数据面 route。
-# discovery card 让 server 探测；数据面 route 让 gateway 转发的 JSON-RPC/REST
-# 能真正落到本 runtime 的 A2A 协议端点（路线 C 直连）。
-_managed_a2a_card = None
-_a2a_config = None
+# Runtime identity is available before registration for discovery.  Operator
+# enables the complete composition only after every Secret projection exists.
+_managed_a2a_bootstrap = None
 _a2a_adapter = None
 if os.environ.get("KSADK_A2A_RUNTIME_ID", "").strip():
-    from ksadk.managed_a2a_card import build_managed_a2a_card_if_configured
-
-    _managed_a2a_card = build_managed_a2a_card_if_configured()
-    try:
-        from ksadk.a2a.routes import A2AConfig
+    if os.environ.get("KSADK_A2A_MANAGED_BOOTSTRAP_ENABLED", "").strip().lower() == "true":
+        from ksadk.a2a.platform import build_managed_a2a_bootstrap_from_env
         from ksadk.runtime.factory import create_runtime_adapter
 
         _a2a_adapter = create_runtime_adapter(runtime_context)
-        _base = (
-            os.environ.get("KSADK_A2A_INTERNAL_BASE_URL", "").strip()
-            or "http://localhost:8080"
-        )
-        _a2a_config = A2AConfig(
-            enabled=True,
-            base_url=_base,
-            agent_name=(
-                os.environ.get("KSADK_A2A_AGENT_NAME", "").strip()
-                or os.environ.get("KSADK_A2A_RUNTIME_ID", "").strip()
-            ),
-            streaming=True,
-            task_store_dsn="sqlite+aiosqlite:///.agentengine/a2a_tasks.db",
-        )
-    except Exception as _e:
-        logger.warning(f"managed A2A 数据面装配失败,回退 discovery-only: {{_e}}")
-        _a2a_config = None
-        _a2a_adapter = None
+        _managed_a2a_bootstrap = build_managed_a2a_bootstrap_from_env()
+    else:
+        from ksadk.managed_a2a_card import build_managed_a2a_card_if_configured
+
+        _managed_a2a_bootstrap = build_managed_a2a_card_if_configured()
 app = create_runtime_app(
     RuntimeAppConfig(
         runtime_type=detection_result.type.value,
         runtime_executor=RuntimeExecutor(build_default_runtime_registry()),
         launch_context=runtime_context,
-        a2a=_a2a_config or _managed_a2a_card,
+        a2a=_managed_a2a_bootstrap,
         a2a_runtime_adapter=_a2a_adapter,
     ),
     configure_runtime_app,

ksadk/builders/framework_requirements.py

@@ -19,6 +19,8 @@ LANGCHAIN_ECOSYSTEM_REQUIREMENTS = (
     "langchain-openai>=1.4.0,<2.0.0",
     "langchain-core>=1.5.0,<2.0.0",
     "langgraph>=1.2.0,<1.3.0",
+    # Plain Code runtimes use the local SQLite checkpoint backend by default.
+    "langgraph-checkpoint-sqlite>=2.0.0",
 )
 
 DEEPAGENTS_REQUIREMENTS = ("deepagents>=0.6.2,<1.0.0",)