datawhalechina/hello-agents · error · WorkflowExecutionError

失败：

Error message

{stage}失败：{payload.get('message', '未知工具错误')}

What it means

Raised by _run_tool when the parsed JSON object has a falsy 'ok' field — the tool succeeded at the protocol level but reported a logical failure. The message field from the payload is surfaced (falling back to '未知工具错误' when the tool omitted it), prefixed with the stage name.

Solutions

1. Treat the embedded message as the real error: it comes from the tool itself (e.g. 'no results'); fix the underlying condition or the arguments the model passed.
2. If 'no results' is expected and recoverable, change the tool to return ok:true with an empty result set so the workflow can continue.
3. Improve tool descriptions/schemas so the model supplies valid arguments that avoid the failure.

Example fix

# before (tool)
return json.dumps({"ok": False, "message": "no results"})

# after (empty result is not an error)
return json.dumps({"ok": True, "results": []})

# treat logical tool failures as data, not crashes: normalize at the boundary
import json

def safe_tool_call(registry, name, params):
    raw = registry.get_tool(name).run(params)
    payload = json.loads(raw)
    if not payload.get("ok"):
        return None  # signal 'unavailable' instead of raising
    return payload

try:
    result = workflow.run(requirement)
except WorkflowExecutionError as e:
    if "未知工具错误" in str(e):
        # tool reported ok:false without a message — improve the tool's payload
        log.warning("tool %s failed without message", stage)
    raise  # logical failures usually need argument or data fixes, not retries

When it happens

Trigger: A tool returns {"ok": false, "message": "query returned no rows"}; any custom tool signalling failure via the ok flag; the tool returns {"ok": false} with no message key, yielding the '未知工具错误' fallback text.

Common situations: A search/lookup tool finds nothing for the model's arguments; an external dependency checked by the tool is down; validation inside the tool rejects the model-provided parameters.

Related errors

• 阶段返回了空结果
• 阶段执行失败：
• 失败：工具执行异常：
• 失败：工具 未注册
• 需求不能为空

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

Appendix: source

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

        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,
            self.team.reviewer,
            self.team.synthesizer,
        ):
            clear_history = getattr(agent, "clear_history", None)
            if callable(clear_history):
                clear_history()

    @staticmethod

View on GitHub (pinned to 606a07d341)