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

ksadk/harness/subagent.py

@@ -0,0 +1,253 @@
+"""子 Agent 执行（收口 6 / plan §14）：多 Agent 作为可选能力。
+
+Engine 支持 ``sub_agents``：工具名 → 子 Agent 配置（instructions + 可选
+tools）。父 Agent 的模型像调用普通工具一样发起子任务；引擎在 tool_calls
+节点内联运行一个子 ManagedLangGraphEngine 到完成，子事件（含
+agent.started/completed、自己的 turn/node/model/usage）以**子 agent_id**
+写入父事件流——事件树（event_tree）据此把子 Agent 展示为独立树节点。
+
+约束：
+- 子 Agent 不再嵌套子 Agent（单层，避免失控递归）；
+- 子 Agent 共享父 Reasoner 与工具注册表（数据面由宿主装配）；
+- 每次委派使用独立 Checkpoint namespace、轮数预算和墙钟超时；
+- Skill 默认继承，MCP 必须显式授权后才继承；
+- 子 Agent 结果以其最终文本作为工具结果回流父对话。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from jsonschema import ValidationError, validate
+from pydantic import BaseModel, ConfigDict, Field
+
+from ksadk.harness.events import RuntimeEvent
+from ksadk.harness.spec import (
+    CapabilityBindings,
+    ExecutionStrategySpec,
+    HarnessSpec,
+    PromptSpec,
+    SubAgentBinding,
+)
+
+
+@dataclass
+class SubAgentSpec:
+    """子 Agent 配置（宿主声明，引擎内联执行）。"""
+
+    name: str
+    instructions: str
+    #: 允许子 Agent 使用的工具名（空 = 不用工具，只做文本推理）。
+    tools: tuple[str, ...] = ()
+    description: str = ""
+    timeout_seconds: float = 120.0
+    max_turns: int = 4
+    max_total_tokens: int | None = None
+    max_artifacts: int | None = None
+    max_tool_calls: int | None = None
+    output_schema: dict[str, Any] | None = None
+    depends_on: tuple[str, ...] = ()
+    failure_policy: str = "propagate"
+    max_retries: int = 0
+    inherit_skills: bool = True
+    inherit_mcp: bool = False
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_binding(cls, binding: SubAgentBinding) -> "SubAgentSpec":
+        """把不可变 Revision 声明投影为本次 Run 的执行配置。"""
+        return cls(**binding.model_dump())
+
+    @property
+    def openai_schema(self) -> dict[str, Any]:
+        """模型可见的工具 schema（子 Agent 即工具，任务描述入参）。"""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description or f"委托子 Agent {self.name} 完成任务并返回其结论",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"task": {"type": "string", "description": "要完成的子任务描述"}},
+                    "required": ["task"],
+                },
+            },
+        }
+
+
+class SubAgentResult(BaseModel):
+    """父 Agent 可消费、平台可审计的稳定子任务结果。"""
+
+    model_config = ConfigDict(extra="allow")
+
+    status: str
+    output: Any = None
+    artifact_refs: tuple[str, ...] = ()
+    usage: dict[str, int] = Field(default_factory=dict)
+    evidence: dict[str, Any] = Field(default_factory=dict)
+    error_category: str | None = None
+    error: str | None = None
+
+
+class SubAgentOutputValidationError(ValueError):
+    """子任务最终输出不满足 Revision 声明的 Schema。"""
+
+
+def validate_subagent_output(text: str, schema: dict[str, Any] | None) -> Any:
+    """按声明解析并校验最终输出；无 Schema 时保持原文本。"""
+    text = text.strip()
+    if not text:
+        raise SubAgentOutputValidationError("sub-agent did not produce a final result")
+    if re.search(r"DSML", text.replace("｜", "|"), re.IGNORECASE):
+        raise SubAgentOutputValidationError(
+            "sub-agent returned an unexecuted tool call instead of a result"
+        )
+    if schema is None:
+        return text
+    try:
+        value = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise SubAgentOutputValidationError(
+            f"sub-agent output_schema requires JSON output: {exc.msg}"
+        ) from exc
+    try:
+        validate(instance=value, schema=schema)
+    except ValidationError as exc:
+        raise SubAgentOutputValidationError(
+            f"sub-agent output_schema validation failed: {exc.message}"
+        ) from exc
+    return value
+
+
+def order_subagent_tool_calls(
+    calls: list[dict[str, Any]], specs: dict[str, "SubAgentSpec"]
+) -> list[dict[str, Any]]:
+    """对同批子任务稳定拓扑排序；普通工具与无依赖子任务保持原顺序。"""
+    positions = {str(call.get("name") or ""): index for index, call in enumerate(calls)}
+    call_names = set(positions)
+    dependencies = {
+        name: {dependency for dependency in spec.depends_on if dependency in call_names}
+        for name, spec in specs.items()
+        if name in call_names
+    }
+
+    def rank(name: str, trail: frozenset[str] = frozenset()) -> int:
+        if name in trail:
+            raise SubAgentExecutionError("dependency_cycle", f"sub-agent dependency cycle: {name}")
+        parents = dependencies.get(name, set())
+        if not parents:
+            return 0
+        return 1 + max(rank(parent, trail | {name}) for parent in parents)
+
+    return sorted(
+        calls,
+        key=lambda call: (
+            rank(str(call.get("name") or "")),
+            positions[str(call.get("name") or "")],
+        ),
+    )
+
+
+def child_spec(parent_spec: HarnessSpec, sub: SubAgentSpec) -> HarnessSpec:
+    """由父 Spec 派生子 Spec（同模型绑定，独立指令）。"""
+    # Skill 是只读知识能力，默认继承；MCP 可能触达外部系统，只有 Revision
+    # 明确授权时才继承，防止委派扩大权限面。
+    return HarnessSpec(
+        agent_revision_ref=parent_spec.agent_revision_ref,
+        model=parent_spec.model,
+        prompt=PromptSpec(instructions=sub.instructions),
+        capabilities=CapabilityBindings(
+            skill_bindings=(parent_spec.capabilities.skill_bindings if sub.inherit_skills else ()),
+            mcp_bindings=(parent_spec.capabilities.mcp_bindings if sub.inherit_mcp else ()),
+        ),
+        context_policy=parent_spec.context_policy,
+        memory_policy=parent_spec.memory_policy,
+        approval_policy=parent_spec.approval_policy,
+        sandbox_policy=parent_spec.sandbox_policy,
+        observability_policy=parent_spec.observability_policy,
+        execution_strategy=ExecutionStrategySpec(
+            config={
+                "max_tool_calls": sub.max_tool_calls,
+                "max_artifacts": sub.max_artifacts,
+                "max_total_tokens": sub.max_total_tokens,
+            }
+        ),
+    )
+
+
+async def run_subagent(
+    *,
+    engine: Any,
+    parent_run: Any,
+    sub: SubAgentSpec,
+    task: str,
+    call_id: str = "",
+) -> tuple[dict[str, Any], list[RuntimeEvent]]:
+    """运行子 Agent 到完成，返回 (最终文本, 以父 seq 重排的子事件)。
+
+    子事件信封：invocation_id 同父 Run（单一审计流），agent_id 为
+    ``{父agent_id}:{子名}``（事件树按 agent 分组展示子 Agent）。
+    """
+    from ksadk.harness.engine.subagents import execute_subagent
+
+    return await execute_subagent(
+        engine=engine, parent_run=parent_run, sub=sub, task=task, call_id=call_id
+    )
+
+
+class SubAgentExecutionError(RuntimeError):
+    """Classified child failure safe to project into Tool events."""
+
+    def __init__(self, category: str, message: str) -> None:
+        super().__init__(message)
+        self.category = category
+
+
+def resequence_child_events(
+    parent_run: Any, events: list[RuntimeEvent], *, observe: bool = False
+) -> None:
+    """把缓冲的子事件按父 seq 重排后并入父流（tool.call 事件之后统一落盘）。"""
+    for ev in events:
+        parent_run.seq += 1
+        payload = dict(ev.payload)
+        if ev.event_type in {"agent.started", "agent.completed"}:
+            payload.setdefault("parent_agent_id", parent_run.state.agent_id)
+        parent_run.events.append(
+            RuntimeEvent.create(
+                ev.event_type,
+                agent_id=ev.agent_id,
+                user_id=ev.user_id,
+                session_id=ev.session_id,
+                # v1 invocation_id 保持父审计流兼容；v2 run_id 保留独立子 Run。
+                invocation_id=parent_run.handle.run_id,
+                seq_id=parent_run.seq,
+                payload=payload,
+                phase=ev.phase,
+                run_id=ev.run_id or ev.invocation_id,
+                scope_id=ev.scope_id or f"agent:{ev.agent_id}",
+                parent_scope_id=ev.parent_scope_id or f"agent:{parent_run.state.agent_id}",
+                parent_run_id=ev.parent_run_id or parent_run.handle.run_id,
+            )
+        )
+
+        if observe:
+            projected = parent_run.events[-1]
+            if parent_run.controller is not None:
+                parent_run.control_events.append(projected)
+                parent_run.controller.observe(projected)
+            parent_run.observed_event_ids.add(projected.event_id)
+
+
+__all__ = [
+    "SubAgentOutputValidationError",
+    "SubAgentResult",
+    "SubAgentSpec",
+    "child_spec",
+    "order_subagent_tool_calls",
+    "resequence_child_events",
+    "run_subagent",
+    "validate_subagent_output",
+]

ksadk/harness/tool_policy.py

@@ -0,0 +1,131 @@
+"""Harness Tool Policy 决策（plan §11.1）。
+
+确定性决策表（无模型调用）：
+
+- CRITICAL 风险或外部副作用 + 高敏数据 → require_approval；
+- 策略显式 deny（如目的地不在允许清单）→ deny；
+- 其余 → allow。
+
+决策输入覆盖 plan 要求的最小集：tenant/user/agent、tool+版本、参数摘要、
+敏感等级、外部副作用、网络目的地、环境、Revision Policy、历史 Receipt。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ksadk.harness.capabilities import RiskLevel
+
+#: 风险等级序（str-Enum 不可比较，用显式序号）。
+_RISK_ORDER = {
+    RiskLevel.LOW: 0,
+    RiskLevel.MEDIUM: 1,
+    RiskLevel.HIGH: 2,
+    RiskLevel.CRITICAL: 3,
+}
+#: 审批阈值（含）：该风险等级及以上需要审批。
+_APPROVAL_RISK = 2  # HIGH
+#: 拒绝阈值（含）：该风险等级及以上在正式环境需审批。
+_DENY_RISK = 3  # CRITICAL
+
+
+@dataclass(frozen=True)
+class ToolCallContext:
+    """一次 Tool 调用的决策输入。"""
+
+    tenant_id: str
+    user_id: str
+    agent_id: str
+    tool_name: str
+    tool_version: str = "1.0.0"
+    risk_level: RiskLevel = RiskLevel.LOW
+    has_external_side_effects: bool = False
+    data_sensitivity: str = "internal"  # public/internal/confidential/restricted
+    network_destination: str = ""
+    environment: str = "draft"  # draft / revision
+    #: Revision Policy 侧白名单：为空表示不限制目的地。
+    allowed_destinations: tuple[str, ...] = ()
+    #: 历史 Receipt：此前是否已成功执行同一 call（幂等去重）。
+    prior_receipt_id: str = ""
+
+
+@dataclass(frozen=True)
+class ToolDecision:
+    action: str  # allow / deny / require_approval
+    reason: str
+    policy_ref: str
+    risk_level: RiskLevel
+    disclosure: str = ""
+
+
+@dataclass
+class ToolPolicy:
+    """Revision 级工具策略（宿主从 HarnessSpec.tool_policy 投影）。"""
+
+    policy_ref: str = "tool-policy://default@1"
+    #: 强制审批的工具名前缀（如高危财务工具）。
+    approval_required_prefixes: tuple[str, ...] = field(default=())
+    #: 明确拒绝的工具名前缀。
+    denied_prefixes: tuple[str, ...] = field(default=())
+    #: 允许的网络目的地（空 = 不限制）。
+    allowed_destinations: tuple[str, ...] = field(default=())
+    #: 环境限制：正式环境默认更严。
+    strict_in_revision: bool = True
+
+    def decide(self, context: ToolCallContext) -> ToolDecision:
+        if any(context.tool_name.startswith(p) for p in self.denied_prefixes):
+            return ToolDecision(
+                action="deny",
+                reason=f"tool {context.tool_name} is denied by revision policy",
+                policy_ref=self.policy_ref,
+                risk_level=context.risk_level,
+                disclosure="Revision Policy 明确拒绝该工具",
+            )
+        if self.allowed_destinations and context.network_destination:
+            if context.network_destination not in self.allowed_destinations:
+                return ToolDecision(
+                    action="deny",
+                    reason=(
+                        f"network destination {context.network_destination!r} "
+                        f"not in allowlist {list(self.allowed_destinations)}"
+                    ),
+                    policy_ref=self.policy_ref,
+                    risk_level=context.risk_level,
+                    disclosure="网络目的地不在允许清单",
+                )
+        if _RISK_ORDER[context.risk_level] >= _DENY_RISK and context.environment == "revision":
+            if not context.prior_receipt_id:
+                return ToolDecision(
+                    action="require_approval",
+                    reason="critical risk in revision environment requires approval",
+                    policy_ref=self.policy_ref,
+                    risk_level=context.risk_level,
+                    disclosure="Critical 风险工具在正式环境需审批",
+                )
+        needs_approval = (
+            _RISK_ORDER[context.risk_level] >= _APPROVAL_RISK
+            or context.has_external_side_effects
+            or context.data_sensitivity in {"confidential", "restricted"}
+            or any(context.tool_name.startswith(p) for p in self.approval_required_prefixes)
+        )
+        if needs_approval and not context.prior_receipt_id:
+            return ToolDecision(
+                action="require_approval",
+                reason=(
+                    f"risk={context.risk_level.value}, "
+                    f"side_effects={context.has_external_side_effects}, "
+                    f"sensitivity={context.data_sensitivity}"
+                ),
+                policy_ref=self.policy_ref,
+                risk_level=context.risk_level,
+                disclosure="高风险/外部副作用/敏感数据工具需审批",
+            )
+        return ToolDecision(
+            action="allow",
+            reason="within policy",
+            policy_ref=self.policy_ref,
+            risk_level=context.risk_level,
+        )
+
+
+__all__ = ["ToolCallContext", "ToolDecision", "ToolPolicy"]

ksadk/harness/tool_receipts.py

@@ -0,0 +1,96 @@
+"""Harness Tool Receipt（plan §11.2）——审批后仅执行一次的幂等锚点。
+
+审批恢复流程要求：审批通过 → 校验 revision/checkpoint/receipt → 执行一次 →
+持久化 ToolReceipt。Receipt 以 (invocation_id, call_id) 为幂等键：重复执行
+同一审批调用直接返回既有结果，不再触发副作用。
+
+Receipt 保证的是「已持久化执行结果不会因 Graph 重放而再次执行」。外部系统已
+成功、但 Receipt 提交前进程即崩溃的极小窗口，MCP Binding 可显式声明
+``idempotency_mode="transport"``，由 Harness 将 ``run_id + call_id`` 派生的
+稳定幂等键透传给远端；不支持该合同的 Tool 仍需由上游提供幂等键或事务性
+outbox，不能宣称端到端 exactly-once。
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+from pathlib import Path
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ToolReceipt:
+    invocation_id: str
+    call_id: str
+    tool_name: str
+    arguments_digest: str
+    decision: str  # approved / denied
+    status: str  # executed / skipped
+    result_digest: str = ""
+
+
+class ToolReceiptStore:
+    """本地 SQLite Receipt 存储（幂等键 (invocation_id, call_id)）。"""
+
+    _SCHEMA = """
+    CREATE TABLE IF NOT EXISTS harness_tool_receipts (
+        invocation_id    TEXT NOT NULL,
+        call_id          TEXT NOT NULL,
+        tool_name        TEXT NOT NULL,
+        arguments_digest TEXT NOT NULL,
+        decision         TEXT NOT NULL,
+        status           TEXT NOT NULL,
+        result_digest    TEXT NOT NULL DEFAULT '',
+        PRIMARY KEY (invocation_id, call_id)
+    );
+    """
+
+    def __init__(self, db_path: str = ":memory:") -> None:
+        self.path = Path(db_path)
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._conn.executescript(self._SCHEMA)
+        self._lock = threading.Lock()
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+
+    def record(self, receipt: ToolReceipt) -> ToolReceipt | None:
+        """记录 Receipt；幂等键已存在时返回既有 Receipt（不覆盖）。"""
+        with self._lock:
+            existing = self._conn.execute(
+                "SELECT invocation_id, call_id, tool_name, arguments_digest, "
+                "decision, status, result_digest FROM harness_tool_receipts "
+                "WHERE invocation_id = ? AND call_id = ?",
+                (receipt.invocation_id, receipt.call_id),
+            ).fetchone()
+            if existing:
+                return ToolReceipt(*existing)
+            self._conn.execute(
+                "INSERT INTO harness_tool_receipts VALUES (?,?,?,?,?,?,?)",
+                (
+                    receipt.invocation_id,
+                    receipt.call_id,
+                    receipt.tool_name,
+                    receipt.arguments_digest,
+                    receipt.decision,
+                    receipt.status,
+                    receipt.result_digest,
+                ),
+            )
+            self._conn.commit()
+            return None
+
+    def get(self, invocation_id: str, call_id: str) -> ToolReceipt | None:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT invocation_id, call_id, tool_name, arguments_digest, "
+                "decision, status, result_digest FROM harness_tool_receipts "
+                "WHERE invocation_id = ? AND call_id = ?",
+                (invocation_id, call_id),
+            ).fetchone()
+        return ToolReceipt(*row) if row else None
+
+
+__all__ = ["ToolReceipt", "ToolReceiptStore"]

ksadk/harness/tool_reliability.py

@@ -0,0 +1,81 @@
+"""Tool 执行可靠性合同。
+
+Harness 不把所有 Tool 包装成虚假的 ``exactly-once``。本模块根据 Tool 的
+副作用、Receipt 和 Transport 幂等能力，给出可审计的交付语义：
+
+- ``replay_safe``：只读或无副作用，重放不会产生业务副作用；
+- ``effectively_once``：Receipt 关闭提交后的重放窗口，Transport 幂等键关闭
+  外部成功但 Receipt 尚未提交的窗口；
+- ``at_least_once``：Receipt 只能关闭提交后的窗口，提交前崩溃可能重复副作用；
+- ``best_effort``：没有 Receipt，且工具副作用合同未知或不可重试。
+
+这里刻意不使用 ``exactly_once``：跨网络、跨存储事务没有统一原子提交时，平台
+只能声明经过验证的效果语义，不能承诺数学意义上的恰好一次。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class ToolDeliverySemantics(str, Enum):
+    """Harness 对单次 Tool Call 的诚实交付语义。"""
+
+    REPLAY_SAFE = "replay_safe"
+    EFFECTIVELY_ONCE = "effectively_once"
+    AT_LEAST_ONCE = "at_least_once"
+    BEST_EFFORT = "best_effort"
+
+
+_REPLAY_SAFE_SIDE_EFFECTS = frozenset({"none", "read"})
+
+
+@dataclass(frozen=True)
+class ToolReliability:
+    """一项 Tool 在本次装配中的可靠性声明。"""
+
+    semantics: ToolDeliverySemantics
+    side_effect: str
+    receipt_enabled: bool
+    transport_idempotent: bool
+
+    def to_event_payload(self) -> dict[str, object]:
+        """生成 metadata-only 事件投影，不包含幂等键或业务参数。"""
+        return {
+            "semantics": self.semantics.value,
+            "side_effect": self.side_effect,
+            "receipt_enabled": self.receipt_enabled,
+            "transport_idempotent": self.transport_idempotent,
+        }
+
+
+def classify_tool_reliability(
+    *,
+    side_effect: str = "unknown",
+    receipt_enabled: bool = False,
+    transport_idempotent: bool = False,
+) -> ToolReliability:
+    """根据真实能力分类，不因配置缺失抬高承诺等级。"""
+    normalized = str(side_effect or "unknown").lower()
+    if normalized in _REPLAY_SAFE_SIDE_EFFECTS:
+        semantics = ToolDeliverySemantics.REPLAY_SAFE
+    elif receipt_enabled and transport_idempotent:
+        semantics = ToolDeliverySemantics.EFFECTIVELY_ONCE
+    elif receipt_enabled:
+        semantics = ToolDeliverySemantics.AT_LEAST_ONCE
+    else:
+        semantics = ToolDeliverySemantics.BEST_EFFORT
+    return ToolReliability(
+        semantics=semantics,
+        side_effect=normalized,
+        receipt_enabled=receipt_enabled,
+        transport_idempotent=transport_idempotent,
+    )
+
+
+__all__ = [
+    "ToolDeliverySemantics",
+    "ToolReliability",
+    "classify_tool_reliability",
+]

ksadk/harness/user_errors.py

@@ -0,0 +1,69 @@
+"""用户可读错误消息翻译（plan §7.2 / 体验缺口 B）。
+
+把引擎层的技术错误分类翻译为用户可读的中文消息，
+不暴露 raw exception / stack trace / 内部状态。
+
+分层：
+  - 引擎层：classify_model_failure → 稳定类别（已有）
+  - 本层：类别 → 用户可读消息
+  - 事件层：RUN_FAILED payload.error 使用本层消息
+
+不改变引擎层错误分类逻辑，只加一层用户面向的翻译。
+"""
+
+from __future__ import annotations
+
+from ksadk.harness.model_provider import ClassifiedModelFailure, ModelFailureKind
+
+#: 错误类别 → 用户可读消息模板。
+_USER_MESSAGES: dict[ModelFailureKind, str] = {
+    ModelFailureKind.RATE_LIMIT: "模型调用频率受限，请稍后重试",
+    ModelFailureKind.TIMEOUT: "模型响应超时，请检查网络或重试",
+    ModelFailureKind.UNAVAILABLE: "模型服务暂时不可用，请稍后重试",
+    ModelFailureKind.AUTHENTICATION: "模型凭证无效，请检查 API Key 配置",
+    ModelFailureKind.PERMISSION: "模型访问被拒绝，请检查权限配置",
+    ModelFailureKind.NOT_FOUND: "指定的模型不存在，请检查模型配置",
+    ModelFailureKind.CONTEXT_LENGTH: "对话上下文过长，正在自动压缩后重试",
+    ModelFailureKind.INVALID_REQUEST: "模型请求格式异常，请重试或调整提示",
+    ModelFailureKind.TRANSPORT: "模型网络连接异常，正在自动重试",
+    ModelFailureKind.UNKNOWN: "Agent 运行遇到错误，请重试",
+}
+
+#: 工具错误通用消息（不暴露 raw exception）。
+_TOOL_ERROR_MESSAGE = "工具调用失败，请检查工具配置或稍后重试"
+_APPROVAL_DENIED_MESSAGE = "工具调用被审批拒绝，未执行"
+
+
+def user_facing_error(
+    error: Exception | None = None,
+    *,
+    failure: ClassifiedModelFailure | None = None,
+    context: str = "",
+) -> str:
+    """返回用户可读的错误消息。
+
+    Args:
+        error: 原始异常（用于分类，不暴露给用户）。
+        failure: 已分类的失败（优先于 error）。
+        context: 上下文标识（"model" / "tool" / "approval"），决定用哪套消息。
+
+    Returns:
+        用户可读的中文消息，不含 raw exception / stack trace。
+    """
+    if context == "tool":
+        return _TOOL_ERROR_MESSAGE
+    if context == "approval":
+        return _APPROVAL_DENIED_MESSAGE
+
+    if failure is None and error is not None:
+        from ksadk.harness.model_provider import classify_model_failure
+
+        failure = classify_model_failure(error)
+
+    if failure is not None:
+        return _USER_MESSAGES.get(failure.kind, "Agent 运行遇到错误，请重试")
+
+    return "Agent 运行遇到错误，请重试"
+
+
+__all__ = ["user_facing_error"]