What causes "Please set OPENAI_API_KEY environment variable." in microsoft/autogen?

Export OPENAI_API_KEY before running the snippet.

microsoft/autogen · error · Exception

Please set OPENAI_API_KEY environment variable.

Error message

Please set OPENAI_API_KEY environment variable.

What it means

Guard in SemanticKernelCodeSnippet.CreateSemanticKernelAgentAsync: OPENAI_API_KEY is null, so it throws before Kernel.CreateBuilder().AddOpenAIChatCompletion(...) is given an empty key. The Semantic Kernel path still consumes an OpenAI key, which surprises developers who expected a separate SK credential.

Source

Thrown at dotnet/samples/AgentChat/AutoGen.Basic.Sample/CodeSnippet/SemanticKernelCodeSnippet.cs:22

using AutoGen.Core;
using AutoGen.SemanticKernel;
using AutoGen.SemanticKernel.Extension;
using FluentAssertions;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;

namespace AutoGen.Basic.Sample.CodeSnippet;

public class SemanticKernelCodeSnippet
{
    public async Task<string> GetWeather(string location)
    {
        return "The weather in " + location + " is sunny.";
    }
    public async Task CreateSemanticKernelAgentAsync()
    {
        #region create_semantic_kernel_agent
        var openAIKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new Exception("Please set OPENAI_API_KEY environment variable.");
        var modelId = "gpt-3.5-turbo";
        var builder = Kernel.CreateBuilder()
           .AddOpenAIChatCompletion(modelId: modelId, apiKey: openAIKey);
        var kernel = builder.Build();

        // create a semantic kernel agent
        var semanticKernelAgent = new SemanticKernelAgent(
            kernel: kernel,
            name: "assistant",
            systemMessage: "You are an assistant that help user to do some tasks.");

        // SemanticKernelAgent supports the following message types:
        // - IMessage<ChatMessageContent> where ChatMessageContent is from Azure.AI.OpenAI

        var helloMessage = new ChatMessageContent(AuthorRole.User, "Hello");

        // Use MessageEnvelope.Create to create an IMessage<ChatRequestMessage>
        var chatMessageContent = MessageEnvelope.Create(helloMessage);

View on GitHub (pinned to 027ecf0a37)

Solutions

Export OPENAI_API_KEY before running the snippet.
If you intend to use Azure OpenAI with SK, switch to builder.AddAzureOpenAIChatCompletion(deployment, endpoint, azureKey) and set AZURE_OPENAI_API_KEY/AZURE_OPENAI_ENDPOINT instead.
Set the variable in CI secrets/launchSettings for test and IDE runs.
Restart the process after changing the environment.

Example fix

// before
builder.AddOpenAIChatCompletion(modelId: modelId, apiKey: openAIKey);

// after (Azure variant, when only Azure credentials exist)
builder.AddAzureOpenAIChatCompletion(
    deploymentName: deploymentName,
    endpoint: endpoint,   // from AZURE_OPENAI_ENDPOINT
    apiKey: azureKey);    // from AZURE_OPENAI_API_KEY

Defensive patterns

Strategy: validation

Validate before calling

var openAIKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY");
if (string.IsNullOrWhiteSpace(openAIKey))
{
    Console.Error.WriteLine("Semantic Kernel snippet uses OpenAI: set OPENAI_API_KEY (or switch to AddAzureOpenAIChatCompletion).");
    return;
}

Prevention

Remember AddOpenAIChatCompletion needs OPENAI_API_KEY even under Semantic Kernel.
For Azure, use AddAzureOpenAIChatCompletion with AZURE_OPENAI_* variables.
Centralize credential checks before building the Kernel.

When it happens

Trigger: Running the Semantic Kernel snippet without OPENAI_API_KEY, even though the agent is a SemanticKernelAgent — the underlying connector is OpenAI chat completion.

Common situations: Developer assumed Semantic Kernel uses its own auth or Azure key and didn't set the OpenAI one; Azure deployments should use AddAzureOpenAIChatCompletion instead, which needs different env vars.

Related errors

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/170aa6f0ac646b0d. Report an issue: GitHub.