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

ksadk/builders/container_builder.py

@@ -2,6 +2,7 @@
 Container Builder - Docker 镜像构建
 """
 
+import json
 import os
 import platform
 import shutil
@@ -404,12 +405,12 @@ CMD ["python", "entrypoint.py"]
             "pydantic>=2.0.0",
             "pyyaml>=6.0.0",
             "httpx>=0.24.0",
-            # Tracing
+            # Tracing — OTLP 双写收敛:只用 OTel + openinference 自动插桩,
+            # 不再安装 Langfuse SDK(callback 路径已删除,Langfuse 通过标准 OTLP 接收)。
             "opentelemetry-api>=1.37.0",
             "opentelemetry-sdk>=1.37.0",
             "opentelemetry-exporter-otlp>=1.37.0",
             "openinference-instrumentation-langchain>=0.1.0",
-            "langfuse>=2.0.0",
         ]
 
         framework = detection_result.type.value
@@ -441,6 +442,9 @@ CMD ["python", "entrypoint.py"]
 
     def _generate_entrypoint(self, detection_result, package_name: str) -> str:
         """生成 entrypoint.py"""
+        runtime_config_json = json.dumps(
+            self._load_config(), ensure_ascii=False, separators=(",", ":"), default=str
+        )
         return f'''"""
 AgentEngine Container 模式入口
 """
@@ -448,6 +452,7 @@ AgentEngine Container 模式入口
 import sys
 import os
 import logging
+import json
 from pathlib import Path
 
 # ========== 日志配置 ==========
@@ -489,15 +494,11 @@ except ImportError:
 
 env_keys = [
     "AGENT_RUNTIME_NAME", "AGENT_RUNTIME_ID", "ACCOUNT_ID", "PORT",
-    "LANGFUSE_BASE_URL", "LANGFUSE_HOST", "LANGFUSE_PUBLIC_KEY",
-    "LANGFUSE_SECRET_KEY", "LANGFUSE_USE_CALLBACK",
     "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
     "OTEL_EXPORTER_OTLP_HEADERS", "OTEL_EXPORTER_OTLP_TRACES_HEADERS",
-    "OTEL_SERVICE_NAME", "CLOUD_MONITOR_APP_KEY",
-    "CLOUD_MONITOR_OTLP_ENABLED", "CLOUD_MONITOR_OTLP_ENDPOINT",
-    "CLOUD_MONITOR_OTLP_TRACES_ENDPOINT", "CLOUD_MONITOR_OTLP_HEADERS",
-    "CLOUD_MONITOR_LANGFUSE_HOST", "CLOUD_MONITOR_LANGFUSE_PUBLIC_KEY",
-    "CLOUD_MONITOR_LANGFUSE_SECRET_KEY", "CLOUD_MONITOR_LANGFUSE_ENABLED",
+    "OTEL_SERVICE_NAME",
+    "CLOUD_MONITOR_OTLP_ENDPOINT", "CLOUD_MONITOR_OTLP_TRACES_ENDPOINT",
+    "CLOUD_MONITOR_OTLP_HEADERS", "CLOUD_MONITOR_OTLP_TRACES_HEADERS",
     "LANGCHAIN_TRACING_V2", "MODEL_NAME",
 ]
 for key in env_keys:
@@ -511,15 +512,9 @@ for key in env_keys:
 from ksadk.configs import setup_environment
 setup_environment(Path("/app"))
 
-try:
-    from ksadk.runners.patch_langchain import apply_patch as apply_langchain_patch
-    apply_langchain_patch()
-except ImportError:
-    pass
-
-from ksadk.runners import create_runner
 from ksadk.detection import DetectionResult, FrameworkType
-from ksadk.server import app, set_runner
+from ksadk.runtime import RuntimeExecutor, RuntimeLaunchContext, build_default_runtime_registry
+from ksadk.server import RuntimeAppConfig, configure_runtime_app, create_runtime_app
 import uvicorn
 
 # 检测结果 (构建时固化)
@@ -535,49 +530,81 @@ detection_result = DetectionResult(
 logger.info(f"框架: {{detection_result.name}}")
 logger.info(f"入口: {{detection_result.entry_point}}")
 
-# 初始化 Tracing (如果配置了 Langfuse、标准 OTLP HTTP 或 CloudMonitor OTLP)
+# 初始化 Tracing (如果配置了标准 OTLP HTTP 或 CloudMonitor OTLP)
 has_otlp = bool(
     os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
     or os.environ.get("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT")
 )
 has_cloud_monitor_otlp = bool(
-    os.environ.get("CLOUD_MONITOR_APP_KEY")
+    os.environ.get("CLOUD_MONITOR_OTLP_TRACES_HEADERS")
+    or os.environ.get("CLOUD_MONITOR_OTLP_HEADERS")
     or os.environ.get("CLOUD_MONITOR_OTLP_ENDPOINT")
     or os.environ.get("CLOUD_MONITOR_OTLP_TRACES_ENDPOINT")
+    or os.environ.get("CLOUD_MONITOR_APP_KEY")
 )
-has_cloud_monitor_langfuse = bool(
-    os.environ.get("CLOUD_MONITOR_LANGFUSE_PUBLIC_KEY")
-    or os.environ.get("CLOUD_MONITOR_LANGFUSE_SECRET_KEY")
-    or os.environ.get("CLOUD_MONITOR_LANGFUSE_HOST")
-)
-if (
-    os.environ.get("LANGFUSE_PUBLIC_KEY")
-    or has_otlp
-    or has_cloud_monitor_otlp
-    or has_cloud_monitor_langfuse
-):
+if has_otlp or has_cloud_monitor_otlp:
     try:
         from ksadk.tracing import setup_tracing
-        use_callback_only = (
-            os.environ.get("LANGFUSE_USE_CALLBACK", "").strip().lower()
-            in ("1", "true", "yes", "on")
-        )
-        setup_tracing(use_callback_only=use_callback_only)
+        setup_tracing()
         logger.info(
             f"Tracing 已启用 (OTLP={{has_otlp}}, "
-            f"CloudMonitorOTLP={{has_cloud_monitor_otlp}}, "
-            f"CloudMonitorLangfuse={{has_cloud_monitor_langfuse}}, "
-            f"CallbackOnly={{use_callback_only}})"
+            f"CloudMonitorOTLP={{has_cloud_monitor_otlp}})"
         )
     except Exception as e:
         logger.warning(f"Tracing 初始化失败: {{e}}")
 
-# 创建 Runner 并加载 Agent
-logger.info("正在加载 Agent...")
-runner = create_runner(detection_result, "/app")
-runner.load_agent()
-set_runner(runner, loaded=True)
-logger.info("Agent 加载成功!")
+# 只装配统一 RuntimeAdapter 执行链；具体 Adapter 在请求开始时由 Registry 创建。
+runtime_build_config = json.loads({runtime_config_json!r})
+runtime_context = RuntimeLaunchContext(
+    runtime_type=detection_result.type.value,
+    project_dir=Path("/app"),
+    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
+_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
+        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
+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_runtime_adapter=_a2a_adapter,
+    ),
+    configure_runtime_app,
+)
+logger.info("RuntimeAdapter 执行链装配成功!")
 
 if __name__ == "__main__":
     port = int(os.environ.get("PORT", 8080))

ksadk/builders/framework_requirements.py

@@ -4,7 +4,8 @@ from __future__ import annotations
 
 from typing import Iterable
 
-FASTAPI_REQUIREMENT = "fastapi>=0.100.0,<1.0.0"
+FASTAPI_REQUIREMENT = "fastapi>=0.136.0,<0.137.0"
+STARLETTE_REQUIREMENT = "starlette>=1.0,<1.4"
 
 ADK_REQUIREMENTS = (
     # goal-00: 与 ksadk 自身 adk extra 对齐,允许 1.34.x 与 2.x

ksadk/builders/ks3_uploader.py

@@ -10,7 +10,7 @@ from pathlib import Path
 from typing import Optional
 
 import click
-from ks3.upload import UploadTask
+from ks3.upload import UploadTask  # type: ignore[import-untyped]
 
 from ksadk.common.constants import get_ks3_endpoints
 
@@ -258,7 +258,7 @@ class KS3Uploader:
         return record_dir / f"{safe_key}.ks3resume"
 
     def _upload_via_host(self, file_path: Path, object_key: str, host: str) -> bool:
-        from ks3.connection import Connection
+        from ks3.connection import Connection  # type: ignore[import-untyped]
 
         ak = os.environ.get("KSYUN_ACCESS_KEY") or os.environ.get("KS3_ACCESS_KEY")
         sk = os.environ.get("KSYUN_SECRET_KEY") or os.environ.get("KS3_SECRET_KEY")

ksadk/builders/managed_runtime_builder.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import hashlib
 import json
-import zipfile
 from pathlib import Path
 from typing import Any
 
@@ -20,10 +19,51 @@ _MANIFEST_KEYS = (
     "artifact_type",
     "runtime",
     "model",
+    "models",
     "prompt",
+    "task_prompt",
+    "skills",
+    "mcp_servers",
+    "sandbox",
+    "approval_mode",
+    "context",
+    "memory",
 )
 
 
+def managed_runtime_lock_path(manifest_path: Path) -> Path:
+    """Return the immutable lock that accompanies a YAML-only declaration.
+
+    ``ManagedRuntime`` is not a user-code artifact.  Keeping its two small
+    declaration files next to one another makes that visible in both the
+    workspace and the build receipt, while still preserving a historical
+    manifest for rollback.
+    """
+
+    return manifest_path.with_suffix(".lock.json")
+
+
+def serialize_managed_runtime_manifest(manifest: dict[str, Any]) -> bytes:
+    """Serialize the Server-canonical ManagedRuntime declaration.
+
+    The Server validates ``ManifestSHA256`` after parsing and re-dumping YAML
+    with sorted keys.  Clients must hash those exact canonical bytes instead
+    of the editable source formatting, otherwise a valid Studio/CLI build is
+    rejected during ``CreateAgent``/``UpdateAgent`` admission.
+    """
+
+    canonical = yaml.safe_dump(
+        manifest,
+        allow_unicode=True,
+        sort_keys=True,
+        default_flow_style=False,
+        width=10_000,
+    )
+    if not canonical.endswith("\n"):
+        canonical += "\n"
+    return canonical.encode("utf-8")
+
+
 class ManagedRuntimeBuilder(BaseBuilder):
     """Build a deterministic YAML-only deployment artifact.
 
@@ -44,7 +84,10 @@ class ManagedRuntimeBuilder(BaseBuilder):
         self.build_dir = self.project_dir / ".agentengine" / "managed_runtime"
 
     def build(self) -> BuildResult:
-        config = self._load_config()
+        # An explicitly supplied snapshot is authoritative.  Studio can keep
+        # more than one Agent manifest in a workspace, so falling back to the
+        # root agentengine.yaml here would silently build the wrong Agent.
+        config = dict(self.config) if self.config else self._load_config()
         error = self._validate_config(config)
         if error:
             return BuildResult(success=False, error_message=error)
@@ -63,36 +106,35 @@ class ManagedRuntimeBuilder(BaseBuilder):
         runtime_name = str(runtime.get("name") or config.get("framework") or "").strip().lower()
         runtime = {"name": runtime_name, "version": version}
         manifest = self._normalized_manifest(config, runtime)
-        manifest_bytes = yaml.safe_dump(
-            manifest,
-            allow_unicode=True,
-            sort_keys=False,
-        ).encode("utf-8")
+        manifest_bytes = serialize_managed_runtime_manifest(manifest)
         manifest_sha256 = hashlib.sha256(manifest_bytes).hexdigest()
         lock = {
             "schema_version": RUNTIME_MANIFEST_SCHEMA,
             "runtime": runtime,
             "manifest_sha256": manifest_sha256,
         }
-        lock_bytes = (
-            json.dumps(lock, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
-        ).encode("utf-8")
+        lock_bytes = (json.dumps(lock, ensure_ascii=False, indent=2, sort_keys=True) + "\n").encode(
+            "utf-8"
+        )
 
         self.build_dir.mkdir(parents=True, exist_ok=True)
         name = str(config.get("name") or self.project_dir.name).strip() or self.project_dir.name
         project_version = str(config.get("version") or "1.0.0").strip() or "1.0.0"
-        artifact_path = self.build_dir / f"{name}-{project_version}-runtime.zip"
-        self._write_bundle(
-            artifact_path,
-            {
-                "agentengine.yaml": manifest_bytes,
-                "runtime-lock.json": lock_bytes,
-            },
+        # This local declaration receipt is retained for Studio rollback.
+        # It is deliberately *not* a ZIP: YAML agents have no user code, no
+        # KS3 artifact and no code-downloader path.  Version alone is mutable
+        # in an editable Agent, so retain the exact canonical YAML plus its
+        # lock under the content digest.
+        artifact_path = self.build_dir / (
+            f"{name}-{project_version}-{manifest_sha256[:16]}-runtime.yaml"
         )
+        lock_path = managed_runtime_lock_path(artifact_path)
+        artifact_path.write_bytes(manifest_bytes)
+        lock_path.write_bytes(lock_bytes)
         return BuildResult(
             success=True,
             artifact_path=artifact_path,
-            artifact_size=artifact_path.stat().st_size,
+            artifact_size=artifact_path.stat().st_size + lock_path.stat().st_size,
             metadata={
                 "agent_name": name,
                 "framework": str(config.get("framework") or ""),
@@ -133,13 +175,3 @@ class ManagedRuntimeBuilder(BaseBuilder):
             elif key in config:
                 normalized[key] = config[key]
         return normalized
-
-    @staticmethod
-    def _write_bundle(path: Path, files: dict[str, bytes]) -> None:
-        with zipfile.ZipFile(path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
-            for name in sorted(files):
-                info = zipfile.ZipInfo(name)
-                info.date_time = (1980, 1, 1, 0, 0, 0)
-                info.compress_type = zipfile.ZIP_DEFLATED
-                info.external_attr = 0o100644 << 16
-                archive.writestr(info, files[name])

ksadk/cli/__init__.py

@@ -67,13 +67,18 @@ ROOT_HELP_COMMANDS = {
     "completion",
     "dashboard",
     "deploy",
+    "eval",
+    "evalset",
     "files",
     "init",
     "hermes",
     "launch",
+    "managed-runtime",
     "mcp",
+    "observe",
     "openclaw",
     "run",
+    "studio",
     "version",
     "web",
 }
@@ -87,13 +92,18 @@ SHORT_HELP_MAP = {
     "completion": "Shell 补全管理",
     "dashboard": "打开云端 Agent Dashboard",
     "deploy": "部署到云端",
+    "eval": "评测本地、A2A 或 Codex Agent",
+    "evalset": "预览或上传 EvalSet 云端快照",
     "files": "管理 workspace 文件",
     "hermes": "Hermes Agent 资源管理",
     "init": "创建新项目",
     "launch": "一键构建+部署",
+    "managed-runtime": "启动平台托管的 YAML Agent",
     "mcp": "MCP 资源管理",
+    "observe": "导出本地 Agent 观测数据",
     "openclaw": "OpenClaw 资源管理",
     "run": "运行 Agent",
+    "studio": "启动本地 Agent 构建控制台",
     "version": "Agent 版本管理",
     "web": "本地调试 Agent Invoke UI",
     "config": "项目配置与模型设置",
@@ -173,12 +183,21 @@ class ColoredHelpGroup(click.Group):
         _write_colored_help_row(formatter, "agentengine init", "初始化项目")
         _write_colored_help_row(formatter, "agentengine run", "运行 API Server")
         _write_colored_help_row(formatter, "agentengine web", "本地调试 Agent Invoke UI")
+        _write_colored_help_row(formatter, "agentengine studio", "本地 Agent 构建控制台")
+        _write_colored_help_row(formatter, "agentengine eval", "评测本地、A2A 或 Codex Agent")
+        _write_colored_help_row(formatter, "agentengine evalset", "预览或上传 EvalSet 云端快照")
+        _write_colored_help_row(formatter, "agentengine observe", "导出本地 Agent 观测数据")
 
         # 云端部署
         formatter.write(click.style("  🚀  云端部署:\n\n", fg="blue", bold=True))
         _write_colored_help_row(formatter, "agentengine build", "构建部署制品")
         _write_colored_help_row(formatter, "agentengine deploy", "部署到云端")
         _write_colored_help_row(formatter, "agentengine launch", "一键构建+部署")
+        _write_colored_help_row(
+            formatter,
+            "agentengine managed-runtime",
+            "启动平台托管的 YAML Agent",
+        )
         _write_colored_help_row(formatter, "agentengine agent", "Agent 资源管理")
         _write_colored_help_row(formatter, "agentengine version", "Agent 版本管理")
         _write_colored_help_row(formatter, "agentengine mcp", "MCP 资源管理")
@@ -319,6 +338,7 @@ def _register_optional_command(cli: click.Group, module_path: str, *cmd_names: s
 def _register_commands():
     from ksadk.cli.cmd_create import create
     from ksadk.cli.cmd_deploy import deploy
+    from ksadk.cli.cmd_managed_runtime import managed_runtime
     from ksadk.cli.cmd_run import run
     from ksadk.cli.cmd_web import web
 
@@ -326,6 +346,7 @@ def _register_commands():
     _add_command_once(cli, run)
     _add_command_once(cli, deploy)
     _add_command_once(cli, web)
+    _add_command_once(cli, managed_runtime)
 
     # init 作为主命令 (PRD 规范)
     _add_command_once(cli, create, name="init")
@@ -336,6 +357,10 @@ def _register_commands():
     _register_optional_command(cli, "ksadk.cli.cmd_config", "config")
     _register_optional_command(cli, "ksadk.cli.cmd_model", "model")
     _register_optional_command(cli, "ksadk.cli.cmd_build", "build")
+    _register_optional_command(cli, "ksadk.cli.cmd_studio", "studio")
+    _register_optional_command(cli, "ksadk.cli.cmd_eval", "eval")
+    _register_optional_command(cli, "ksadk.cli.cmd_evalset", "evalset")
+    _register_optional_command(cli, "ksadk.cli.cmd_observe", "observe")
     _register_optional_command(cli, "ksadk.cli.cmd_launch", "launch")
     _register_optional_command(cli, "ksadk.cli.cmd_agent", "agent")
     _register_optional_command(cli, "ksadk.cli.cmd_status", "status")

ksadk/cli/cmd_a2a.py

@@ -32,10 +32,8 @@ from ksadk.a2a import (
 from ksadk.cli.local_runtime import reexec_with_project_venv_if_needed
 from ksadk.cli.resource_common import CONTEXT_SETTINGS
 from ksadk.detection import FrameworkDetector
-from ksadk.runners.factory import create_runner
-from ksadk.runtime.adapter import RuntimeAdapter
-from ksadk.runtime.framework_adapters import ADKRuntimeAdapter, LangGraphRuntimeAdapter
-from ksadk.runtime.runner_adapter import RunnerRuntimeAdapter
+from ksadk.runtime.factory import create_runtime_adapter
+from ksadk.runtime.launch import RuntimeLaunchContext
 
 _HELP = dict(help_option_names=["-h", "--help"])
 _DEFAULT_TASK_STORE_DSN = "sqlite+aiosqlite:///.agentengine/a2a_tasks.db"
@@ -121,7 +119,10 @@ def serve(
         command_args.append("--no-trace")
     reexec_with_project_venv_if_needed(agent_path, command_args)
     task_store_dsn = _resolve_task_store_dsn(task_store_dsn, agent_path)
-    detection_result, runner = _load_runner(agent_path, no_trace=no_trace)
+    detection_result, runtime_adapter = _load_runtime_adapter(
+        agent_path,
+        no_trace=no_trace,
+    )
     from fastapi import FastAPI
 
     app = FastAPI(title=f"ksadk A2A: {detection_result.name}")
@@ -135,12 +136,10 @@ def serve(
         include_reasoning=include_reasoning,
     )
     runtime_type = detection_result.type.value
-    runtime_adapter = _select_runtime_adapter(runtime_type, runner)
     from ksadk.a2a.task_adapter import A2ARuntimeTaskAdapter
 
     add_a2a_protocol_routes(
         app,
-        runner,
         config,
         task_adapter=A2ARuntimeTaskAdapter(runtime_adapter, runtime_type=runtime_type),
     )
@@ -212,7 +211,8 @@ def _space_client(space_id: str | None = None) -> A2ASpaceClient:
     except ValueError as exc:
         raise click.ClickException(
             f"A2A Space 未配置:{exc}。"
-            "请传 --space-id，或由 AgentEngine 部署注入 KSADK_A2A_SPACE_IDS；同时需要"
+            "请传 --space-id，或由 AgentEngine 部署注入 KSADK_A2A_SPACE_ID"
+            "（兼容 KSADK_A2A_SPACE_IDS）；同时需要"
             "KSADK_A2A_CONTROL_PLANE_URL 和 audience workload token。"
         ) from exc
 
@@ -312,40 +312,27 @@ def _detect_project(agent_path: Path, *, configure_environment: bool = True):
     return result
 
 
-def _load_runner(agent_path: Path, *, no_trace: bool):
+def _load_runtime_adapter(agent_path: Path, *, no_trace: bool):
     detection_result = _detect_project(agent_path)
+    runtime_type = detection_result.type.value
     if not no_trace:
-        _setup_tracing(detection_result.type.value)
-    runner = create_runner(detection_result, str(agent_path))
-    runner.load_agent()
-    return detection_result, runner
-
-
-def _select_runtime_adapter(runtime_type: str, runner) -> RuntimeAdapter:
-    # langchain create_agent 产物是 LangGraph CompiledStateGraph，
-    # 与 langgraph 共用 time-travel resume。
-    if runtime_type in ("langgraph", "langchain"):
-        return LangGraphRuntimeAdapter(runner)
-    if runtime_type == "adk":
-        return ADKRuntimeAdapter(runner)
-    return RunnerRuntimeAdapter(runner, runtime_type=runtime_type)
+        _setup_tracing(runtime_type)
+    context = RuntimeLaunchContext(
+        runtime_type=runtime_type,
+        project_dir=agent_path,
+        detection=detection_result,
+        config=dict(getattr(detection_result, "raw_config", None) or {}),
+    )
+    return detection_result, create_runtime_adapter(context)
 
 
 def _setup_tracing(framework_type: str) -> None:
     try:
-        import os
 
         from ksadk.tracing import setup_tracing
 
-        use_callback_only = os.getenv("LANGFUSE_USE_CALLBACK", "").strip().lower() in (
-            "1",
-            "true",
-            "yes",
-            "on",
-        )
         setup_tracing(
             enable_inmemory=True,
-            use_callback_only=use_callback_only,
         )
     except Exception:
         return

ksadk/cli/cmd_create.py

@@ -976,7 +976,7 @@ def _generate_deepagents_service_adapter_content(analysis: dict) -> str:
         runnable_build = """        try:
             runnable_module = importlib.import_module(RUNNABLE_MODULE, __package__)
             deep_agent_runnable = getattr(runnable_module, "DeepAgentRunnable")
-            return deep_agent_runnable(agent, _NullLangfuseManager())
+            return deep_agent_runnable(agent, _NullObservabilityManager())
         except Exception:
             return None
 """
@@ -992,20 +992,11 @@ import asyncio
 import importlib
 from typing import Any
 
-try:
-    from langchain_core.callbacks import BaseCallbackHandler
-except Exception:  # pragma: no cover - dependency may be absent during static checks
-    BaseCallbackHandler = object
-
 INIT_MODULE = "{init_module}"
 {runnable_module_constant}
 
-class _NoopCallbackHandler(BaseCallbackHandler):
-    pass
-
-
-class _NullLangfuseManager:
-    callback_handler = _NoopCallbackHandler()
+class _NullObservabilityManager:
+    callback_handler = None
 
 
 class AgentEngineDeepAgentsServiceAdapter:
@@ -1591,16 +1582,16 @@ deploy:
 def _write_codex_project_config(project_path: Path, package_name: str) -> None:
     """Write the minimal codex runtime project:yaml 驱动,无 package/agent.py。
 
-    codex 的 agent 逻辑由 prompt 承载(CodexRunner.load_agent 是 no-op),所以只生成
+    codex 的 agent 逻辑由 prompt 承载，所以只生成
     canonical agentengine.yaml(framework: codex,model+prompt)+ requirements +
-    README。model/prompt 经 CodexRunner 传入 codex thread(开发者指令)。
+    README。model/prompt 经 CodexRuntimeAdapter 传入 codex thread(开发者指令)。
     """
     (project_path / "agentengine.yaml").write_text(
         f"""# AgentEngine codex runtime 项目配置
 name: {package_name}
 version: "1.0.0"
 
-# 框架:codex(开发态 CodexRunner → 部署态 codex-runtime)
+# 框架:codex（本地和部署统一使用 CodexRuntimeAdapter）
 framework: codex
 artifact_type: ManagedRuntime
 
@@ -1609,7 +1600,7 @@ artifact_type: ManagedRuntime
 runtime:
   name: codex
 
-# codex 的模型与开发者指令(CodexRunner 读取并传入 codex thread)
+# codex 的模型与开发者指令（CodexRuntimeAdapter 传入 codex thread）
 model: glm-5.2
 prompt: |
   你是 codex 编码助手。简洁回答,能跑命令验证就跑(shell 工具),中文回复。
@@ -1639,7 +1630,9 @@ ksadk web .
 - codex 自动探测模型协议:OpenAI 官方直连,星流 chat 模型自动启用转换代理。
 - `agentengine build .` 只生成 YAML manifest bundle，不打包本机 Codex 二进制。若
   `runtime.version` 未指定，build 需要连接到已配置 Runtime catalog；离线构建请显式锁定版本。
-- 部署时服务端解析 ManagedRuntime 版本和 Linux 镜像 digest。
+- 部署时服务端解析 ManagedRuntime 版本和 Linux 镜像 digest。云端必须已发布 Runtime
+  catalog、对应镜像和内联 manifest 控制面；未发布时请继续使用本地 `ksadk web`，不要把
+  `runtime.version` 随意改成开发机版本，KsADK 不回退为 Code 部署。
 """,
         encoding="utf-8-sig",
     )
@@ -1885,8 +1878,6 @@ PORT=8080
     elif framework == "codex":
         env_content = _generate_codex_env_content(global_env)
     else:
-        langfuse_url = global_env.get("LANGFUSE_BASE_URL", "")
-
         env_content = """# ======================
 # 模型配置 (必填, 可以从星流平台获取https://ksp.console.ksyun.com/#/apiKey)
 # ======================
@@ -1909,13 +1900,9 @@ PORT=8080
 # 可观测性 (可选)
 # ======================
 """
-        env_content += "# LANGFUSE_PUBLIC_KEY=pk-xxx\n"
-        env_content += "# LANGFUSE_SECRET_KEY=sk-xxx\n"
-
-        if langfuse_url:
-            env_content += f"LANGFUSE_BASE_URL={langfuse_url}\n"
-        else:
-            env_content += "# LANGFUSE_BASE_URL=https://cloud.langfuse.com\n"
+        env_content += "# OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf\n"
+        env_content += "# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://collector.example.com/v1/traces\n"
+        env_content += "# OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20placeholder\n"
 
         env_content += """
 # ======================

ksadk/cli/cmd_dashboard.py

@@ -64,6 +64,10 @@ _PATH_EMBEDDED_OPTION_HINTS = (
 DEFAULT_PRIVATE_LINK_EXPIRES_SECONDS = 24 * 60 * 60
 MAX_PRIVATE_LINK_EXPIRES_SECONDS = 365 * 24 * 60 * 60
 DEFAULT_REGION = "cn-beijing-6"
+# Hosted UI is the shared interaction surface for platform-managed Agents.
+# The access link keeps the user/session/Agent binding while this path keeps
+# the Web release independent from the Agent runtime image.
+HOSTED_INTERACTION_UI_PATH = "/hosted-ui/chat"
 
 DASHBOARD_RESOURCE = ResourceDescriptor(
     name="Dashboard",
@@ -528,7 +532,17 @@ def _open_dashboard(
     )
     normalized_path = _normalize_ui_path(resolved_ui.path or "/")
     custom_ui_enabled = str(resolved_ui.profile or "").strip().lower() == "custom"
-    link_path = normalized_path if ui_path is not None or custom_ui_enabled else None
+    # Hermes owns its own dashboard surface and OpenClaw takes its gateway
+    # branch below.  The shared Hosted UI is the default only for the generic
+    # ADK/LangChain-compatible profiles; an explicit/custom path always wins.
+    use_hosted_interaction_ui = resolved_ui.profile in {"adk", "langchain"}
+    link_path = (
+        normalized_path
+        if ui_path is not None or custom_ui_enabled
+        else HOSTED_INTERACTION_UI_PATH
+        if use_hosted_interaction_ui
+        else None
+    )
     base_url = _build_base_ui_url(endpoint, normalized_path)
 
     if direct: