{"record":{"id":"41c30b85edb020d2","repo":"microsoft/semantic-kernel","slug":"aicontextproviders-with-aifunctions-are-not-suppor","errorCode":null,"errorMessage":"AIContextProviders with AIFunctions are not supported when Agent UseImmutableKernel setting is false.","messagePattern":"AIContextProviders with AIFunctions are not supported when Agent UseImmutableKernel setting is false\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Agents/AzureAI/AzureAIAgent.cs","lineNumber":153,"sourceCode":"            messages,\n            thread,\n            () => new AzureAIAgentThread(this.Client),\n            cancellationToken).ConfigureAwait(false);\n\n        Kernel kernel = this.GetKernel(options);\n#pragma warning disable SKEXP0110, SKEXP0130 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.\n        if (this.UseImmutableKernel)\n        {\n            kernel = kernel.Clone();\n        }\n\n        // Get the context contributions from the AIContextProviders.\n        AIContext providersContext = await azureAIAgentThread.AIContextProviders.ModelInvokingAsync(messages, cancellationToken).ConfigureAwait(false);\n\n        // Check for compatibility AIContextProviders and the UseImmutableKernel setting.\n        if (providersContext.AIFunctions is { Count: > 0 } && !this.UseImmutableKernel)\n        {\n            throw new InvalidOperationException(\"AIContextProviders with AIFunctions are not supported when Agent UseImmutableKernel setting is false.\");\n        }\n\n        kernel.Plugins.AddFromAIContext(providersContext, \"Tools\");\n#pragma warning restore SKEXP0110, SKEXP0130 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.\n\n        string mergedAdditionalInstructions = FormatAdditionalInstructions(providersContext, options);\n        var extensionsContextOptions = options is null ?\n            new AzureAIAgentInvokeOptions() { AdditionalInstructions = mergedAdditionalInstructions } :\n            new AzureAIAgentInvokeOptions(options) { AdditionalInstructions = mergedAdditionalInstructions };\n\n        using var activity = ModelDiagnostics.StartAgentInvocationActivity(this.Id, this.GetDisplayName(), this.Description, kernel, messages);\n        List<ChatMessageContent>? chatMessageContents = activity is not null ? [] : null;\n\n        await foreach (var result in InternalInvokeAsync().ConfigureAwait(false))\n        {\n            yield return new(result, azureAIAgentThread);\n            chatMessageContents?.Add(result);\n        }","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Agents/AzureAI/AzureAIAgent.cs#L135-L171","documentation":"Thrown by AzureAIAgent.InvokeAsync when AIContextProviders supply AIFunctions (providersContext.AIFunctions.Count > 0) but the agent's UseImmutableKernel property is false (the default). AIFunctions require the kernel to be cloned (immutable mode) so that provider-injected functions don't mutate the shared kernel. Without cloning, the functions would permanently pollute the agent's kernel instance.","triggerScenarios":"An AzureAIAgent has AIContextProviders registered on its thread that contribute AIFunctions, and UseImmutableKernel is left at its default value of false. This occurs during InvokeAsync after the providers' ModelInvokingAsync returns context with functions.","commonSituations":"Adding an AIContextProvider that returns AIFunctions (e.g., a memory or tool provider) without setting agent.UseImmutableKernel = true. Migrating from an older version where this combination was silently allowed. Using experimental SKEXP0110 context providers for the first time.","solutions":["Set agent.UseImmutableKernel = true before invoking when using AIContextProviders with AIFunctions.","Alternatively, remove the AIFunctions from the context providers if immutability is not desired.","Register plugins directly on the kernel instead of through AIContextProviders to avoid the immutability requirement."],"exampleFix":"// before\nvar agent = new AzureAIAgent(...);\nthread.AIContextProviders.Add(providerWithFunctions);\nawait agent.InvokeAsync(messages, thread); // throws\n\n// after\nvar agent = new AzureAIAgent(...)\n{\n    UseImmutableKernel = true\n};\nthread.AIContextProviders.Add(providerWithFunctions);\nawait agent.InvokeAsync(messages, thread);","handlingStrategy":"validation","validationCode":"// Before invoking, check if providers may contribute AIFunctions\nif (!agent.UseImmutableKernel && thread.AIContextProviders.HasFunctionProviders())\n{\n    agent.UseImmutableKernel = true;\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    await agent.InvokeAsync(messages, thread, options, ct);\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"UseImmutableKernel\"))\n{\n    agent.UseImmutableKernel = true;\n    await agent.InvokeAsync(messages, thread, options, ct);\n}","preventionTips":["Set UseImmutableKernel = true whenever you add AIContextProviders with AIFunctions.","Document this requirement at the point where context providers are registered.","Consider always enabling UseImmutableKernel for safety in multi-tenant scenarios."],"tags":["azureai-agent","ai-context-providers","useimmutablekernel","invalidoperation","skexp0110"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}