Skapa en .NET OpenAI-agent med hjälp av en MCP-server i Azure Container Apps

Den här artikeln visar hur du skapar en MCP-agent (Model Context Protocol) med hjälp av .NET. I det här exemplet ansluter MCP-klienten (skriven i C#/.NET) till en MCP-server (skriven i TypeScript) för att hantera en att göra-lista. Klienten hittar tillgängliga verktyg från servern och skickar dem till en Azure OpenAI-modell. Användarna kan sedan prata med att göra-systemet med hjälp av vardagsspråket.

Gå till koden

Kolla in AI-mallen OpenAI MCP Agent Building Block AI. Det här exemplet visar hur du skapar en OpenAI-agent som använder en MCP-klient för att använda en befintlig MCP-server.

Gå till avsnittet med kodgenomgång för att förstå hur det här exemplet fungerar.

Översikt över arkitektur

Följande diagram visar exempelappens enkla arkitektur:

• MCP-klient: Ansluter till MCP-servern och hittar tillgängliga verktyg
• Chattklient: Fungerar med Azure OpenAI för att förstå naturligt språk
• Blazor-användargränssnitt: Tillhandahåller ett webbgränssnitt där användare kan chatta
• Transportlager: Använder Server-Sent events (SSE) för att skicka meddelanden i realtid
• Autentisering: Använder JWT-token för att skydda anslutningen

MCP-servern körs som en containerbaserad app i Azure Container Apps (ACA). Den använder en TypeScript-serverdel för att tillhandahålla verktyg till MCP-klienten via Model Context Protocol. Alla verktyg fungerar med en SQLite-databas för serverdelen.

Kostnad

För att hålla kostnaderna låga använder det här exemplet prisnivåer för bas- eller förbrukning för de flesta resurser. Justera nivån efter behov och ta bort resurser när du är klar för att undvika avgifter.

Förutsättningar

• Visual Studio Code – den senaste versionen för mcp-serverutveckling.
• .NET 9 SDK
• C# Dev Kit för Visual Studio Code Visual Studio Code-tillägg
• GitHub Copilot Visual Studio Code-tillägg
• GitHub Copilot Chat Visual Studio Code-tillägg
• Azure Developer CLI (azd)
• AI Foundry-tillägget Visual Studio Code-tillägg
• En distribuerad AI Foundry gpt-5-mini-modell

En utvecklingscontainer innehåller alla beroenden som du behöver för den här artikeln. Du kan köra den i GitHub Codespaces (i en webbläsare) eller lokalt med hjälp av Visual Studio Code.

Följ den här artikeln genom att se till att du uppfyller följande krav:

Distribuera en AI Foundry gpt-5-mini-modell med hjälp av AI Foundry VS Code Extension

Distribuera en gpt-5-mini modell med hjälp av AI Foundry-tillägget i Visual Studio Code med hjälp av följande steg:

Skapa ett AI Foundry-projekt och distribuera modellen

• Om du vill skapa ett AI Foundry-projekt och distribuera en gpt-5-mini modell följer du kom igång-instruktionerna i artikeln Arbeta med Azure AI Foundry for Visual Studio Code-tillägget (förhandsversion).

Skapa anslutningssträngen openAI-modell

1. gpt-5-mini När modellen har distribuerats högerklickar du på modellen i AI Foundry-tillägget och väljer Kopiera API-nyckel för att kopiera modellens API-nyckel till Urklipp.

2. Högerklicka sedan på den distribuerade gpt-5-mini modellen i AI Foundry-tillägget och välj Kopiera slutpunkt för att kopiera modellens slutpunkt till Urklipp, enligt följande skärmbild:

   

3. Skapa slutligen en anslutningssträng för den distribuerade gpt-5-mini modellen med hjälp av den kopierade slutpunkten och API-nyckeln i följande format: Endpoint=<AZURE_OPENAI_ENDPOINT>;Key=<AZURE_OPENAI_API_KEY>. Du behöver den här anslutningssträngen senare i artikeln.

Öppna utvecklingsmiljön

Följ de här stegen för att konfigurera en förkonfigurerad utvecklingsmiljö med alla nödvändiga beroenden.

Distribuera och köra

Exempellagringsplatsen innehåller alla kod- och konfigurationsfiler för MCP-agentens Azure-distribution. Följande steg beskriver exempeldistributionsprocessen för MCP-agenten i Azure.

Distribuera till Azure

Ange JWT-token

• Ange JWT-token för MCP-servern genom att köra följande kommando i terminalen längst ned på skärmen:

  # zsh/bash
  ./scripts/set-jwttoken.sh
  

  # PowerShell
  ./scripts/Set-JwtToken.ps1
  

Lägga till JWT-token i azd-miljökonfiguration

1. Lägg till JWT-token i azd-miljökonfigurationen genom att köra följande kommando i terminalen längst ned på skärmen:

   # zsh/bash
   env_dir=".azure/$(azd env get-value AZURE_ENV_NAME)"
   mkdir -p "$env_dir"
   cat ./src/McpTodo.ServerApp/.env >> "$env_dir/.env"
   

   # PowerShell
   $dotenv = Get-Content ./src/McpTodo.ServerApp/.env
   $dotenv | Add-Content -Path ./.azure/$(azd env get-value AZURE_ENV_NAME)/.env -Encoding utf8 -Force
   

   Anmärkning

   Som standard skyddas MCP-klientappen av den inbyggda ACA-autentiseringsfunktionen. Du kan inaktivera den här funktionen innan du kör azd up genom att ange:

   azd env set USE_LOGIN false
   

2. Kör följande Azure Developer CLI-kommando för Azure-resursetablering och källkodsdistribution:

   azd up
   

3. Använd följande tabell för att besvara anvisningarna:

   Omedelbar	Answer
   Miljönamn	Använd ett kort, gemener. Lägg till ditt namn eller alias. Till exempel my-mcp-agent. Miljönamnet blir en del av resursgruppens namn.
   Subscription	Välj den prenumeration där du vill skapa resurser.
   Plats (för värd)	Välj distributionsplatsen för modellen i listan.
   OpenAI-anslutningssträng	Klistra in anslutningssträngen för OpenAI-modellen som du skapade tidigare i avsnittet Skapa anslutningssträngen för OpenAI-modellen .

4. Appdistributionen tar 5 till 10 minuter.

5. När distributionen är klar kan du komma åt MCP-agenten med hjälp av URL:en i utdata. URL:en ser ut så här:

   https://<env-name>.<container-id>.<region>.azurecontainerapps.io
   

6. Öppna URL:en i en webbläsare för att använda MCP-agenten.

Använda TODO MCP-agenten

När MCP-agenten har körts kan du använda de verktyg som den tillhandahåller i agentläge. Så här använder du MCP-verktyg i agentläge:

1. Navigera till klientappens URL och logga in på appen.

   Anmärkning

   om du anger värdet USE_LOGIN till falsekanske du inte uppmanas att logga in.

2. Ange en uppmaning som "Jag måste skicka ett e-postmeddelande till min chef på onsdag" i chattinmatningsrutan och lägg märke till hur verktyg anropas automatiskt efter behov.

3. MCP-agenten använder de verktyg som tillhandahålls av MCP-servern för att uppfylla begäran och returnera ett svar i chattgränssnittet.

4. Experimentera med andra frågor som:

   Give me a list of to dos.
   Set "meeting at 1pm".
   Give me a list of to dos.
   Mark #1 as completed.
   Delete #1 from the to-do list.
   

Utforska koden

Exempellagringsplatsen innehåller alla kod- och konfigurationsfiler för MCP-agentens Azure-distribution. I följande avsnitt går vi igenom de viktigaste komponenterna i MCP-agentkoden.

KONFIGURATION och konfiguration av MCP-klient

Programmet konfigurerar MCP-klienten i Program.cs. Den här konfigurationen definierar hur du ansluter och vilka alternativ som ska användas. Koden använder flera avancerade mönster, inklusive .NET Aspire-integrering och tjänststandarder:

builder.Services.AddSingleton<IMcpClient>(sp =>
{
    var config = sp.GetRequiredService<IConfiguration>();
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();

    var uri = new Uri(config["McpServers:TodoList"]!);

    var clientTransportOptions = new SseClientTransportOptions()
    {
        Endpoint = new Uri($"{uri.AbsoluteUri.TrimEnd('/')}/mcp"),
        AdditionalHeaders = new Dictionary<string, string>
        {
            { "Authorization", $"Bearer {config["McpServers:JWT:Token"]!}" }
        }
    };
    var clientTransport = new SseClientTransport(clientTransportOptions, loggerFactory);

    var clientOptions = new McpClientOptions()
    {
        ClientInfo = new Implementation()
        {
            Name = "MCP Todo Client",
            Version = "1.0.0",
        }
    };

    return McpClientFactory.CreateAsync(clientTransport, clientOptions, loggerFactory).GetAwaiter().GetResult();
});

Viktig implementeringsinformation:

• Transportkonfiguration: SseClientTransportOptions stöder både Server-Sent Events (SSE) och strömmande HTTP-transport. Transportmetoden beror på slutpunkts-URL:en – slutpunkter som slutar med /sse användning Server-Sent händelser, medan slutpunkter slutar med /mcp användning av strömmande HTTP. Den här metoden möjliggör kommunikation i realtid mellan klient och server
• Autentiseringshuvuden: JWT-token går in för att skydda serverkommunikationen AdditionalHeaders
• Klientinformation: McpClientOptions anger klientens namn och version för servern
• Fabriksmönster: McpClientFactory.CreateAsync() ansluter och slutför protokollhandskakningen

Standardintegrering av .NET Aspire-tjänsten

Programmet använder standardmönstret för .NET Aspire-tjänsten för övergripande problem:

// McpTodo.ServiceDefaults/Extensions.cs
public static TBuilder AddServiceDefaults<TBuilder>(this TBuilder builder) where TBuilder : IHostApplicationBuilder
{
    builder.ConfigureOpenTelemetry();
    builder.AddDefaultHealthChecks();
    builder.Services.AddServiceDiscovery();
    
    builder.Services.ConfigureHttpClientDefaults(http =>
    {
        // Turn on resilience by default
        http.AddStandardResilienceHandler();
        // Turn on service discovery by default
        http.AddServiceDiscovery();
    });
    
    return builder;
}

Tjänstens standardförmåner:

• Komposterbara tilläggsmetoder: Systemet använder ett rensningsmönster för att lägga till delade funktioner
• Standard Resilience Handlers: Systemet lägger till inbyggda regler för återförsök, kretsbrytare och timeout för dig
• Service Discovery-integrering: Systemet hittar tjänster automatiskt i containermiljöer
• OpenTelemetry som standard: Systemet får fullständig övervakning utan installationsarbete

Följande diagram visar relationen mellan övergripande problem och programtjänster:

Lösning för konfigurations-URL

Exemplet innehåller avancerad URL-lösning för olika miljöer:

// AspireUrlParserExtensions.cs
public static Uri Resolve(this Uri uri, IConfiguration config)
{
    var absoluteUrl = uri.ToString();
    if (absoluteUrl.StartsWith("https+http://"))
    {
        var appname = absoluteUrl.Substring("https+http://".Length).Split('/')[0];
        var https = config[$"services:{appname}:https:0"]!;
        var http = config[$"services:{appname}:http:0"]!;
        
        return string.IsNullOrWhiteSpace(https) ? new Uri(http) : new Uri(https);
    }
    // Handle other URL formats...
}

Konfigurationshanteringsfunktioner:

• Abstraktion för Service Discovery: Systemet hanterar utvecklings- och produktions-URL:er rent
• Protokollförhandling: Systemet väljer FÖRST HTTPS och återgår sedan till HTTP
• Konfigurationskonvention: Systemet använder standardkonfigurationsmönster för .NET Aspire-tjänsten

Implementering av autentisering

Det här exemplet använder JWT-autentisering (JSON-webbtoken) för att skydda anslutningen mellan MCP-klienten och servern.

dotnet user-secrets --project ./src/McpTodo.ClientApp set McpServers:JWT:Token "$TOKEN"

MCP-klienten hämtar JWT-token från konfigurationen och innehåller den i HTTP-huvudena för autentisering vid anslutning till MCP-servern:

AdditionalHeaders = new Dictionary<string, string>
{
    { "Authorization", $"Bearer {config["McpServers:JWT:Token"]!}" }
}

Den här metoden säkerställer:

• Säker kommunikation: Systemet tillåter endast klienter med giltiga token att ansluta till MCP-servern
• Token-Based auktorisering: Med JWT-token kan systemet verifiera användare utan att lagra sessionsdata
• Konfigurationshantering: Systemet lagrar känsliga token på ett säkert sätt i användarhemligheter under utvecklingen

Azure Container Apps-autentiseringsintegrering

Infrastrukturen visar avancerade autentiseringsmönster med inbyggda funktioner för autentisering och auktorisering i Azure Container Apps ("Enkel autentisering"):

// containerapps-authconfigs.bicep
resource containerappAuthConfig 'Microsoft.App/containerApps/authConfigs@2024-10-02-preview' = {
  properties: {
    identityProviders: {
      azureActiveDirectory: {
        enabled: true
        registration: {
          clientId: clientId
          openIdIssuer: openIdIssuer
        }
      }
    }
    login: {
      tokenStore: {
        enabled: true
        azureBlobStorage: {
          blobContainerUri: '${storageAccount.properties.primaryEndpoints.blob}/token-store'
          managedIdentityResourceId: userAssignedIdentity.id
        }
      }
    }
  }
}

Avancerade autentiseringsfunktioner:

• Zero-Code-autentisering: Azure Container Apps tillhandahåller inbyggd autentisering
• Hanterad identitet för lagring: Systemet lagrar token på ett säkert sätt utan anslutningssträngar
• Autentiseringsuppgifter för federerad identitet: Systemet möjliggör arbetsbelastningsidentitet för Kubernetes-autentisering

Följande diagram visar säkerhetshandskakningen mellan komponenter:

Identifiering och registrering av verktyg

MCP-klienten identifierar tillgängliga verktyg från servern under komponentinitiering i Chat.razor:

protected override async Task OnInitializedAsync()
{
    messages.Add(new(ChatRole.System, SystemPrompt));
    tools = await McpClient.ListToolsAsync();
    chatOptions.Tools = [.. tools];
}

Så här fungerar verktygsidentifiering:

1. Serverfråga: McpClient.ListToolsAsync() skickar en begäran till MCP-servern för att visa tillgängliga verktyg
2. Schemahämtning: Servern skickar tillbaka verktygsdefinitioner med namn, beskrivningar och indatascheman
3. Verktygsregistrering: Systemet registrerar verktyg med ChatOptions -objektet, vilket gör dem tillgängliga för OpenAI-klienten
4. Typsäkerhet: Klassen McpClientTool ärver från AIFunction, vilket ger smidig integrering med Microsoft.Extensions.AI

Följande diagram visar hur verktygsscheman parsas och registreras:

OpenAI-integrering och funktionsanrop

Konfigurationen av chattklienten visar hur MCP-verktyg integreras med Azure OpenAI:

var chatClient = openAIClient.GetChatClient(config["OpenAI:DeploymentName"]).AsIChatClient();

builder.Services.AddChatClient(chatClient)
                .UseFunctionInvocation()
                .UseLogging();

Integreringsfördelar:

• Automatisk funktionsanrop: Tillägget .UseFunctionInvocation() aktiverar automatisk verktygskörning baserat på LLM-beslut
• Enkel verktygsåtkomst: MCP-verktyg fungerar som inbyggda funktioner för OpenAI-modellen
• Svarsbearbetning: Systemet lägger automatiskt till verktygsresultat i konversationsflödet

Real-Time chattimplementering

Chattgränssnittet i Chat.razor visar strömmande svar och verktygskörning med avancerade Blazor-mönster:

private async Task AddUserMessageAsync(ChatMessage userMessage)
{
    CancelAnyCurrentResponse();

    // Add the user message to the conversation
    messages.Add(userMessage);
    chatSuggestions?.Clear();
    await chatInput!.FocusAsync();

    // Stream and display a new response from the IChatClient
    var responseText = new TextContent("");
    currentResponseMessage = new ChatMessage(ChatRole.Assistant, [responseText]);
    currentResponseCancellation = new();
    await foreach (var update in ChatClient.GetStreamingResponseAsync([.. messages], chatOptions, currentResponseCancellation.Token))
    {
        messages.AddMessages(update, filter: c => c is not TextContent);
        responseText.Text += update.Text;
        ChatMessageItem.NotifyChanged(currentResponseMessage);
    }

    // Store the final response in the conversation, and begin getting suggestions
    messages.Add(currentResponseMessage!);
    currentResponseMessage = null;
    chatSuggestions?.Update(messages);
}

Funktioner för direktuppspelningsimplementering:

• Real-Time Uppdateringar: GetStreamingResponseAsync() skickar svarsuppdateringar bit för bit
• Verktygskörning: Systemprocessfunktionen anropar automatiskt under strömning
• Svarstid för användargränssnittet: ChatMessageItem.NotifyChanged() uppdaterar användargränssnittet i realtid
• Support för annullering: Användare kan avbryta långvariga åtgärder

Avancerade användargränssnittsmönster för Blazor

Implementeringen använder avancerade användargränssnittsmönster för realtidsuppdateringar:

Memory-Safe händelsehantering:

// ChatMessageItem.razor
private static readonly ConditionalWeakTable<ChatMessage, ChatMessageItem> SubscribersLookup = new();

public static void NotifyChanged(ChatMessage source)
{
    if (SubscribersLookup.TryGetValue(source, out var subscriber))
    {
        subscriber.StateHasChanged();
    }
}

Integrering av anpassade webbkomponenter:

// ChatMessageList.razor.js
window.customElements.define('chat-messages', class ChatMessages extends HTMLElement {
    connectedCallback() {
        this._observer = new MutationObserver(mutations => this._scheduleAutoScroll(mutations));
        this._observer.observe(this, { childList: true, attributes: true });
    }
    
    _scheduleAutoScroll(mutations) {
        // Debounce the calls and handle smart auto-scrolling
        cancelAnimationFrame(this._nextAutoScroll);
        this._nextAutoScroll = requestAnimationFrame(() => {
            const addedUserMessage = mutations.some(m => 
                Array.from(m.addedNodes).some(n => 
                    n.parentElement === this && n.classList?.contains('user-message')));
            // Smart scrolling logic...
        });
    }
});

Avancerad tillståndshantering:

// Chat.razor
private void CancelAnyCurrentResponse()
{
    // If a response was cancelled while streaming, include it in the conversation so it's not lost
    if (currentResponseMessage is not null)
    {
        messages.Add(currentResponseMessage);
    }
    
    currentResponseCancellation?.Cancel();
    currentResponseMessage = null;
}

Blazor UI-fördelar:

• Hybridwebbkomponenter: Systemet kombinerar Blazor Server med anpassade element för bättre prestanda
• Memory-Safe händelsehantering: Systemet använder ConditionalWeakTable för att förhindra minnesläckor
• Smart automatisk rullning: Systemet ger användarvänligt chattbeteende med avblåsning
• Graciös annullering: Systemet sparar delvis arbete när användare avbryter åtgärder

Flöde för begäran/svar

Så här flödar en typisk användarinteraktion genom systemet:

1. Användarindata: Användaren skriver ett meddelande som "Lägg till "Köp matvaror" i min att göra-lista
2. Meddelandebearbetning: Systemet lägger till meddelandet i konversationshistoriken
3. LLM-analys: Azure OpenAI analyserar begäran och bestämmer vilka verktyg som ska användas
4. Verktygsidentifiering: Modellen hittar rätt MCP-verktyg (till exempel addTodo)
5. Verktygskörning: MCP-klienten anropar servern med nödvändiga parametrar
6. Svarsbearbetning: Systemet lägger till serversvaret i konversationen
7. Uppdatering av användargränssnittet: Systemet visar resultatet för användaren i realtid

Följande diagram visar hur meddelanden flödar från användarindata via OpenAI till verktygskörning och tillbaka till användargränssnittet:

Asynkron mönsterhantering

Programmet visar avancerade asynkrona mönster för bakgrundsåtgärder:

// ChatSuggestions.razor
public void Update(IReadOnlyList<ChatMessage> messages)
{
    // Runs in the background and handles its own cancellation/errors
    _ = UpdateSuggestionsAsync(messages);
}

private async Task UpdateSuggestionsAsync(IReadOnlyList<ChatMessage> messages)
{
    cancellation?.Cancel();
    cancellation = new CancellationTokenSource();
    
    try
    {
        var response = await ChatClient.GetResponseAsync<string[]>(
            [.. ReduceMessages(messages), new(ChatRole.User, Prompt)],
            cancellationToken: cancellation.Token);
        // Handle response...
    }
    catch (Exception ex) when (ex is not OperationCanceledException)
    {
        await DispatchExceptionAsync(ex);
    }
}

Bakgrundsaktivitetsfördelar:

• Brand och glöm med säkerhet: Systemet använder _ = mönster med korrekt undantagshantering
• Minskning av smart kontext: Systemet begränsar konversationshistoriken för att förhindra tokens spill
• Smart annullering: Systemet rensar konkurrerande åtgärder korrekt

Felhantering och återhämtning

Implementeringen innehåller flera motståndskraftsmönster:

private void CancelAnyCurrentResponse()
{
    // If a response was cancelled while streaming, include it in the conversation so it's not lost
    if (currentResponseMessage is not null)
    {
        messages.Add(currentResponseMessage);
    }

    currentResponseCancellation?.Cancel();
    currentResponseMessage = null;
}

Motståndskraftsfunktioner:

• Graciös annullering: Systemet sparar pågående svar när användarna avbryter dem
• Anslutningsåterställning: SSE-transporten hanterar anslutningen avbryts automatiskt
• Tillståndshantering: Användargränssnittstillståndet förblir konsekvent under fel
• Loggningsintegrering: Systemet ger fullständig loggning för felsökning och övervakning

Observerbarhets- och hälsokontroller

Programmet innehåller avancerade observerbarhetsmönster:

Konfiguration av smart hälsokontroll:

// Extensions.cs
public static WebApplication MapDefaultEndpoints(this WebApplication app)
{
    if (app.Environment.IsDevelopment())
    {
        // All health checks must pass for app to be considered ready
        app.MapHealthChecks(HealthEndpointPath);
        
        // Only health checks tagged with "live" must pass for app to be considered alive
        app.MapHealthChecks(AlivenessEndpointPath, new HealthCheckOptions
        {
            Predicate = r => r.Tags.Contains("live")
        });
    }
    return app;
}

OpenTelemetry med intelligent filtrering:

// Extensions.cs
.AddAspNetCoreInstrumentation(tracing =>
    // Exclude health check requests from tracing
    tracing.Filter = context =>
        !context.Request.Path.StartsWithSegments(HealthEndpointPath)
        && !context.Request.Path.StartsWithSegments(AlivenessEndpointPath)
)

Observerbarhetsfördelar:

• Environment-Aware slutpunkter: Exponering för säkerhetsmedveten hälsokontroll
• Liveness vs Readiness: Hälsokontrollmönster i Kubernetes-stil
• Minskning av telemetribrus: Filtrera bort rutinmässiga hälsokontroller från spårningar

Konfiguration och miljökonfiguration

Programmet stöder flera miljöer via konfiguration:

var openAIClient = Constants.GitHubModelEndpoints.Contains(endpoint.TrimEnd('/'))
                   ? new OpenAIClient(credential, openAIOptions)
                   : new AzureOpenAIClient(new Uri(endpoint), credential);

Konfigurationsalternativ:

• Azure OpenAI: Produktionsdistributioner använder vanligtvis Azure OpenAI-tjänsten
• GitHub-modeller: Utvecklingsscenarier kan använda GitHub-modeller
• Lokal utveckling: Stöd för lokala MCP-serverinstanser
• Containerdistribution: Azure Container Apps för produktionsvärd

Rensa resurser

När du har använt MCP-agenten rensar du de resurser som du har skapat för att undvika onödiga kostnader.

Följ dessa steg för att rensa resurser:

• Ta bort De Azure-resurser som skapats av Azure Developer CLI genom att köra följande kommando i terminalen längst ned på skärmen:

  azd down --purge --force
  

Rensa GitHub Codespaces

Få hjälp

Logga problemet till lagringsplatsens problem.

Relaterade resurser

• Skapa en TypeScript MCP-server med Hjälp av Azure Container Apps