datawhalechina/hello-agents · critical · RuntimeError

LLM_API_KEY 环境变量未设置

Error message

LLM_API_KEY 环境变量未设置

What it means

agent_system's default-LLM factory raises the same RuntimeError as the other StockSage agents: LLM_API_KEY is absent from the environment. This coordinator/system agent additionally reads LLM_TIMEOUT from app.config settings with an env fallback, but only the missing key is fatal at this point.

Source

Thrown at Co-creation-projects/lcyting-StockSage-agent/agents/agent_system.py:247

    # ---- 健康检查 ----

    def is_ready(self) -> bool:
        try:
            self._ensure_llm()
            return True
        except Exception:
            return False


def _create_default_llm() -> HelloAgentsLLM:
    model = os.getenv("LLM_MODEL_ID")
    api_key = os.getenv("LLM_API_KEY")
    base_url = os.getenv("LLM_BASE_URL")
    provider = os.getenv("LLM_PROVIDER", "auto")

    if not api_key:
        raise RuntimeError("LLM_API_KEY 环境变量未设置")

    try:
        from app.config import settings

        raw_timeout = int(settings.LLM_TIMEOUT)
    except Exception:
        raw_timeout = int(os.getenv("LLM_TIMEOUT", "60"))
    # ReAct 多轮 + 工具调用 + 协调者多 Agent 串联，默认 60s 极易中途超时
    timeout = max(raw_timeout, 180)

    return HelloAgentsLLM(
        model=model,
        api_key=api_key,
        base_url=base_url,
        provider=provider,
        temperature=0.3,
        max_tokens=8192,
        timeout=timeout,

View on GitHub (pinned to 606a07d341)

Solutions

1. Set LLM_API_KEY in the environment or .env that the launching process actually reads.
2. Pass a shared llm instance when constructing the agent system to skip env resolution entirely.
3. For schedulers/cron/systemd, list the env var explicitly in the unit/job definition.
4. Add a preflight env check at app startup listing all missing LLM_* variables.

Example fix

# before
llm = _create_default_llm()  # RuntimeError: LLM_API_KEY not set

# after
missing = [v for v in ("LLM_API_KEY",) if not os.getenv(v)]
if missing:
    raise SystemExit(f"missing env vars: {missing}; source .env first")
llm = _create_default_llm()

missing = [v for v in ("LLM_API_KEY", "LLM_BASE_URL") if not os.getenv(v)]
if missing:
    raise SystemExit(f"missing env vars for agent system: {missing}")
system = AgentSystem()

def agent_system_env_ready() -> bool:
    return bool(os.getenv("LLM_API_KEY"))

try:
    llm = _create_default_llm()
except RuntimeError as e:
    if "LLM_API_KEY" in str(e):
        raise SystemExit("set LLM_API_KEY (see .env.example) before starting") from e
    raise

When it happens

Trigger: Creating the multi-agent system without LLM_API_KEY set and without injecting an llm instance; note this factory swallows unrelated exceptions when importing app.config (broad except), so misconfigured settings silently fall back to env defaults.

Common situations: Running the orchestrator in a fresh environment (no .env); subprocess/scheduler launches that don't inherit the interactive shell env; misnamed key in .env (e.g. LLM_KEY).

Related errors

• 未配置 AMiner API Key。请前往 https://open.aminer.cn/ 注册获取，然后在 .env
• Missing required environment variables: {missing_env_vars}.
• LLM client is not configured. Check .env.
• API密钥和服务地址必须被提供或在.env文件中定义。
• LLM_API_KEY 环境变量未设置

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