{"record":{"id":"0e4cb7be11f62d84","repo":"JuliusBrussee/caveman","slug":"autogen-requires-a-stable-caveman-scope-for-each-agent-or","errorCode":null,"errorMessage":"AutoGen requires a stable Caveman Scope for each agent or model context","messagePattern":"AutoGen requires a stable Caveman Scope for each agent or model context","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/middleware/python/caveman_middleware/autogen.py","lineNumber":79,"sourceCode":"\ndef _runtime(key):\n    try:\n        return _component_runtimes.get()[key]\n    except KeyError:\n        raise ValueError(f\"Bind runtime {key!r} with caveman_middleware.autogen.component_runtimes before loading\") from None\n\n\ndef _supported(runtime):\n    return supports_framework(runtime, (\"autogen-core\", \"0.7\", \"0.8\"), (\"autogen-agentchat\", \"0.7\", \"0.8\"), (\"autogen-ext\", \"0.7\", \"0.8\"))\n\n\ndef _version_supported():\n    return matches_framework((\"autogen-core\", \"0.7\", \"0.8\"), (\"autogen-agentchat\", \"0.7\", \"0.8\"), (\"autogen-ext\", \"0.7\", \"0.8\"))\n\n\ndef _check(runtime, scope):\n    if not isinstance(scope, Scope):\n        raise TypeError(\"AutoGen requires a stable Caveman Scope for each agent or model context\")\n    return runtime.as_async() if isinstance(runtime, MiddlewareRuntime) else runtime\n\n\ndef _schema():\n    parameters = copy.deepcopy(RECOVERY_SCHEMA)\n    # AutoGen's OpenAI structured-output helper rejects every non-strict tool,\n    # even when that tool is not called. A stable strict schema remains usable\n    # on typed calls; those calls still use only recovery-free transformations.\n    parameters[\"required\"] = list(parameters[\"properties\"])\n    return {\"name\": \"caveman_retrieve\", \"description\": RECOVERY_DESCRIPTION,\n            \"parameters\": parameters, \"strict\": True}\n\n\ndef _observed_usage(result):\n    if result is None or result.cached:\n        return None\n    # Native AutoGen converts an absent provider usage block to two zeros.\n    # Preserve its CreateResult, but do not book those defaults as measurement.","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/middleware/python/caveman_middleware/autogen.py#L61-L97","documentation":"The Caveman AutoGen middleware adapter requires an explicit Scope object to be passed alongside the runtime; the Scope anchors recovery sessions and config so each agent or model context has a stable identity. _check() raises this TypeError immediately at construction time when the scope argument is anything other than a caveman Scope instance (e.g. None, a string name, or a dict).","triggerScenarios":"Constructing CavemanChatCompletionClient or CavemanWorkbench (which both call _check via their __init__) with scope=None, with a string identifier, or with an object from a different library that is not caveman_middleware's Scope class.","commonSituations":"Passing a config dict instead of a Scope; forgetting to create a Scope after upgrading the middleware; building agents dynamically in loops and defaulting scope to None; mixing Scope classes from different caveman package versions.","solutions":["Create and pass a caveman Scope instance (from caveman_middleware import Scope; scope = Scope(...)) to the adapter constructor.","If a scope name/config is stored elsewhere, reconstruct a Scope from it before constructing the client/workbench.","Verify the imported Scope comes from caveman_middleware, not another package or an older major version.","Check that no code path passes scope=None as a default; make scope a required constructor argument in your wrapper."],"exampleFix":"// before\nclient = CavemanChatCompletionClient(inner_client, runtime=runtime, scope=None)\n// after\nfrom caveman_middleware import Scope\nscope = Scope(\"agent-primary\")\nclient = CavemanChatCompletionClient(inner_client, runtime=runtime, scope=scope)","handlingStrategy":"type-guard","validationCode":"from caveman_middleware import Scope\nif not isinstance(scope, Scope):\n    raise TypeError(f\"scope must be a caveman Scope, got {type(scope).__name__}\")","typeGuard":"def is_scope(obj) -> bool:\n    from caveman_middleware import Scope\n    return isinstance(obj, Scope)","tryCatchPattern":"try:\n    client = CavemanChatCompletionClient(inner, runtime=rt, scope=maybe_scope)\nexcept TypeError as e:\n    if \"stable Caveman Scope\" in str(e):\n        client = CavemanChatCompletionClient(inner, runtime=rt, scope=Scope(default_name))\n    else:\n        raise","preventionTips":["Make scope a required keyword argument in your agent factory so it can never default to None.","Construct Scope objects next to runtime setup, not inline at call sites.","Add an isinstance(scope, Scope) assert in shared construction helpers."],"tags":["python","autogen","middleware","type-error","scope"],"backgroundTag":"invalid-argument-value","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"}