NousResearch/hermes-agent · error · ImportError

The 'azure-identity' package is required for Azure AI Foundr

Error message

The 'azure-identity' package is required for Azure AI Foundry Entra ID authentication. Install it with: pip install azure-identity

What it means

Raised while importing azure.identity for Azure AI Foundry Entra ID auth: the import failed AND the tools.lazy_deps module itself could not be imported, so the lazy-install escape hatch is unavailable. The adapter deliberately surfaces an actionable ImportError instead of a bare ModuleNotFoundError.

Source

Thrown at agent/azure_identity_adapter.py:85

        return True
    except Exception:
        return False


def _require_azure_identity():
    """Import ``azure.identity``, lazy-installing it if allowed.

    Raises ``ImportError`` with a clear actionable message when the
    package is missing and lazy installs are disabled.
    """
    try:
        import azure.identity as _ai
        return _ai
    except ImportError:
        try:
            from tools.lazy_deps import ensure, FeatureUnavailable
        except ImportError as exc:
            raise ImportError(
                "The 'azure-identity' package is required for Azure AI "
                "Foundry Entra ID authentication. Install it with: "
                "pip install azure-identity"
            ) from exc

        try:
            ensure(_AZURE_IDENTITY_FEATURE, prompt=False)
        except FeatureUnavailable as exc:
            raise ImportError(
                "The 'azure-identity' package is required for Azure AI "
                "Foundry Entra ID authentication. " + str(exc)
            ) from exc

        # Retry import after lazy install.
        import azure.identity as _ai  # noqa: WPS440
        return _ai

View on GitHub (pinned to c896c09c42)

Solutions

pip install azure-identity in the active venv.
Reinstall/repair hermes-agent so tools.lazy_deps is importable (pip install -e . from the repo root).
Verify the correct Python interpreter/venv is active (which python; pip -V).

Example fix

pip install azure-identity

Defensive patterns

Strategy: validation

Validate before calling

try:
    import azure.identity  # noqa
    ok = True
except ImportError:
    ok = False
# and ensure hermes install is intact
import tools.lazy_deps  # noqa — should not raise

Try / catch

try:
    from agent.azure_identity_adapter import _import_azure_identity
    _import_azure_identity()
except ImportError as e:
    if "azure-identity" in str(e):
        run("pip install azure-identity")

Prevention

Install optional provider extras up front when you plan to use them.
Prefer pip install -e '.[all-relevant-extras]' over partial installs.
Validate the venv with `hermes doctor`-style import checks after install.

When it happens

Trigger: Selecting the Azure Foundry provider with Entra auth in an environment where azure-identity is absent and Hermes' tools.lazy_deps is not importable (broken install, partial venv, exotic packaging).

Common situations: Broken/partial pip install of hermes-agent; running from a source checkout with unresolved deps; a stripped-down container.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/971ed75d1247b177. Report an issue: GitHub.