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.

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.

Appendix: 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)