agentengine-sdk-python 0.6.2__py3-none-any.whl → 0.6.9__py3-none-any.whl

ksadk/cli/agent_ref.py

@@ -0,0 +1,204 @@
+"""Resource reference resolution helpers for CLI commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class ResolvedResourceRef:
+    value: str
+    source: str
+    resource: str = "agent"
+    source_path: Optional[Path] = None
+
+    @property
+    def source_text(self) -> str:
+        if self.source == "cli":
+            return "命令行参数"
+        if self.source.startswith("state."):
+            field = self.source.split(".", 1)[1]
+            return f"{self._path_name()} 的 {field}"
+        if self.source.startswith("config."):
+            field = self.source.split(".", 1)[1]
+            return f"{self._path_name()} 的 {field}"
+        return self.source
+
+    def _path_name(self) -> str:
+        if self.source_path:
+            return self.source_path.name
+        return "本地文件"
+
+
+ResolvedAgentRef = ResolvedResourceRef
+
+
+def merge_agent_inputs(
+    *,
+    agent_option: Optional[str] = None,
+    positional_agent: Optional[str] = None,
+    legacy_name: Optional[str] = None,
+) -> Optional[str]:
+    """Merge all agent inputs and detect conflicts."""
+    candidates = [
+        ("--agent", _normalize(agent_option)),
+        ("位置参数", _normalize(positional_agent)),
+        ("--name", _normalize(legacy_name)),
+    ]
+    values = [(label, value) for label, value in candidates if value]
+    if not values:
+        return None
+
+    first_value = values[0][1]
+    for _, value in values[1:]:
+        if value != first_value:
+            labels = " / ".join(label for label, _ in values)
+            raise ValueError(f"检测到多个不同的 Agent 参数来源: {labels}，请只保留一个")
+    return first_value
+
+
+def resolve_agent_ref(
+    explicit: Optional[str],
+    *,
+    cwd: Optional[Path] = None,
+    include_state: bool = True,
+    include_project_config: bool = True,
+) -> Optional[ResolvedAgentRef]:
+    """Resolve agent reference from CLI input and local files."""
+    return resolve_resource_ref(
+        explicit,
+        resource="agent",
+        cwd=cwd,
+        include_state=include_state,
+        include_project_config=include_project_config,
+    )
+
+
+def resolve_resource_ref(
+    explicit: Optional[str],
+    *,
+    resource: str,
+    cwd: Optional[Path] = None,
+    include_state: bool = True,
+    include_project_config: bool = False,
+) -> Optional[ResolvedResourceRef]:
+    """Resolve a resource reference from CLI input and local files."""
+    if explicit:
+        return ResolvedResourceRef(value=explicit, source="cli", resource=resource)
+
+    root = cwd or Path(".")
+
+    if include_state:
+        state_path = root / ".agentengine.state"
+        state_data = _read_yaml_dict(state_path)
+        if state_data:
+            for field_name, value in _state_candidates(state_data, resource):
+                return ResolvedResourceRef(
+                    value=value,
+                    source=f"state.{field_name}",
+                    resource=resource,
+                    source_path=state_path,
+                )
+
+    if include_project_config:
+        for file_name in ("agentengine.yaml", "ksadk.yaml"):
+            path = root / file_name
+            data = _read_yaml_dict(path)
+            if not data:
+                continue
+            name = _normalize(data.get("name"))
+            if name:
+                return ResolvedResourceRef(
+                    value=name,
+                    source="config.name",
+                    resource=resource,
+                    source_path=path,
+                )
+
+    return None
+
+
+def resolve_mcp_ref(
+    explicit: Optional[str],
+    *,
+    cwd: Optional[Path] = None,
+    include_state: bool = True,
+) -> Optional[ResolvedResourceRef]:
+    return resolve_resource_ref(
+        explicit,
+        resource="mcp",
+        cwd=cwd,
+        include_state=include_state,
+        include_project_config=False,
+    )
+
+
+def resolve_openclaw_ref(
+    explicit: Optional[str],
+    *,
+    cwd: Optional[Path] = None,
+    include_state: bool = True,
+) -> Optional[ResolvedResourceRef]:
+    return resolve_resource_ref(
+        explicit,
+        resource="openclaw",
+        cwd=cwd,
+        include_state=include_state,
+        include_project_config=False,
+    )
+
+
+def _normalize(value: Optional[object]) -> Optional[str]:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        value = str(value)
+    value = value.strip()
+    return value or None
+
+
+def _state_candidates(state_data: dict, resource: str) -> list[tuple[str, str]]:
+    state_type = _normalize(state_data.get("type"))
+
+    if resource == "agent":
+        if state_type == "mcp":
+            return []
+        return _pick_fields(state_data, ("agent_id", "name"))
+
+    if resource == "mcp":
+        if state_type != "mcp":
+            return []
+        return _pick_fields(state_data, ("mcp_id", "name"))
+
+    if resource == "openclaw":
+        if state_type != "openclaw":
+            return []
+        return _pick_fields(state_data, ("agent_id", "name"))
+
+    return []
+
+
+def _pick_fields(state_data: dict, fields: tuple[str, ...]) -> list[tuple[str, str]]:
+    values: list[tuple[str, str]] = []
+    for field in fields:
+        value = _normalize(state_data.get(field))
+        if value:
+            values.append((field, value))
+    return values
+
+
+def _read_yaml_dict(path: Path) -> Optional[dict]:
+    if not path.exists():
+        return None
+    try:
+        import yaml
+
+        with open(path, encoding="utf-8-sig") as f:
+            data = yaml.safe_load(f) or {}
+        if isinstance(data, dict):
+            return data
+    except Exception:
+        return None
+    return None

ksadk/cli/cmd_a2a.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Sequence
+
+import click
+import uvicorn
+
+import ksadk.configs as configs
+from ksadk.a2a import AgentCardBuilder, KsA2AServer
+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
+
+
+@click.group("a2a", context_settings=CONTEXT_SETTINGS, help="A2A 协议服务与 Agent Card")
+def a2a():
+    """A2A protocol helpers."""
+
+
+@a2a.command("serve", context_settings=dict(help_option_names=["-h", "--help"]))
+@click.argument(
+    "agent_dir",
+    default=".",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+)
+@click.option("--host", default="0.0.0.0", show_default=True, help="服务监听地址")
+@click.option("--port", default=8081, show_default=True, type=int, help="服务端口")
+@click.option("--url", default=None, help="Agent Card 对外宣告地址")
+@click.option("--name", default=None, help="覆盖 Agent 名称")
+@click.option("--description", default="", help="覆盖 Agent 描述")
+@click.option("--skill", "skills", multiple=True, help="可重复传入，追加 Agent Card 技能")
+@click.option("--no-trace", is_flag=True, help="禁用 Tracing")
+def serve(
+    agent_dir: Path,
+    host: str,
+    port: int,
+    url: str | None,
+    name: str | None,
+    description: str,
+    skills: Sequence[str],
+    no_trace: bool,
+):
+    """启动 A2A 协议服务。"""
+    agent_path = agent_dir.resolve()
+    command_args = [
+        "a2a",
+        "serve",
+        str(agent_path),
+        "--host",
+        host,
+        "--port",
+        str(port),
+    ]
+    if url:
+        command_args.extend(["--url", url])
+    if name:
+        command_args.extend(["--name", name])
+    if description:
+        command_args.extend(["--description", description])
+    for skill in skills:
+        command_args.extend(["--skill", skill])
+    if no_trace:
+        command_args.append("--no-trace")
+    reexec_with_project_venv_if_needed(agent_path, command_args)
+
+    detection_result, runner = _load_runner(agent_path, no_trace=no_trace)
+    app_name = name or detection_result.name
+    public_url = url or f"http://127.0.0.1:{port}"
+    server = KsA2AServer(
+        runner=runner,
+        app_name=app_name,
+        url=public_url,
+        description=description,
+        skills=skills,
+    )
+    uvicorn.run(server.build(), host=host, port=port)
+
+
+@a2a.command("card", context_settings=dict(help_option_names=["-h", "--help"]))
+@click.argument(
+    "agent_dir",
+    default=".",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+)
+@click.option(
+    "--url",
+    default="http://127.0.0.1:8081",
+    show_default=True,
+    help="Agent Card 对外宣告地址",
+)
+@click.option("--name", default=None, help="覆盖 Agent 名称")
+@click.option("--description", default="", help="覆盖 Agent 描述")
+@click.option("--skill", "skills", multiple=True, help="可重复传入，追加 Agent Card 技能")
+def card(
+    agent_dir: Path,
+    url: str,
+    name: str | None,
+    description: str,
+    skills: Sequence[str],
+):
+    """输出 Agent Card JSON。"""
+    agent_path = agent_dir.resolve()
+    detection_result = _detect_project(agent_path)
+    payload = _build_agent_card_payload(
+        app_name=name or detection_result.name,
+        url=url,
+        description=description,
+        skills=skills,
+    )
+    click.echo(json.dumps(payload, ensure_ascii=False))
+
+
+def _detect_project(agent_path: Path):
+    configs.setup_environment(agent_path)
+    result = FrameworkDetector(str(agent_path)).detect()
+    if result.type.value == "unknown":
+        raise click.ClickException("未检测到支持的框架 (LangChain/LangGraph/DeepAgents/ADK)")
+    return result
+
+
+def _load_runner(agent_path: Path, *, no_trace: bool):
+    detection_result = _detect_project(agent_path)
+    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 _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,
+            enable_langfuse=None,
+            use_callback_only=use_callback_only,
+        )
+    except Exception:
+        return
+
+
+def _build_agent_card_payload(
+    *,
+    app_name: str,
+    url: str,
+    description: str,
+    skills: Sequence[str],
+) -> dict:
+    card = AgentCardBuilder(
+        name=app_name,
+        url=url,
+        description=description,
+        skills=skills,
+    ).build()
+    return card.model_dump(mode="json")

ksadk/cli/cmd_agent.py

@@ -0,0 +1,201 @@
+"""Canonical Agent resource group."""
+
+from __future__ import annotations
+
+import click
+from pathlib import Path
+
+from ksadk.cli.cmd_destroy import run_delete_command
+from ksadk.cli.cmd_invoke import run_invoke_command
+from ksadk.cli.cmd_status import run_status_command
+from ksadk.cli.dry_run import dry_run_option
+from ksadk.cli.error_utils import ensure_dry_run_supported, ensure_json_output_supported
+from ksadk.cli.resource_common import CONTEXT_SETTINGS, pagination_options
+from ksadk.cli.ui import output_option as cli_output_option
+
+
+@click.group("agent", context_settings=CONTEXT_SETTINGS)
+def agent():
+    """Agent 资源管理。"""
+
+
+@agent.command("list", context_settings=CONTEXT_SETTINGS)
+@pagination_options(default_page=1, default_size=20)
+@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("--framework", help="按框架过滤，支持逗号分隔多个值，如 langgraph,adk")
+@dry_run_option()
+@cli_output_option()
+def list_agents(
+    page: int,
+    size: int,
+    region: str,
+    account_id: str,
+    framework: str | None,
+    dry_run: bool,
+    output_mode: str | None,
+):
+    """列出已部署的 Agent。"""
+    _ = output_mode
+    run_status_command(
+        agent_ref=None,
+        agent_option=None,
+        show_all=True,
+        watch=False,
+        interval=2,
+        region=region,
+        account_id=account_id,
+        framework=framework,
+        dry_run=dry_run,
+        compatibility_alias=False,
+        page=page,
+        size=size,
+    )
+
+
+@agent.command("status", context_settings=CONTEXT_SETTINGS)
+@click.argument("agent_ref", required=False)
+@click.option("--agent", "--agent-id", "agent_option", "-a", help="Agent 名称或 ID")
+@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 反查）")
+@dry_run_option()
+@cli_output_option()
+def status_agent(
+    agent_ref: str | None,
+    agent_option: str | None,
+    watch: bool,
+    interval: int,
+    region: str,
+    account_id: str,
+    dry_run: bool,
+    output_mode: str | None,
+):
+    """查看单个 Agent 状态。"""
+    _ = output_mode
+    run_status_command(
+        agent_ref=agent_ref,
+        agent_option=agent_option,
+        show_all=False,
+        watch=watch,
+        interval=interval,
+        region=region,
+        account_id=account_id,
+        dry_run=dry_run,
+        compatibility_alias=False,
+    )
+
+
+@agent.command("invoke", context_settings=CONTEXT_SETTINGS)
+@click.argument("agent_ref", required=False)
+@click.option("--agent", "--agent-id", "agent_option", "-a", help="Agent 名称或 ID")
+@click.option("--endpoint", "-e", help="Agent Endpoint URL (覆盖自动获取)")
+@click.option("--api-key", help="AgentEngine API Key (覆盖本地配置)")
+@click.option(
+    "--gateway-token",
+    "openclaw_gateway_token",
+    envvar="OPENCLAW_GATEWAY_TOKEN",
+    help="OpenClaw Gateway token/password（用于 OpenClaw token/password 模式的 /v1/responses）",
+)
+@click.option("--message", "-m", help="发送的消息 (单次调用模式)")
+@click.option("--session", "-s", help="Session ID (可选)")
+@click.option("--region", "-r", default="cn-beijing-6", envvar="KSYUN_REGION", help="区域")
+@click.option("--local", "-l", is_flag=True, help="连接本地服务 (http://localhost:8080)")
+@click.option("--insecure", "-k", is_flag=True, help="跳过 SSL 证书验证 (类似 curl -k)")
+@click.option(
+    "--transport",
+    type=click.Choice(["auto", "chat", "native"], case_sensitive=False),
+    default="auto",
+    show_default=True,
+    help="交互传输层: auto(自动), chat(HTTP /v1/chat/completions), native(Hermes 远端终端)",
+)
+@click.option(
+    "--local-workspace",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    help="仅 Hermes 远程 native 模式: 先将本地目录同步到远端 workspace",
+)
+@click.option(
+    "--remote-workspace-path",
+    help="远端 workspace 子目录 (默认使用本地目录名)",
+)
+@click.option("--model", help="指定模型名称")
+@click.option("--show-thinking", is_flag=True, help="显示模型思考过程")
+@cli_output_option()
+def invoke_agent(
+    agent_ref: str | None,
+    agent_option: str | None,
+    endpoint: str | None,
+    api_key: str | None,
+    openclaw_gateway_token: str | None,
+    message: str | None,
+    session: str | None,
+    region: str,
+    local: bool,
+    insecure: bool,
+    transport: str,
+    local_workspace: Path | None,
+    remote_workspace_path: str | None,
+    model: str | None,
+    show_thinking: bool,
+    output_mode: str | None,
+):
+    """与 Agent 交互。"""
+    _ = output_mode
+    ensure_dry_run_supported(
+        "agentengine agent invoke",
+        suggestion="请使用 `agentengine agent status --output json` 获取结构化元数据。",
+    )
+    ensure_json_output_supported(
+        "agentengine agent invoke",
+        suggestion="请使用 `agentengine agent status --output json` 获取结构化元数据。",
+    )
+    run_invoke_command(
+        agent_ref=agent_ref,
+        agent_option=agent_option,
+        endpoint=endpoint,
+        api_key=api_key,
+        openclaw_gateway_token=openclaw_gateway_token,
+        message=message,
+        session=session,
+        region=region,
+        local=local,
+        insecure=insecure,
+        transport=transport,
+        local_workspace=local_workspace,
+        remote_workspace_path=remote_workspace_path,
+        model=model,
+        show_thinking=show_thinking,
+        compatibility_alias=False,
+    )
+
+
+@agent.command("delete", context_settings=CONTEXT_SETTINGS)
+@click.argument("agent_refs", nargs=-1)
+@click.option("--agent", "--agent-id", "agent_options", "-a", multiple=True, help="Agent 名称或 ID，可重复传入")
+@click.option("--yes", "-y", "assume_yes", is_flag=True, help="跳过确认")
+@click.option("--force", "-f", "assume_yes", is_flag=True, hidden=True, help="(兼容) 跳过确认")
+@click.option("--region", "-r", default="cn-beijing-6", envvar="KSYUN_REGION", help="区域")
+@click.option("--account-id", envvar="KSYUN_ACCOUNT_ID", help="金山云账号 ID（可选；未设置时从 AK/SK 反查）")
+@dry_run_option()
+@cli_output_option()
+def delete_agent(
+    agent_refs: tuple[str, ...],
+    agent_options: tuple[str, ...],
+    assume_yes: bool,
+    region: str,
+    account_id: str,
+    dry_run: bool,
+    output_mode: str | None,
+):
+    """删除一个或多个 Agent。"""
+    _ = output_mode
+    run_delete_command(
+        agent_refs=agent_refs,
+        agent_options=agent_options,
+        assume_yes=assume_yes,
+        region=region,
+        account_id=account_id,
+        dry_run=dry_run,
+        compatibility_alias=False,
+    )