.NET OpenAI-ügynök létrehozása MCP-kiszolgálóval a Azure Container Apps

Ez a cikk bemutatja, hogyan hozhat létre modellkörnyezeti protokoll (MCP) ügynököt .NET használatával. Ebben a mintában az MCP-ügyfél (C#/.NET) egy (TypeScriptben írt) MCP-kiszolgálóhoz csatlakozik egy teendőlista kezeléséhez. Az ügyfél megkeresi a kiszolgálóról elérhető eszközöket, és elküldi őket egy Azure OpenAI-modellnek. Ezután a felhasználók mindennapi nyelvet használva beszélhetnek a teendő-rendszerrel.

A kód megismerése

Tekintse meg az OpenAI MCP ügynök építőelem AI sablonját. Ez a példa bemutatja, hogyan hozhat létre olyan OpenAI-ügynököt, amely MCP-ügyfél használatával használ egy meglévő MCP-kiszolgálót.

A minta működésének megismeréséhez ugorjon a kódbemutató szakaszra .

Architekturális áttekintés

Az alábbi ábra a mintaalkalmazás egyszerű architektúráját mutatja be: Diagram, amely a Visual Studio Code-ból üzemeltetett ügynököt és MCP-ügyfelet az MCP szerverhez mutatja.

  • MCP-ügyfél: Csatlakozik az MCP-kiszolgálóhoz, és megkeresi az elérhető eszközöket
  • Chat-ügyfél: Az Azure OpenAI a természetes nyelv megértésére használható
  • Blazor felhasználói felület: Egy webes felületet biztosít, ahol a felhasználók cseveghetnek
  • Átviteli réteg: Server-Sent eseményeket (SSE) használ az üzenetek valós idejű küldéséhez
  • Hitelesítés: JWT-jogkivonatokkal védi a kapcsolatot

Az MCP-kiszolgáló tárolóalapú alkalmazásként fut a Azure Container Apps (ACA) rendszeren. TypeScript-háttérrendszerrel biztosít eszközöket az MCP-ügyfélnek a Model Context Protocolon keresztül. Minden eszköz egy háttérbeli SQLite-adatbázissal működik.

Megjegyzés:

Látogasson el a Build a TypeScript MCP server using Azure Container Apps oldalra, hogy megtekinthesse a cikkben használt TypeScript MCP-kiszolgáló kódleírását.

Költség

A költségek alacsony szinten tartása érdekében ez a minta alapszintű vagy fogyasztási tarifacsomagokat használ a legtöbb erőforráshoz. Igény szerint állítsa be a szintet, és törölje az erőforrásokat, ha elkészült a díjak elkerülése érdekében.

Előfeltételek

A fejlesztői tároló tartalmazza a cikkhez szükséges összes függőséget. Futtathatja a GitHub Codespaces-ben (böngészőben) vagy helyben a Visual Studio Code használatával.

A cikk követéséhez győződjön meg arról, hogy megfelel az alábbi előfeltételeknek:

Foundry gpt-5-mini modell üzembe helyezése az Foundry VS Code-bővítmény használatával

Helyezzen üzembe egy gpt-5-mini modellt az Foundry bővítmény használatával Visual Studio Code a következő lépésekkel:

Foundry-projekt létrehozása és a modell üzembe helyezése

Az OpenAI modell kapcsolati sztring létrehozása

  1. A gpt-5-mini modell üzembe helyezése után kattintson a jobb gombbal a modellre az Foundry bővítményben, és válassza az API-kulcs másolása lehetőséget a modell API-kulcsának vágólapra másolásához.

  2. Ezután kattintson a jobb gombbal az üzembe helyezett gpt-5-mini modellre az Foundry bővítményben, és válassza a Végpont másolása lehetőséget a modell végpontjának vágólapra másolásához, ahogyan az alábbi képernyőképen látható:

    Képernyőkép az üzembe helyezett modell helyi menüjéről a Végpont másolása és az API-kulcs másolása beállítás kiemelésével.

  3. Végül hozzon létre egy connection string az üzembe helyezett gpt-5-mini modellhez a másolt végpont és AZ API-kulcs használatával a következő formátumban: Endpoint=<AZURE_OPENAI_ENDPOINT>;Key=<AZURE_OPENAI_API_KEY>. Erre a connection string a cikk későbbi részében lesz szüksége.

Nyílt fejlesztési környezet

Az alábbi lépésekkel előre konfigurált fejlesztői környezetet állíthat be az összes szükséges függőséggel együtt.

GitHub Codespaces egy GitHub által felügyelt fejlesztési tárolót futtat a webes Visual Studio Code felülettel. A legegyszerűbb beállításhoz használja GitHub codespace-eket, mivel a cikkhez előre telepített szükséges eszközökkel és függőségekkel rendelkezik.

Fontos

Minden GitHub-fiók legfeljebb 60 órán át használhatja a Codespace-eket havonta két alapvető példánnyal. További információkért tekintse meg a GitHub Codespaces havi tárhelyét és alapóra-kiosztását.

Az alábbi lépésekkel hozzon létre egy új GitHub codespace-t a main GitHub adattár Azure-Samples/openai-mcp-agent-dotnet ágán.

  1. Kattintson a jobb gombbal az alábbi gombra, és válassza a Hivatkozás megnyitása az új ablakban lehetőséget. Ez a művelet lehetővé teszi, hogy a fejlesztési környezet és a dokumentáció egymás mellett legyen megnyitva.

    Open in GitHub Codespaces

  2. A Kódtér létrehozása lapon tekintse át, majd válassza az Új kódtér létrehozása lehetőséget.

  3. Várja meg, amíg a codespace elindul. Eltarthat néhány percig.

  4. Győződjön meg arról, hogy az üzembe helyezett modell neve gpt-5-mini. Ha az üzembe helyezett modell eltérő, frissítse a src/McpTodo.ClientApp/appsettings.json helyőrzőt a megfelelő üzembe helyezési névvel.

    {
  "OpenAI": {
    // Make sure this is the right deployment name.
    "DeploymentName": "gpt-5-mini"
  }
}

  5. Jelentkezzen be a Azure a Azure fejlesztői parancssori felülettel a képernyő alján lévő terminálban.

    azd auth login

  6. Másolja ki a kódot a terminálból, majd illessze be egy böngészőbe. Kövesse az utasításokat a Azure-fiókjával való hitelesítéshez.

A többi feladatot ebben a fejlesztési tárolóban hajtja végre.

Megjegyzés:

Az MCP-ügynök helyben történő futtatása:

  1. Állítsa be a környezetet a mintaadattár Getting started szakaszában leírtak szerint.
  2. Telepítse az MCP-kiszolgálót az Get MCP Server App szakasz utasításait követve a mintaadattárban.
  3. Az MCP-ügynök helyi futtatásához kövesse a mintaadattár Futtatás helyileg szakaszában található utasításokat.
  4. A folytatáshoz ugorjon a TODO MCP-ügynök használata szakaszra.

Üzembe helyezés és futtatás

A mintaadattár tartalmazza az MCP-ügynök Azure üzembe helyezéshez szükséges összes kódot és konfigurációs fájlt. Az alábbi lépések végigvezetik az MCP ügynök mintapéldájának Azure-ba történő üzembe helyezési folyamatán.

Üzembe helyezés az Azure-ra

Fontos

Azure erőforrásai ebben a részben azonnal pénzbe kerülnek, még akkor is, ha a parancs befejezése előtt leállítja azt.

A JWT-jogkivonat beállítása

  • Állítsa be az MCP-kiszolgáló JWT-jogkivonatát a képernyő alján található terminál következő parancsának futtatásával:

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

    # PowerShell
./scripts/Set-JwtToken.ps1

JWT-jogkivonat hozzáadása az azd környezeti konfigurációhoz

  1. Adja hozzá a JWT-jogkivonatot az azd környezeti konfigurációhoz a képernyő alján található terminál következő parancsának futtatásával:

    # 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

    Megjegyzés:

    Alapértelmezés szerint az MCP-ügyfélalkalmazást az ACA beépített hitelesítési funkciója védi. A következő beállítással kikapcsolhatja ezt a funkciót a futtatás azd up előtt:

    azd env set USE_LOGIN false

  2. Futtassa a következő Azure Fejlesztői parancssori felület parancsot Azure erőforrás-kiépítéshez és a forráskód üzembe helyezéséhez:

    azd up

  3. Az alábbi táblázat segítségével válaszolhat a kérdésekre:

    Haladéktalan Válasz
    Környezet neve Használjon rövid kisbetűs nevet. Adja hozzá a nevét vagy aliasát. Például: my-mcp-agent. A környezet neve az erőforráscsoport nevének részévé válik.
    Subscription Válassza ki azt az előfizetést, amelyben erőforrásokat szeretne létrehozni.
    Hely (üzemeltetéshez) Válassza ki a modell üzembehelyezési helyét a listából.
    OpenAI kapcsolati karakterlánc Illessze be a korábban létrehozott OpenAI modell csatlakozási karakterláncát a OpenAI Modell csatlakozási karakterláncának létrehozása szakaszba.

  4. Az alkalmazás üzembe helyezése 5–10 percet vesz igénybe.

  5. Az üzembe helyezés befejeződése után az MCP-ügynök a kimenet URL-címével érhető el. Az URL-cím így néz ki:

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

  6. Nyissa meg az URL-címet egy webböngészőben az MCP-ügynök használatához.

A TODO MCP-ügynök használata

Az MCP-ügynök futtatása után az általa biztosított eszközöket ügynök módban használhatja. Az MCP-eszközök használata ügynök módban:

  1. Lépjen az ügyfélalkalmazás URL-címére, és jelentkezzen be az alkalmazásba.

    Megjegyzés:

    ha ezt az USE_LOGIN értéket falseállítja be, előfordulhat, hogy a rendszer nem kéri a bejelentkezést.

  2. Írja be a csevegés beviteli mezőjébe a "Szerdán e-mailt kell küldenem a felettesemnek" üzenetet, és figyelje meg, hogy a rendszer szükség szerint automatikusan meghívja az eszközöket.

  3. Az MCP-ügynök az MCP-kiszolgáló által biztosított eszközökkel teljesíti a kérést, és választ ad vissza a csevegőfelületen.

  4. Kísérletezzen más kérdésekkel, például:

    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.

A kód megismerése

A mintaadattár tartalmazza az MCP-ügynök Azure üzembe helyezéshez szükséges összes kódot és konfigurációs fájlt. Az alábbi szakaszok végigvezetik az MCP-ügynökkód fő összetevőin.

MCP-ügyfél konfigurálása és beállítása

Az alkalmazás beállítja az MCP-ügyfelet a következőben Program.cs: . Ez a konfiguráció határozza meg a csatlakozás módját és a használni kívánt beállításokat. A kód számos speciális mintát használ, például .NET Aspire integrációt és szolgáltatás alapértelmezéseket:

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();
});

Főbb megvalósítási részletek:

  • Átviteli konfiguráció: SseClientTransportOptions támogatja az Server-Sent eseményeket (SSE) és a streamelhető HTTP-átvitelt. Az átviteli módszer a végpont URL-címétől függ – a /sse végződő végpontok Server-Sent eseményeket használnak, míg a /mcp végződő végpontok streamelhető HTTP-t alkalmaznak. Ez a megközelítés valós idejű kommunikációt tesz lehetővé az ügyfél és a kiszolgáló között
  • Hitelesítési fejlécek: A JWT-jogkivonatok a AdditionalHeaders kiszolgálói kommunikáció biztonságossá tételéhez kerülnek
  • Ügyféladatok: McpClientOptions közli a kiszolgálóval az ügyfél nevét és verzióját
  • Gyári minta: McpClientFactory.CreateAsync() csatlakoztatja és végrehajtja a protokoll kézfogását

.NET Aspire szolgáltatás alapértelmezett integrációja

Az alkalmazás .NET Aspire szolgáltatás alapértelmezett mintáját használja a horizontális problémákhoz:

// 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;
}

A szolgáltatás alapértelmezett előnyei:

  • Írható bővítménymetelyek: A rendszer tiszta szerkesztőmintát használ a megosztott funkciók hozzáadásához
  • Standard rugalmasságkezelők: A rendszer beépített újrapróbálkozási, áramkör megszakító, és időtúllépési szabályokat biztosít Önnek.
  • Szolgáltatásfelderítési integráció: A rendszer automatikusan megkeresi a szolgáltatásokat tárolókörnyezetekben
  • OpenTelemetry alapértelmezés szerint: A rendszer teljes figyelést kap a beállítási munka nélkül

Az alábbi ábra a keresztirányú aggodalmak és az alkalmazásszolgáltatások közötti kapcsolatot mutatja be:

A keresztirányú aggodalmak és az alkalmazásszolgáltatások közötti kapcsolatot bemutató ábra.

Konfigurációs URL-feloldás

A minta kifinomult URL-feloldásokat tartalmaz a különböző környezetekhez:

// 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...
}

Konfigurációkezelési funkciók:

  • Szolgáltatásfelderítési absztrakció: A rendszer tisztán kezeli a fejlesztési és éles URL-címeket
  • Protokoll-egyeztetés: A rendszer először a HTTPS-t választja, majd visszaesik a HTTP-be
  • konfigurációs konvenció: A rendszer szabványos .NET Aspire szolgáltatásbeállítási mintákat használ

Hitelesítés implementálása

Ez a minta JWT (JSON Web Token) hitelesítéssel biztosítja az MCP-ügyfél és a kiszolgáló közötti kapcsolatot.

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

Megjegyzés:

A szkriptek automatikusan létrehozták a $TOKEN változót, amikor a Bash (set-jwttoken.sh) vagy a PowerShell (Set-JwtToken.ps1) szkriptet futtatta az Azure telepítés szakaszának korábbi részében. Ezek a szkriptek a következő lépéseket hajtják végre:

  1. A JWT-jogkivonat létrehozásához futtassa npm run generate-token az MCP-kiszolgálóalkalmazásban.
  2. A létrehozott .env fájl elemzése a JWT_TOKEN érték kinyeréséhez
  3. Automatikusan tárolja az MCPClient .NET felhasználói titkos kulcsaiban

Az MCP-ügyfél lekéri a JWT-jogkivonatot a konfigurációból, és a HTTP-fejlécekbe foglalja a hitelesítéshez, amikor az MCP-kiszolgálóhoz csatlakozik:

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

Ez a megközelítés a következőket biztosítja:

  • Biztonságos kommunikáció: A rendszer csak az érvényes jogkivonatokkal rendelkező ügyfelek számára engedélyezi az MCP-kiszolgálóhoz való csatlakozást
  • Token-Based Engedélyezés: A JWT-jogkivonatok lehetővé teszik a rendszer számára, hogy munkamenet-adatok tárolása nélkül ellenőrizze a felhasználókat
  • Konfigurációkezelés: A rendszer biztonságosan tárolja a bizalmas jogkivonatokat a felhasználói titkos kódokban a fejlesztés során

Azure Container Apps hitelesítési integráció

Az infrastruktúra speciális hitelesítési mintákat jelenít meg Azure Container Apps beépített hitelesítési és engedélyezési funkciókkal ("Easy Auth"):

// 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
        }
      }
    }
  }
}

Speciális hitelesítési funkciók:

  • Zero-Code Hitelesítés: Azure Container Apps beépített hitelesítést biztosít
  • Kezelt identitás a tároláshoz: A rendszer biztonságosan tárolja a tokent kapcsolati karakterláncok nélkül.
  • Összevont identitás hitelesítő adatai: A rendszer engedélyezi a számítási feladatok identitását a Kubernetes-stílusú hitelesítéshez

Az alábbi ábra az összetevők közötti biztonsági kézfogást mutatja be:

Az összetevők közötti biztonsági kézfogást bemutató ábra.

Eszközfelderítés és -regisztráció

Az MCP-ügyfél felderíti a kiszolgálóról elérhető eszközöket az összetevők inicializálása során a következő helyen Chat.razor:

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

Az eszközfelderítés működése:

  1. Kiszolgálói lekérdezés: McpClient.ListToolsAsync() kérést küld az MCP-kiszolgálónak az elérhető eszközök listázásához
  2. Sémalekérés: A kiszolgáló neveket, leírásokat és bemeneti sémákat tartalmazó eszközdefiníciókat küld vissza
  3. Eszközregisztráció: A rendszer regisztrálja az eszközöket az ChatOptions objektummal, így azok elérhetővé válnak az OpenAI-ügyfél számára
  4. Típusbiztonság: Az McpClientTool osztály örökli a AIFunction osztályból, lehetővé téve a zökkenőmentes integrációt a Microsoft.Extensions.AI-vel.

Az alábbi ábra az eszközséma elemzését és regisztrálását mutatja be:

Az eszközfelderítést és a regisztrációs folyamatot bemutató ábra.

OpenAI-integráció és függvényhívás

A csevegési ügyfélkonfiguráció bemutatja, hogyan integrálhatók az MCP-eszközök Azure OpenAI-val:

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

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

Integrációs előnyök:

  • Automatikus függvényhívás: A .UseFunctionInvocation() bővítmény az LLM-döntések alapján bekapcsolja az automatikus eszközvégrehajtást
  • Egyszerű eszközhozzáférés: Az MCP-eszközök beépített függvényként működnek az OpenAI-modellhez
  • Válaszfeldolgozás: A rendszer automatikusan hozzáadja az eszköz eredményeit a beszélgetési folyamathoz

Real-Time csevegés implementálása

A csevegési felület speciális Blazor-mintákkal mutatja be a Chat.razor streamelési válaszokat és az eszközök végrehajtását:

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);
}

Streamelési megvalósítási funkciók:

  • Real-Time Frissítések: GetStreamingResponseAsync() a válaszfrissítéseket bitenként továbbítja
  • Eszközvégrehajtás: A rendszer automatikusan dolgozza fel a függvényhívásokat a streamelés során
  • Felhasználói felület válaszkészsége: ChatMessageItem.NotifyChanged() valós időben frissíti a felhasználói felületet
  • Lemondási támogatás: A felhasználók megszakíthatják a hosszú ideig futó műveleteket

Speciális Blazor felhasználói felületi minták

Az implementáció speciális felhasználói felületi mintákat használ a valós idejű frissítésekhez:

Memory-Safe eseménykezelés:

// 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();
    }
}

Egyéni webösszetevők integrációja:

// 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...
        });
    }
});

Speciális állapotkezelés:

// 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;
}

A Blazor felhasználói felület előnyei:

  • Hibrid webösszetevők: A rendszer a Blazor Servert egyéni elemekkel kombinálja a jobb teljesítmény érdekében
  • Memory-Safe eseménykezelés: A rendszer a ConditionalWeakTable használatával megakadályozza a memóriaszivárgást
  • Intelligens automatikus görgetés: A rendszer felhasználóbarát csevegési funkciókat biztosít a debounce kezelésével.
  • Elegáns lemondás: A rendszer részleges munkát ment, amikor a felhasználók megszakítják a műveleteket

Kérelem-/válaszfolyamat

Az alábbiak szerint halad át egy tipikus felhasználói interakció a rendszeren:

  1. Felhasználói bevitel: A felhasználó beír egy olyan üzenetet, mint "Adj hozzá 'Vásárlási listához' a teendőlistámhoz"
  2. Üzenetfeldolgozás: A rendszer hozzáadja az üzenetet a beszélgetési előzményekhez
  3. LLM Analysis: Azure OpenAI elemzi a kérést, és meghatározza, hogy mely eszközöket használja
  4. Eszközfelderítés: A modell megkeresi a megfelelő MCP-eszközt (például addTodo)
  5. Eszköz végrehajtása: Az MCP-ügyfél meghívja a kiszolgálót a szükséges paraméterekkel
  6. Válaszfeldolgozás: A rendszer hozzáadja a kiszolgálói választ a beszélgetéshez
  7. Felhasználói felület frissítése: A rendszer valós időben jeleníti meg az eredményt a felhasználónak

Az alábbi ábra bemutatja, hogyan áramlanak az üzenetek a felhasználói bemenettől az OpenAI-on át az eszközvégrehajtásig és vissza a felhasználói felületre:

A kérés/válasz folyamatot ábrázoló diagram.

Aszinkron mintakezelés

Az alkalmazás a háttérműveletek kifinomult aszinkron mintáit mutatja be:

// 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);
    }
}

Háttérfeladat előnyei:

  • Fire-and-Forget with Safety: A rendszer a _ = mintát alkalmazza, megfelelő kivételkezeléssel.
  • Intelligens környezet csökkentése: A rendszer korlátozza a beszélgetések előzményeit, hogy megakadályozza a token túlcsordulását
  • Intelligens lemondás: A rendszer megfelelően tisztítja meg a versengő műveleteket

Hibakezelés és rugalmasság

Az implementáció számos rugalmassági mintát tartalmaz:

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;
}

Rugalmassági funkciók:

  • Zökkenőmentes lemondás: A rendszer menti a folyamatban lévő válaszokat, amikor a felhasználók megszakítják azokat.
  • Kapcsolat helyreállítása: Az SSE-átvitel automatikusan kezeli a kapcsolat megszakadését
  • Állapotkezelés: A felhasználói felület állapota konzisztens marad a hibák során
  • Naplózási integráció: A rendszer teljes naplózást biztosít a hibakereséshez és a monitorozáshoz

Megfigyelhetőség és állapot-ellenőrzések

Az alkalmazás kifinomult megfigyelhetőségi mintákat tartalmaz:

Intelligens állapot-ellenőrzési konfiguráció:

// 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;
}

OpenTelemetria intelligens szűréssel:

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

Megfigyelhetőségi előnyök:

  • Környezetérzékeny végpontok: Biztonságtudatos állapotellenőrzés kitettsége
  • Élőség és készültség: Kubernetes-stílusú állapotellenőrzési minták
  • Telemetriai zajcsökkentés: A rutinállapot-ellenőrzések kiszűrése a nyomkövetésekből

Konfiguráció és környezet beállítása

Az alkalmazás konfigurációval több környezetet támogat:

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

Konfigurációs beállítások:

  • Azure OpenAI: Az éles üzembe helyezések általában az Azure OpenAI Szolgáltatást használják
  • GitHub modellek: A fejlesztési forgatókönyvek GitHub modelleket használhatnak
  • Helyi fejlesztés: Helyi MCP-kiszolgálópéldányok támogatása
  • Konténer telepítés: Azure Container Apps éles üzemeltetéshez

Erőforrások tisztítása

Miután befejezte az MCP-ügynök használatát, törölje a létrehozott erőforrásokat, hogy elkerülje a szükségtelen költségeket.

Az erőforrások törléséhez kövesse az alábbi lépéseket:

  • Törölje a Azure fejlesztői parancssori felület által létrehozott Azure erőforrásokat a képernyő alján található terminálon a következő paranccsal:

    azd down --purge --force

GitHub kódterek takarítása

Törölje a GitHub Codespaces környezetet, hogy maximálisan kihasználhassa a magonkénti ingyenes órákat.

Fontos

GitHub-fiókjának ingyenes tárhelyéről és magóráiról további információt a GitHub Codespaces által havonta biztosított tárhely és magórák című témakörben talál.

  1. Jelentkezzen be a GitHub Codespaces felületére.

  2. Keresse meg a Azure-Samples/openai-mcp-agent-dotnet GitHub adattárból létrehozott aktív kódtereket.

  3. Nyissa meg a kódtér helyi menüjét, és válassza a Törléslehetőséget.

Segítség kérése

Rögzítse a problémát a tároló Issues lapján.

  • TypeScript MCP-kiszolgáló létrehozása Azure Container Apps
  • Last updated on