What causes "AZURE_OPENAI_ENDPOINT is not set." in microsoft/semantic-kernel?

Set AZURE_OPENAI_ENDPOINT in your environment before running

microsoft/semantic-kernel · error · InvalidOperationException

AZURE_OPENAI_ENDPOINT is not set.

Error message

AZURE_OPENAI_ENDPOINT is not set.

What it means

The Handoff Orchestration migration sample throws InvalidOperationException when AZURE_OPENAI_ENDPOINT is missing. This sample simulates a customer-service scenario with multiple specialized agents (order tracking, returns) that hand off conversations. The endpoint feeds AzureOpenAIChatClient construction with AzureCliCredential for both SK and AF comparison paths.

Source

Thrown at dotnet/samples/AgentFrameworkMigration/AgentOrchestrations/Step03_Handoff/Program.cs:19

// Copyright (c) Microsoft. All rights reserved.

#pragma warning disable MAAIW001 // Experimental: HandoffWorkflowBuilder

using System.ComponentModel;
using System.Text.Json;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.Agents.Orchestration;
using Microsoft.SemanticKernel.Agents.Orchestration.Handoff;
using Microsoft.SemanticKernel.Agents.Runtime.InProcess;
using Microsoft.SemanticKernel.ChatCompletion;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

// Queries to simulate user input during the interactive orchestration
List<string> Queries = [
    "I'd like to track the status of my first order 123.",
    "I want to return another order of mine whose ID is 456 because it arrived damaged.",
];

// This sample compares running handoff orchestrations using
// Semantic Kernel and the Agent Framework.
Console.WriteLine("=== Semantic Kernel Handoff Orchestration ===");
// State to help format the streaming output
bool newAgentTurn = true;
string previousFunctionCallId = string.Empty;
await SKHandoffOrchestration();

Console.WriteLine("\n=== Agent Framework Handoff Agent Workflow ===");
await AFHandoffAgentWorkflow();

View on GitHub (pinned to c028a0c7dc)

Solutions

Set AZURE_OPENAI_ENDPOINT in your environment before running
Optionally set AZURE_OPENAI_DEPLOYMENT_NAME (defaults to gpt-4o-mini)
If running from VS, add the variable to Properties/launchSettings.json under environmentVariables
Ensure az login is current for AzureCliCredential

Example fix

// before
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");

// after — load from launchSettings or user secrets as fallback
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException(
        "AZURE_OPENAI_ENDPOINT is not set. See README.md Environment Variables section.");

Defensive patterns

Strategy: validation

Validate before calling

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
if (string.IsNullOrWhiteSpace(endpoint))
{
    Console.Error.WriteLine("AZURE_OPENAI_ENDPOINT is not set. Required for handoff orchestration.");
    return;
}

Type guard

static bool IsAzureOpenAIEndpointConfigured() =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT"));

Try / catch

try
{
    var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
        ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
}
catch (InvalidOperationException ex) when (ex.Message.Contains("AZURE_OPENAI_ENDPOINT"))
{
    Console.Error.WriteLine(ex.Message);
    return;
}

Prevention

Configure env vars in launchSettings.json when running handoff samples from Visual Studio
Run az login before executing samples that rely on AzureCliCredential
Create a shared setup script for all AgentOrchestration samples since they share the same env var
Validate env vars in a guard method called at the top of Main

When it happens

Trigger: Running AgentOrchestrations/Step03_Handoff without AZURE_OPENAI_ENDPOINT. The throw at line 19 fires before the simulated Queries list and streaming output logic execute.

Common situations: New clone without environment setup; the handoff sample requires multiple agents so developers may assume it has a different setup process (it does not — same single endpoint variable); running from Visual Studio without project-level environment variables configured in launchSettings.json.

Related errors

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