microsoft/semantic-kernel · error · InvalidOperationException

AIContextProviders with AIFunctions are not supported when A

Error message

AIContextProviders with AIFunctions are not supported when Agent UseImmutableKernel setting is false.

What it means

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.

Source

Thrown at dotnet/src/Agents/AzureAI/AzureAIAgent.cs:153

            messages,
            thread,
            () => new AzureAIAgentThread(this.Client),
            cancellationToken).ConfigureAwait(false);

        Kernel kernel = this.GetKernel(options);
#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.
        if (this.UseImmutableKernel)
        {
            kernel = kernel.Clone();
        }

        // Get the context contributions from the AIContextProviders.
        AIContext providersContext = await azureAIAgentThread.AIContextProviders.ModelInvokingAsync(messages, cancellationToken).ConfigureAwait(false);

        // Check for compatibility AIContextProviders and the UseImmutableKernel setting.
        if (providersContext.AIFunctions is { Count: > 0 } && !this.UseImmutableKernel)
        {
            throw new InvalidOperationException("AIContextProviders with AIFunctions are not supported when Agent UseImmutableKernel setting is false.");
        }

        kernel.Plugins.AddFromAIContext(providersContext, "Tools");
#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.

        string mergedAdditionalInstructions = FormatAdditionalInstructions(providersContext, options);
        var extensionsContextOptions = options is null ?
            new AzureAIAgentInvokeOptions() { AdditionalInstructions = mergedAdditionalInstructions } :
            new AzureAIAgentInvokeOptions(options) { AdditionalInstructions = mergedAdditionalInstructions };

        using var activity = ModelDiagnostics.StartAgentInvocationActivity(this.Id, this.GetDisplayName(), this.Description, kernel, messages);
        List<ChatMessageContent>? chatMessageContents = activity is not null ? [] : null;

        await foreach (var result in InternalInvokeAsync().ConfigureAwait(false))
        {
            yield return new(result, azureAIAgentThread);
            chatMessageContents?.Add(result);
        }

View on GitHub (pinned to c028a0c7dc)

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.

Example fix

// before
var agent = new AzureAIAgent(...);
thread.AIContextProviders.Add(providerWithFunctions);
await agent.InvokeAsync(messages, thread); // throws

// after
var agent = new AzureAIAgent(...)
{
    UseImmutableKernel = true
};
thread.AIContextProviders.Add(providerWithFunctions);
await agent.InvokeAsync(messages, thread);

Defensive patterns

Strategy: validation

Validate before calling

// Before invoking, check if providers may contribute AIFunctions
if (!agent.UseImmutableKernel && thread.AIContextProviders.HasFunctionProviders())
{
    agent.UseImmutableKernel = true;
}

Try / catch

try
{
    await agent.InvokeAsync(messages, thread, options, ct);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("UseImmutableKernel"))
{
    agent.UseImmutableKernel = true;
    await agent.InvokeAsync(messages, thread, options, ct);
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/41c30b85edb020d2. Report an issue: GitHub.