Azure AI Provider

Provider Key: azure-ai

Overview

The Azure AI provider enables HPD-Agent to use Microsoft Azure OpenAI models and Azure AI Foundry deployments. Built on Microsoft's modern Azure AI stack, it provides enterprise-grade security, OAuth authentication, and seamless integration with Azure's AI infrastructure.

Key Features:

Azure OpenAI models
Azure AI Foundry/Projects support
OAuth/Entra ID authentication (DefaultAzureCredential)
API key authentication (traditional Azure OpenAI)
Streaming support for real-time responses
Function/tool calling capabilities
Vision support (GPT-4 Vision models)
Structured JSON output with schema validation
Deterministic generation with seed support

For detailed API documentation, see:

AzureAIProviderConfig API Reference - Complete property listing

Quick Start

Minimal Example (OAuth Authentication)

csharp

using HPD.Agent;
using HPD.Agent.Providers.AzureAI;

// Authenticate via Azure CLI
// Run: az login

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4")
    .Build();

var response = await agent.RunAsync("What is the capital of France?");
Console.WriteLine(response);

Minimal Example (API Key Authentication)

csharp

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4",
        apiKey: "your-api-key")
    .Build();

Installation

bash

dotnet add package HPD-Agent.Providers.AzureAI

Dependencies:

Azure.AI.Projects - Azure AI Projects SDK
Azure.AI.OpenAI - Azure OpenAI client library
Azure.Identity - DefaultAzureCredential for OAuth
Microsoft.Extensions.AI.OpenAI - IChatClient integration

Configuration

Configuration Patterns

The Azure AI provider supports all three configuration patterns. Choose the one that best fits your needs.

1. Builder Pattern (Fluent API)

Best for: Simple configurations and quick prototyping.

csharp

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4",
        configure: opts =>
        {
            opts.MaxTokens = 4096;
            opts.Temperature = 0.7f;
            opts.TopP = 0.9f;
            opts.UseDefaultAzureCredential = true; // OAuth authentication
        })
    .Build();

2. Config Pattern (Data-Driven)

Best for: Serialization, persistence, and configuration files.

C# Config Object:

csharp

var config = new AgentConfig
{
    Name = "AzureAIAgent",
    Provider = new ProviderConfig
    {
        ProviderKey = "azure-ai",
        ModelName = "gpt-4",
        Endpoint = "https://my-resource.openai.azure.com"
    }
};

var azureOpts = new AzureAIProviderConfig
{
    MaxTokens = 4096,
    Temperature = 0.7f,
    TopP = 0.9f,
    UseDefaultAzureCredential = true
};
config.Provider.SetTypedProviderConfig(azureOpts);

var agent = await config.BuildAsync();

JSON Config File:

json

{
    "Name": "AzureAIAgent",
    "Provider": {
        "ProviderKey": "azure-ai",
        "ModelName": "gpt-4",
        "Endpoint": "https://my-resource.openai.azure.com",
        "ProviderOptionsJson": "{\"maxTokens\":4096,\"temperature\":0.7,\"topP\":0.9,\"useDefaultAzureCredential\":true}"
    }
}

csharp

var agent = await AgentConfig
    .BuildFromFileAsync("azure-config.json");

3. Builder + Config Pattern (Recommended)

Best for: Production deployments with reusable configuration and runtime customization.

csharp

// Define base config once
var config = new AgentConfig
{
    Name = "AzureAIAgent",
    Provider = new ProviderConfig
    {
        ProviderKey = "azure-ai",
        ModelName = "gpt-4",
        Endpoint = "https://my-resource.openai.azure.com"
    }
};

var azureOpts = new AzureAIProviderConfig
{
    MaxTokens = 4096,
    Temperature = 0.7f,
    UseDefaultAzureCredential = true
};
config.Provider.SetTypedProviderConfig(azureOpts);

// Reuse with different runtime customizations
var agent1 = new AgentBuilder(config)
    .WithServiceProvider(services)
    .WithToolkit<MathToolkit>()
    .Build();

var agent2 = new AgentBuilder(config)
    .WithServiceProvider(services)
    .WithToolkit<FileToolkit>()
    .Build();

Provider-Specific Options

The AzureAIProviderConfig class provides comprehensive configuration options organized by category:

Core Parameters

csharp

configure: opts =>
{
    // Maximum tokens to generate (default: 4096)
    opts.MaxTokens = 4096;

    // Sampling temperature (0.0-2.0, default: 1.0)
    opts.Temperature = 0.7f;

    // Top-P nucleus sampling (0.0-1.0)
    opts.TopP = 0.9f;

    // Stop sequences
    opts.StopSequences = new List<string> { "STOP", "END" };
}

Sampling & Penalties

csharp

configure: opts =>
{
    // Frequency penalty (-2.0 to 2.0)
    // Reduces repetition of tokens based on their frequency
    opts.FrequencyPenalty = 0.5f;

    // Presence penalty (-2.0 to 2.0)
    // Encourages new topics by penalizing any repeated token
    opts.PresencePenalty = 0.5f;
}

Deterministic Generation

csharp

configure: opts =>
{
    // Seed for reproducible outputs
    opts.Seed = 12345;

    // Use with temperature = 0 for maximum determinism
    opts.Temperature = 0.0f;
}

Structured JSON Output

csharp

configure: opts =>
{
    // Option 1: Loose JSON mode
    opts.ResponseFormat = "json_object";

    // Option 2: Strict schema validation
    opts.ResponseFormat = "json_schema";
    opts.JsonSchemaName = "UserResponse";
    opts.JsonSchema = @"{
        ""type"": ""object"",
        ""properties"": {
            ""name"": { ""type"": ""string"" },
            ""age"": { ""type"": ""number"" }
        },
        ""required"": [""name"", ""age""]
    }";
    opts.JsonSchemaIsStrict = true;
}

Tool/Function Calling

csharp

configure: opts =>
{
    // Tool choice behavior: "auto" (default), "none", "required"
    opts.ToolChoice = "auto";
}

Azure-Specific Configuration

csharp

configure: opts =>
{
    // Use OAuth/Entra ID authentication (recommended for production)
    opts.UseDefaultAzureCredential = true;

    // Azure AI Project ID (optional - extracted from endpoint if not provided)
    opts.ProjectId = "my-project";
}

Authentication

Azure AI supports two authentication methods with automatic fallback.

Authentication Priority Order

OAuth/Entra ID (if UseDefaultAzureCredential = true or no API key provided)
API Key (if provided via config, environment, or appsettings)

Method 1: OAuth/Entra ID

OAuth provides enhanced security, automatic token rotation, and enterprise identity integration.

Prerequisites

Install Azure CLI:

bash

# macOS
brew install azure-cli

# Windows
winget install Microsoft.AzureCLI

# Linux
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

Local Development (Azure CLI)

bash

# Login to Azure
az login

# (Optional) Set default subscription
az account set --subscription "your-subscription-id"

csharp

// Automatically uses Azure CLI credentials
var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4",
        configure: opts => opts.UseDefaultAzureCredential = true)
    .Build();

Production (Managed Identity)

When running on Azure infrastructure (App Service, Functions, AKS, etc.):

csharp

// Automatically uses Managed Identity - no credentials needed
var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4",
        configure: opts => opts.UseDefaultAzureCredential = true)
    .Build();

DefaultAzureCredential Chain

DefaultAzureCredential tries authentication methods in this order:

Environment variables - Service principal credentials
Workload Identity - Kubernetes workload identity
Managed Identity - Azure-hosted applications
Visual Studio - Local development (Windows)
VS Code - Local development
Azure CLI - Local development (cross-platform)
Azure PowerShell - Local development
Interactive Browser - Fallback for local development

Method 2: API Key Authentication

Environment Variables

bash

export AZURE_AI_ENDPOINT="https://my-resource.openai.azure.com"
export AZURE_AI_API_KEY="your-api-key"

csharp

// Automatically uses environment variables
var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: Environment.GetEnvironmentVariable("AZURE_AI_ENDPOINT"),
        model: "gpt-4")
    .Build();

Configuration File (appsettings.json)

json

{
    "AzureAI": {
        "Endpoint": "https://my-resource.openai.azure.com",
        "ApiKey": "your-api-key"
    }
}

csharp

var config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: config["AzureAI:Endpoint"],
        model: "gpt-4",
        apiKey: config["AzureAI:ApiKey"])
    .Build();

Explicit API Key

csharp

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4",
        apiKey: "your-api-key")
    .Build();

Security Warning: Never hardcode API keys in source code. Use environment variables, Azure Key Vault, or Managed Identity instead.

Endpoint Types

The Azure AI provider supports two types of endpoints with automatic detection.

Azure AI Foundry / Projects

Modern Azure AI platform with centralized model management and OAuth authentication.

Endpoint Format:

https://<account>.services.ai.azure.com/api/projects/<project-name>

Example:

csharp

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-account.services.ai.azure.com/api/projects/my-project",
        model: "gpt-4",
        configure: opts => opts.UseDefaultAzureCredential = true)
    .Build();

Features:

OAuth/Entra ID authentication required
Centralized project management
Access to Azure AI Foundry resources
Unified endpoint for multiple models
API key authentication not supported

Traditional Azure OpenAI

Classic Azure OpenAI Service endpoints.

Endpoint Format:

https://<resource-name>.openai.azure.com

Example:

csharp

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4",
        apiKey: "your-api-key")
    .Build();

Features:

API key authentication supported
OAuth/Entra ID authentication supported
Direct resource access
Backward compatibility

Supported Models

Azure AI provides access to OpenAI models through Azure's infrastructure.

Common Models

Model ID	Description	Context Window	Best For
`gpt-4o`	GPT-4 Omni	128K tokens	Most capable, multimodal
`gpt-4o-mini`	GPT-4 Omni Mini	128K tokens	Fast, cost-effective
`gpt-4-turbo`	GPT-4 Turbo	128K tokens	Advanced reasoning
`gpt-4`	GPT-4	8K tokens	Original GPT-4
`gpt-4-32k`	GPT-4 32K	32K tokens	Extended context
`gpt-35-turbo`	GPT-3.5 Turbo	16K tokens	Fast, cost-effective

Model Naming

In Azure, you deploy models with custom deployment names:

Deployment Name vs Model ID:

csharp

// Use your deployment name, not the model ID
.WithAzureAI(
    endpoint: "https://my-resource.openai.azure.com",
    model: "my-gpt4-deployment",  // ← Your custom deployment name
    ...)

Finding Deployment Names:

Azure Portal → Azure OpenAI resource → Model deployments
Azure AI Foundry → Your project → Deployments

Advanced Features

Structured Outputs with JSON Schema

Force the model to generate JSON matching a specific schema.

csharp

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4",
        configure: opts =>
        {
            opts.ResponseFormat = "json_schema";
            opts.JsonSchemaName = "ContactInfo";
            opts.JsonSchema = @"{
                ""type"": ""object"",
                ""properties"": {
                    ""name"": { ""type"": ""string"" },
                    ""email"": { ""type"": ""string"", ""format"": ""email"" },
                    ""phone"": { ""type"": ""string"" }
                },
                ""required"": [""name"", ""email""],
                ""additionalProperties"": false
            }";
            opts.JsonSchemaIsStrict = true;
        })
    .Build();

var response = await agent.RunAsync("Extract contact info: John Doe, john@example.com");
// Response will be valid JSON matching the schema

Deterministic Generation

Generate reproducible outputs for testing and debugging.

csharp

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4",
        configure: opts =>
        {
            opts.Seed = 12345; // Same seed = same output
            opts.Temperature = 0.0f; // Remove randomness
        })
    .Build();

// Will always generate the same response for the same input
var response1 = await agent.RunAsync("Write a haiku about code");
var response2 = await agent.RunAsync("Write a haiku about code");
// response1 == response2 (with high probability)

Vision Capabilities

Use GPT-4 Vision models to analyze images.

csharp

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4o") // Vision-capable model
    .Build();

var response = await agent.RunAsync(
    "What objects are in this image?",
    imageUrl: "https://example.com/image.jpg");

Function Calling with Tools

csharp

public class WeatherToolkit
{
    [AIFunction("Get current weather for a location")]
    public string GetWeather(string location)
    {
        return $"Weather in {location}: Sunny, 72°F";
    }
}

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4",
        configure: opts => opts.ToolChoice = "auto")
    .WithToolkit<WeatherToolkit>()
    .Build();

var response = await agent.RunAsync("What's the weather in Paris?");

Error Handling

The Azure AI provider includes intelligent error classification and automatic retry logic.

Error Categories

Category	HTTP Status	Retry Behavior	Examples
AuthError	401, 403	No retry	Invalid credentials, insufficient permissions
RateLimitRetryable	429	Exponential backoff	Quota exceeded, throttling
ClientError	400, 404	No retry	Invalid request, deployment not found
Transient	503	Retry	Service unavailable, timeout
ServerError	500-599	Retry	Internal server error

Common Exceptions

DeploymentNotFound (404)

The API deployment for this resource does not exist.

Solution:

Verify deployment name matches exactly in Azure Portal
Wait 2-5 minutes if just created
Check deployment is in correct resource/project

AccessDeniedException (401/403)

Authentication failed or insufficient permissions.

Solution:

For OAuth: Run az login or verify Managed Identity
For API key: Verify key is correct and not expired
Check Azure RBAC permissions include Cognitive Services OpenAI User role

RateLimitException (429)

Rate limit exceeded - requests throttled.

Solution: Automatically retried with exponential backoff. If persistent:

Request quota increase in Azure Portal
Use multiple deployments for load distribution
Implement request rate limiting

InvalidRequestException (400)

Validation error in request parameters.

Solution:

Check parameter ranges (temperature, top_p, etc.)
Verify JSON schema format
Ensure model supports requested features

Examples

Example 1: Basic Chat

csharp

using HPD.Agent;
using HPD.Agent.Providers.AzureAI;

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4",
        configure: opts => opts.UseDefaultAzureCredential = true)
    .Build();

var response = await agent.RunAsync("Explain quantum computing simply.");
Console.WriteLine(response);

Example 2: Streaming Responses

csharp

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4")
    .Build();

await foreach (var chunk in agent.RunAsync("Write a story about AI."))
{
    Console.Write(chunk);
}

Example 3: Function Calling

csharp

public class CalculatorToolkit
{
    [AIFunction("Add two numbers")]
    public double Add(double a, double b) => a + b;

    [AIFunction("Multiply two numbers")]
    public double Multiply(double a, double b) => a * b;
}

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4",
        configure: opts => opts.ToolChoice = "auto")
    .WithToolkit<CalculatorToolkit>()
    .Build();

var response = await agent.RunAsync("What is 25 * 4 + 10?");

Example 4: Structured Output

csharp

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-resource.openai.azure.com",
        model: "gpt-4",
        configure: opts =>
        {
            opts.ResponseFormat = "json_schema";
            opts.JsonSchemaName = "MovieReview";
            opts.JsonSchema = @"{
                ""type"": ""object"",
                ""properties"": {
                    ""title"": { ""type"": ""string"" },
                    ""rating"": { ""type"": ""number"", ""minimum"": 0, ""maximum"": 10 },
                    ""summary"": { ""type"": ""string"" },
                    ""recommendation"": { ""type"": ""boolean"" }
                },
                ""required"": [""title"", ""rating"", ""summary"", ""recommendation""]
            }";
            opts.JsonSchemaIsStrict = true;
        })
    .Build();

var response = await agent.RunAsync("Review the movie Inception.");
// Returns structured JSON matching the schema

Example 5: Multi-Region Deployment

csharp

var config = new AgentConfig
{
    Provider = new ProviderConfig
    {
        ProviderKey = "azure-ai",
        ModelName = "gpt-4"
    }
};

// Primary region
var primaryAgent = new AgentBuilder(config)
    .WithAzureAI(
        endpoint: "https://eastus-resource.openai.azure.com",
        model: "gpt-4")
    .Build();

// Failover region
var failoverAgent = new AgentBuilder(config)
    .WithAzureAI(
        endpoint: "https://westus-resource.openai.azure.com",
        model: "gpt-4")
    .Build();

try
{
    var response = await primaryAgent.RunAsync(message);
}
catch
{
    var response = await failoverAgent.RunAsync(message);
}

Example 6: Azure AI Foundry with Projects

csharp

var agent = await new AgentBuilder()
    .WithAzureAI(
        endpoint: "https://my-account.services.ai.azure.com/api/projects/my-project",
        model: "gpt-4",
        configure: opts =>
        {
            opts.UseDefaultAzureCredential = true;
            opts.MaxTokens = 4096;
            opts.Temperature = 0.7f;
        })
    .Build();

var response = await agent.RunAsync("Analyze this data...");

Troubleshooting

"Endpoint is required for Azure AI"

Problem: Missing endpoint configuration.

Solution:

csharp

// Option 1: Explicit endpoint
.WithAzureAI(endpoint: "https://my-resource.openai.azure.com", ...)

// Option 2: Environment variable
Environment.SetEnvironmentVariable("AZURE_AI_ENDPOINT", "https://...");

// Option 3: appsettings.json
{ "AzureAI": { "Endpoint": "https://..." } }

"DefaultAzureCredential failed to retrieve a token"

Problem: No authentication method available.

Solution: Install Azure CLI and login:

bash

brew install azure-cli  # or: winget install Microsoft.AzureCLI
az login

"Azure AI Foundry/Projects endpoints require OAuth"

Problem: Trying to use API key with Azure AI Foundry endpoint.

Solution: Azure AI Foundry only supports OAuth:

csharp

configure: opts => opts.UseDefaultAzureCredential = true
// OR remove the API key and it will automatically use OAuth

"HTTP 404 (DeploymentNotFound)"

Problem: Deployment name doesn't exist or not ready.

Solution:

Verify deployment name in Azure Portal (case-sensitive!)
Wait 2-5 minutes if just created
Check you're using the correct endpoint for the deployment

"Temperature must be between 0 and 2"

Problem: Invalid temperature value.

Solution:

csharp

opts.Temperature = 0.7f  // Valid (0.0-2.0)
// NOT: opts.Temperature = 3.0f  //  Invalid

"AzureCliCredential authentication failed: Azure CLI not installed"

Problem: Azure CLI not installed for OAuth authentication.

Solution: Install Azure CLI:

bash

# macOS
brew install azure-cli

# Windows
winget install Microsoft.AzureCLI

# Linux
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

Then login:

bash

az login