microsoft/semantic-kernel · critical · InvalidOperationException

Please provide a valid `AzureAI:ConnectionString` secret to

Error message

Please provide a valid `AzureAI:ConnectionString` secret to run this sample. See the associated README.md for more details.

What it means

CreateAzureAIAgentAsync checks config["AzureAI:Endpoint"] and throws if it is not present. IMPORTANT discrepancy: the error message references `AzureAI:ConnectionString`, but the code actually checks `AzureAI:Endpoint`. So the message is misleading — supplying a ConnectionString alone will NOT satisfy this guard; you must supply an Endpoint. The agent is then created via AzureCliCredential using that endpoint.

Source

Thrown at dotnet/samples/Demos/ModelContextProtocolClientServer/MCPClient/Samples/AzureAIAgentWithMCPToolsSample.cs:93

    /// Creates an instance of <see cref="AzureAIAgent"/> with the specified name and instructions.
    /// </summary>
    /// <param name="kernel">The kernel instance.</param>
    /// <param name="name">The name of the agent.</param>
    /// <param name="instructions">The instructions for the agent.</param>
    /// <returns>An instance of <see cref="AzureAIAgent"/>.</returns>
    private static async Task<AzureAIAgent> CreateAzureAIAgentAsync(Kernel kernel, string name, string instructions)
    {
        // Load and validate configuration
        IConfigurationRoot config = new ConfigurationBuilder()
            .AddUserSecrets<Program>()
            .AddEnvironmentVariables()
            .Build();

        if (config["AzureAI:Endpoint"] is not { } endpoint)
        {
            const string Message = "Please provide a valid `AzureAI:ConnectionString` secret to run this sample. See the associated README.md for more details.";
            Console.Error.WriteLine(Message);
            throw new InvalidOperationException(Message);
        }

        string modelId = config["AzureAI:ChatModelId"] ?? "gpt-4o-mini";

        // Create the Azure AI Agent
        PersistentAgentsClient agentsClient = AzureAIAgent.CreateAgentsClient(endpoint, new AzureCliCredential());

        PersistentAgent agent = await agentsClient.Administration.CreateAgentAsync(modelId, name, null, instructions);

        return new AzureAIAgent(agent, agentsClient)
        {
            Kernel = kernel
        };
    }
}

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set AzureAI:Endpoint (the message's 'ConnectionString' reference is wrong — Endpoint is what is checked).
2. Report/fix the message-vs-key mismatch upstream so the hint is accurate.
3. Confirm an Azure CLI login exists since AzureCliCredential is used (`az login`).
4. Optionally set AzureAI:ChatModelId (defaults to gpt-4o-mini).

Example fix

// before (misleading message)
if (config["AzureAI:Endpoint"] is not { } endpoint)
{
    const string Message = "Please provide a valid `AzureAI:ConnectionString` secret...";
    throw new InvalidOperationException(Message);
}

// after (correct, accurate message)
if (config["AzureAI:Endpoint"] is not { } endpoint)
{
    const string Message = "Please provide a valid `AzureAI:Endpoint` secret to run this sample. See the associated README.md for more details.";
    Console.Error.WriteLine(Message);
    throw new InvalidOperationException(Message);
}

if (config["AzureAI:Endpoint"] is not { } endpoint)
    throw new InvalidOperationException(
        "Set AzureAI:Endpoint (note: the code checks Endpoint, NOT ConnectionString despite the message).");

static bool HasAzureAiEndpoint(IConfigurationRoot c) =>
    !string.IsNullOrEmpty(c["AzureAI:Endpoint"]);

When it happens

Trigger: config["AzureAI:Endpoint"] is null (the `is not { } endpoint` pattern fails). Even if AzureAI:ConnectionString is set, this still throws because the check is on Endpoint.

Common situations: User followed the message and set AzureAI:ConnectionString but not Endpoint; Azure AI project endpoint not copied from the portal; or env var uses the wrong key.

Related errors

• Configuration is not setup correctly.
• Please provide valid MSGraph configuration in appsettings.De
• Invalid kernel selection. {selectedKernelName} is not a vali
• Please provide valid Ollama configuration in appsettings.Dev
• Please provide valid AzureOpenAI configuration in appsetting

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