datawhalechina/hello-agents · critical · ImportError

请安装 hello-agents: pip install 'hello-agents[all]>=0.2.7'

Error message

请安装 hello-agents: pip install 'hello-agents[all]>=0.2.7'

What it means

ImportError raised by the LLM adapter when constructing HelloAgentsLLM fails because the hello-agents package is not importable. The adapter catches the original ImportError, logs it, and re-raises with install instructions pinned to hello-agents[all]>=0.2.7. It fires at initialization time, before any completion request is made.

Source

Thrown at Co-creation-projects/Shawnxyxy-HealthRecordAgent/backend/core/llm_adapter.py:37

    def _init_llm(self):
        """初始化 HelloAgent LLM"""
        try:
            from hello_agents import HelloAgentsLLM

            self.llm = HelloAgentsLLM(
                model=self.config.llm.model_name,
                api_key=self.config.llm.api_key,
                base_url=self.config.llm.base_url,
                temperature=self.config.llm.temperature,
                max_tokens=self.config.llm.max_tokens,
                timeout=self.config.llm.timeout
            )

            logger.info(f"HelloAgent LLM 初始化成功: {self.config.llm.model_name}")
        except ImportError as e:
            logger.error(f"hello-agents 未安装: {str(e)}")
            raise ImportError("请安装 hello-agents: pip install 'hello-agents[all]>=0.2.7'")
        except Exception as e:
            logger.error(f"HelloAgent LLM 初始化失败: {str(e)}")
            raise
    
    def _format_messages(self, prompt: Union[str, List[dict]]) -> List[dict]:
        if isinstance(prompt, str):
            return [{"role": "user", "content": prompt}]
        if isinstance(prompt, list):
            return prompt
        return [{"role": "user", "content": str(prompt)}]

    async def ainvoke(self, prompt: Union[str, List[dict]], **kwargs) -> str:
        try:
            messages = self._format_messages(prompt)
            response = await asyncio.to_thread(self.llm.invoke, messages, **kwargs)
            return self._extract_text(response)
        except Exception as e:
            raise LLMException(f"LLM 调用失败: {e}")

View on GitHub (pinned to 606a07d341)

Solutions

1. pip install 'hello-agents[all]>=0.2.7' in the SAME virtualenv/interpreter the backend runs under.
2. Verify with: python -c "import hello_agents" (or the exact module the traceback names) and check pip show hello-agents for the version.
3. Add the dependency to requirements.txt/pyproject so deploys install it automatically.
4. If the install exists but import still fails, read the logged original error — it may name a missing sub-dependency to install separately.

Example fix

# before
pip install hello-agents  # missing [all] extras -> ImportError at runtime

# after
pip install 'hello-agents[all]>=0.2.7'
python -c "import hello_agents; print(hello_agents.__version__)"

try:
    import hello_agents  # noqa: F401
except ImportError:
    sys.exit("missing dependency: pip install 'hello-agents[all]>=0.2.7'")

try:
    adapter = LLMAdapter(config)
except ImportError as e:
    if "hello-agents" in str(e):
        sys.exit(f"install dependency: pip install 'hello-agents[all]>=0.2.7'")
    raise

When it happens

Trigger: Instantiating the adapter/agent stack in an environment where 'import hello_agents' (or its sub-dependencies under the [all] extra) fails — package not installed, wrong virtualenv, or an extras dependency missing so the top-level import fails.

Common situations: Fresh clone without installing requirements; deploying with a minimal install that lacks the [all] extras (embedding/vector deps); running under a different interpreter than the one used to install packages.

Related errors

• 请安装 PyPDF2: pip install PyPDF2
• 工具 '{tool_name}' 不存在
• LLM思考超时
• LLM思考失败: {str(e)}
• 创建内置 MCP 服务器需要 fastmcp 库。请安装: pip install fastmcp

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