datawhalechina/hello-agents · error · WorkflowExecutionError

{stage}阶段返回了空结果

Error message

{stage}阶段返回了空结果

What it means

Raised by _run_agent when agent.run() returns something that is not a non-empty string — i.e. None, a non-str object, or a whitespace-only string. The guard sits between 'the call succeeded' and 'the stage produced output', catching framework/model edge cases where a response exists but has no usable content.

Source

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

        if not isinstance(requirement, str):
            raise WorkflowExecutionError("需求必须是字符串")
        requirement = requirement.strip()
        if not requirement:
            raise WorkflowExecutionError("需求不能为空")
        if len(requirement) > MAX_REQUIREMENT_LENGTH:
            raise WorkflowExecutionError(
                f"需求文本不能超过 {MAX_REQUIREMENT_LENGTH} 个字符"
            )
        return requirement

    @staticmethod
    def _run_agent(stage: str, agent: AgentLike, prompt: str) -> str:
        try:
            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

View on GitHub (pinned to 606a07d341)

Solutions

1. Inspect which stage failed and log repr(agent.run(prompt)) in a minimal repro to see the actual return value.
2. If the library changed its return type, adapt by extracting the text field (e.g. response.content) in your agent wrapper.
3. For real empty-content responses, add a retry — occasional blank completions are transient.
4. Fix mocks/stubs to return a non-empty string per the AgentLike protocol.

Example fix

# before (test stub)
class StubAgent:
    def run(self, prompt): return None

# after
class StubAgent:
    def run(self, prompt): return f"stub output for {prompt[:20]}"

# verify an agent honors the AgentLike contract before wiring it in
def check_agent(agent) -> None:
    out = agent.run("ping")
    assert isinstance(out, str) and out.strip(), f"bad return: {out!r}"

for a in (team.analyst, team.architect, team.reviewer, team.synthesizer):
    check_agent(a)

def returns_usable_text(agent) -> bool:
    try:
        out = agent.run("ping")
    except Exception:
        return False
    return isinstance(out, str) and bool(out.strip())

try:
    result = workflow.run(requirement)
except WorkflowExecutionError as e:
    if "返回了空结果" in str(e):
        result = workflow.run(requirement)  # blank completions are often transient: retry once
    else:
        raise

When it happens

Trigger: An agent implementation returns None on internal failure; the LLM returns only whitespace/tool-calls with no text content; a mock or stub agent in tests returns a dict instead of str.

Common situations: Upgrading the agents library changes run()'s return type (e.g. now returns a response object); reasoning models occasionally emit empty content turns; test doubles not matching the AgentLike protocol.

Related errors

• {stage}阶段执行失败：{exc}
• {stage}失败：工具 {name} 未注册
• {stage}失败：{payload.get('message', '未知工具错误')}
• 工具 '{tool_name}' 不存在
• LLM思考超时

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