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 FinalizeInvokeOptionsAsync when AIContextProviders contribute one or more AIFunctions (tools) but the agent's UseImmutableKernel is false. With UseImmutableKernel=false (the default, Agent.cs:79) the kernel is shared, and the code would add the provider's tools as plugins directly to that shared kernel — polluting it for every other caller. The library refuses rather than silently mutating shared state. With UseImmutableKernel=true the kernel is cloned (kernel.Clone()) first, so plugin additions are isolated.

Source

Thrown at dotnet/src/Agents/OpenAI/OpenAIResponseAgent.cs:178

        return await this.EnsureThreadExistsWithMessagesAsync(messages, thread, () => new ChatHistoryAgentThread(), cancellationToken).ConfigureAwait(false);
    }

    private async Task<OpenAIResponseAgentInvokeOptions> FinalizeInvokeOptionsAsync(ICollection<ChatMessageContent> messages, AgentInvokeOptions? options, AgentThread agentThread, CancellationToken cancellationToken)
    {
        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 AIContextProviders contributions to the kernel.
        AIContext providersContext = await agentThread.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 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);
        OpenAIResponseAgentInvokeOptions extensionsContextOptions =
            options is null ?
                new()
                {
                    AdditionalInstructions = mergedAdditionalInstructions,
                    Kernel = kernel,
                } :
                new(options)
                {
                    AdditionalInstructions = mergedAdditionalInstructions,
                    Kernel = kernel,
                };

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set responseAgent.UseImmutableKernel = true (this clones the kernel so provider tools can be added safely).
2. Alternatively, remove AIFunctions from the AIContextProviders if you must keep the shared mutable kernel.
3. Set the property at construction time before the first invoke so FinalizeInvokeOptionsAsync sees it.

Example fix

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

// after
var agent = new OpenAIResponseAgent(client) { UseImmutableKernel = true };
await agent.InvokeAsync(messages, thread);

// Enable immutable kernel before invoking when providers carry functions
if (thread.AIContextProviders.Any(p => p is { } /* exposes AIFunctions */))
{
    responseAgent.UseImmutableKernel = true;
}
await responseAgent.InvokeAsync(messages, thread);

When it happens

Trigger: Configuring an OpenAIResponseAgent whose AgentThread has AIContextProviders that return AIFunctions, and invoking it while agent.UseImmutableKernel is left at its default of false.

Common situations: Adding a tool/function provider to a thread and forgetting to enable immutable kernel; copying a working config from a single-agent setup into a shared-kernel service.

Related errors

• OpenAIResponseAgent is not for use with AgentChat.
• Please provide an Azure OpenAI Responses deployment name
• AZURE_OPENAI_ENDPOINT is not set.
• AZURE_OPENAI_ENDPOINT is not set.
• AZURE_OPENAI_ENDPOINT is not set.

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