datawhalechina/hello-agents · error · WorkflowExecutionError

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

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.

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)

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": []})
Defensive patterns

Strategy: fallback

Validate before calling

# 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 / catch

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

Prevention

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.