microsoft/autogen · error · InvalidOperationException

AZURE_OPENAI_CONNECTION_STRING not set, try something like A

Error message

AZURE_OPENAI_CONNECTION_STRING not set, try something like AZURE_OPENAI_CONNECTION_STRING = "Endpoint=https://TODO.openai.azure.com/;Key=TODO;Deployment=TODO"

What it means

Thrown by the HelloAIAgents sample when AZURE_OPENAI_CONNECTION_STRING is null. Note a quirk: the shipped Program.cs calls Environment.SetEnvironmentVariable with a literal 'TODO' placeholder right before the null check, so as-written the throw is dead code; the failure developers actually see is downstream auth errors from the placeholder values. The throw only fires if that hardcoded line is removed (as it should be) without setting a real connection string.

Source

Thrown at dotnet/samples/Hello/HelloAIAgents/Program.cs:17

// Copyright (c) Microsoft Corporation. All rights reserved.
// Program.cs

using Hello;
using Microsoft.AutoGen.Agents;
using Microsoft.AutoGen.Contracts;
using Microsoft.AutoGen.Core;

// send a message to the agent
var builder = new HostApplicationBuilder();
// put these in your environment or appsettings.json
builder.Configuration["HelloAIAgents:ModelType"] = "azureopenai";
builder.Configuration["HelloAIAgents:LlmModelName"] = "gpt-3.5-turbo";
Environment.SetEnvironmentVariable("AZURE_OPENAI_CONNECTION_STRING", "Endpoint=https://TODO.openai.azure.com/;Key=TODO;Deployment=TODO");
if (Environment.GetEnvironmentVariable("AZURE_OPENAI_CONNECTION_STRING") == null)
{
    throw new InvalidOperationException("AZURE_OPENAI_CONNECTION_STRING not set, try something like AZURE_OPENAI_CONNECTION_STRING = \"Endpoint=https://TODO.openai.azure.com/;Key=TODO;Deployment=TODO\"");
}
builder.Configuration["ConnectionStrings:HelloAIAgents"] = Environment.GetEnvironmentVariable("AZURE_OPENAI_CONNECTION_STRING");
builder.AddChatCompletionService("HelloAIAgents");
var _ = new AgentTypes(new Dictionary<string, Type>
{
    { "HelloAIAgents", typeof(HelloAIAgent) }
});
var local = true;
if (Environment.GetEnvironmentVariable("AGENT_HOST") != null) { local = false; }
var app = await Microsoft.AutoGen.Core.Grpc.AgentsApp.PublishMessageAsync("HelloAgents", new NewMessageReceived
{
    Message = "World"
}, local: local).ConfigureAwait(false);
await app.WaitForShutdownAsync();

namespace Hello
{
    [TopicSubscription("HelloAgents")]

View on GitHub (pinned to 027ecf0a37)

Solutions

Remove the Environment.SetEnvironmentVariable placeholder line and set a real AZURE_OPENAI_CONNECTION_STRING='Endpoint=https://<your-res>.openai.azure.com/;Key=<your-key>;Deployment=<your-deployment>' in the environment or appsettings.json.
If you keep the env var approach, verify it parses: it must contain Endpoint, Key and Deployment segments separated by ';'.
Confirm the deployment name exists on the Azure OpenAI resource (Deployments blade) and the key is a valid Key1/Key2.
Check builder.Configuration['ConnectionStrings:HelloAIAgents'] is populated before calling AddChatCompletionService.

Example fix

// before
Environment.SetEnvironmentVariable("AZURE_OPENAI_CONNECTION_STRING", "Endpoint=https://TODO.openai.azure.com/;Key=TODO;Deployment=TODO");
if (Environment.GetEnvironmentVariable("AZURE_OPENAI_CONNECTION_STRING") == null) { throw ... }

// after
var cs = Environment.GetEnvironmentVariable("AZURE_OPENAI_CONNECTION_STRING")
    ?? builder.Configuration.GetConnectionString("HelloAIAgents")
    ?? throw new InvalidOperationException("Set AZURE_OPENAI_CONNECTION_STRING='Endpoint=https://<res>.openai.azure.com/;Key=<key>;Deployment=<dep>'");
builder.Configuration["ConnectionStrings:HelloAIAgents"] = cs;

Defensive patterns

Strategy: validation

Validate before calling

var cs = Environment.GetEnvironmentVariable("AZURE_OPENAI_CONNECTION_STRING");
if (string.IsNullOrWhiteSpace(cs) || cs.Contains("TODO"))
{
    Console.Error.WriteLine("Set AZURE_OPENAI_CONNECTION_STRING='Endpoint=https://<res>.openai.azure.com/;Key=<key>;Deployment=<dep>'");
    return;
}
foreach (var part in new[] { "Endpoint=", "Key=", "Deployment=" })
    if (!cs.Contains(part)) { Console.Error.WriteLine($"Connection string missing '{part}' segment."); return; }

Try / catch

try { var app = await AgentsApp.PublishMessageAsync(...); } catch (Exception ex) when (ex.Message.Contains("AZURE_OPENAI_CONNECTION_STRING") || ex is InvalidOperationException) { Console.Error.WriteLine($"Configuration error: {ex.Message}"); }

Prevention

Remove placeholder SetEnvironmentVariable lines from samples before running them; placeholders cause confusing downstream auth errors instead of this clear throw.
Validate the connection-string shape (Endpoint/Key/Deployment segments) at startup.
Prefer appsettings.json ConnectionStrings over Environment.SetEnvironmentVariable in sample code.

When it happens

Trigger: Deleting/replace the placeholder SetEnvironmentVariable line in the sample but not providing AZURE_OPENAI_CONNECTION_STRING in the environment or appsettings.json; format must be 'Endpoint=https://<res>.openai.azure.com/;Key=<key>;Deployment=<dep>'.

Common situations: User runs the sample unmodified and sends 'Endpoint=https://TODO...' to Azure, getting 401/404 instead; user removes the placeholder but has a malformed connection string (missing Deployment segment); confusion between AGENT_HOST (enables gRPC runtime) and the AI connection string.

Related errors

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