Azure OpenAI SDK Acceptance Criteria (.NET)

SDK: Azure.AI.OpenAIRepository: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/openai/Azure.AI.OpenAINuGet Package: https://www.nuget.org/packages/Azure.AI.OpenAIPurpose: Skill testing acceptance criteria for validating generated code correctness

---

1. Imports

1.1 ✅ CORRECT: Client Imports

using Azure.AI.OpenAI;
using OpenAI.Chat;
using Azure.Identity;

1.2 ✅ CORRECT: Streaming Imports

using OpenAI.Chat;
// StreamingChatCompletionUpdate is in OpenAI.Chat namespace

1.3 ✅ CORRECT: Tool/Function Imports

using OpenAI.Chat;
using System.Text.Json;
// ChatTool, ChatToolCall, ToolChatMessage are in OpenAI.Chat namespace

1.4 ✅ CORRECT: Assistants API Imports

using OpenAI.Assistants;
// Assistants API is experimental - requires #pragma warning disable OPENAI001

1.5 ❌ INCORRECT: Wrong import paths

// WRONG - using old Azure.AI.OpenAI namespaces for chat models
using Azure.AI.OpenAI.Chat;

// WRONG - ChatCompletionsClient doesn't exist in current SDK
using Azure.AI.OpenAI;
var client = new ChatCompletionsClient(...);

// WRONG - mixing OpenAI and Azure.AI.OpenAI incorrectly
using OpenAI;
var client = new OpenAI.OpenAIClient(...); // Different from AzureOpenAIClient

---

2. Authentication

2.1 ✅ CORRECT: DefaultAzureCredential (Recommended)

AzureOpenAIClient azureClient = new(
    new Uri("https://your-resource.openai.azure.com"),
    new DefaultAzureCredential());

ChatClient chatClient = azureClient.GetChatClient("my-gpt-4o-deployment");

2.2 ✅ CORRECT: API Key Credential

string apiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")
    ?? throw new InvalidOperationException("AZURE_OPENAI_API_KEY not set");

AzureOpenAIClient azureClient = new(
    new Uri("https://your-resource.openai.azure.com"),
    new ApiKeyCredential(apiKey));

ChatClient chatClient = azureClient.GetChatClient("my-gpt-4o-deployment");

2.3 ✅ CORRECT: Environment Variables for Configuration

string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT not set");
string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT not set");

AzureOpenAIClient azureClient = new(new Uri(endpoint), new DefaultAzureCredential());
ChatClient chatClient = azureClient.GetChatClient(deploymentName);

2.4 ❌ INCORRECT: Hardcoded credentials

// WRONG - hardcoded API key
AzureOpenAIClient azureClient = new(
    new Uri("https://my-resource.openai.azure.com"),
    new ApiKeyCredential("sk-hardcoded-key"));

// WRONG - hardcoded endpoint in production
AzureOpenAIClient azureClient = new(
    new Uri("https://production-resource.openai.azure.com"),
    new DefaultAzureCredential());

---

3. Chat Completions

3.1 ✅ CORRECT: Basic Chat Completion

AzureOpenAIClient azureClient = new(
    new Uri(endpoint),
    new DefaultAzureCredential());

ChatClient chatClient = azureClient.GetChatClient("gpt-4o-deployment");

ChatCompletion completion = chatClient.CompleteChat(
    [
        new SystemChatMessage("You are a helpful assistant."),
        new UserChatMessage("What is Azure OpenAI?"),
    ]);

Console.WriteLine($"{completion.Role}: {completion.Content[0].Text}");

3.2 ✅ CORRECT: Multi-turn Conversation

ChatCompletion completion = chatClient.CompleteChat(
    [
        new SystemChatMessage("You are a helpful assistant that talks like a pirate."),
        new UserChatMessage("Hi, can you help me?"),
        new AssistantChatMessage("Arrr! Of course, me hearty! What can I do for ye?"),
        new UserChatMessage("What's the best way to train a parrot?"),
    ]);

3.3 ❌ INCORRECT: Using wrong message types

// WRONG - using string array instead of ChatMessage types
var completion = chatClient.CompleteChat(new[] { "Hello", "How are you?" });

// WRONG - mixing old SDK patterns
var options = new ChatCompletionsOptions
{
    Messages = { new ChatMessage(ChatRole.User, "Hello") }
};

---

4. Streaming

4.1 ✅ CORRECT: Streaming Chat Completions

CollectionResult<StreamingChatCompletionUpdate> completionUpdates = chatClient.CompleteChatStreaming(
    [
        new SystemChatMessage("You are a helpful assistant."),
        new UserChatMessage("Write a short poem about Azure."),
    ]);

foreach (StreamingChatCompletionUpdate update in completionUpdates)
{
    foreach (ChatMessageContentPart contentPart in update.ContentUpdate)
    {
        Console.Write(contentPart.Text);
    }
}

4.2 ✅ CORRECT: Async Streaming

AsyncCollectionResult<StreamingChatCompletionUpdate> completionUpdates = 
    chatClient.CompleteChatStreamingAsync(
        [
            new SystemChatMessage("You are a helpful assistant."),
            new UserChatMessage("Tell me about cloud computing."),
        ]);

await foreach (StreamingChatCompletionUpdate update in completionUpdates)
{
    foreach (ChatMessageContentPart contentPart in update.ContentUpdate)
    {
        Console.Write(contentPart.Text);
    }
}

4.3 ❌ INCORRECT: Not handling streaming updates properly

// WRONG - treating streaming result as single response
var result = chatClient.CompleteChatStreaming([...]);
Console.WriteLine(result.Content); // Streaming doesn't work this way

---

5. Tool/Function Calling

5.1 ✅ CORRECT: Define Function Tool

ChatTool getCurrentWeatherTool = ChatTool.CreateFunctionTool(
    functionName: "get_current_weather",
    functionDescription: "Get the current weather in a given location",
    functionParameters: BinaryData.FromString("""
    {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city and state, e.g. Boston, MA"
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "The temperature unit to use"
            }
        },
        "required": ["location"]
    }
    """)
);

5.2 ✅ CORRECT: Handle Tool Calls

ChatCompletionOptions options = new()
{
    Tools = { getCurrentWeatherTool },
};

List<ChatMessage> messages =
    [
        new UserChatMessage("What's the weather like in Seattle?"),
    ];

ChatCompletion completion = chatClient.CompleteChat(messages, options);

if (completion.FinishReason == ChatFinishReason.ToolCalls)
{
    // Add the assistant message with tool calls to history
    messages.Add(new AssistantChatMessage(completion));
    
    foreach (ChatToolCall toolCall in completion.ToolCalls)
    {
        // Process the tool call and get result
        string result = ProcessToolCall(toolCall);
        
        // Add tool result to messages
        messages.Add(new ToolChatMessage(toolCall.Id, result));
    }
    
    // Continue the conversation with tool results
    completion = chatClient.CompleteChat(messages, options);
}

5.3 ✅ CORRECT: Streaming Tool Calls

StringBuilder contentBuilder = new();
StreamingChatToolCallsBuilder toolCallsBuilder = new();

foreach (StreamingChatCompletionUpdate update in chatClient.CompleteChatStreaming(messages, options))
{
    foreach (ChatMessageContentPart contentPart in update.ContentUpdate)
    {
        contentBuilder.Append(contentPart.Text);
    }
    
    foreach (StreamingChatToolCallUpdate toolCallUpdate in update.ToolCallUpdates)
    {
        toolCallsBuilder.Append(toolCallUpdate);
    }
}

IReadOnlyList<ChatToolCall> toolCalls = toolCallsBuilder.Build();

5.4 ❌ INCORRECT: Old function calling patterns

// WRONG - using deprecated Functions property
var options = new ChatCompletionOptions
{
    Functions = { ... } // Functions is deprecated, use Tools
};

---

6. Azure-Specific Features

6.1 ✅ CORRECT: On Your Data (Azure AI Search)

#pragma warning disable AOAI001

ChatCompletionOptions options = new();
options.AddDataSource(new AzureSearchChatDataSource()
{
    Endpoint = new Uri("https://your-search-resource.search.windows.net"),
    IndexName = "contoso-products-index",
    Authentication = DataSourceAuthentication.FromApiKey(
        Environment.GetEnvironmentVariable("AZURE_SEARCH_KEY")),
});

ChatCompletion completion = chatClient.CompleteChat(
    [
        new UserChatMessage("What are the best-selling Contoso products?"),
    ],
    options);

ChatMessageContext context = completion.GetMessageContext();
if (context?.Intent is not null)
{
    Console.WriteLine($"Intent: {context.Intent}");
}
foreach (ChatCitation citation in context?.Citations ?? [])
{
    Console.WriteLine($"Citation: {citation.Content}");
}

6.2 ✅ CORRECT: Government Cloud Configuration

AzureOpenAIClientOptions options = new()
{
    Audience = AzureOpenAIAudience.AzureGovernment,
};

AzureOpenAIClient azureClient = new(
    new Uri("https://your-resource.openai.azure.us"),
    new DefaultAzureCredential(),
    options);

---

7. Assistants API

7.1 ✅ CORRECT: Create and Use Assistants

#pragma warning disable OPENAI001

AssistantClient assistantClient = azureClient.GetAssistantClient();

Assistant assistant = await assistantClient.CreateAssistantAsync(
    model: "my-gpt-4o-deployment",
    new AssistantCreationOptions()
    {
        Name = "Math Tutor",
        Instructions = "You help with math problems. Use the code interpreter when needed.",
        Tools = { ToolDefinition.CreateCodeInterpreter() },
    });

ThreadInitializationMessage initialMessage = new(
    MessageRole.User,
    ["Calculate the factorial of 10"]);

AssistantThread thread = await assistantClient.CreateThreadAsync(new ThreadCreationOptions()
{
    InitialMessages = { initialMessage },
});

7.2 ✅ CORRECT: Stream Assistant Run

await foreach (StreamingUpdate update in assistantClient.CreateRunStreamingAsync(thread.Id, assistant.Id))
{
    if (update.UpdateKind == StreamingUpdateReason.RunCreated)
    {
        Console.WriteLine("--- Run started ---");
    }
    else if (update is MessageContentUpdate contentUpdate)
    {
        Console.Write(contentUpdate.Text);
    }
}

7.3 ✅ CORRECT: Cleanup Assistants Resources

// Delete resources when no longer needed
await assistantClient.DeleteAssistantAsync(assistant.Id);
await assistantClient.DeleteThreadAsync(thread.Id);

---

8. Embeddings

8.1 ✅ CORRECT: Generate Embeddings

EmbeddingClient embeddingClient = azureClient.GetEmbeddingClient("text-embedding-ada-002-deployment");

EmbeddingCollection embeddings = embeddingClient.GenerateEmbeddings(
    [
        "First text to embed",
        "Second text to embed",
    ]);

foreach (Embedding embedding in embeddings)
{
    ReadOnlyMemory<float> vector = embedding.ToFloats();
    Console.WriteLine($"Embedding dimensions: {vector.Length}");
}

---

9. Image Generation (DALL-E)

9.1 ✅ CORRECT: Generate Image

ImageClient imageClient = azureClient.GetImageClient("dall-e-3-deployment");

GeneratedImage image = imageClient.GenerateImage(
    "A futuristic cityscape with flying cars at sunset",
    new ImageGenerationOptions()
    {
        Size = GeneratedImageSize.W1024xH1024,
        Quality = GeneratedImageQuality.High,
    });

Console.WriteLine($"Image URL: {image.ImageUri}");

---

10. Error Handling

10.1 ✅ CORRECT: Handle API Errors

try
{
    ChatCompletion completion = await chatClient.CompleteChatAsync(messages);
}
catch (ClientResultException ex) when (ex.Status == 429)
{
    Console.WriteLine("Rate limited. Retry after delay.");
}
catch (ClientResultException ex)
{
    Console.WriteLine($"API error ({ex.Status}): {ex.Message}");
}

10.2 ❌ INCORRECT: Swallowing errors

// WRONG - empty catch block
try
{
    var completion = await chatClient.CompleteChatAsync(messages);
}
catch { }

---

11. Best Practices

11.1 ✅ CORRECT: Reuse Client Instances

public class OpenAIService
{
    private readonly ChatClient _chatClient;
    
    public OpenAIService(string endpoint, string deployment)
    {
        var azureClient = new AzureOpenAIClient(
            new Uri(endpoint),
            new DefaultAzureCredential());
        _chatClient = azureClient.GetChatClient(deployment);
    }
    
    public async Task<string> GetCompletionAsync(string prompt)
    {
        var completion = await _chatClient.CompleteChatAsync([new UserChatMessage(prompt)]);
        return completion.Value.Content[0].Text;
    }
}

11.2 ❌ INCORRECT: Creating clients per request

// WRONG - wasteful to create new client for each request
public async Task<string> GetCompletion(string prompt)
{
    var client = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
    var chatClient = client.GetChatClient(deployment);
    // ...
}