What causes "LLM_API_KEY 环境变量未设置" in datawhalechina/hello-agents?

export LLM_API_KEY=... (or add it to .env and ensure the entrypoint loads it) before starting the app.

datawhalechina/hello-agents · critical · RuntimeError

LLM_API_KEY 环境变量未设置

Error message

LLM_API_KEY 环境变量未设置

What it means

advisor_agent's default-LLM factory raises RuntimeError when the LLM_API_KEY environment variable is missing. The agent lazily constructs its Buffett-style advisor LLM from env (LLM_MODEL_ID, LLM_API_KEY, LLM_BASE_URL, LLM_PROVIDER), and only the key is mandatory — model/base_url may default downstream.

Source

Thrown at Co-creation-projects/lcyting-StockSage-agent/agents/advisor_agent.py:258

    except Exception as e:
        parts.append(f"## 数据收集错误\n{str(e)}")

    return "\n\n".join(parts) if parts else "暂无可用数据"


def _truncate(text: str, max_len: int) -> str:
    return truncate_at_natural_boundary(text or "", max_len, "...[已截断]")


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 环境变量未设置")

    raw_timeout = int(os.getenv("LLM_TIMEOUT", "60"))
    buffett_timeout = max(raw_timeout, 180)

    return HelloAgentsLLM(
        model=model,
        api_key=api_key,
        base_url=base_url,
        provider=provider,
        temperature=0.4,
        max_tokens=6144,
        timeout=buffett_timeout,
    )

View on GitHub (pinned to 606a07d341)

Solutions

export LLM_API_KEY=... (or add it to .env and ensure the entrypoint loads it) before starting the app.
Or inject a preconfigured llm: HelloAgentsLLM(...) into the agent so no env lookup is needed.
For containers, pass -e LLM_API_KEY or use env_file in compose.
Add a startup preflight that checks required env vars and fails with a clear message.

Example fix

# before
agent = AdvisorAgent()  # RuntimeError if env missing

# after
llm = HelloAgentsLLM(api_key=os.environ["LLM_API_KEY"], ...) if os.getenv("LLM_API_KEY") else None
agent = AdvisorAgent(llm=llm) if llm else fail_fast("LLM_API_KEY not set")

Defensive patterns

Strategy: validation

Validate before calling

if not os.getenv("LLM_API_KEY"):
    raise SystemExit("LLM_API_KEY not set — add it to .env or export before starting the advisor")
agent = AdvisorAgent()

Type guard

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

Try / catch

try:
    agent = AdvisorAgent()
except RuntimeError as e:
    if "LLM_API_KEY" in str(e):
        agent = AdvisorAgent(llm=shared_llm)  # inject preconfigured instance
    else:
        raise

Prevention

Run one shared env preflight for all agents at app startup.
Inject a preconfigured llm instance in tests and deployments instead of relying on env.
Export env vars in the exact process that runs the agent (server, cron, container).

When it happens

Trigger: Instantiating the advisor agent without LLM_API_KEY exported and without passing an llm= argument; .env not loaded in the process (web server, cron, container) that runs the agent.

Common situations: Deploying the Streamlit/app server from a shell that lacks the env; docker exec/cron contexts dropping env; forgetting load_dotenv() in the entrypoint.

Related errors

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