Environment:Microsoft Semantic kernel OpenAI API Environment

Knowledge Sources	Semantic Kernel OpenAI API Reference Azure OpenAI Docs
Domains	Infrastructure, AI_Services
Last Updated	2026-02-11 20:00 GMT

Overview

Credential and configuration environment for connecting Semantic Kernel to OpenAI, Azure OpenAI, and other AI provider APIs.

Description

This environment defines the API keys, endpoints, and configuration values required to connect Semantic Kernel to external AI services. The SDK supports multiple configuration methods: environment variables with double-underscore hierarchy separators, .NET User Secrets for development, appsettings.json configuration files, and direct constructor parameters. All AI connectors in Semantic Kernel depend on valid credentials being available at runtime.

The OpenAI connector requires at minimum an API key and model ID. The Azure OpenAI connector additionally requires an endpoint URL and deployment name. Other providers (Google Gemini, HuggingFace, Amazon Bedrock, Mistral AI) have their own credential requirements.

Usage

Use this environment for any Semantic Kernel workflow that communicates with an external AI service. This includes chat completion, embedding generation, image generation, and audio transcription. Without valid credentials, all AI-dependent implementations will fail with authentication errors.

System Requirements

Category	Requirement	Notes
Network	Internet access	Required for API calls to OpenAI, Azure, and other cloud AI services
OS	Any	No OS-specific requirements beyond those in the base .NET SDK environment

Dependencies

NuGet Packages (per provider)

OpenAI: Microsoft.SemanticKernel.Connectors.OpenAI (depends on OpenAI >= 2.7.0)
Azure OpenAI: Microsoft.SemanticKernel.Connectors.AzureOpenAI (depends on Azure.AI.OpenAI >= 2.7.0-beta.2, Azure.Identity >= 1.17.1)
Google Gemini: Microsoft.SemanticKernel.Connectors.Google (depends on Google.GenAI >= 0.11.0)
HuggingFace: Microsoft.SemanticKernel.Connectors.HuggingFace
Mistral AI: Microsoft.SemanticKernel.Connectors.MistralAI
Amazon Bedrock: Microsoft.SemanticKernel.Connectors.Amazon (depends on AWSSDK.BedrockRuntime >= 4.0.14.5)
Ollama (local): OllamaSharp >= 5.4.12

Credentials

The following environment variables or configuration keys must be set depending on the AI provider used:

OpenAI

OpenAI__ApiKey or OPENAI_API_KEY: OpenAI API key (required)
OpenAI__ModelId or OPENAI_MODEL: Model name, e.g. gpt-4o (optional, defaults vary)
OpenAI__OrgId: Organization ID (optional)

Azure OpenAI

AzureOpenAI__Endpoint or AZURE_OPENAI_ENDPOINT: Service endpoint URL (required)
AzureOpenAI__ChatDeploymentName or AZURE_OPENAI_DEPLOYMENT_NAME: Deployment name (required)
AzureOpenAI__ApiKey: API key (required unless using Azure Identity)

Azure AI Foundry

AZURE_FOUNDRY_PROJECT_ENDPOINT: Azure AI Foundry project endpoint (required)
AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME: Deployment name (optional, defaults to gpt-4o)

Other Providers

HuggingFace__ApiKey: HuggingFace API token
Bing__ApiKey: Bing Web Search API key (for search plugins)
Postgres__ConnectionString: PostgreSQL connection string (for vector store)

WARNING: Never commit actual API keys or secrets to source control. Use .NET User Secrets or environment variables for development.

Quick Install

# Install the OpenAI connector package
dotnet add package Microsoft.SemanticKernel.Connectors.OpenAI

# Set credentials via .NET User Secrets (recommended for development)
dotnet user-secrets init
dotnet user-secrets set "OpenAI:ApiKey" "sk-your-key-here"
dotnet user-secrets set "OpenAI:ModelId" "gpt-4o"

# Or via environment variables (double underscore for hierarchy)
export OpenAI__ApiKey="sk-your-key-here"
export OpenAI__ModelId="gpt-4o"

# For Azure OpenAI
dotnet add package Microsoft.SemanticKernel.Connectors.AzureOpenAI
dotnet user-secrets set "AzureOpenAI:Endpoint" "https://your-service.openai.azure.com"
dotnet user-secrets set "AzureOpenAI:ChatDeploymentName" "gpt-4o"
dotnet user-secrets set "AzureOpenAI:ApiKey" "your-azure-key"

Code Evidence

Service registration pattern from dotnet/samples/GettingStarted/Step1_Create_Kernel.cs:

IKernelBuilder builder = Kernel.CreateBuilder();
builder.AddOpenAIChatClient(
    modelId: "gpt-4o",
    apiKey: "your-api-key");
Kernel kernel = builder.Build();

Custom HttpClient retry policy from dotnet/src/Connectors/Connectors.OpenAI/Core/ClientCore.cs:214-215:

options.RetryPolicy = new ClientRetryPolicy(maxRetries: 0); // Disable retry policy if and only if a custom HttpClient is provided.
options.NetworkTimeout = Timeout.InfiniteTimeSpan; // Disable default timeout

Common Errors

Error Message	Cause	Solution
`AuthenticationError: Incorrect API key provided`	Invalid or expired OpenAI API key	Verify `OpenAI__ApiKey` is correctly set
`401 Unauthorized`	Missing or invalid Azure OpenAI credentials	Check endpoint URL, deployment name, and API key
`HttpRequestException: No such host is known`	Incorrect Azure OpenAI endpoint	Verify the `AzureOpenAI__Endpoint` URL format
`The model 'X' does not exist`	Wrong model or deployment name	Use exact model ID (e.g., `gpt-4o`) or Azure deployment name

Compatibility Notes

Azure Identity: When using Azure.Identity (e.g., DefaultAzureCredential), the API key is not required. This is recommended for production Azure deployments.
Ollama: Runs locally and does not require cloud API keys. Requires a local Ollama installation.
Multiple providers: Semantic Kernel supports registering multiple AI services simultaneously and selecting between them via service IDs.
User Secrets: The recommended approach for local development. Configuration hierarchy: environment variables override appsettings.json, which overrides User Secrets.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment