Öğretici: Microsoft Agent Framework veya Foundry Agent Service (.NET) ile Azure App Service'te aracı web uygulaması oluşturma

Bu öğreticide, mevcut bir veri temelli ASP.NET Core CRUD uygulamasına aracılık özelliğinin nasıl ekleneceği gösterilmektedir. Bunu iki farklı yaklaşım kullanarak yapar: Microsoft Agent Framework ve Foundry Agent Service.

Web uygulamanızın zaten alışveriş, otel rezervasyonu veya veri yönetimi gibi kullanışlı özellikleri varsa, bu işlevleri araç olarak ( Microsoft Agent Framework için) veya openAPI uç noktası ( Foundry Agent Service için) olarak sarmalayarak web uygulamanıza aracı işlevselliği eklemek oldukça kolaydır. Bu öğreticide basit bir to-do listesi uygulamasıyla başlayacaksınız. Sonunda, App Service uygulamasında bir aracıyla görev oluşturabilecek, güncelleştirebilecek ve yönetebileceksiniz.

Hem Microsoft Agent Framework hem de Foundry Agent Service, yapay zeka destekli özelliklerle aracı web uygulamaları oluşturmanıza olanak tanır. Aşağıdaki tabloda dikkat edilmesi gereken bazı noktalar ve dengeler gösterilmektedir:

Consideration Microsoft Aracı Çerçevesi Döküm Acentası Hizmeti
Performance Hızlı (yerel olarak çalışır) Daha yavaş (yönetilen, uzak hizmet)
Development Tam kod, maksimum denetim Düşük kod, hızlı tümleştirme
Testing Kodda manuel/birim testler Hızlı test için yerleşik oyun alanı
Scalability App-managed Azure tarafından yönetilen, otomatik ölçeklendirilen
Güvenlik korumaları Özel uygulama gerekiyor Yerleşik içerik güvenliği ve moderasyonu
Kimlik Özel uygulama gerekiyor Yerleşik aracı kimliği ve kimlik doğrulaması
Enterprise Özel tümleştirme gerekiyor Yerleşik Microsoft 365/Teams dağıtımı ve Microsoft 365 entegre edilmiş araç çağrıları.

Bu eğitimde şunları öğreniyorsunuz:

  • Mevcut uygulama işlevselliğini Microsoft Agent Framework araçlarına dönüştürün.
  • Microsoft Agent Framework aracısına araçları ekleyin ve bir web uygulamasında kullanın.
  • Mevcut uygulama işlevselliğini Foundry Agent Service için OpenAPI uç noktasına dönüştürün.
  • Web uygulamasında bir Foundry aracısını çağırma.
  • Yönetilen kimlik bağlantısı için gerekli izinleri atayın.

Prerequisites

Codespaces ile örneği açma

Başlamanın en kolay yolu, gerekli tüm araçların önceden yüklenmiş olduğu eksiksiz bir geliştirme ortamı sağlayan GitHub Codespaces'ı kullanmaktır.

  1. konumundaki GitHub deposuna https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-ai-foundry-agentgidin.

  2. Kod düğmesini seçin, Codespaces sekmesini ve ardından Main üzerinde kod alanı oluştur'u seçin.

  3. Codespace'ınızın başlatılması için birkaç dakika bekleyin. Hazır olduğunuzda, tarayıcınızda tam olarak yapılandırılmış bir geliştirme ortamı görürsünüz.

  4. Uygulamayı yerel olarak çalıştırın:

    dotnet run

  5. Uygulamanızın 5280 numaralı bağlantı noktasında çalıştığınıgördüğünüzde Tarayıcıda Aç'ı seçin ve birkaç görev ekleyin.

Aracı kodunu gözden geçirme

Her iki yaklaşım da aynı uygulama desenini kullanır; burada aracı bir sağlayıcıda hizmet olarak (Program.cs) başlatılır ve ilgili Blazor bileşenine eklenir.

AgentFrameworkProvider, Services/AgentFrameworkProvider.cs'da başlatılır. Başlatma kodu aşağıdakileri yapar:

  • AzureOpenAIClient kullanarak Azure OpenAI'den bir oluşturur.
  • CRUD uygulaması işlevselliğini kapsayan TaskCrudTool örneğini alır (Araçlar/TaskCrudTool.cs içinde). Description Araç yöntemlerindeki öznitelikler aracının bunları nasıl çağıracaklarını belirlemesine yardımcı olur.
  • CreateAIAgent() kullanarak AIFunctionFactory.Create() aracılığıyla kaydedilen talimatlar ve araçlarla bir yapay zeka aracısı oluşturur.
  • Agentin gezinti boyunca konuşmayı sürdürmesini sağlamak için bir iş parçacığı oluşturur.
// Create IChatClient
IChatClient chatClient = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetChatClient(deployment)
    .AsIChatClient();

// Get TaskCrudTool instance from service provider
var taskCrudTool = sp.GetRequiredService<TaskCrudTool>();

// Create agent with tools
var agent = chatClient.CreateAIAgent(
    instructions: @"You are an agent that manages tasks using CRUD operations. 
        Use the provided functions to create, read, update, and delete tasks. 
        Always call the appropriate function for any task management request.
        Don't try to handle any requests that are not related to task management.
        When handling requests, if you're missing any information, don't make it up but prompt the user for it instead.",
    tools:
    [
        AIFunctionFactory.Create(taskCrudTool.CreateTaskAsync),
        AIFunctionFactory.Create(taskCrudTool.ReadTasksAsync),
        AIFunctionFactory.Create(taskCrudTool.UpdateTaskAsync),
        AIFunctionFactory.Create(taskCrudTool.DeleteTaskAsync)
    ]);

// Create thread for this scoped instance (persists across navigation)
var thread = agent.GetNewThread();

return (agent, thread);

Kullanıcı bir ileti her gönderdiğinde, Blazor bileşeni (Components/Pages/AgentFrameworkAgent.razor içinde), kullanıcı girdisi ve aracı iş parçacığı ile Agent.RunAsync() çağırır. Ajan iş parçacığı sohbet geçmişini takip eder.

var response = await this.Agent.RunAsync(sentInput, this.agentThread);

Örnek uygulamayı dağıtma

Örnek depo, yönetilen kimlikli bir App Service uygulaması oluşturan ve örnek uygulamanızı dağıtan bir Azure Geliştirici CLI (AZD) şablonu içerir.

  1. Terminalde Azure Geliştirici CLI'sini kullanarak Azure'da oturum açın:

    azd auth login

    Kimlik doğrulama işlemini tamamlamak için yönergeleri izleyin.

  2. Azure App Service uygulamasını AZD şablonuyla dağıtın:

    azd up

  3. İstendiğinde aşağıdaki yanıtları verin:

    Question Answer
    Yeni bir ortam adı girin: Benzersiz bir ad yazın.
    Kullanılacak azure aboneliğini seçin: Aboneliği seçin.
    Kullanılacak kaynak grubunu seçin: Yeni kaynak grubu oluştur'u seçin.
    Kaynak grubunun oluşturulacağı konumu seçin: İsveç Orta seçin.
    Yeni kaynak grubu için bir ad girin: Enter yazın.

  4. AZD çıktısında, uygulamanızın URL'ini bulun ve tarayıcıda bu URL'ye gidin. AZD çıktısındaki URL şöyle görünür:

     Deploying services (azd deploy)

   (✓) Done: Deploying service web
   - Endpoint: <URL>

  5. Otomatik olarak oluşturulan OpenAPI şemasını varsayılan /openapi/v1.json yolda açmak için OpenAPI şema öğesini seçin. Bu şemaya daha sonra ihtiyacınız olacak.

  6. Dağıtım başarılı olduktan sonra dağıtılan uygulamanız için bir URL görürsünüz.

    Artık sistem tarafından atanan yönetilen kimliğe sahip bir App Service uygulamanız var.

Microsoft Foundry kaynağını oluşturma ve yapılandırma

  1. Dökümhane portalında, en üstteki Yeni Dökümhane radyo düğmesinin etkin olarak ayarlandığından emin olun ve bir proje oluşturun.

  2. Seçtiğiniz bir modeli dağıtın (bkz. Microsoft Foundry Hızlı Başlangıcı: Kaynak oluşturma).

  3. Model oyun alanının en üstünden model adını kopyalayın.

  4. Azure OpenAI uç noktasını almanın en kolay yolu hala klasik portaldandır. Yeni Dökümhane seçenek düğmesini, ardından Azure OpenAI'yi seçin ve daha sonra için Azure OpenAI uç noktasındaki URL'yi kopyalayın.

    OpenAI uç noktasının ve dökümhane portalındaki döküm projesi uç noktasının nasıl kopyalanmasını gösteren ekran görüntüsü.

Gerekli izinleri ata

  1. Yeni Foundry portalının üst menüsünden Çalışma'yı ve ardından Yönetici'yi seçin. Foundry projenizin satırında iki bağlantı görmeniz gerekir. Ad sütunundaki kaynak Foundry projesi kaynağıdır, Ana kaynak sütunundaki kaynak ise Foundry kaynağıdır.

    Dökümhane kaynağına veya dökümhane proje kaynağına hızlı bir şekilde gitmeyi gösteren ekran görüntüsü.

  2. Üst Kaynak içinde Foundry kaynağı'nı ve ardından Azure portalında bu kaynağı yönetin seçin. Azure portalından, dağıtılan web uygulamasına kaynak için rol tabanlı erişim atayabilirsiniz.

  3. App Service uygulamasının yönetilen kimliği için aşağıdaki rolü ekleyin:

    Hedef kaynak Gerekli rol Şunun için gerekli:
    Döküm Bilişsel Hizmetler OpenAI Kullanıcısı Microsoft Agent Framework'teki sohbet tamamlama hizmeti.

    Yönergeler için bkz. Azure portal kullanarak Azure rollerini atama.

Örnek uygulamanızda bağlantı değişkenlerini yapılandırma

  1. appsettings.json açın. Daha önce Foundry portalından kopyaladığınız değerleri kullanarak aşağıdaki değişkenleri yapılandırın:

    Variable Description
    AzureOpenAIEndpoint Azure OpenAI uç noktası (klasik Foundry portalından kopyalanır).
    ModelDeployment Dağıtımdaki model adı (yeni Foundry portalındaki model oyun alanından kopyalanır).

    Note

    Öğreticiyi basit tutmak için, appsettings.json'daki bu değişkenleri kullanacak ve bunların App Service'teki uygulama ayarlarıyla üzerine yazılmasından kaçınacaksınız.

    Note

    Öğreticiyi basit tutmak için, appsettings.json'daki bu değişkenleri kullanacak ve bunların App Service'teki uygulama ayarlarıyla üzerine yazılmasından kaçınacaksınız.

  2. Azure CLI ile Azure'da oturum açın:

    az login

    Bu, örnek koddaki Azure Identity istemci kitaplığının oturum açmış kullanıcı için bir kimlik doğrulama belirteci almasını sağlar. Bu kullanıcı için gerekli rolü daha önce eklediğinizi unutmayın.

  3. Uygulamayı yerel olarak çalıştırın:

    dotnet run

  4. Uygulamanızın 5280 numaralı bağlantı noktasında çalıştığınıgördüğünüzde Tarayıcıda Aç'ı seçin.

  5. Sohbet arabirimini denemek için Microsoft Agent Framework Aracısı bağlantısını ve Foundry Agent Hizmeti bağlantısını seçin. Bir yanıt alırsanız, uygulamanız Microsoft Foundry kaynağına başarıyla bağlanıyordur.

  6. GitHub Codespaces'ta uygulama değişikliklerinizi yayınlayın.

    azd up

  7. Dağıtılan uygulamaya yeniden gidin ve sohbet aracılarını test edin.

Kaynakları temizle

Uygulamayla işiniz bittiğinde, daha fazla maliyet oluşmasını önlemek için App Service kaynaklarını silebilirsiniz:

azd down --purge

AZD şablonu Microsoft Foundry kaynaklarını içermediğinden, isterseniz bunları el ile silmeniz gerekir.

Daha fazla kaynak

  • Last updated on