datawhalechina/hello-agents · critical · HelloAgentsException

API密钥和服务地址必须被提供或在.env文件中定义。

Error message

API密钥和服务地址必须被提供或在.env文件中定义。

What it means

HelloAgentsLLM's constructor raises HelloAgentsException when, after provider resolution (custom provider reads LLM_API_KEY/LLM_BASE_URL env vars; others go through _resolve_credentials), either api_key or base_url is falsy. The model gets a default if unset, but key and base URL have no defaults — they must come from arguments or environment.

Source

Thrown at Co-creation-projects/lcyting-StockSage-agent/HelloAgents Optimized/hello_agents/core/llm.py:84

        self.kwargs = kwargs

        # 自动检测provider或使用指定的provider
        requested_provider = (provider or "").lower() if provider else None
        self.provider = provider or self._auto_detect_provider(api_key, base_url)

        if requested_provider == "custom":
            self.provider = "custom"
            self.api_key = api_key or os.getenv("LLM_API_KEY")
            self.base_url = base_url or os.getenv("LLM_BASE_URL")
        else:
            # 根据provider确定API密钥和base_url
            self.api_key, self.base_url = self._resolve_credentials(api_key, base_url)

        # 验证必要参数
        if not self.model:
            self.model = self._get_default_model()
        if not all([self.api_key, self.base_url]):
            raise HelloAgentsException(
                "API密钥和服务地址必须被提供或在.env文件中定义。"
            )

        # 创建OpenAI客户端
        self._client = self._create_client()

    def _auto_detect_provider(
        self, api_key: Optional[str], base_url: Optional[str]
    ) -> str:
        """
        自动检测LLM提供商

        检测逻辑：
        1. 优先检查特定提供商的环境变量
        2. 根据API密钥格式判断
        3. 根据base_url判断
        4. 默认返回通用配置
        """

View on GitHub (pinned to 606a07d341)

Solutions

  1. Set the provider-appropriate env vars: for provider="custom" export both LLM_API_KEY and LLM_BASE_URL; for named providers export that provider's key env var.
  2. Or pass api_key= and base_url= explicitly to the constructor.
  3. Ensure load_dotenv() runs before creating the LLM if credentials live in .env.
  4. Check LLM_PROVIDER — a wrong value routes credential resolution to the wrong env var names.

Example fix

# before
llm = HelloAgentsLLM(model="gpt-4o-mini")  # raises if env unset

# after
from dotenv import load_dotenv
load_dotenv()  # populates LLM_API_KEY / LLM_BASE_URL
llm = HelloAgentsLLM(model="gpt-4o-mini", api_key=..., base_url=...)  # or explicit args
Defensive patterns

Strategy: validation

Validate before calling

from dotenv import load_dotenv
load_dotenv()
assert os.getenv("LLM_API_KEY") and os.getenv("LLM_BASE_URL"), (
    "LLM_API_KEY and LLM_BASE_URL must be set for provider 'custom'")
llm = HelloAgentsLLM()

Type guard

def llm_credentials_present(api_key: str | None, base_url: str | None) -> bool:
    return bool(api_key and base_url)

Try / catch

try:
    llm = HelloAgentsLLM(model=m, api_key=k, base_url=u)
except HelloAgentsException as e:
    raise SystemExit(f"LLM init failed ({e}); check .env / provider env vars") from e

Prevention

When it happens

Trigger: Instantiating HelloAgentsLLM() with no args and no .env / env vars set; custom provider with only LLM_API_KEY exported but not LLM_BASE_URL; a named provider whose expected env var (e.g. OPENAI_API_KEY) is absent so _resolve_credentials returns an empty base_url.

Common situations: Fresh clone without .env setup; python-dotenv load_dotenv() not called before construction; wrong provider string so credential resolution looks up the wrong env var names; CI runners without secrets configured.

Related errors

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