crewAIInc/crewAI · error · ImportError

`minds_sdk` package not found, please run `pip install minds

Error message

`minds_sdk` package not found, please run `pip install minds-sdk`

What it means

AIMindTool's constructor tries to import minds.client and minds.datasources after validating the API key; if the optional minds_sdk distribution is not installed, the ImportError is caught and re-raised with an install hint. This is the standard CrewAI pattern for optional tool dependencies — the package is not bundled with crewai-tools by default.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/ai_mind_tool/ai_mind_tool.py:59

            ),
        ]
    )

    def __init__(self, api_key: str | None = None, **kwargs: Any) -> None:
        super().__init__(**kwargs)
        self.api_key = api_key or os.getenv("MINDS_API_KEY")
        if not self.api_key:
            raise ValueError(
                "API key must be provided either through constructor or MINDS_API_KEY environment variable"
            )

        try:
            from minds.client import Client  # type: ignore[import-not-found]
            from minds.datasources import (  # type: ignore[import-not-found]
                DatabaseConfig,
            )
        except ImportError as e:
            raise ImportError(
                "`minds_sdk` package not found, please run `pip install minds-sdk`"
            ) from e

        minds_client = Client(api_key=self.api_key)

        datasources = []
        for datasource in self.datasources:
            config = DatabaseConfig(
                name=f"{AIMindToolConstants.DATASOURCE_NAME_PREFIX}_{secrets.token_hex(5)}",
                engine=datasource["engine"],
                description=datasource["description"],
                connection_data=datasource["connection_data"],
                tables=datasource["tables"],
            )
            datasources.append(config)

        name = f"{AIMindToolConstants.MIND_NAME_PREFIX}_{secrets.token_hex(5)}"

View on GitHub (pinned to 754d7323be)

Solutions

Install the SDK: `pip install minds-sdk` (or `uv add minds-sdk`).
Confirm the install landed in the running interpreter: `python -c "import minds.client"` using the same python that runs the app.
Add minds-sdk to your project dependencies so fresh environments get it automatically.

Example fix

# before
tool = AIMindTool(datasources=[...])  # ImportError

# after (shell)
# pip install minds-sdk
tool = AIMindTool(datasources=[...])

Defensive patterns

Strategy: fallback

Validate before calling

def minds_sdk_available() -> bool:
    try:
        import minds.client  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

try:
    tool = AIMindTool(datasources=[...])
except ImportError as e:
    if "minds_sdk" in str(e):
        raise SystemExit("Install missing dependency: pip install minds-sdk") from e
    raise

Prevention

Add optional tool SDKs to your lockfile when you adopt the tool — don't rely on runtime install hints.
Gate tool construction behind an availability probe when the feature is optional.
Verify imports with the same interpreter that runs the app, not a stray shell.

When it happens

Trigger: Constructing AIMindTool in an environment where `pip install minds-sdk` was never run, or where it is installed in a different virtualenv/interpreter than the one running CrewAI.

Common situations: Fresh clone/new venv without extras; UV/poetry lockfiles missing the optional dep; CI cache restored without the package; multiple Python interpreters (system vs venv).

Related errors

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/638a07148bcacda7. Report an issue: GitHub.