{"record":{"id":"cbd8157e83ef1222","repo":"JuliusBrussee/caveman","slug":"install-caveman-middleware-agno-to-use-the-agno-adapter","errorCode":null,"errorMessage":"Install caveman-middleware[agno] to use the Agno adapter","messagePattern":"Install caveman-middleware\\[agno\\] to use the Agno adapter","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"packages/middleware/python/caveman_middleware/agno.py","lineNumber":21,"sourceCode":"\nimport asyncio\nimport contextvars\nimport copy\nimport functools\nimport inspect\nimport json\nimport uuid\nfrom dataclasses import dataclass, field, fields\nfrom importlib.metadata import version\n\ntry:\n    from agno.models.base import Model\n    from agno.models.message import Message\n    from agno.run.base import RunContext\n    from agno.run.cancel import araise_if_cancelled, raise_if_cancelled\n    from agno.tools.function import Function\nexcept ModuleNotFoundError as error:\n    raise ImportError(\"Install caveman-middleware[agno] to use the Agno adapter\") from error\n\nfrom caveman_cloud.middleware import Adapter, Candidate, MiddlewareError, MiddlewareRuntime, Scope\nfrom caveman_cloud.middleware.runtime import RECOVERY_DESCRIPTION, RECOVERY_SCHEMA\nfrom ._native import Attempt, manifest, owner, plain\nfrom ._versions import matches_framework\n\nADAPTER = Adapter(\"agno\", \"0.1.0\", \"3.0.9\", \"agno-message-v1\")\n_SIGNATURES = {name: inspect.signature(getattr(Model, name)) for name in\n               (\"response\", \"aresponse\", \"response_stream\", \"aresponse_stream\")}\n\n\ndef scope_from_run(run, *, namespace: str) -> Scope:\n    \"\"\"Resolve a native Agent or Team run's session, with explicit branch metadata.\"\"\"\n    session = getattr(run, \"session_id\", None)\n    if not isinstance(session, str) or not session:\n        raise ValueError(\"Agno middleware requires a nonempty native session_id\")\n    metadata = getattr(run, \"metadata\", None) or {}\n    return Scope(namespace, session, metadata.get(\"caveman_branch_id\", \"main\"), metadata.get(\"caveman_cache_epoch\", \"0\"))","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/middleware/python/caveman_middleware/agno.py#L3-L39","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["pip install \"caveman-middleware[agno]\"","If agno is present but imports fail, pin/upgrade to a compatible agno version (check matches_framework in _versions)","Install agno directly (pip install agno) if you manage it separately","Avoid importing the adapter module in code paths that do not use Agno"],"exampleFix":"# before\npip install caveman-middleware\nfrom caveman_middleware import agno  # ImportError\n# after\npip install \"caveman-middleware[agno]\"\nfrom caveman_middleware import agno","handlingStrategy":"try-catch","validationCode":"import importlib.util\ndef agno_extra_installed() -> bool:\n    return importlib.util.find_spec(\"agno\") is not None","typeGuard":null,"tryCatchPattern":"try:\n    from caveman_middleware import agno as agno_adapter\nexcept ImportError as e:\n    if \"caveman-middleware[agno]\" in str(e):\n        raise SystemExit(\"Install with: pip install 'caveman-middleware[agno]'\") from e\n    raise","preventionTips":["Declare caveman-middleware[agno] in requirements/pyproject when using Agno","Guard the adapter import behind a feature flag with a clear install hint","Pin agno to a version compatible with the adapter (matches_framework)","Keep optional extras installed in CI to catch breakage early"],"tags":["python","dependency","agno","optional-extra"],"backgroundTag":"missing-optional-dependency","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}