{"record":{"id":"80274fbfc0dedf78","repo":"microsoft/autogen","slug":"include-usage-and-extra-create-args-stream-option","errorCode":null,"errorMessage":"include_usage and extra_create_args['stream_options']['include_usage'] are both set, but differ in value.","messagePattern":"include_usage and extra_create_args\\['stream_options'\\]\\['include_usage'\\] are both set, but differ in value\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py","lineNumber":862,"sourceCode":"            - `max_tokens` (int): The maximum number of tokens to generate in the completion.\n            - `top_p` (float): An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass.\n            - `frequency_penalty` (float): A value between -2.0 and 2.0 that penalizes new tokens based on their existing frequency in the text so far, decreasing the likelihood of repeated phrases.\n            - `presence_penalty` (float): A value between -2.0 and 2.0 that penalizes new tokens based on whether they appear in the text so far, encouraging the model to talk about new topics.\n        \"\"\"\n\n        create_params = self._process_create_args(\n            messages,\n            tools,\n            tool_choice,\n            json_output,\n            extra_create_args,\n        )\n\n        if include_usage is not None:\n            if \"stream_options\" in create_params.create_args:\n                stream_options = create_params.create_args[\"stream_options\"]\n                if \"include_usage\" in stream_options and stream_options[\"include_usage\"] != include_usage:\n                    raise ValueError(\n                        \"include_usage and extra_create_args['stream_options']['include_usage'] are both set, but differ in value.\"\n                    )\n            else:\n                # If stream options are not present, add them.\n                create_params.create_args[\"stream_options\"] = {\"include_usage\": True}\n\n        if max_consecutive_empty_chunk_tolerance != 0:\n            warnings.warn(\n                \"The 'max_consecutive_empty_chunk_tolerance' parameter is deprecated and will be removed in the future releases. All of empty chunks will be skipped with a warning.\",\n                DeprecationWarning,\n                stacklevel=2,\n            )\n\n        if create_params.response_format is not None:\n            chunks = self._create_stream_chunks_beta_client(\n                tool_params=create_params.tools,\n                oai_messages=create_params.messages,\n                response_format=create_params.response_format,","sourceCodeStart":844,"sourceCodeEnd":880,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py#L844-L880","documentation":"Thrown during streaming (create_stream) when the explicit include_usage parameter and extra_create_args['stream_options']['include_usage'] are both set but to different values. The client refuses to guess which the caller intended, since usage accounting would silently differ from the request options.","triggerScenarios":"Calling create_stream with include_usage=False while also passing extra_create_args={'stream_options': {'include_usage': True}} (or the reverse mismatch). Only differing values raise; equal values are accepted.","commonSituations":"Copy-pasting request kwargs (with stream_options) into a call that also sets the dedicated include_usage argument; libraries wrapping create_stream that add stream_options for their own usage tracking while the app sets include_usage separately.","solutions":["Set the value in only one place: either the include_usage parameter or extra_create_args['stream_options']['include_usage'], not both","If both must appear, make them equal (both True or both False)","Remove 'stream_options' from extra_create_args and rely on the include_usage parameter"],"exampleFix":"# before\nasync for chunk in client.create_stream(\n    [msg],\n    include_usage=False,\n    extra_create_args={\"stream_options\": {\"include_usage\": True}},\n):\n    ...\n\n# after\nasync for chunk in client.create_stream(\n    [msg],\n    include_usage=True,\n):\n    ...","handlingStrategy":"validation","validationCode":"extra = dict(extra_create_args)\nstream_opts = extra.get(\"stream_options\", {})\nif \"include_usage\" in stream_opts:\n    stream_opts[\"include_usage\"] = bool(stream_opts[\"include_usage\"])\n    include_usage = stream_opts[\"include_usage\"]  # single source of truth\nextra[\"stream_options\"] = stream_opts","typeGuard":null,"tryCatchPattern":"try:\n    async for chunk in client.create_stream(messages, include_usage=iu, extra_create_args=extra):\n        ...\nexcept ValueError as e:\n    if \"include_usage\" in str(e):\n        extra.pop(\"stream_options\", None)  # retry with only the parameter\n        async for chunk in client.create_stream(messages, include_usage=iu):\n            ...\n    else:\n        raise","preventionTips":["Never set include_usage in both the parameter and extra_create_args","Encapsulate create_stream calls in one wrapper that owns stream_options","When copying request kwargs between calls, strip keys the wrapper already sets"],"tags":["openai","streaming","usage","parameter-conflict"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}