JuliusBrussee/caveman · error · ImportError

Install caveman-middleware[agno] to use the Agno adapter

Error message

Install caveman-middleware[agno] to use the Agno adapter

What it means

The Agno adapter imports agno.models.base, agno.models.message and related modules at import time; if agno is not installed, it re-raises as an ImportError telling you to install the caveman-middleware[agno] extra. The adapter deliberately does not ship agno as a hard dependency.

Solutions

1. pip install "caveman-middleware[agno]"
2. If agno is present but imports fail, pin/upgrade to a compatible agno version (check matches_framework in _versions)
3. Install agno directly (pip install agno) if you manage it separately
4. Avoid importing the adapter module in code paths that do not use Agno

Example fix

# before
pip install caveman-middleware
from caveman_middleware import agno  # ImportError
# after
pip install "caveman-middleware[agno]"
from caveman_middleware import agno

import importlib.util
def agno_extra_installed() -> bool:
    return importlib.util.find_spec("agno") is not None

try:
    from caveman_middleware import agno as agno_adapter
except ImportError as e:
    if "caveman-middleware[agno]" in str(e):
        raise SystemExit("Install with: pip install 'caveman-middleware[agno]'") from e
    raise

When it happens

Trigger: Importing caveman_middleware.agno (or anything that imports it) in an environment where the agno package is absent, or where an installed agno version lacks one of the imported submodules.

Common situations: Installing caveman-middleware from PyPI without extras and then wiring the Agno adapter; a slim production image omitting optional deps; an agno upgrade removing/moving imported modules.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• Agno middleware requires a nonempty native session_id
• Agno scope resolver must return a Caveman Scope
• Expected an existing native Agno Model
• Install caveman-middleware[crewai] to use the CrewAI adapter
• Install caveman-middleware[google] to use the Google adapter

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/cbd8157e83ef1222. Report an issue: GitHub.

Appendix: source

Thrown at packages/middleware/python/caveman_middleware/agno.py:21

import asyncio
import contextvars
import copy
import functools
import inspect
import json
import uuid
from dataclasses import dataclass, field, fields
from importlib.metadata import version

try:
    from agno.models.base import Model
    from agno.models.message import Message
    from agno.run.base import RunContext
    from agno.run.cancel import araise_if_cancelled, raise_if_cancelled
    from agno.tools.function import Function
except ModuleNotFoundError as error:
    raise ImportError("Install caveman-middleware[agno] to use the Agno adapter") from error

from caveman_cloud.middleware import Adapter, Candidate, MiddlewareError, MiddlewareRuntime, Scope
from caveman_cloud.middleware.runtime import RECOVERY_DESCRIPTION, RECOVERY_SCHEMA
from ._native import Attempt, manifest, owner, plain
from ._versions import matches_framework

ADAPTER = Adapter("agno", "0.1.0", "3.0.9", "agno-message-v1")
_SIGNATURES = {name: inspect.signature(getattr(Model, name)) for name in
               ("response", "aresponse", "response_stream", "aresponse_stream")}


def scope_from_run(run, *, namespace: str) -> Scope:
    """Resolve a native Agent or Team run's session, with explicit branch metadata."""
    session = getattr(run, "session_id", None)
    if not isinstance(session, str) or not session:
        raise ValueError("Agno middleware requires a nonempty native session_id")
    metadata = getattr(run, "metadata", None) or {}
    return Scope(namespace, session, metadata.get("caveman_branch_id", "main"), metadata.get("caveman_cache_epoch", "0"))

View on GitHub (pinned to 3ee70a1026)