AI-Powered Applications with .NET Fundamentals

AI-Powered Applications with .NET Fundamentals

13+

Move beyond AI prototypes. Build production-ready intelligent applications with .NET 10.

0 followers
22 chapters
Software & AI Development
2026

$49 a year. The paperback ships free with your first year.

Buying multiple copies? Request bulk pricing.
You're viewing a limited preview. Create a free account to read free books or get Premium to unlock the entire library.

Chapter 1: Introduction to AI-Powered Applications in .NET 10

What You Will Learn

  • Articulate the distinct responsibilities of Microsoft.Extensions.AI, Semantic Kernel, and Microsoft Agent Framework in a .NET 10 AI application
  • Map the Contoso Support Copilot domain entities to their architectural roles in a support workflow
  • Design interface boundaries that separate application logic from AI orchestration and agent coordination
  • Configure the foundational dependency injection structure for a multi-layered AI application using the three primary abstractions
  • Position Azure AI Foundry as the underlying infrastructure beneath the three-layer AI architecture

Prerequisites

No additional prerequisites beyond those listed in About This Book.

Concept Overview

Building AI-powered applications in .NET 10 requires a clear architectural strategy. The ecosystem offers three distinct capabilities. Microsoft.Extensions.AI provides foundational abstractions for chat clients, embedding generators, and structured output; each serves distinct interaction patterns with language models through a unified but granular interface surface. Semantic Kernel builds on this foundation to offer prompt orchestration, plugin management, and workflow composition. Microsoft Agent Framework 1.0 introduces agent contracts, handoff patterns, and multi-agent coordination for complex scenarios.

This book builds Contoso Support Copilot, an AI-powered customer support and knowledge assistant for a SaaS platform. The application helps customer support engineers triage tickets, search trusted product knowledge, draft grounded replies, summarize case history, and prepare escalations. It operates inside a support portal and maintains a clear boundary between AI-generated suggestions and human approval.

The domain model centers on entities such as SupportTicket, TicketMessage, CustomerAccount, KnowledgeArticle, and ArticleChunk. Support engineers interact with the copilot through a portal that orchestrates these entities through the three architectural layers. TicketMessage captures individual communications within a thread, while ArticleChunk represents vector-searchable segments of documentation. Azure AI Foundry hosts the GPT-5 models and embedding deployments that power the underlying intelligence, sitting below the abstraction layers as the infrastructure layer.

A critical architectural principle governs this design. Domain services must never depend directly on AI infrastructure concerns. Instead, application code depends on abstractions that isolate the specifics of model invocation, prompt templating, and agent coordination. This separation preserves testability, enables fallback behavior, and allows the infrastructure to evolve without destabilizing business logic. In production, I have seen teams conflate these layers; the result is always a brittle system that is difficult to test. Keep the boundaries strict.

Microsoft.Extensions.AI serves as the lowest-level abstraction that the application consumes directly for simple model interactions. Semantic Kernel sits above it, providing the orchestration engine for complex prompt workflows and plugin execution. Microsoft Agent Framework 1.0 (the Microsoft.Agents.AI package) operates at the highest level, supplying AIAgent, ChatClientAgent, AITool, and AgentThread to coordinate specialized agents that may invoke Semantic Kernel workflows. Azure AI Foundry remains the underlying infrastructure, hosting the models and providing the endpoint connectivity.

The IAgent and IAgentCoordinator interfaces introduced in this chapter are not framework types. They are a thin Contoso domain wrapper that enforces correlation propagation, structured failure modes, and observability hooks above the framework. Each IAgent implementation in the book ultimately delegates to a ChatClientAgent. Chapter 10 reaches the framework primitives directly.

Step-by-Step Implementation

Step 1: Define the Core Domain Entities

The SupportTicket record represents the core domain entity around which the copilot operates. It captures the essential data that AI workflows will summarize, classify, and respond to. Alongside it, TicketMessage captures individual communications, CustomerAccount links the ticket to customer context, and SupportCaseSummary stores the output of AI-generated summarization.

public record SupportTicket
{
    public Guid Id { get; init; }
    public string Subject { get; init; } = string.Empty;
    public string Description { get; init; } = string.Empty;
    public string Status { get; init; } = "Open";
    public string Priority { get; init; } = "Normal";
    public string ProductArea { get; init; } = string.Empty;
    public DateTime CreatedAt { get; init; }
    public DateTime? ResolvedAt { get; init; }
    public List<TicketMessage> Messages { get; init; } = new();
    public CustomerAccount? Customer { get; init; }
}

public record TicketMessage
{
    public Guid Id { get; init; }
    public string Content { get; init; } = string.Empty;
    public bool IsFromCustomer { get; init; }
    public DateTime SentAt { get; init; }
}

public record CustomerAccount
{
    public Guid Id { get; init; }
    public string Name { get; init; } = string.Empty;
    public string Tier { get; init; } = string.Empty;
}

public record SupportCaseSummary
{
    public Guid TicketId { get; init; }
    public string Summary { get; init; } = string.Empty;
    public DateTime GeneratedAt { get; init; }
    public int InputTokens { get; init; }
    public int OutputTokens { get; init; }
}

These records use init-only properties to ensure immutability within the domain. The ProductArea property becomes critical later when routing tickets to specialized agents or filtering knowledge base searches. The SupportCaseSummary entity captures token usage metrics essential for cost tracking and observability.

Step 2: Define the KnowledgeArticle and ArticleChunk Entities

Approved support documentation requires structured representation. The KnowledgeArticle record represents approved support documentation that the copilot will search and cite when drafting responses. The ArticleChunk record represents vector-searchable segments of that content.

public record KnowledgeArticle
{
    public Guid Id { get; init; }
    public string Title { get; init; } = string.Empty;
    public string Content { get; init; } = string.Empty;
    public string ProductArea { get; init; } = string.Empty;
    public string[] Tags { get; init; } = Array.Empty<string>();
    public DateTime LastUpdated { get; init; }
    public bool IsPublished { get; init; }
    public List<ArticleChunk> Chunks { get; init; } = new();
}

public record ArticleChunk
{
    public Guid Id { get; init; }
    public string Content { get; init; } = string.Empty;
    public float[] Embedding { get; init; } = Array.Empty<float>();
    public int ChunkIndex { get; init; }
}

The IsPublished flag ensures the copilot only references approved content. The Chunks collection supports semantic search through vector embeddings that you will implement in later chapters.

Step 3: Define the ISupportContext Interface

Data access requires abstraction from Entity Framework specifics. The ISupportContext interface provides this boundary, including methods for retrieving ticket messages and searching the knowledge base.

public interface ISupportContext
{
    Task<SupportTicket?> GetTicketAsync(Guid ticketId, CancellationToken cancellationToken = default);
    Task<IReadOnlyList<TicketMessage>> GetTicketMessagesAsync(Guid ticketId, CancellationToken cancellationToken = default);
    Task<IReadOnlyList<SupportTicket>> GetOpenTicketsAsync(string productArea, CancellationToken cancellationToken = default);
    Task<IReadOnlyList<KnowledgeArticle>> SearchKnowledgeBaseAsync(string query, string productArea, CancellationToken cancellationToken = default);
    Task SaveTicketAsync(SupportTicket ticket, CancellationToken cancellationToken = default);
}

This interface isolates the AI orchestration layer from data access concerns. The GetTicketMessagesAsync method retrieves the full message thread required for summarization workflows. The SearchKnowledgeBaseAsync method will later integrate with vector search, but the interface remains agnostic to the retrieval mechanism.

Step 4: Define the ISupportChatClient Abstraction

Microsoft.Extensions.AI defines standard abstractions for chat clients. In this step, you define the application-specific interface ISupportChatClient that mirrors these concepts while remaining under your control for testing and customization. This avoids naming collisions with the framework's IChatClient while maintaining semantic alignment.

public interface ISupportChatClient
{
    Task<ChatResponse> CompleteAsync(string prompt, ChatOptions? options = null, CancellationToken cancellationToken = default);
    IAsyncEnumerable<ChatResponseChunk> CompleteStreamingAsync(string prompt, ChatOptions? options = null, CancellationToken cancellationToken = default);
}

public record ChatResponse
{
    public string Content { get; init; } = string.Empty;
    public int InputTokens { get; init; }
    public int OutputTokens { get; init; }
    public string ModelId { get; init; } = string.Empty;
    public string FinishReason { get; init; } = string.Empty;
}

public record ChatResponseChunk
{
    public string Content { get; init; } = string.Empty;
    public bool IsComplete { get; init; }
}

public record ChatOptions
{
    public float Temperature { get; init; } = 0.7f;
    public int MaxTokens { get; init; } = 2000;
    public string? SystemPrompt { get; init; }
}

The ISupportChatClient interface abstracts the raw model interaction. The ChatResponse record includes token usage metrics that you will need for cost tracking and observability. In production, I have seen teams discover that missing these metrics made cost attribution impossible after the fact. Streaming support enables responsive user interfaces for long-form content generation.

Step 5: Define the IKernelOrchestrator Interface

Prompt orchestration requires its own abstraction layer. This interface abstracts those services so your application code does not depend directly on Semantic Kernel types.

public interface IKernelOrchestrator
{
    Task<string> ExecutePromptAsync(string promptTemplate, Dictionary<string, object> variables, CancellationToken cancellationToken = default);
    Task<T> ExecuteStructuredPromptAsync<T>(string promptTemplate, Dictionary<string, object> variables, CancellationToken cancellationToken = default) where T : class;
    void RegisterPlugin(string pluginName, object pluginFunctions);
    Task<string> ExecutePluginFunctionAsync(string pluginName, string functionName, Dictionary<string, object> parameters, CancellationToken cancellationToken = default);
}

The ExecuteStructuredPromptAsync method returns typed responses deserialized from JSON output; concrete implementations handle schema validation and parsing. The plugin registration methods enable the extensibility that separates business logic from AI infrastructure.

Step 6: Define the IAgentCoordinator Interface

Multi-agent coordination introduces additional complexity. The following interfaces define application-specific contracts for agent execution and handoff that map to Agent Framework concepts while keeping your domain isolated from specific framework types.

public interface IAgentCoordinator
{
    Task<AgentResult> ExecuteAgentAsync(string agentName, AgentContext context, CancellationToken cancellationToken = default);
    Task HandoffAsync(string fromAgent, string toAgent, AgentContext context, CancellationToken cancellationToken = default);
    Task RegisterAgentAsync(string agentName, IAgent agent, CancellationToken cancellationToken = default);
}

public interface IAgent
{
    string Name { get; }
    Task<AgentResult> ExecuteAsync(AgentContext context, CancellationToken cancellationToken = default);
}

public record AgentContext
{
    public Guid ConversationId { get; init; }
    public SupportTicket? CurrentTicket { get; init; }
    public string Intent { get; init; } = string.Empty;
    public Dictionary<string, object> Metadata { get; init; } = new();
}

public record AgentResult
{
    public string Response { get; init; } = string.Empty;
    public bool RequiresHandoff { get; init; }
    public string? NextAgent { get; init; }
    public Dictionary<string, object> Artifacts { get; init; } = new();
}

The AgentContext record carries the SupportTicket entity through the agent workflow, ensuring agents have access to relevant domain state. The RequiresHandoff flag enables cooperative multi-agent scenarios where one agent delegates to another.

Step 7: Implement the SqlSupportContext Class

Concrete implementations must precede DI configuration. The SqlSupportContext class implements ISupportContext using Entity Framework Core. This stub implementation establishes the class signature; you will complete the data access logic in Chapter 2.

public class SqlSupportContext : ISupportContext
{
    public Task<SupportTicket?> GetTicketAsync(Guid ticketId, CancellationToken cancellationToken = default)
        => throw new NotImplementedException();
    public Task<IReadOnlyList<TicketMessage>> GetTicketMessagesAsync(Guid ticketId, CancellationToken cancellationToken = default)
        => throw new NotImplementedException();
    public Task<IReadOnlyList<SupportTicket>> GetOpenTicketsAsync(string productArea, CancellationToken cancellationToken = default)
        => throw new NotImplementedException();
    public Task<IReadOnlyList<KnowledgeArticle>> SearchKnowledgeBaseAsync(string query, string productArea, CancellationToken cancellationToken = default)
        => throw new NotImplementedException();
    public Task SaveTicketAsync(SupportTicket ticket, CancellationToken cancellationToken = default)
        => throw new NotImplementedException();
}

Step 8: Implement the AzureFoundryChatClient Class

Model connectivity requires a concrete client implementation. The AzureFoundryChatClient class implements ISupportChatClient by connecting to Azure AI Foundry hosted models. This implementation will handle the actual HTTP communication with the GPT-5 endpoints.

public class AzureFoundryChatClient : ISupportChatClient
{
    private readonly string _endpoint;
    private readonly string _key;

    public AzureFoundryChatClient(string endpoint, string key)
    {
        _endpoint = endpoint;
        _key = key;
    }

    public Task<ChatResponse> CompleteAsync(string prompt, ChatOptions? options = null, CancellationToken cancellationToken = default)
        => throw new NotImplementedException();
    public IAsyncEnumerable<ChatResponseChunk> CompleteStreamingAsync(string prompt, ChatOptions? options = null, CancellationToken cancellationToken = default)
        => throw new NotImplementedException();
}

Step 9: Implement the SemanticKernelOrchestrator Class

Semantic Kernel integration wraps the orchestration engine. The SemanticKernelOrchestrator class implements IKernelOrchestrator by wrapping Semantic Kernel functionality. It translates application calls into kernel operations.

public class SemanticKernelOrchestrator : IKernelOrchestrator
{
    public Task<string> ExecutePromptAsync(string promptTemplate, Dictionary<string, object> variables, CancellationToken cancellationToken = default)
        => throw new NotImplementedException();
    public Task<T> ExecuteStructuredPromptAsync<T>(string promptTemplate, Dictionary<string, object> variables, CancellationToken cancellationToken = default) where T : class
        => throw new NotImplementedException();
    public void RegisterPlugin(string pluginName, object pluginFunctions)
        => throw new NotImplementedException();
    public Task<string> ExecutePluginFunctionAsync(string pluginName, string functionName, Dictionary<string, object> parameters, CancellationToken cancellationToken = default)
        => throw new NotImplementedException();
}

Step 10: Implement the AgentFrameworkCoordinator and TriageAgent Classes

Agent coordination requires a registry pattern. The AgentFrameworkCoordinator implements IAgentCoordinator by maintaining a registry of named agents. It resolves agent names to instances when ExecuteAgentAsync is called. The TriageAgent provides a concrete implementation of the IAgent interface.

public class AgentFrameworkCoordinator : IAgentCoordinator
{
    private readonly Dictionary<string, IAgent> _agents = new();
    private readonly IServiceProvider _serviceProvider;

    public AgentFrameworkCoordinator(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
    }

    public Task RegisterAgentAsync(string agentName, IAgent agent, CancellationToken cancellationToken = default)
    {
        _agents[agentName] = agent;
        return Task.CompletedTask;
    }

    public Task<AgentResult> ExecuteAgentAsync(string agentName, AgentContext context, CancellationToken cancellationToken = default)
    {
        if (!_agents.TryGetValue(agentName, out var agent))
            throw new ArgumentException($"Agent {agentName} not registered");
        return agent.ExecuteAsync(context, cancellationToken);
    }

    public Task HandoffAsync(string fromAgent, string toAgent, AgentContext context, CancellationToken cancellationToken = default)
        => throw new NotImplementedException();
}

public class TriageAgent : IAgent
{
    public string Name { get; }
    public TriageAgent(string name) => Name = name;
    public Task<AgentResult> ExecuteAsync(AgentContext context, CancellationToken cancellationToken = default)
        => throw new NotImplementedException();
}

The coordinator uses a dictionary to map agent names to instances, enabling the ExecuteAgentAsync("TriageAgent", ...) call to resolve the correct implementation.

Step 11: Implement the SupportCopilotService

Service composition brings the layers together. With the abstractions and implementations defined, you now implement the application service that composes these dependencies to provide copilot functionality. This service represents the primary API that the support portal consumes.

using System.Linq;

public class SupportCopilotService
{
    private readonly ISupportContext _supportContext;
    private readonly ISupportChatClient _chatClient;
    private readonly IKernelOrchestrator _kernelOrchestrator;
    private readonly IAgentCoordinator _agentCoordinator;

    public SupportCopilotService(
        ISupportContext supportContext,
        ISupportChatClient chatClient,
        IKernelOrchestrator kernelOrchestrator,
        IAgentCoordinator agentCoordinator)
    {
        _supportContext = supportContext;
        _chatClient = chatClient;
        _kernelOrchestrator = kernelOrchestrator;
        _agentCoordinator = agentCoordinator;
    }

    public async Task<string> DraftReplyAsync(Guid ticketId, CancellationToken cancellationToken = default)
    {
        var ticket = await _supportContext.GetTicketAsync(ticketId, cancellationToken);
        if (ticket is null)
        {
            throw new ArgumentException($"Ticket {ticketId} not found", nameof(ticketId));
        }

        var articles = await _supportContext.SearchKnowledgeBaseAsync(ticket.Subject, ticket.ProductArea, cancellationToken);
        var articlesText = string.Join("\n", articles.Select(a => $"{a.Title}: {a.Content[..Math.Min(200, a.Content.Length)]}"));

        var context = new Dictionary<string, object>
        {
            ["ticketSubject"] = ticket.Subject,
            ["ticketDescription"] = ticket.Description,
            ["productArea"] = ticket.ProductArea,
            ["relevantArticles"] = articlesText
        };

        return await _kernelOrchestrator.ExecutePromptAsync(
            "Draft a professional support response for the following ticket about {{$productArea}}.\n\n" +
            "Subject: {{$ticketSubject}}\nDescription: {{$ticketDescription}}\n\n" +
            "Consider these knowledge articles: {{$relevantArticles}}",
            context,
            cancellationToken);
    }

    public async Task<SupportCaseSummary> SummarizeTicketAsync(Guid ticketId, CancellationToken cancellationToken = default)
    {
        var ticket = await _supportContext.GetTicketAsync(ticketId, cancellationToken);
        if (ticket is null)
        {
            throw new ArgumentException($"Ticket {ticketId} not found", nameof(ticketId));
        }

        var messages = await _supportContext.GetTicketMessagesAsync(ticketId, cancellationToken);
        var messageHistory = string.Join("\n", messages.Select(m => $"{(m.IsFromCustomer ? "Customer" : "Agent")}: {m.Content}"));

        var prompt = $"Summarize the following support ticket concisely. Identify the key issue, current status, and recommended next steps.\n\nSubject: {ticket.Subject}\nDescription: {ticket.Description}\nStatus: {ticket.Status}\n\nMessage History:\n{messageHistory}";

        var response = await _chatClient.CompleteAsync(prompt, new ChatOptions { Temperature = 0.2f, MaxTokens = 500 }, cancellationToken);

        return new SupportCaseSummary
        {
            TicketId = ticketId,
            Summary = response.Content,
            GeneratedAt = DateTime.UtcNow,
            InputTokens = response.InputTokens,
            OutputTokens = response.OutputTokens
        };
    }

    public async Task<AgentResult> TriageTicketAsync(Guid ticketId, CancellationToken cancellationToken = default)
    {
        var ticket = await _supportContext.GetTicketAsync(ticketId, cancellationToken);
        if (ticket is null)
        {
            throw new ArgumentException($"Ticket {ticketId} not found", nameof(ticketId));
        }

        var context = new AgentContext
        {
            ConversationId = Guid.NewGuid(),
            CurrentTicket = ticket,
            Intent = "triage",
            Metadata = { ["priority"] = ticket.Priority }
        };

        return await _agentCoordinator.ExecuteAgentAsync("TriageAgent", context, cancellationToken);
    }
}

This service coordinates the three AI layers. The SupportCopilotService depends on all three architectural layers but remains agnostic to their implementations. It uses ISupportChatClient for simple summarization, IKernelOrchestrator for complex prompt workflows that require knowledge grounding, and IAgentCoordinator for multi-step triage processes. The SummarizeTicketAsync method returns a structured SupportCaseSummary containing token usage metrics for observability.

Step 12: Configure Dependency Injection in Visual Studio

In Visual Studio, open the Solution Explorer and locate Program.cs in the ContosoSupportCopilot project. Double-click to open the file. Inside the WebApplication.CreateBuilder call, add the following service registrations:

var builder = WebApplication.CreateBuilder(args);

// Domain and application services
builder.Services.AddScoped<ISupportContext, SqlSupportContext>();
builder.Services.AddScoped<SupportCopilotService>();

// AI Infrastructure abstractions
// Microsoft.Extensions.AI layer
builder.Services.AddScoped<ISupportChatClient>(sp =>
    new AzureFoundryChatClient(
        builder.Configuration["AzureAI:Endpoint"]!,
        builder.Configuration["AzureAI:Key"]!));

// Semantic Kernel orchestration layer
builder.Services.AddScoped<IKernelOrchestrator, SemanticKernelOrchestrator>();

// Agent Framework coordination layer
builder.Services.AddScoped<IAgentCoordinator, AgentFrameworkCoordinator>();
builder.Services.AddScoped<TriageAgent>(sp => new TriageAgent("TriageAgent"));

var app = builder.Build();

// Register agents with the coordinator by name
using (var scope = app.Services.CreateScope())
{
    var coordinator = scope.ServiceProvider.GetRequiredService<IAgentCoordinator>();
    var triageAgent = scope.ServiceProvider.GetRequiredService<TriageAgent>();
    await coordinator.RegisterAgentAsync("TriageAgent", triageAgent);
}

app.Run();

This configuration wires the architectural stack. The registration uses a factory delegate for ISupportChatClient to pass configuration values to the constructor. The TriageAgent is registered with its concrete type, then resolved and registered by name with the coordinator during startup. This enables name-based agent resolution.

Full Example

The following consolidated example presents the foundational domain model, interface abstractions, stub implementations, and service composition that define the Contoso Support Copilot architecture. This code establishes the base upon which subsequent chapters build.

// Domain Entities
public record SupportTicket
{
    public Guid Id { get; init; }
    public string Subject { get; init; } = string.Empty;
    public string Description { get; init; } = string.Empty;
    public string Status { get; init; } = "Open";
    public string Priority { get; init; } = "Normal";
    public string ProductArea { get; init; } = string.Empty;
    public DateTime CreatedAt { get; init; }
    public DateTime? ResolvedAt { get; init; }
    public List<TicketMessage> Messages { get; init; } = new();
    public CustomerAccount? Customer { get; init; }
}

public record TicketMessage
{
    public Guid Id { get; init; }
    public string Content { get; init; } = string.Empty;
    public bool IsFromCustomer { get; init; }
    public DateTime SentAt { get; init; }
}

public record CustomerAccount
{
    public Guid Id { get; init; }
    public string Name { get; init; } = string.Empty;
    public string Tier { get; init; } = string.Empty;
}

public record SupportCaseSummary
{
    public Guid TicketId { get; init; }
    public string Summary { get; init; } = string.Empty;
    public DateTime GeneratedAt { get; init; }
    public int InputTokens { get; init; }
    public int OutputTokens { get; init; }
}

public record KnowledgeArticle
{
    public Guid Id { get; init; }
    public string Title { get; init; } = string.Empty;
    public string Content { get; init; } = string.Empty;
    public string ProductArea { get; init; } = string.Empty;
    public string[] Tags { get; init; } = Array.Empty<string>();
    public DateTime LastUpdated { get; init; }
    public bool IsPublished { get; init; }
    public List<ArticleChunk> Chunks { get; init; } = new();
}

public record ArticleChunk
{
    public Guid Id { get; init; }
    public string Content { get; init; } = string.Empty;
    public float[] Embedding { get; init; } = Array.Empty<float>();
    public int ChunkIndex { get; init; }
}

// Domain Context Abstraction
public interface ISupportContext
{
    Task<SupportTicket?> GetTicketAsync(Guid ticketId, CancellationToken cancellationToken = default);
    Task<IReadOnlyList<TicketMessage>> GetTicketMessagesAsync(Guid ticketId, CancellationToken cancellationToken = default);
    Task<IReadOnlyList<SupportTicket>> GetOpenTicketsAsync(string productArea, CancellationToken cancellationToken = default);
    Task<IReadOnlyList<KnowledgeArticle>> SearchKnowledgeBaseAsync(string query, string productArea, CancellationToken cancellationToken = default);
    Task SaveTicketAsync(SupportTicket ticket, CancellationToken cancellationToken = default);
}

// Application Chat Abstraction
public interface ISupportChatClient
{
    Task<ChatResponse> CompleteAsync(string prompt, ChatOptions? options = null, CancellationToken cancellationToken = default);
    IAsyncEnumerable<ChatResponseChunk> CompleteStreamingAsync(string prompt, ChatOptions? options = null, CancellationToken cancellationToken = default);
}

public record ChatResponse
{
    public string Content { get; init; } = string.Empty;
    public int InputTokens { get; init; }
    public int OutputTokens { get; init; }
    public string ModelId { get; init; } = string.Empty;
    public string FinishReason { get; init; } = string.Empty;
}

public record ChatResponseChunk
{
    public string Content { get; init; } = string.Empty;
    public bool IsComplete { get; init; }
}

public record ChatOptions
{
    public float Temperature { get; init; } = 0.7f;
    public int MaxTokens { get; init; } = 2000;
    public string? SystemPrompt { get; init; }
}

// Semantic Kernel Abstraction
public interface IKernelOrchestrator
{
    Task<string> ExecutePromptAsync(string promptTemplate, Dictionary<string, object> variables, CancellationToken cancellationToken = default);
    Task<T> ExecuteStructuredPromptAsync<T>(string promptTemplate, Dictionary<string, object> variables, CancellationToken cancellationToken = default) where T : class;
    void RegisterPlugin(string pluginName, object pluginFunctions);
    Task<string> ExecutePluginFunctionAsync(string pluginName, string functionName, Dictionary<string, object> parameters, CancellationToken cancellationToken = default);
}

// Agent Framework Abstractions
public interface IAgentCoordinator
{
    Task<AgentResult> ExecuteAgentAsync(string agentName, AgentContext context, CancellationToken cancellationToken = default);
    Task HandoffAsync(string fromAgent, string toAgent, AgentContext context, CancellationToken cancellationToken = default);
    Task RegisterAgentAsync(string agentName, IAgent agent, CancellationToken cancellationToken = default);
}

public interface IAgent
{
    string Name { get; }
    Task<AgentResult> ExecuteAsync(AgentContext context, CancellationToken cancellationToken = default);
}

public record AgentContext
{
    public Guid ConversationId { get; init; }
    public SupportTicket? CurrentTicket { get; init; }
    public string Intent { get; init; } = string.Empty;
    public Dictionary<string, object> Metadata { get; init; } = new();
}

public record AgentResult
{
    public string Response { get; init; } = string.Empty;
    public bool RequiresHandoff { get; init; }
    public string? NextAgent { get; init; }
    public Dictionary<string, object> Artifacts { get; init; } = new();
}

// Concrete Implementations
public class SqlSupportContext : ISupportContext
{
    public Task<SupportTicket?> GetTicketAsync(Guid ticketId, CancellationToken cancellationToken = default) => throw new NotImplementedException();
    public Task<IReadOnlyList<TicketMessage>> GetTicketMessagesAsync(Guid ticketId, CancellationToken cancellationToken = default) => throw new NotImplementedException();
    public Task<IReadOnlyList<SupportTicket>> GetOpenTicketsAsync(string productArea, CancellationToken cancellationToken = default) => throw new NotImplementedException();
    public Task<IReadOnlyList<KnowledgeArticle>> SearchKnowledgeBaseAsync(string query, string productArea, CancellationToken cancellationToken = default) => throw new NotImplementedException();
    public Task SaveTicketAsync(SupportTicket ticket, CancellationToken cancellationToken = default) => throw new NotImplementedException();
}

public class AzureFoundryChatClient : ISupportChatClient
{
    private readonly string _endpoint;
    private readonly string _key;
    public AzureFoundryChatClient(string endpoint, string key) { _endpoint = endpoint; _key = key; }
    public Task<ChatResponse> CompleteAsync(string prompt, ChatOptions? options = null, CancellationToken cancellationToken = default) => throw new NotImplementedException();
    public IAsyncEnumerable<ChatResponseChunk> CompleteStreamingAsync(string prompt, ChatOptions? options = null, CancellationToken cancellationToken = default) => throw new NotImplementedException();
}

public class SemanticKernelOrchestrator : IKernelOrchestrator
{
    public Task<string> ExecutePromptAsync(string promptTemplate, Dictionary<string, object> variables, CancellationToken cancellationToken = default) => throw new NotImplementedException();
    public Task<T> ExecuteStructuredPromptAsync<T>(string promptTemplate, Dictionary<string, object> variables, CancellationToken cancellationToken = default) where T : class => throw new NotImplementedException();
    public void RegisterPlugin(string pluginName, object pluginFunctions) => throw new NotImplementedException();
    public Task<string> ExecutePluginFunctionAsync(string pluginName, string functionName, Dictionary<string, object> parameters, CancellationToken cancellationToken = default) => throw new NotImplementedException();
}

public class AgentFrameworkCoordinator : IAgentCoordinator
{
    private readonly Dictionary<string, IAgent> _agents = new();
    public Task RegisterAgentAsync(string agentName, IAgent agent, CancellationToken cancellationToken = default) { _agents[agentName] = agent; return Task.CompletedTask; }
    public Task<AgentResult> ExecuteAgentAsync(string agentName, AgentContext context, CancellationToken cancellationToken = default) => _agents.TryGetValue(agentName, out var agent) ? agent.ExecuteAsync(context, cancellationToken) : throw new ArgumentException($"Agent {agentName} not found");
    public Task HandoffAsync(string fromAgent, string toAgent, AgentContext context, CancellationToken cancellationToken = default) => throw new NotImplementedException();
}

public class TriageAgent : IAgent
{
    public string Name { get; }
    public TriageAgent(string name) => Name = name;
    public Task<AgentResult> ExecuteAsync(AgentContext context, CancellationToken cancellationToken = default) => throw new NotImplementedException();
}

// Application Service
public class SupportCopilotService
{
    private readonly ISupportContext _supportContext;
    private readonly ISupportChatClient _chatClient;
    private readonly IKernelOrchestrator _kernelOrchestrator;
    private readonly IAgentCoordinator _agentCoordinator;

    public SupportCopilotService(ISupportContext supportContext, ISupportChatClient chatClient, IKernelOrchestrator kernelOrchestrator, IAgentCoordinator agentCoordinator)
    {
        _supportContext = supportContext;
        _chatClient = chatClient;
        _kernelOrchestrator = kernelOrchestrator;
        _agentCoordinator = agentCoordinator;
    }

    public async Task<string> DraftReplyAsync(Guid ticketId, CancellationToken cancellationToken = default)
    {
        var ticket = await _supportContext.GetTicketAsync(ticketId, cancellationToken);
        if (ticket is null) throw new ArgumentException($"Ticket {ticketId} not found", nameof(ticketId));
        var articles = await _supportContext.SearchKnowledgeBaseAsync(ticket.Subject, ticket.ProductArea, cancellationToken);
        var articlesText = string.Join("\n", articles.Select(a => $"{a.Title}: {a.Content[..Math.Min(200, a.Content.Length)]}"));
        var context = new Dictionary<string, object> { ["ticketSubject"] = ticket.Subject, ["ticketDescription"] = ticket.Description, ["productArea"] = ticket.ProductArea, ["relevantArticles"] = articlesText };
        return await _kernelOrchestrator.ExecutePromptAsync("Draft a professional support response for {{$productArea}}:\nSubject: {{$ticketSubject}}\nDescription: {{$ticketDescription}}\nArticles: {{$relevantArticles}}", context, cancellationToken);
    }

    public async Task<SupportCaseSummary> SummarizeTicketAsync(Guid ticketId, CancellationToken cancellationToken = default)
    {
        var ticket = await _supportContext.GetTicketAsync(ticketId, cancellationToken);
        if (ticket is null) throw new ArgumentException($"Ticket {ticketId} not found", nameof(ticketId));
        var messages = await _supportContext.GetTicketMessagesAsync(ticketId, cancellationToken);
        var messageHistory = string.Join("\n", messages.Select(m => $"{(m.IsFromCustomer ? "Customer" : "Agent")}: {m.Content}"));
        var prompt = $"Summarize:\nSubject: {ticket.Subject}\nDescription: {ticket.Description}\nStatus: {ticket.Status}\nHistory:\n{messageHistory}";
        var response = await _chatClient.CompleteAsync(prompt, new ChatOptions { Temperature = 0.2f, MaxTokens = 500 }, cancellationToken);
        return new SupportCaseSummary { TicketId = ticketId, Summary = response.Content, GeneratedAt = DateTime.UtcNow, InputTokens = response.InputTokens, OutputTokens = response.OutputTokens };
    }

    public async Task<AgentResult> TriageTicketAsync(Guid ticketId, CancellationToken cancellationToken = default)
    {
        var ticket = await _supportContext.GetTicketAsync(ticketId, cancellationToken);
        if (ticket is null) throw new ArgumentException($"Ticket {ticketId} not found", nameof(ticketId));
        var context = new AgentContext { ConversationId = Guid.NewGuid(), CurrentTicket = ticket, Intent = "triage", Metadata = { ["priority"] = ticket.Priority } };
        return await _agentCoordinator.ExecuteAgentAsync("TriageAgent", context, cancellationToken);
    }
}

// Configuration (Program.cs)
// var builder = WebApplication.CreateBuilder(args);
// builder.Services.AddScoped<ISupportContext, SqlSupportContext>();
// builder.Services.AddScoped<SupportCopilotService>();
// builder.Services.AddScoped<ISupportChatClient>(sp => new AzureFoundryChatClient(builder.Configuration["AzureAI:Endpoint"]!, builder.Configuration["AzureAI:Key"]!));
// builder.Services.AddScoped<IKernelOrchestrator, SemanticKernelOrchestrator>();
// builder.Services.AddScoped<IAgentCoordinator, AgentFrameworkCoordinator>();
// builder.Services.AddScoped<TriageAgent>(sp => new TriageAgent("TriageAgent"));
// var app = builder.Build();
// using (var scope = app.Services.CreateScope()) { var coord = scope.ServiceProvider.GetRequiredService<IAgentCoordinator>(); var agent = scope.ServiceProvider.GetRequiredService<TriageAgent>(); coord.RegisterAgentAsync("TriageAgent", agent).Wait(); }
// app.Run();

This architecture separates concerns into distinct layers. Domain entities remain pure records with no AI dependencies, while interface abstractions isolate the application from infrastructure specifics. Stub implementations establish the structure for subsequent chapters. The SupportCopilotService composes these capabilities without leaking implementation details.

Common Mistakes

  • Coupling domain logic directly to Semantic Kernel or Agent Framework types. Avoid referencing Kernel or Agent classes directly in your domain services. This creates brittle code that resists testing and prevents swapping implementations. Always depend on the abstractions defined in this chapter.
  • Using Microsoft.Extensions.AI for complex orchestration. Do not attempt to build multi-step workflows or plugin systems using only ISupportChatClient. This interface serves simple request-response scenarios. Complex prompt chaining belongs in the Semantic Kernel layer.
  • Implementing agents before establishing basic chat capabilities. Resist the urge to build IAgentCoordinator implementations before you have working ISupportChatClient and IKernelOrchestrator implementations. Agents depend on these lower layers; attempting to build them first results in circular dependencies and incomplete abstractions.
  • Ignoring token usage in abstraction design. Failing to include InputTokens and OutputTokens in your ChatResponse record prevents cost tracking and observability. Add these metrics to your abstraction from the start; retrofitting them later requires changing every implementation.
  • Mixing synchronous and asynchronous initialization in AI services. Do not perform expensive initialization (such as loading models or establishing Azure connections) inside service constructors. This blocks the dependency injection container and slows application startup. Use lazy initialization or factory patterns instead.

Performance and Production Considerations

The abstraction layer introduced in this chapter adds minimal overhead; interface dispatch costs are negligible compared to network latency from Azure AI Foundry calls. However, the architectural separation enables critical production optimizations.

Memory management becomes predictable when domain entities remain immutable records. The SupportTicket and KnowledgeArticle records shown here allocate efficiently and serialize cleanly for caching or logging. Avoid mutable domain models in AI workflows; they complicate thread safety when multiple agents process the same ticket concurrently.

Testability improves dramatically with these interfaces. You can implement ISupportChatClient using a local mock that returns canned responses, enabling unit tests for SupportCopilotService that execute in milliseconds without network calls. Similarly, mock implementations of ISupportContext allow testing AI logic without database dependencies.

The streaming interface in ISupportChatClient supports responsive user interfaces. When implementing the concrete Azure Foundry client, ensure you properly dispose of HTTP response streams to avoid socket exhaustion under load. The IAsyncEnumerable<ChatResponseChunk> pattern backpressures naturally; consume it with await foreach to prevent memory buffering of large responses.

Latency budgets require attention at this architectural stage. The SupportCopilotService methods compose multiple AI calls (such as searching the knowledge base then generating a draft). In production, you will add timeouts and circuit breakers to these compositions. Define timeout policies at the interface implementation level, not inside the application service, so all consumers benefit from consistent resilience patterns.

Summary

This chapter established the architectural foundation for Contoso Support Copilot. You defined the domain entities SupportTicket, TicketMessage, CustomerAccount, SupportCaseSummary, KnowledgeArticle, and ArticleChunk that represent the core data of the support workflow. You created three critical abstractions: ISupportChatClient for model access through Microsoft.Extensions.AI, IKernelOrchestrator for prompt orchestration through Semantic Kernel, and IAgentCoordinator for multi-agent coordination through the Microsoft Agent Framework.

The SupportCopilotService demonstrates how application logic composes these abstractions without depending on specific AI infrastructure. This separation enables testing, fallback behavior, and infrastructure evolution. The dependency injection configuration shows how these layers coexist in a .NET 10 application, with Azure AI Foundry serving as the underlying model host. Subsequent chapters will implement the concrete classes for these interfaces while the domain logic remains stable.

Key Terms

  • Microsoft.Extensions.AI: The application-facing abstraction layer for model access in .NET 10, providing unified interfaces for chat completions, embeddings, and structured output.
  • Semantic Kernel: An orchestration framework that manages prompt templates, plugin execution, and complex AI workflow composition.
  • Microsoft Agent Framework: A coordination layer for multi-agent scenarios, handling agent contracts, handoff patterns, and distributed workflow execution.
  • IAgentCoordinator: A custom application interface defining contracts for agent coordination, abstracting Microsoft Agent Framework capabilities to preserve testability.
  • AgentContext: A custom application record containing conversation state, ticket references, and metadata passed between agents; maps to framework context concepts but remains under application control.
  • Azure AI Foundry: Microsoft's platform for hosting and managing AI models, including GPT-5 and embedding services, operating as infrastructure beneath the application abstraction layers.
  • Domain Entity: A core business object such as SupportTicket or KnowledgeArticle that represents data within the application's problem space without AI infrastructure dependencies.
  • Abstraction Layer: An interface-based boundary that isolates application logic from infrastructure concerns, enabling testability and implementation flexibility.
  • Token Usage Metrics: Measurements of input and output tokens consumed during model interactions, essential for cost tracking and observability.

Mini Quiz

  1. Contoso Support Copilot receives a high-priority support ticket. The application must extract the customer's intent, search the knowledge base for relevant articles, and draft a grounded reply. According to the architectural boundaries defined in this chapter, which component owns the responsibility for orchestrating these AI-driven steps while keeping the domain logic testable?

A. Azure AI Foundry SDK called directly from the API controller

B. SupportCopilotService using IKernelOrchestrator

C. The React frontend making separate API calls to each microservice

D. SQL Server stored procedures containing prompt templates

  1. Examine the following implementation of a domain service method:
public async Task<string> AnalyzeTicketAsync(Guid ticketId, CancellationToken cancellationToken)
{
    var ticket = await _supportContext.GetTicketAsync(ticketId, cancellationToken);

    var promptVariables = new Dictionary<string, object>
    {
        ["subject"] = ticket.Subject,
        ["priority"] = ticket.Priority,
        ["description"] = ticket.Description
    };

    return await _kernelOrchestrator.ExecutePromptAsync(
        "AnalyzeTicket", promptVariables, cancellationToken);
}

What does this code demonstrate about the architectural layering established in this chapter?

A. Direct database access from the orchestration layer violates separation of concerns

B. Proper separation between data access, domain logic, and AI orchestration abstractions

C. Tight coupling to Azure AI Foundry SDK implementation details

D. Bypassing the abstraction layers to improve response latency

  1. Which abstraction layer provides the unified interface for chat completions and embeddings in .NET 10?

A. Semantic Kernel

B. Microsoft Agent Framework

C. Microsoft.Extensions.AI

D. Azure AI Foundry SDK

  1. Why does SupportCopilotService depend on ISupportContext and IKernelOrchestrator interfaces rather than concrete implementations?

A. To reduce memory usage in the application

B. To enable testing, fallback behavior, and infrastructure evolution without destabilizing business logic

C. To improve the raw performance of AI model calls

D. To eliminate the need for dependency injection configuration

  1. In the architectural hierarchy presented in this chapter, which component operates at the highest level to coordinate multiple specialized agents?

A. IChatClient

B. IKernelOrchestrator

C. IAgentCoordinator

D. ISupportContext

  1. What specific information does the ChatResponse record include to support production observability and cost tracking?

A. Only the response content string

B. Input tokens, output tokens, model ID, and finish reason

C. Database connection strings and query execution times

D. User authentication tokens and session identifiers

Answers are provided in the Answer Key at the end of the book.

Activity

Extend the Contoso Support Copilot domain model to support escalation drafting workflows. In production support environments, you'll find that clear escalation documents are critical for engineering handoffs, so this activity grounds the implementation in that real-world requirement.

  • Create a new record named EscalationDraft with properties for TicketId, EngineeringSummary, ReproductionSteps, and BusinessImpact.
  • Extend the ISupportContext interface with a method Task SaveEscalationDraftAsync(EscalationDraft draft, CancellationToken cancellationToken = default).
  • Implement a new method DraftEscalationAsync(Guid ticketId, CancellationToken cancellationToken) in SupportCopilotService that retrieves the ticket using _supportContext, constructs a prompt template requesting an escalation analysis, and invokes _kernelOrchestrator.ExecutePromptAsync.
  • Include the ticket's Subject, Description, Priority, and ProductArea in the prompt variables dictionary passed to the orchestrator.
  • Write a simple unit test that mocks ISupportContext to return a test ticket with known values, then verify that DraftEscalationAsync constructs the expected prompt context and calls the orchestrator with the correct ticket data.

Enjoying this book?

Create a free account to leave comments, track your progress, and more!

Read and listen on the go with the unQbd app. Get the app
An unhandled error has occurred. Reload 🗙

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please reload the page.