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

ksadk/cli/cmd_replay.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+"""ksadk replay — 基于 RuntimeEvent store + session 级订阅的历史回放 (goal-16)。
+
+CLI 是消费 RuntimeAdapter/RuntimeEvent 的薄壳(不含 runtime 逻辑):replay 复用 goal-10
+``RuntimeEventStore`` 与 goal-12 共享 parser/replay,把某 session 的 RuntimeEvent 历史
+回放为确定性 transcript(text/reasoning/tool/artifact/run + a2ui/a2a extras)。
+
+注:回放的是经 RuntimeEvent 持久化的新事件模型(带 runtime marker);legacy SessionEvent
+(旧 assistant_message 等)不在本模型内,不回放。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import click
+
+from ksadk.cli.resource_common import CONTEXT_SETTINGS
+from ksadk.events.replay import replay_transcript
+from ksadk.events.store import RuntimeEventStore
+
+_HELP = dict(help_option_names=["-h", "--help"])
+
+
+@click.command(
+    "replay", context_settings=CONTEXT_SETTINGS, help="回放某 session 的 RuntimeEvent 历史"
+)
+@click.argument("session_id")
+@click.option(
+    "--after-seq-id", default=0, show_default=True, type=int, help="从该 seq cursor 之后回放"
+)
+@click.option("--before-seq-id", default=None, type=int, help="回放上界(不含该 seq)")
+@click.option(
+    "--format", "fmt", type=click.Choice(["json", "text"]), default="text", show_default=True
+)
+def replay(session_id: str, after_seq_id: int, before_seq_id: int | None, fmt: str):
+    """回放 session 的 RuntimeEvent 历史(text/reasoning/tool/artifact/run)。"""
+    asyncio.run(_run(session_id, after_seq_id=after_seq_id, before_seq_id=before_seq_id, fmt=fmt))
+
+
+async def _run(session_id: str, *, after_seq_id: int, before_seq_id: int | None, fmt: str) -> None:
+    from ksadk.sessions import resolve_session_service
+
+    store = RuntimeEventStore(resolve_session_service())
+    parser = await replay_transcript(
+        store, session_id, after_seq_id=after_seq_id, before_seq_id=before_seq_id
+    )
+    transcript = parser.transcript()
+    if fmt == "json":
+        click.echo(json.dumps(transcript, ensure_ascii=False, sort_keys=True))
+        return
+
+    items = transcript["items"]
+    if not items and not transcript["extras"]:
+        click.echo(f"session {session_id} 无 RuntimeEvent 历史(或该 session 未经新事件模型持久化)")
+        return
+    for item in items:
+        kind = item.get("kind")
+        if kind in ("text", "reasoning"):
+            marker = "▍final" if item.get("final") else "▍delta"
+            click.echo(f"[{kind}/{item.get('phase')}] {marker} {item.get('text')}")
+        elif kind == "tool_call":
+            done = "✓" if item.get("done") else "…"
+            click.echo(f"[tool] {done} {item.get('name')} ({item.get('call_id')})")
+        elif kind == "artifact":
+            click.echo(f"[artifact] {item.get('name')} v{item.get('version')}")
+    for inv, status in transcript["run_status"].items():
+        click.echo(f"[run] {inv}: {status}")
+    for extra in transcript["extras"]:
+        click.echo(f"[{extra['event_type']}] {json.dumps(extra['payload'], ensure_ascii=False)}")

ksadk/cli/cmd_run.py

@@ -5,12 +5,13 @@ ksadk run - 本地运行 Agent
 对于 LangChain/LangGraph/DeepAgents 项目，使用自己的实现
 """
 
-import click
-import asyncio
+import os
 import subprocess
 import sys
-import os
 from pathlib import Path
+
+import click
+
 from ksadk.cli.error_utils import ensure_json_output_supported, print_exception
 from ksadk.cli.local_runtime import reexec_with_project_venv_if_needed
 from ksadk.cli.ui import (
@@ -38,16 +39,28 @@ from ksadk.cli.ui import (
     is_flag=True,
     help="兼容参数；TUI 已默认使用 inline viewport 并保留终端 scrollback",
 )
-def run(agent_dir: str, port: int, interactive: bool, no_trace: bool, model: str, show_thinking: bool, no_stream: bool, no_alt_screen: bool):
+def run(
+    agent_dir: str,
+    port: int,
+    interactive: bool,
+    no_trace: bool,
+    model: str,
+    show_thinking: bool,
+    no_stream: bool,
+    no_alt_screen: bool,
+):
     """运行 Agent (支持 LangChain / LangGraph / DeepAgents / ADK)
 
     AGENT_DIR: Agent 项目目录 (默认: 当前目录)
     """
     ensure_json_output_supported(
         "agentengine run",
-        suggestion="请改用 `agentengine agent status --output json` 或 `agentengine build --output json` 获取结构化信息。",
+        suggestion=(
+            "请改用 `agentengine agent status --output json` 或 "
+            "`agentengine build --output json` 获取结构化信息。"
+        ),
     )
-    from ksadk.detection import FrameworkDetector, FrameworkType
+    from ksadk.detection import FrameworkDetector
 
     agent_path = Path(agent_dir).resolve()
     command_args = ["run", str(agent_path), "--port", str(port)]
@@ -91,7 +104,7 @@ def run(agent_dir: str, port: int, interactive: bool, no_trace: bool, model: str
         "langchain": "LangChain",
         "langgraph": "LangGraph",
         "deepagents": "DeepAgents",
-        "unknown": "Unknown"
+        "unknown": "Unknown",
     }
     framework_name = framework_map.get(result.type.value, result.type.value)
 
@@ -99,10 +112,16 @@ def run(agent_dir: str, port: int, interactive: bool, no_trace: bool, model: str
     print_kv("Agent 名称", str(result.name))
     print_kv("入口点", str(result.entry_point))
 
+    from ksadk.cli.cmd_web import configure_local_runtime_persistence
+
+    configure_local_runtime_persistence(agent_path, result.type.value)
+
     # 2. 根据框架类型选择处理方式
     # 所有框架统一使用 _run_custom() 以支持 Langfuse 自动插桩
     # (Langfuse instrumentation 需要在同一进程内生效)
-    _run_custom(result, agent_path, port, interactive, no_trace, show_thinking, no_stream, no_alt_screen)
+    _run_custom(
+        result, agent_path, port, interactive, no_trace, show_thinking, no_stream, no_alt_screen
+    )
 
 
 def _run_adk_cli(agent_path: Path, port: int = 8080, command: str = "run"):
@@ -178,9 +197,10 @@ def _run_custom(
     # 初始化 Tracing
     if not no_trace:
         try:
-            from ksadk.tracing import setup_tracing
             import os
 
+            from ksadk.tracing import setup_tracing
+
             has_langfuse = bool(os.getenv("LANGFUSE_PUBLIC_KEY"))
             has_otlp = bool(
                 os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
@@ -203,7 +223,9 @@ def _run_custom(
             if has_otlp:
                 print_info("Tracing: Enabled (InMemory + OTLP HTTP)")
             elif has_langfuse:
-                print_info(f"Tracing: Enabled (InMemory + Langfuse, CallbackOnly={use_callback_only})")
+                print_info(
+                    f"Tracing: Enabled (InMemory + Langfuse, CallbackOnly={use_callback_only})"
+                )
             else:
                 print_info("Tracing: Enabled")
         except Exception as e:
@@ -225,6 +247,7 @@ def _run_custom(
     if interactive:
         # TUI 交互模式
         from ksadk.tui.loop import run_tui
+
         run_tui(
             runner,
             show_thinking=show_thinking,

ksadk/cli/cmd_status.py

@@ -4,15 +4,17 @@ agentengine status - 查看 Agent 运行状态和 Endpoint
 支持 watch 模式实时刷新
 """
 
-import click
 import asyncio
 import time
-from pathlib import Path
 from datetime import datetime
+from pathlib import Path
 from typing import Sequence
+
+import click
+
 from ksadk.api.client import DryRunExit
 from ksadk.cli.agent_ref import merge_agent_inputs, resolve_agent_ref
-from ksadk.cli.dry_run import dry_run_option, run_async_with_dry_run, effective_dry_run
+from ksadk.cli.dry_run import dry_run_option, effective_dry_run, run_async_with_dry_run
 from ksadk.cli.error_utils import print_exception, resolution_error, usage_error
 from ksadk.cli.resource_common import (
     CONTEXT_SETTINGS,
@@ -24,14 +26,10 @@ from ksadk.cli.resource_common import (
 from ksadk.cli.ui import (
     get_console,
     is_json_output,
-    print_error,
     print_info,
-    print_kv,
-    print_title,
-    print_warn,
+    replica_rich_style,
     status_click_color,
     status_rich_style,
-    replica_rich_style,
     summary_panel,
 )
 
@@ -55,7 +53,9 @@ AGENT_LIST_HIDDEN_FRAMEWORK_LABELS = {
 @click.option("--watch", "-w", is_flag=True, help="Watch 模式，持续刷新")
 @click.option("--interval", "-i", default=2, help="Watch 刷新间隔 (秒)")
 @click.option("--region", "-r", default="cn-beijing-6", envvar="KSYUN_REGION", help="区域")
-@click.option("--account-id", envvar="KSYUN_ACCOUNT_ID", help="金山云账号 ID（可选；未设置时从 AK/SK 反查）")
+@click.option(
+    "--account-id", envvar="KSYUN_ACCOUNT_ID", help="金山云账号 ID（可选；未设置时从 AK/SK 反查）"
+)
 @dry_run_option()
 def status(
     agent_ref: str,
@@ -125,9 +125,12 @@ def run_status_command(
         if not resolved:
             raise resolution_error(
                 "请指定 Agent（--agent 或位置参数），或在当前目录提供可解析的本地配置",
-                hints=["自动解析顺序: .agentengine.state -> agentengine.yaml/ksadk.yaml", "请先执行 `agentengine agent list`。"],
+                hints=[
+                    "自动解析顺序: .agentengine.state -> agentengine.yaml/ksadk.yaml",
+                    "请先执行 `agentengine agent list`。",
+                ],
             )
-        agent = resolved.value
+        agent = str(resolved.value)
         if resolved.source != "cli":
             print_info(f"未显式指定 Agent，使用 {resolved.source_text}: {agent}")
 
@@ -136,23 +139,34 @@ def run_status_command(
     if watch and dry_run:
         raise usage_error("Watch 模式不支持 dry-run，请去掉 --watch 或取消 dry-run。")
     if watch and is_json_output():
-        raise usage_error("Watch 模式不支持 `--output json`。", hints=["请去掉 `--watch` 或改用 `agentengine agent status --output json`。"])
+        raise usage_error(
+            "Watch 模式不支持 `--output json`。",
+            hints=["请去掉 `--watch` 或改用 `agentengine agent status --output json`。"],
+        )
 
     # Dry Run 模式由 AgentEngineClient 处理
     # 只要传入 dry_run=True，底层 client 会抛出 DryRunExit 异常
 
+    resolved_account_id = account_id or ""
     if show_all:
         run_async_with_dry_run(
-            _list_all_agents(region, account_id, dry_run, page=page, size=size, framework=framework),
+            _list_all_agents(
+                region,
+                resolved_account_id,
+                dry_run,
+                page=page,
+                size=size,
+                framework=framework,
+            ),
             dry_run=dry_run,
             dry_run_resource="agent",
             dry_run_action="list",
         )
     elif watch:
-        _watch_status(agent, region, account_id, interval)
+        _watch_status(str(agent), region, resolved_account_id, interval)
     else:
         run_async_with_dry_run(
-            _show_agent_status(agent, region, account_id, dry_run),
+            _show_agent_status(str(agent), region, resolved_account_id, dry_run),
             dry_run=dry_run,
             dry_run_resource="agent",
             dry_run_action="status",
@@ -170,7 +184,7 @@ def _watch_status(agent: str, region: str, account_id: str, interval: int):
             click.clear()
 
             # 显示标题
-            click.secho(f"Agent Status Monitor", fg="blue", bold=True)
+            click.secho("Agent Status Monitor", fg="blue", bold=True)
             click.echo(f"   Agent: {agent}")
             click.echo(f"   Region: {region}")
             click.echo(f"   更新时间: {datetime.now().strftime('%H:%M:%S')}")
@@ -205,7 +219,9 @@ async def _show_agent_status(
         # 先按 ID 查询，失败后再按名称查询，避免依赖字符串前缀判断。
         result = await _get_agent_runtime(agent, region, account_id, dry_run, is_name=False)
         if result.get("status") == "Error":
-            result_by_name = await _get_agent_runtime(agent, region, account_id, dry_run, is_name=True)
+            result_by_name = await _get_agent_runtime(
+                agent, region, account_id, dry_run, is_name=True
+            )
             if result_by_name.get("status") != "Error":
                 result = result_by_name
 
@@ -219,14 +235,14 @@ async def _show_agent_status(
     langfuse_url = result.get("langfuseTraceUrl")
     from dateutil import parser
 
-    created_at = result.get('createdAt')
+    created_at = result.get("createdAt")
     if created_at:
         dt = parser.parse(created_at)
         created_at = dt.astimezone().isoformat()
     else:
         created_at = "-"
 
-    updated_at = result.get('updatedAt')
+    updated_at = result.get("updatedAt")
     if updated_at:
         dt = parser.parse(updated_at)
         updated_at = dt.astimezone().isoformat()
@@ -378,8 +394,8 @@ async def _list_all_agents(
     rows = []
     items = []
     for r in results:
-        agent_id = (r.get("agentRuntimeId") or "N/A")
-        name = (r.get("agentRuntimeName") or "N/A")
+        agent_id = r.get("agentRuntimeId") or "N/A"
+        name = r.get("agentRuntimeName") or "N/A"
         status_val = r.get("status", "Unknown")
         ready = int(r.get("readyReplicas", 0) or 0)
         replicas = int(r.get("replicas", 0) or 0)
@@ -419,8 +435,20 @@ async def _list_all_agents(
         columns=(
             {"header": "ID", "key": "id", "style": "#58a6ff", "no_wrap": True, "min_width": 24},
             {"header": "名称", "key": "name", "style": "#c9d1d9", "min_width": 20},
-            {"header": "状态", "key": "status", "no_wrap": True, "justify": "center", "min_width": 10},
-            {"header": "副本", "key": "replicas_display", "no_wrap": True, "justify": "center", "min_width": 8},
+            {
+                "header": "状态",
+                "key": "status",
+                "no_wrap": True,
+                "justify": "center",
+                "min_width": 10,
+            },
+            {
+                "header": "副本",
+                "key": "replicas_display",
+                "no_wrap": True,
+                "justify": "center",
+                "min_width": 8,
+            },
             {"header": "Endpoint", "key": "endpoint", "style": "#8b949e", "overflow": "ellipsis"},
         ),
         rows=rows,
@@ -446,7 +474,9 @@ async def _list_all_agents(
         ],
     )
     if not is_json_output():
-        console.print(summary_panel(total=len(results), healthy=running, attention=unhealthy, noun="Agent"))
+        console.print(
+            summary_panel(total=len(results), healthy=running, attention=unhealthy, noun="Agent")
+        )
 
 
 def _get_status_color(status: str) -> str:
@@ -454,19 +484,24 @@ def _get_status_color(status: str) -> str:
     return status_click_color(status)
 
 
-async def _get_agent_runtime(agent: str, region: str, account_id: str, dry_run: bool = False, is_name: bool = False) -> dict:
+async def _get_agent_runtime(
+    agent: str, region: str, account_id: str, dry_run: bool = False, is_name: bool = False
+) -> dict:
     """获取 Agent 运行时状态
 
     调用 AgentEngine Server API
     """
     from ksadk.api import AgentEngineClient
+
     try:
         extra_headers = {}
         # 传递 Account ID
         if account_id:
             extra_headers["X-Ksc-Account-Id"] = account_id
 
-        async with AgentEngineClient(region=region, dry_run=dry_run, extra_headers=extra_headers) as client:
+        async with AgentEngineClient(
+            region=region, dry_run=dry_run, extra_headers=extra_headers
+        ) as client:
             if is_name:
                 response = await client.get_agent(name=agent)
             else:
@@ -484,10 +519,21 @@ async def _get_agent_runtime(agent: str, region: str, account_id: str, dry_run:
                 "description": basic.get("description", "") or response.get("description", ""),
                 "status": basic.get("status", "") or response.get("status", "Unknown"),
                 "phase": basic.get("phase", "") or response.get("phase", ""),
-                "replicas": basic.get("replicas") if basic.get("replicas") is not None else response.get("replicas", deploy.get("scaling", {}).get("min_replicas", 1)),
-                "readyReplicas": basic.get("ready_replicas") if basic.get("ready_replicas") is not None else response.get("ready_replicas", 0),
-                "endpoint": quick.get("public_endpoint") or quick.get("private_endpoint") or response.get("endpoint", ""),
-                "langfuseTraceUrl": adv.get("observability_url", "") or response.get("langfuse_trace_url", ""),
+                "replicas": (
+                    basic.get("replicas")
+                    if basic.get("replicas") is not None
+                    else response.get("replicas", deploy.get("scaling", {}).get("min_replicas", 1))
+                ),
+                "readyReplicas": (
+                    basic.get("ready_replicas")
+                    if basic.get("ready_replicas") is not None
+                    else response.get("ready_replicas", 0)
+                ),
+                "endpoint": quick.get("public_endpoint")
+                or quick.get("private_endpoint")
+                or response.get("endpoint", ""),
+                "langfuseTraceUrl": adv.get("observability_url", "")
+                or response.get("langfuse_trace_url", ""),
                 "createdAt": basic.get("created_at", "") or response.get("created_at", ""),
                 "updatedAt": basic.get("updated_at", "") or response.get("updated_at", ""),
                 "message": basic.get("message", "") or response.get("message", ""),
@@ -517,13 +563,16 @@ async def _list_agent_runtimes(
     调用 AgentEngine Server API
     """
     from ksadk.api import AgentEngineClient
+
     try:
         extra_headers = {}
         # 传递 Account ID
         if account_id:
             extra_headers["X-Ksc-Account-Id"] = account_id
 
-        async with AgentEngineClient(region=region, dry_run=dry_run, extra_headers=extra_headers) as client:
+        async with AgentEngineClient(
+            region=region, dry_run=dry_run, extra_headers=extra_headers
+        ) as client:
             response = await client.list_agents(
                 region=region,
                 framework=framework,

ksadk/cli/cmd_version.py

@@ -1,14 +1,15 @@
 """agentengine version - Agent 版本资源管理。"""
 
 import os
-import click
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Optional
-from datetime import datetime, timedelta, timezone
+
+import click
 
 from ksadk.api.client import DryRunExit
 from ksadk.cli.agent_ref import merge_agent_inputs, resolve_agent_ref
-from ksadk.cli.dry_run import dry_run_option, run_async_with_dry_run, effective_dry_run
+from ksadk.cli.dry_run import dry_run_option, effective_dry_run, run_async_with_dry_run
 from ksadk.cli.error_utils import abort_with_cli_error, resolution_error
 from ksadk.cli.resource_common import (
     CONTEXT_SETTINGS,
@@ -23,7 +24,8 @@ from ksadk.cli.resource_common import (
     render_descriptor_list,
     render_descriptor_status,
 )
-from ksadk.cli.ui import get_console, output_option as cli_output_option, status_rich_style
+from ksadk.cli.ui import get_console, status_rich_style
+from ksadk.cli.ui import output_option as cli_output_option
 
 console = get_console()
 
@@ -94,8 +96,9 @@ def _extract_agent_id(agent: dict) -> Optional[str]:
     if isinstance(basic, dict):
         agent_id = basic.get("agent_id")
         if agent_id:
-            return agent_id
-    return agent.get("agent_id") or agent.get("id")
+            return str(agent_id)
+    fallback = agent.get("agent_id") or agent.get("id")
+    return str(fallback) if fallback else None
 
 
 async def _resolve_agent_id(agent_ref: str, client) -> Optional[str]:
@@ -147,9 +150,7 @@ async def _resolve_target_agent_id(
         include_project_config=True,
     )
     if not resolved:
-        raise ValueError(
-            "请指定 Agent（--agent 或位置参数），或在当前目录提供可解析的本地配置"
-        )
+        raise ValueError("请指定 Agent（--agent 或位置参数），或在当前目录提供可解析的本地配置")
 
     if resolved.source != "cli":
         console.print(
@@ -162,7 +163,9 @@ async def _resolve_target_agent_id(
     return agent_id
 
 
-@click.group("version", context_settings=CONTEXT_SETTINGS, help=build_resource_group_help(VERSION_RESOURCE))
+@click.group(
+    "version", context_settings=CONTEXT_SETTINGS, help=build_resource_group_help(VERSION_RESOURCE)
+)
 def version():
     pass
 
@@ -345,7 +348,9 @@ def release_version(
     dry_run = effective_dry_run(dry_run)
     try:
         run_async_with_dry_run(
-            _release_version_async(agent_ref, agent_option, name, region, tag, description, dry_run),
+            _release_version_async(
+                agent_ref, agent_option, name, region, tag, description, dry_run
+            ),
             dry_run=dry_run,
             dry_run_resource="version",
             dry_run_action="release",
@@ -437,7 +442,9 @@ def rollback_version(
     dry_run = effective_dry_run(dry_run)
     try:
         run_async_with_dry_run(
-            _rollback_version_async(agent_ref, agent_option, name, region, target, assume_yes, dry_run),
+            _rollback_version_async(
+                agent_ref, agent_option, name, region, target, assume_yes, dry_run
+            ),
             dry_run=dry_run,
             dry_run_resource="version",
             dry_run_action="rollback",
@@ -496,7 +503,7 @@ async def _rollback_version_async(
                     ks3_secret_key=secret_key,
                 )
 
-        fields = [
+        fields: list[tuple[str, str, str | None]] = [
             ("当前版本", str(result.get("current_tag") or "-"), "#58a6ff"),
         ]
         if result.get("message"):