{"record":{"id":"c2e847f8e774f2cf","repo":"datawhalechina/hello-agents","slug":"stage","errorCode":null,"errorMessage":"{stage}阶段返回了空结果","messagePattern":"(.+?)阶段返回了空结果","errorType":"exception","errorClass":"WorkflowExecutionError","httpStatus":null,"severity":"error","filePath":"Co-creation-projects/zenith191-RequirementClarifierAgent/src/workflow.py","lineNumber":135,"sourceCode":"        if not isinstance(requirement, str):\n            raise WorkflowExecutionError(\"需求必须是字符串\")\n        requirement = requirement.strip()\n        if not requirement:\n            raise WorkflowExecutionError(\"需求不能为空\")\n        if len(requirement) > MAX_REQUIREMENT_LENGTH:\n            raise WorkflowExecutionError(\n                f\"需求文本不能超过 {MAX_REQUIREMENT_LENGTH} 个字符\"\n            )\n        return requirement\n\n    @staticmethod\n    def _run_agent(stage: str, agent: AgentLike, prompt: str) -> str:\n        try:\n            response = agent.run(prompt)\n        except Exception as exc:\n            raise WorkflowExecutionError(f\"{stage}阶段执行失败：{exc}\") from exc\n        if not isinstance(response, str) or not response.strip():\n            raise WorkflowExecutionError(f\"{stage}阶段返回了空结果\")\n        return response.strip()\n\n    def _run_tool(\n        self, name: str, parameters: dict[str, object], stage: str\n    ) -> dict[str, object]:\n        \"\"\"通过官方 ToolRegistry 获取工具并解析其字符串协议。\"\"\"\n\n        tool = self.tool_registry.get_tool(name)\n        if tool is None:\n            raise WorkflowExecutionError(f\"{stage}失败：工具 {name} 未注册\")\n        try:\n            raw_result = tool.run(parameters)\n        except Exception as exc:\n            raise WorkflowExecutionError(f\"{stage}失败：工具执行异常：{exc}\") from exc\n        try:\n            payload = json.loads(raw_result)\n        except (TypeError, ValueError) as exc:\n            raise WorkflowExecutionError(f\"{stage}失败：工具返回的不是有效 JSON\") from exc","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/datawhalechina/hello-agents/blob/606a07d341a47be773fab7f4b71177f53f96b2c3/Co-creation-projects/zenith191-RequirementClarifierAgent/src/workflow.py#L117-L153","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect which stage failed and log repr(agent.run(prompt)) in a minimal repro to see the actual return value.","If the library changed its return type, adapt by extracting the text field (e.g. response.content) in your agent wrapper.","For real empty-content responses, add a retry — occasional blank completions are transient.","Fix mocks/stubs to return a non-empty string per the AgentLike protocol."],"exampleFix":"# before (test stub)\nclass StubAgent:\n    def run(self, prompt): return None\n\n# after\nclass StubAgent:\n    def run(self, prompt): return f\"stub output for {prompt[:20]}\"","handlingStrategy":"validation","validationCode":"# verify an agent honors the AgentLike contract before wiring it in\ndef check_agent(agent) -> None:\n    out = agent.run(\"ping\")\n    assert isinstance(out, str) and out.strip(), f\"bad return: {out!r}\"\n\nfor a in (team.analyst, team.architect, team.reviewer, team.synthesizer):\n    check_agent(a)","typeGuard":"def returns_usable_text(agent) -> bool:\n    try:\n        out = agent.run(\"ping\")\n    except Exception:\n        return False\n    return isinstance(out, str) and bool(out.strip())","tryCatchPattern":"try:\n    result = workflow.run(requirement)\nexcept WorkflowExecutionError as e:\n    if \"返回了空结果\" in str(e):\n        result = workflow.run(requirement)  # blank completions are often transient: retry once\n    else:\n        raise","preventionTips":["Pin the agents library version so run()'s return type can't drift silently.","Make test stubs match the AgentLike protocol exactly (return non-empty str).","Retry once on empty responses — providers occasionally emit content-less turns.","Wrap third-party agents in a thin adapter normalizing output to str."],"tags":["python","llm","workflow","empty-response"],"backgroundTag":null,"analyzedSha":"606a07d341a47be773fab7f4b71177f53f96b2c3","analyzedAt":"2026-08-14T22:57:27.446Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}