datawhalechina/hello-agents · error · WorkflowExecutionError

{stage}阶段执行失败：{exc}

Error message

{stage}阶段执行失败：{exc}

What it means

Raised by _run_agent (src/workflow.py:133) when agent.run(prompt) raises any exception; the original is chained with 'from exc' and the stage name (analyst/architect/reviewer/synthesizer) is prefixed. It is a wrapper error — the root cause is whatever the underlying HelloAgents LLM call failed with (network, auth, rate limit, malformed response).

Source

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

    @staticmethod
    def _validate_requirement(requirement: str) -> str:
        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)

View on GitHub (pinned to 606a07d341)

Solutions

1. Read the text after '执行失败：' — it carries the underlying exception; fix that first (auth → key, DNS/conn → base_url, 429 → backoff).
2. Check the stage name to see which agent failed; a first-stage failure usually means config, a later one often means malformed responses.
3. Add retry with exponential backoff around run() for transient network/429 errors.
4. Verify LLM_MODEL_ID, LLM_API_KEY, LLM_BASE_URL with a minimal curl/python call to the provider.

Example fix

# before
result = workflow.run(req)

# after
for attempt in range(3):
    try:
        result = workflow.run(req)
        break
    except WorkflowExecutionError as e:
        if attempt == 2 or '429' not in str(e):
            raise
        time.sleep(2 ** attempt)

# cheap preflight: prove the LLM endpoint+key work before a long workflow
import os, requests

resp = requests.post(
    os.environ["LLM_BASE_URL"].rstrip("/") + "/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['LLM_API_KEY']}"},
    json={"model": os.environ["LLM_MODEL_ID"], "messages": [{"role": "user", "content": "ping"}]},
    timeout=15,
)
resp.raise_for_status()  # surface auth/network issues here, not mid-workflow

from src.workflow import WorkflowExecutionError

last = None
for attempt in range(3):
    try:
        result = workflow.run(requirement)
        break
    except WorkflowExecutionError as e:
        last = e
        msg = str(e)
        transient = any(t in msg for t in ("429", "timeout", "Timeout", "Connection"))
        if not transient or attempt == 2:
            raise
        import time; time.sleep(2 ** attempt)
else:
    raise last

When it happens

Trigger: Any analyst/architect/reviewer/synthesizer stage calling agent.run() while the LLM API key is invalid, the endpoint is unreachable, the rate limit is hit, or the model response cannot be parsed by the agent framework.

Common situations: Expired or wrong API key; wrong LLM_BASE_URL pointing at a provider that 404s; model ID not available on the account; transient 429/503 during peak usage; proxy/firewall blocking egress.

Related errors

• {stage}阶段返回了空结果
• {stage}失败：工具 {name} 未注册
• {stage}失败：工具执行异常：{exc}
• {stage}失败：{payload.get('message', '未知工具错误')}
• 工具 '{tool_name}' 不存在

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