datawhalechina/hello-agents · error · WorkflowExecutionError

{stage}失败：工具执行异常：{exc}

Error message

{stage}失败：工具执行异常：{exc}

What it means

Raised by _run_tool when tool.run(parameters) itself raises; the original exception is chained via 'from exc' and surfaced after '工具执行异常：'. The stage and tool name contextualize it. Root causes live inside the tool implementation — file I/O, network calls, bad parameter values, etc.

Source

Thrown at Co-creation-projects/zenith191-RequirementClarifierAgent/src/workflow.py:149

            response = agent.run(prompt)
        except Exception as exc:
            raise WorkflowExecutionError(f"{stage}阶段执行失败：{exc}") from exc
        if not isinstance(response, str) or not response.strip():
            raise WorkflowExecutionError(f"{stage}阶段返回了空结果")
        return response.strip()

    def _run_tool(
        self, name: str, parameters: dict[str, object], stage: str
    ) -> dict[str, object]:
        """通过官方 ToolRegistry 获取工具并解析其字符串协议。"""

        tool = self.tool_registry.get_tool(name)
        if tool is None:
            raise WorkflowExecutionError(f"{stage}失败：工具 {name} 未注册")
        try:
            raw_result = tool.run(parameters)
        except Exception as exc:
            raise WorkflowExecutionError(f"{stage}失败：工具执行异常：{exc}") from exc
        try:
            payload = json.loads(raw_result)
        except (TypeError, ValueError) as exc:
            raise WorkflowExecutionError(f"{stage}失败：工具返回的不是有效 JSON") from exc
        if not isinstance(payload, dict):
            raise WorkflowExecutionError(f"{stage}失败：工具结果必须是 JSON 对象")
        if not payload.get("ok"):
            raise WorkflowExecutionError(
                f"{stage}失败：{payload.get('message', '未知工具错误')}"
            )
        return payload

    def _clear_agent_histories(self) -> None:
        """避免多次运行时把上一条需求带入下一条需求。"""

        for agent in (
            self.team.analyst,
            self.team.architect,

View on GitHub (pinned to 606a07d341)

Solutions

1. Read the exception text after '工具执行异常：' — it is the tool's own error message; fix that root cause first.
2. Harden the tool: validate parameters, add timeouts and retries around external calls.
3. If the model keeps sending malformed parameters, tighten the tool's JSON schema/description so the LLM produces valid arguments.

Example fix

# before
def run(self, params):
    return open(params["path"]).read()

# after
def run(self, params):
    try:
        return open(params["path"]).read()
    except OSError as e:
        return json.dumps({"ok": False, "message": f"read failed: {e}"})

# dry-run each tool with sample params at startup so failures surface early
sample = {"q": "test"}
raw = tool_registry.get_tool("search").run(sample)
assert json.loads(raw).get("ok") is True

try:
    result = workflow.run(requirement)
except WorkflowExecutionError as e:
    if "工具执行异常" in str(e) and e.__cause__ is not None:
        cause = e.__cause__
        if isinstance(cause, (ConnectionError, TimeoutError)):
            import time; time.sleep(2)
            result = workflow.run(requirement)  # one retry for transient tool I/O
        else:
            raise
    else:
        raise

When it happens

Trigger: Any exception thrown inside tool.run(parameters) during a workflow stage: a search tool hitting a dead URL, a file tool given a missing path, or invalid parameter types from the model.

Common situations: Tool hits a dead URL or DNS failure; tool reads a missing file path; the model passes parameters that violate the tool's expectations (string vs int); timeouts on external services.

Related errors

• {stage}阶段执行失败：{exc}
• {stage}失败：{payload.get('message', '未知工具错误')}
• 工具 '{tool_name}' 执行失败: {str(e)}
• 需求必须是字符串
• 需求不能为空

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/b6c96dbfeeba74a5. Report an issue: GitHub.