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

ksadk/toolsets/__init__.py

@@ -2,11 +2,11 @@ from __future__ import annotations
 
 import json
 import os
-import re
 from collections.abc import Callable, Iterable, Mapping
 from typing import Any
 
 from ksadk.tools.gateway import ToolPolicy, tool_policy_requires_approval
+from ksadk.tools.schema import callable_parameters
 from ksadk.toolsets._langchain import as_tool
 from ksadk.toolsets.a2a import (
     _A2A_TOOL_POLICIES,
@@ -19,12 +19,20 @@ from ksadk.toolsets.a2a import (
 from ksadk.toolsets.platform import component_status, get_platform_tools
 from ksadk.toolsets.sandbox import (
     _SANDBOX_TOOL_POLICIES,
+    browser_inspect_workspace,
     get_sandbox_tools,
     run_code,
     run_command,
     sandbox_backend_name,
     sandbox_status,
 )
+from ksadk.toolsets.skill_management import (
+    _SKILL_MANAGEMENT_TOOL_POLICIES,
+    get_skill_management_tools,
+    skill_bind_agent,
+    skill_discover_github,
+    skill_install,
+)
 from ksadk.toolsets.skills import (
     _SKILL_TOOL_POLICIES,
     _skill_execution_backend,
@@ -33,8 +41,20 @@ from ksadk.toolsets.skills import (
     list_skill_spaces,
     list_skills,
     load_skill,
+    preview_skill,
     search_skills,
 )
+from ksadk.toolsets.tool_selection import (
+    _canonical_toolset_group,
+    _enabled_backend,
+    _normalize_include,
+    _normalize_mode,
+    _normalize_tool_name,
+    _search_terms,
+    _tool_search_reason,
+    _tool_search_score,
+    _tool_search_text,
+)
 from ksadk.toolsets.web import _WEB_TOOL_POLICIES, get_web_tools, web_fetch, web_search
 from ksadk.toolsets.workspace import (
     _WORKSPACE_TOOL_POLICIES,
@@ -51,10 +71,25 @@ from ksadk.toolsets.workspace import (
     write_workspace_files,
 )
 
-_DEFAULT_GROUPS = ("skill", "workspace", "platform", "sandbox", "web", "a2a")
+_DEFAULT_GROUPS = (
+    "skill",
+    "skill-management",
+    "workspace",
+    "platform",
+    "sandbox",
+    "web",
+    "a2a",
+)
 _DISPATCHER_TOOL_NAME = "tool_dispatcher"
 _LEGACY_DISPATCHER_TOOL_NAME = "agentengine_tool_dispatcher"
 _TOOL_SEARCH_NAME = "tool_search"
+
+# 调度类元工具：可触达绑定范围之外的工具，禁止作为 Agent 的可绑定工具
+# 出现在目录/UI 中（harness 构建校验会拒绝它们，见
+# plugins/providers/harness_tools.py）。
+META_DISPATCHER_TOOL_NAMES = frozenset(
+    {"tool_search", "tool_dispatcher", "agentengine_tool_dispatcher"}
+)
 _FOCUSED_TOOL_NAMES = (
     "workspace_status",
     "list_workspace_files",
@@ -69,6 +104,10 @@ _FOCUSED_TOOL_NAMES = (
     "sandbox_status",
     "run_command",
     "run_code",
+    "browser_inspect_workspace",
+    "skill_discover_github",
+    "skill_install",
+    "skill_bind_agent",
     "web_fetch",
     "web_search",
     _TOOL_SEARCH_NAME,
@@ -76,9 +115,19 @@ _FOCUSED_TOOL_NAMES = (
 _DEFERRED_TOOL_NAMES = (_TOOL_SEARCH_NAME, _DISPATCHER_TOOL_NAME)
 _EXTERNAL_TOOL_SPECS: dict[str, dict[str, Any]] = {}
 
+
+def _sandbox_tool_boundary() -> str:
+    backend = sandbox_backend_name()
+    if backend in {"local", "local_process"}:
+        return "local_workspace_process"
+    if backend in {"pod", "pod_process"}:
+        return "agent_pod_process"
+    return "isolated_sandbox"
+
 _TOOLSET_FACTORIES = {
     "skill": get_skill_tools,
     "skills": get_skill_tools,
+    "skill-management": get_skill_management_tools,
     "workspace": get_workspace_tools,
     "platform": get_platform_tools,
     "sandbox": get_sandbox_tools,
@@ -89,11 +138,29 @@ _TOOLSET_FACTORIES = {
 _TOOLSET_DESCRIPTORS: dict[
     str, tuple[tuple[Callable[..., Any], ToolPolicy, dict[str, Any]], ...]
 ] = {
+    "skill-management": (
+        (
+            skill_discover_github,
+            _SKILL_MANAGEMENT_TOOL_POLICIES["skill_discover_github"],
+            {"boundary": "studio_skill_catalog"},
+        ),
+        (
+            skill_install,
+            _SKILL_MANAGEMENT_TOOL_POLICIES["skill_install"],
+            {"boundary": "studio_skill_catalog"},
+        ),
+        (
+            skill_bind_agent,
+            _SKILL_MANAGEMENT_TOOL_POLICIES["skill_bind_agent"],
+            {"boundary": "current_studio_agent_revision"},
+        ),
+    ),
     "skill": (
         (list_skills, _SKILL_TOOL_POLICIES["list_skills"], {}),
         (list_skill_spaces, _SKILL_TOOL_POLICIES["list_skill_spaces"], {}),
         (search_skills, _SKILL_TOOL_POLICIES["search_skills"], {}),
         (load_skill, _SKILL_TOOL_POLICIES["load_skill"], {}),
+        (preview_skill, _SKILL_TOOL_POLICIES["load_skill"], {}),
         (
             execute_skills,
             _SKILL_TOOL_POLICIES["execute_skills"],
@@ -164,7 +231,7 @@ _TOOLSET_DESCRIPTORS: dict[
             {
                 "backend": lambda: sandbox_backend_name(),
                 "enabled": lambda: _enabled_backend(sandbox_backend_name()),
-                "boundary": "isolated_sandbox",
+                "boundary": _sandbox_tool_boundary,
             },
         ),
         (
@@ -173,7 +240,7 @@ _TOOLSET_DESCRIPTORS: dict[
             {
                 "backend": lambda: sandbox_backend_name(),
                 "enabled": lambda: _enabled_backend(sandbox_backend_name()),
-                "boundary": "isolated_sandbox",
+                "boundary": _sandbox_tool_boundary,
             },
         ),
         (
@@ -182,7 +249,16 @@ _TOOLSET_DESCRIPTORS: dict[
             {
                 "backend": lambda: sandbox_backend_name(),
                 "enabled": lambda: _enabled_backend(sandbox_backend_name()),
-                "boundary": "isolated_sandbox",
+                "boundary": _sandbox_tool_boundary,
+            },
+        ),
+        (
+            browser_inspect_workspace,
+            _SANDBOX_TOOL_POLICIES["browser_inspect_workspace"],
+            {
+                "backend": "playwright",
+                "enabled": lambda: sandbox_backend_name() in {"local", "local_process"},
+                "boundary": "local_workspace_browser",
             },
         ),
     ),
@@ -603,6 +679,7 @@ def _build_descriptor_registry(*, include_dispatcher: bool) -> dict[str, dict[st
                     description=(getattr(func, "__doc__", "") or "").strip(),
                     policy=policy,
                     extras=extras,
+                    function=func,
                 )
     for platform_tool in get_platform_tools():
         name = _tool_name(platform_tool)
@@ -615,6 +692,9 @@ def _build_descriptor_registry(*, include_dispatcher: bool) -> dict[str, dict[st
                 "requires_approval": False,
                 "side_effects": [],
                 "enabled": True,
+                "input_schema": callable_parameters(
+                    getattr(platform_tool, "func", platform_tool)
+                ),
             }
             args = _tool_args(platform_tool)
             if args:
@@ -626,6 +706,7 @@ def _build_descriptor_registry(*, include_dispatcher: bool) -> dict[str, dict[st
             name=_DISPATCHER_TOOL_NAME,
             description=(tool_dispatcher.__doc__ or "").strip(),
             policy=ToolPolicy(risk_level="low"),
+            function=tool_dispatcher,
             extras={
                 "boundary": "local_ksadk_builtin_tools",
                 "actions": ["list", "describe", "call"],
@@ -636,6 +717,7 @@ def _build_descriptor_registry(*, include_dispatcher: bool) -> dict[str, dict[st
             name=_TOOL_SEARCH_NAME,
             description=(tool_search.__doc__ or "").strip(),
             policy=ToolPolicy(risk_level="low"),
+            function=tool_search,
             extras={
                 "boundary": "local_ksadk_builtin_tool_registry",
                 "actions": ["search"],
@@ -646,6 +728,7 @@ def _build_descriptor_registry(*, include_dispatcher: bool) -> dict[str, dict[st
             name=_LEGACY_DISPATCHER_TOOL_NAME,
             description=(agentengine_tool_dispatcher.__doc__ or "").strip(),
             policy=ToolPolicy(risk_level="low"),
+            function=agentengine_tool_dispatcher,
             extras={
                 "boundary": "local_ksadk_builtin_tools",
                 "compat_alias_for": _DISPATCHER_TOOL_NAME,
@@ -656,25 +739,6 @@ def _build_descriptor_registry(*, include_dispatcher: bool) -> dict[str, dict[st
     return registry
 
 
-def _canonical_toolset_group(name: object) -> str:
-    value = str(name).strip().lower()
-    if value == "skills":
-        return "skill"
-    return value
-
-
-def _normalize_include(include: Iterable[str] | str | None) -> list[str]:
-    if include is None:
-        return []
-    if isinstance(include, str):
-        return [include]
-    return [str(item) for item in include]
-
-
-def _normalize_tool_name(tool_name: str | None) -> str:
-    return str(tool_name or "").strip()
-
-
 def _normalize_tool_arguments(
     arguments: dict[str, Any] | str | None,
 ) -> tuple[dict[str, Any], dict[str, Any] | None]:
@@ -820,10 +884,6 @@ def _unknown_tool_error(tool_name: str) -> dict[str, Any]:
     }
 
 
-def _enabled_backend(backend: str) -> bool:
-    return backend not in {"", "disabled", "none", "off"}
-
-
 def _profile_default_include(profile: str) -> list[str]:
     normalized = str(profile or "default").strip().lower()
     if normalized == "coding":
@@ -831,17 +891,6 @@ def _profile_default_include(profile: str) -> list[str]:
     return list(_DEFAULT_GROUPS)
 
 
-def _normalize_mode(mode: str) -> str:
-    normalized = str(mode or "direct").strip().lower()
-    if normalized in {"off", "none", "disabled"}:
-        return "off"
-    if normalized in {"dispatcher", "dispatch"}:
-        return "dispatcher"
-    if normalized in {"deferred", "search"}:
-        return "deferred"
-    return "direct"
-
-
 def builtin_tools_mode(default: str = "off") -> str:
     return _normalize_mode(os.environ.get("KSADK_BUILTIN_TOOLS_MODE", default))
 
@@ -874,55 +923,6 @@ def builtin_tools_for_runtime(
     return get_agentengine_tools(profile=resolved_profile, mode=resolved_mode)
 
 
-def _search_terms(text: str) -> list[str]:
-    terms = re.findall(r"[a-zA-Z0-9_]+|[\u4e00-\u9fff]+", text.lower())
-    synonyms = {
-        "edit": ["edit", "replace", "modify", "patch", "write", "file"],
-        "file": ["file", "workspace", "read", "list", "search", "edit"],
-        "grep": ["grep", "search", "rg", "find"],
-        "run": ["run", "command", "shell", "code", "execute"],
-        "web": ["web", "fetch", "search", "url", "http"],
-        "读": ["read", "file", "workspace"],
-        "改": ["edit", "replace", "file"],
-        "搜": ["search", "grep", "find"],
-    }
-    expanded: list[str] = []
-    for term in terms:
-        expanded.append(term)
-        expanded.extend(synonyms.get(term, []))
-    return expanded
-
-
-def _tool_search_text(spec: Mapping[str, Any]) -> str:
-    values = [
-        str(spec.get("name") or ""),
-        str(spec.get("group") or ""),
-        str(spec.get("description") or ""),
-        " ".join((spec.get("args") or {}).keys()) if isinstance(spec.get("args"), Mapping) else "",
-    ]
-    return " ".join(values).lower()
-
-
-def _tool_search_score(terms: list[str], haystack: str, spec: Mapping[str, Any]) -> float:
-    score = 0.0
-    name = str(spec.get("name") or "").lower()
-    for term in terms:
-        if not term:
-            continue
-        if term in name:
-            score += 4.0
-        elif term in haystack:
-            score += 1.0
-    if str(spec.get("group") or "") == "workspace":
-        score += 0.5
-    return score
-
-
-def _tool_search_reason(terms: list[str], haystack: str) -> str:
-    matched = [term for term in terms if term and term in haystack]
-    return f"matched: {', '.join(matched[:4])}" if matched else "matched registry metadata"
-
-
 def _tool_spec(
     *,
     group: str,
@@ -930,6 +930,7 @@ def _tool_spec(
     description: str,
     policy: ToolPolicy,
     extras: Mapping[str, Any] | None = None,
+    function: Callable[..., Any] | None = None,
 ) -> dict[str, Any]:
     spec = {
         "name": name,
@@ -953,10 +954,13 @@ def _tool_spec(
     if name in {"run_command", "run_code", "sandbox_status"}:
         enabled = enabled and _enabled_backend(sandbox_backend_name())
     spec["enabled"] = enabled
+    if function is not None:
+        spec["input_schema"] = callable_parameters(function)
     return spec
 
 
 __all__ = [
+    "META_DISPATCHER_TOOL_NAMES",
     "agentengine_tool_dispatcher",
     "tool_dispatcher",
     "tool_search",
@@ -969,6 +973,7 @@ __all__ = [
     "get_platform_tools",
     "get_sandbox_tools",
     "get_skill_tools",
+    "preview_skill",
     "get_workspace_tools",
     "get_web_tools",
     "multi_edit_workspace_file",

ksadk/toolsets/a2a.py

@@ -14,16 +14,19 @@ call_a2a_agent。LLM 操作哪个远程 agent 通过参数动态指定。
 from __future__ import annotations
 
 import difflib
+import inspect
 import ipaddress
 import os
 import socket
-import uuid
+from contextlib import contextmanager
+from contextvars import ContextVar
 from typing import Any
 from urllib.parse import urlsplit
 
 import httpcore
 import httpx
 
+from ksadk.tools.a2a_policy import A2A_REMOTE_TOOL_POLICY
 from ksadk.tools.gateway import ToolPolicy
 from ksadk.toolsets._langchain import as_tool
 
@@ -101,9 +104,10 @@ def _match_agent(agents: list[dict[str, Any]], ref: str) -> tuple[dict[str, Any]
     if not target:
         return None, [a["agent_id"] for a in agents]
     for a in agents:
-        if _normalize_agent_ref(a["agent_id"]) == target or _normalize_agent_ref(
-            a["name"]
-        ) == target:
+        if (
+            _normalize_agent_ref(a["agent_id"]) == target
+            or _normalize_agent_ref(a["name"]) == target
+        ):
             return a, []
     available = [a["agent_id"] for a in agents]
     names = [_normalize_agent_ref(a["agent_id"]) for a in agents] + [
@@ -129,13 +133,13 @@ def _extract_reply_text(remote_task: Any) -> str:
         message = status.get("message") or {}
         parts: list[str] = []
         # 优先 status.message.parts（终态回复）；无则退到 artifacts 分片。
-        for part in (message.get("parts") or []):
+        for part in message.get("parts") or []:
             if isinstance(part, dict) and part.get("text"):
                 parts.append(part["text"])
         if parts:
             return "".join(parts)
-        for artifact in (remote_task.get("artifacts") or []):
-            for part in (artifact.get("parts") or []):
+        for artifact in remote_task.get("artifacts") or []:
+            for part in artifact.get("parts") or []:
                 if isinstance(part, dict) and part.get("text"):
                     parts.append(part["text"])
         return "".join(parts)
@@ -143,12 +147,12 @@ def _extract_reply_text(remote_task: Any) -> str:
     status = getattr(remote_task, "status", None)
     message = getattr(status, "message", None)
     if message is not None:
-        for part in (getattr(message, "parts", None) or []):
+        for part in getattr(message, "parts", None) or []:
             text = getattr(part, "text", None)
             if isinstance(text, str) and text:
                 parts_text.append(text)
-    for artifact in (getattr(remote_task, "artifacts", None) or []):
-        for part in (getattr(artifact, "parts", None) or []):
+    for artifact in getattr(remote_task, "artifacts", None) or []:
+        for part in getattr(artifact, "parts", None) or []:
             text = getattr(part, "text", None)
             if isinstance(text, str) and text:
                 parts_text.append(text)
@@ -218,7 +222,8 @@ def _validated_card_origin(url: str) -> tuple[str, int, str] | dict[str, Any]:
         or parsed.username is not None
         or parsed.password is not None
         or parsed.netloc.rsplit("@", 1)[-1].endswith(":")
-        or port is not None and not 1 <= port <= 65535
+        or port is not None
+        and not 1 <= port <= 65535
     ):
         return {
             "ok": False,
@@ -327,100 +332,95 @@ def get_a2a_agent_card(agent: str) -> dict[str, Any]:
     return {"ok": True, "agent": matched}
 
 
-def call_a2a_agent(agent: str, message: str) -> dict[str, Any]:
-    """Call a remote A2A agent by id or name with a text message.
+_managed_tool_binding = ContextVar("managed_a2a_tool_binding", default=None)
 
-    ``agent`` accepts A2AAgentId (a2a-agent-*) or card name. Synchronously waits
-    for the remote task to complete and returns the agent's text reply. If the
-    task does not reach a terminal state within the poll budget, returns the
-    last known state and task_id for follow-up.
+
+@contextmanager
+def bind_managed_a2a_tools(invocation_service, request_provider, exposure_plan):
+    """Bind actual tool-call identity and one exposure plan for this execution.
+
+    request_provider(agent, message) returns (A2AInvocationRequest, ScopeTriggerRef).
+    The caller supplies identity from the actual native/canonical tool call.
     """
-    space_id = _a2a_space_id()
-    if not space_id:
-        return {"ok": False, "error_message": "A2A Space not configured"}
-    if not (message or "").strip():
-        return {"ok": False, "error_message": "message is required"}
+    token = _managed_tool_binding.set((invocation_service, request_provider, exposure_plan))
     try:
-        agents = _discover_agents()
-    except Exception as exc:
-        return {"ok": False, "error_type": type(exc).__name__, "error_message": str(exc)}
-    matched, hint = _match_agent(agents, agent)
-    if matched is None:
+        yield
+    finally:
+        _managed_tool_binding.reset(token)
+
+
+async def call_a2a_agent(agent: str, message: str) -> dict[str, Any]:
+    """Invoke a managed remote agent and return its legacy JSON reply envelope.
+
+    The runtime supplies authorization, actual call identity and a fixed target.
+    """
+    binding = _managed_tool_binding.get()
+    if binding is None:
         return {
             "ok": False,
-            "error_message": f"Agent not found: {agent}",
-            "available_agents": hint,
+            "error_type": "A2A_MANAGED_INVOCATION_CONTEXT_REQUIRED",
+            "error_message": "Managed A2A invocation context is required",
         }
+    if not message.strip():
+        return {"ok": False, "error_message": "message is required"}
+    service, provider, plan = binding
     try:
-        card_url = str(matched.get("url") or "").strip()
-        if not card_url:
-            return {"ok": False, "error_message": f"agent {matched['agent_id']} card 无可用 url"}
-
-        def _send() -> dict[str, Any]:
-            # 直接对 card.url 发非流式 SendMessage(returnImmediately=false),同步拿终态回复。
-            # 不走 space_client 的流式 send_message/subscribe(其 task 状态跟踪在异步下不可靠)。
-            payload = {
-                "jsonrpc": "2.0",
-                "method": "SendMessage",
-                "id": "1",
-                "params": {
-                    "message": {
-                        "messageId": f"m-{uuid.uuid4().hex[:12]}",
-                        "role": "ROLE_USER",
-                        "parts": [{"text": message}],
-                    },
-                    "configuration": {"returnImmediately": False},
-                },
-            }
-            # 透传 OTel trace context：把当前 span 注入 traceparent header,
-            # 让被调 agent 的 span 挂到同一条分布式 trace 上。
-            headers = {"Content-Type": "application/json", "A2A-Version": "1.0"}
-            try:
-                from opentelemetry import propagate
-
-                propagate.inject(headers)
-            except Exception:
-                pass
-            validated = _validated_card_origin(card_url)
-            if isinstance(validated, dict):
-                return validated
-            hostname, port, pinned_ip = validated
-            with _pinned_http_client(
-                hostname=hostname,
-                port=port,
-                pinned_ip=pinned_ip,
-            ) as client:
-                resp = client.post(card_url, json=payload, headers=headers)
-            if resp.status_code != 200:
-                return {
-                    "ok": False,
-                    "error_type": "A2AClientError",
-                    "error_message": f"HTTP {resp.status_code}: {resp.text[:200]}",
+        resolved = provider(agent, message)
+        if inspect.isawaitable(resolved):
+            resolved = await resolved
+        request, trigger = resolved
+        plan.assert_generic_target_allowed(request.spec.target_agent_id)
+        snapshots = {}
+        item_kinds = {}
+        from ksadk.events.content import TextContent
+
+        async for event in service.invoke(request, trigger_ref=trigger):
+            snapshot = getattr(event, "snapshot", None) or getattr(event, "initial", None)
+            if snapshot is None:
+                continue
+            if event.item_kind in {"message", "artifact"}:
+                key = (event.scope_id, event.item_id)
+                item_kinds[key] = event.item_kind
+                snapshots[key] = {
+                    part.part_id: part.text
+                    for part in snapshot.parts
+                    if isinstance(part, TextContent)
                 }
-            data = resp.json()
-            if "error" in data and data["error"]:
-                err = str(data["error"])[:300]
-                return {"ok": False, "error_type": "A2AError", "error_message": err}
-            task = (data.get("result") or {}).get("task") or {}
-            return {
-                "ok": True,
-                "agent": matched["agent_id"],
-                "task_id": task.get("id", ""),
-                "state": str((task.get("status") or {}).get("state", "")),
-                "reply": _extract_reply_text(task),
-            }
+        handle = service.handle(request.scope_id)
+        latest = service.snapshot(handle)
+        status = latest.status if latest is not None else "unknown"
+        from ksadk.a2a.result_text import select_terminal_reply
 
-        return _send()
+        return {
+            "ok": status == "completed",
+            "agent": request.spec.target_agent_id,
+            "task_id": handle.platform_task_id,
+            "state": status,
+            "reply": (
+                select_terminal_reply(latest.output_refs, snapshots, item_kinds)
+                if status == "completed" and latest is not None
+                else ""
+            ),
+        }
     except Exception as exc:
-        return {"ok": False, "error_type": type(exc).__name__, "error_message": str(exc)}
+        code = (
+            str(exc)
+            if str(exc).startswith("A2A_") and len(str(exc)) < 128
+            else "A2A_INVOCATION_FAILED"
+        )
+        return {"ok": False, "error_type": code, "error_message": "Managed A2A invocation failed"}
 
 
 def get_a2a_tools() -> list:
-    return [as_tool(list_a2a_agents), as_tool(get_a2a_agent_card), as_tool(call_a2a_agent)]
+    try:
+        from ksadk.a2a.langgraph_tools import managed_tool
+    except ImportError:
+        managed_tool = as_tool
+    return [managed_tool(list_a2a_agents), managed_tool(get_a2a_agent_card), managed_tool(call_a2a_agent)]
 
 
 _A2A_TOOL_POLICIES = {
     "list_a2a_agents": ToolPolicy(risk_level="low"),
     "get_a2a_agent_card": ToolPolicy(risk_level="low"),
-    "call_a2a_agent": ToolPolicy(risk_level="high", side_effects=("a2a_remote_call",)),
+    "call_a2a_agent": A2A_REMOTE_TOOL_POLICY,
 }