datawhalechina/hello-agents · error · RuntimeError

未配置 AMiner API Key。请前往 https://open.aminer.cn/ 注册获取，然后在 .env

Error message

未配置 AMiner API Key。请前往 https://open.aminer.cn/ 注册获取，然后在 .env 中设置: AMINER_API_KEY=你的key

What it means

The AMiner search tool (`aminer_search`) raises RuntimeError from `_get_api_key()` when the `AMINER_API_KEY` environment variable is empty or unset. It is a fail-fast configuration guard: the tool refuses to call the AMiner API without credentials and points the user to https://open.aminer.cn/ registration.

Source

Thrown at Co-creation-projects/chengH425-PaperAssistant/src/aminer_tool.py:41

    覆盖 3.2 亿+ 论文，是 Semantic Scholar 的中文补充。
    """

    SEARCH_URL = "https://datacenter.aminer.cn/gateway/open_platform/api/paper/search"

    def __init__(self):
        super().__init__(
            name="aminer_search",
            description="通过 AMiner API 检索中英文学术论文。"
                        "覆盖 3.2 亿+ 论文，擅长中文文献和中文作者搜索。"
                        "当需要检索中文学术论文或中国学者的英文论文时使用此工具。"
                        "需要先注册获取 API Key: https://open.aminer.cn/"
        )

    def _get_api_key(self) -> str:
        """获取 AMiner API Key"""
        key = os.getenv("AMINER_API_KEY", "")
        if not key:
            raise RuntimeError(
                "未配置 AMiner API Key。请前往 https://open.aminer.cn/ 注册获取，"
                "然后在 .env 中设置: AMINER_API_KEY=你的key"
            )
        return key

    def run(self, parameters: Dict[str, Any]) -> ToolResponse:
        keyword = parameters.get("keyword", "")
        author = parameters.get("author", "")
        max_results = min(parameters.get("max_results", 5), 20)

        if not keyword and not author:
            return ToolResponse.error(
                code="INVALID_PARAM",
                message="请至少提供关键词（keyword）或作者（author）"
            )

        # AMiner 用 title 参数做关键词搜索
        query = keyword or author

View on GitHub (pinned to 606a07d341)

Solutions

Register at https://open.aminer.cn/ and add `AMINER_API_KEY=<your-key>` to the project's .env.
Restart the server after editing .env so the new environment is picked up.
If running under Docker/systemd, ensure the variable is passed via env_file/environment, not only the local .env.
Verify with `python -c "import os; print(bool(os.getenv('AMINER_API_KEY')))"` in the same shell/env as the server.

Example fix

// before
# .env (missing or empty)

# after
# .env
AMINER_API_KEY=your_registered_key_here

Defensive patterns

Strategy: validation

Validate before calling

import os

def aminer_ready() -> bool:
    return bool(os.getenv("AMINER_API_KEY"))

if not aminer_ready():
    print("Set AMINER_API_KEY in .env (register at https://open.aminer.cn/) before using aminer_search")

Try / catch

try:
    result = aminer_tool.run({"keyword": "graph neural networks"})
except RuntimeError as e:
    if "AMINER_API_KEY" in str(e):
        disable_tool("aminer_search")  # degrade gracefully, keep other tools usable
    raise

Prevention

Copy .env.example to .env and fill every *_API_KEY at project setup.
Add a startup check that lists which tool API keys are configured.
Run the server from the directory containing .env so dotenv loads it.

When it happens

Trigger: Invoking the `aminer_search` tool with `AMINER_API_KEY` unset, set to an empty string, or defined only in a .env file that was never loaded (e.g. server started from a different working directory than the one containing .env).

Common situations: Fresh clone without .env setup, .env present but the key line commented out, or deployment environment (Docker/systemd) where .env is not copied in and env vars are not exported.

Related errors

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