Dodaj aplikację App Service jako narzędzie w Foundry Agent Service (.NET)

W tym samouczku dowiesz się, jak uwidocznić funkcjonalność aplikacji ASP.NET Core za pomocą specyfikacji OpenAPI, dodać ją jako narzędzie do Agent Service Foundry i wchodzić w interakcje z aplikacją przy użyciu języka naturalnego w środowisku agentów.

Jeśli aplikacja internetowa ma już przydatne funkcje, takie jak zakupy, rezerwacja hotelowa lub zarządzanie danymi, można łatwo udostępnić te możliwości agentowi sztucznej inteligencji w usłudze Agent usługi Foundry. Po prostu dodając schemat interfejsu OpenAPI do aplikacji, możesz umożliwić agentowi zrozumienie możliwości aplikacji i korzystanie z nich podczas odpowiadania na monity użytkowników. Oznacza to, że wszystko, co może zrobić twoja aplikacja, agent sztucznej inteligencji może również zrobić, przy minimalnym nakładzie pracy poza tworzeniem punktu końcowego interfejsu OpenAPI dla aplikacji. W tym samouczku zaczniesz od prostej aplikacji typu lista to-do. Na koniec będziesz mieć możliwość tworzenia, aktualizowania i zarządzania zadaniami za pomocą agenta za pośrednictwem konwersacyjnej sztucznej inteligencji.

Wymagania wstępne

W tym samouczku założono, że pracujesz z przykładem używanym w artykule Samouczek: wdrażanie aplikacji ASP.NET Core i Azure SQL Database w usłudze Azure App Service.

Otwórz co najmniej przykładową aplikację w usłudze GitHub Codespaces i wdróż aplikację, uruchamiając polecenie azd up.

Dodawanie funkcji interfejsu OpenAPI do aplikacji internetowej

1. W terminalu usługi Codespace dodaj pakiety NuGet Swashbuckle do projektu:

   dotnet add package Swashbuckle.AspNetCore --version 6.5.0
   dotnet add package Swashbuckle.AspNetCore.Annotations --version 6.5.0
   

2. W obszarze Kontrolery/TodosController.cs dodaj następujące metody interfejsu API. Aby były one zgodne z usługą agenta Foundry, należy określić OperationId właściwość w atrybucie SwaggerOperation (zobacz Jak używać usługi agenta Foundry z określonymi narzędziami OpenAPI: Wymagania wstępne).

       // GET: api/todos
       [HttpGet("api/todos")]
       [SwaggerOperation(Summary = "Gets all Todo items", OperationId = "GetTodos")]
       [ProducesResponseType(typeof(IEnumerable<Todo>), 200)]
       public async Task<ActionResult<IEnumerable<Todo>>> GetTodos()
       {
           return await _context.Todo.ToListAsync();
       }
   
       // GET: api/todos/5
       [HttpGet("api/todos/{id}")]
       [SwaggerOperation(Summary = "Gets a Todo item by ID", OperationId = "GetTodoById")]
       [ProducesResponseType(typeof(Todo), 200)]
       [ProducesResponseType(404)]
       public async Task<ActionResult<Todo>> GetTodo(int id)
       {
           var todo = await _context.Todo.FindAsync(id);
   
           if (todo == null)
           {
               return NotFound();
           }
   
           return todo;
       }
   
   
   // POST: api/todos
   [HttpPost("api/todos")]
   [ProducesResponseType(StatusCodes.Status201Created)]
   [ProducesResponseType(StatusCodes.Status400BadRequest)]
   [SwaggerOperation(Summary = "Creates a new todo item.", Description = "Creates a new todo item and returns it.", OperationId = "CreateTodo")]
   public async Task<IActionResult> CreateTodo([FromBody] Todo todo)
   {
       if (!ModelState.IsValid)
       {
           return BadRequest(ModelState);
       }
       _context.Add(todo);
       await _context.SaveChangesAsync();
       return CreatedAtAction(nameof(GetTodo), new { id = todo.ID }, todo);
   }
   
   // PUT: api/todos/{id}
   [HttpPut("api/todos/{id}")]
   [ProducesResponseType(StatusCodes.Status204NoContent)]
   [ProducesResponseType(StatusCodes.Status400BadRequest)]
   [ProducesResponseType(StatusCodes.Status404NotFound)]
   [SwaggerOperation(Summary = "Updates a todo item.", Description = "Updates an existing todo item by ID.", OperationId = "UpdateTodo")]
   public async Task<IActionResult> UpdateTodo(int id, [FromBody] Todo todo)
   {
       // Use the id from the URL fragment only, ignore mismatching check
       if (!TodoExists(id))
       {
           return NotFound();
       }
       todo.ID = id;
       _context.Entry(todo).State = EntityState.Modified;
       await _context.SaveChangesAsync();
       return NoContent();
   }
   
   // DELETE: api/todos/{id}
   [HttpDelete("api/todos/{id}")]
   [ProducesResponseType(StatusCodes.Status204NoContent)]
   [ProducesResponseType(StatusCodes.Status404NotFound)]
   [SwaggerOperation(Summary = "Deletes a todo item.", Description = "Deletes a todo item by ID.", OperationId = "DeleteTodo")]
   public async Task<IActionResult> DeleteTodo(int id)
   {
       var todo = await _context.Todo.FindAsync(id);
       if (todo == null)
       {
           return NotFound();
       }
       _context.Todo.Remove(todo);
       await _context.SaveChangesAsync();
       return NoContent();
   }
   

3. Na górze pliku Controllers/TodosController.cs dodaj następującą dyrektywę using:

   using Swashbuckle.AspNetCore.Annotations;
   

   Ten kod duplikuje funkcjonalność istniejącego kontrolera, co jest niepotrzebne, ale zachowasz go dla uproszczenia. Najlepszym rozwiązaniem jest przeniesienie logiki aplikacji do klasy usługi, a następnie wywołanie metod usługi zarówno z akcji MVC, jak i z metod interfejsu API.

4. W Program.cs zarejestruj usługę generatora Swagger. Umożliwia to dokumentację OpenAPI dla twojego interfejsu API, co pozwala usłudze Foundry Agent Service zrozumieć twoje interfejsy API. Pamiętaj, aby określić adres URL serwera. Usługa Foundry Agent Service wymaga schematu zawierającego adres URL serwera.

   builder.Services.AddSwaggerGen(c =>
   {
       c.EnableAnnotations();
       var websiteHostname = Environment.GetEnvironmentVariable("WEBSITE_HOSTNAME");
       if (!string.IsNullOrEmpty(websiteHostname))
       {
           c.AddServer(new Microsoft.OpenApi.Models.OpenApiServer { Url = $"https://{websiteHostname}" });
       }
   });
   

5. W Program.cs włącz middleware Swagger. To oprogramowanie pośredniczące obsługuje wygenerowaną dokumentację interfejsu OpenAPI w czasie wykonywania, dzięki czemu jest ona dostępna za pośrednictwem przeglądarki.

   app.UseSwagger();
   app.UseSwaggerUI();
   

6. W terminalu usługi Codespace uruchom aplikację za pomocą dotnet run polecenia.

7. Kliknij pozycję Otwórz w przeglądarce.

8. Przejdź do interfejsu Swagger, dodając /swagger/index.html do adresu URL.

9. Upewnij się, że operacje interfejsu API działają, wypróbowując je w Swagger UI.

10. W terminalu usługi Codespace wdróż zmiany, zatwierdzając zmiany (metodę GitHub Actions) lub uruchamiając azd up (metoda interfejsu wiersza polecenia dewelopera platformy Azure).

11. Po wdrożeniu zmian przejdź do https://<your-app's-url>/swagger/v1/swagger.json i skopiuj schemat do późniejszego użycia.

Tworzenie agenta w rozwiązaniu Microsoft Foundry

1. W portalu Foundry w prawym górnym menu wybierz pozycję New Foundry.

2. Jeśli jest to twój pierwszy raz w nowym portalu Foundry, wybierz nazwę projektu i wybierz pozycję Utwórz nowy projekt.

3. Nadaj projektowi nazwę i wybierz pozycję Utwórz.

4. Wybierz pozycję Rozpocznij kompilowanie, a następnie pozycję Utwórz agenta.

5. Nadaj agentowi nazwę i wybierz pozycję Utwórz. Gdy agent jest gotowy, powinien zostać wyświetlony plac zabaw agenta.

   Zwróć uwagę na modele, których można użyć, i dostępnych regionów.

6. Na placu zabaw dla agentów rozwiń Narzędzia i wybierz Dodaj>Niestandardowe>narzędzie OpenAPI>Utwórz.

7. Nadaj narzędziu nazwę i opis. W polu schematu OpenAPI 3.0+ wklej skopiowany wcześniej schemat.

8. Wybierz pozycję Utwórz narzędzie.

9. Wybierz Zapisz.

Przetestuj agenta

1. W obszarze Instrukcje podaj proste instrukcje, takie jak "Użyj narzędzia todosApp, aby ułatwić zarządzanie zadaniami".

2. Porozmawiaj z agentem, wykorzystując następujące podpowiedzi.

   • Pokaż mi wszystkie zadania.
   • Utwórz zadanie o nazwie „Wymyśl trzy żarty o sałacie”.
   • Zmień to na "Wymyśl trzy dowcipy knock-knock."

   

Najlepsze rozwiązania dotyczące zabezpieczeń

W przypadku uwidaczniania interfejsów API za pośrednictwem interfejsu OpenAPI w usłudze Azure App Service postępuj zgodnie z następującymi najlepszymi rozwiązaniami w zakresie zabezpieczeń:

• Uwierzytelnianie i autoryzacja: ochrona punktów końcowych interfejsu OpenAPI przy użyciu uwierzytelniania firmy Microsoft Entra. Aby uzyskać instrukcje krok po kroku, zobacz Zabezpieczanie punktów końcowych interfejsu OpenAPI dla usługi agenta Foundry. Możesz również chronić punkty końcowe za pomocą usługi Azure API Management przy użyciu identyfikatora Microsoft Entra ID i upewnić się, że tylko autoryzowani użytkownicy lub agenci mogą uzyskiwać dostęp do narzędzi.
• Weryfikowanie danych wejściowych: Przykładowy kod sprawdza ModelState.IsValid w metodzie CreateTodo, co zapewnia, że przychodzące dane są zgodne z atrybutami walidacji modelu. Aby uzyskać więcej informacji, zobacz Walidacja modelu w programie ASP.NET Core.
• Użyj protokołu HTTPS: Przykład opiera się na usłudze Azure App Service, która domyślnie wymusza protokół HTTPS i udostępnia bezpłatne certyfikaty TLS/SSL do szyfrowania danych przesyłanych.
• Ogranicz mechanizm CORS: Ogranicz udostępnianie zasobów między źródłami (CORS) tylko do zaufanych domen. Aby uzyskać więcej informacji, zobacz Włączanie mechanizmu CORS.
• Zastosuj ograniczanie szybkości: Użyj usługi API Management lub niestandardowego oprogramowania pośredniczącego, aby zapobiec nadużyciom i atakom typu "odmowa usługi".
• Ukryj poufne punkty końcowe: Unikaj uwidaczniania wewnętrznych lub administracyjnych interfejsów API w schemacie interfejsu OpenAPI.
• Przejrzyj schemat OpenAPI: Upewnij się, że schemat interfejsu OpenAPI nie wycieka poufnych informacji (takich jak wewnętrzne adresy URL, wpisy tajne lub szczegóły implementacji).
• Zachowaj zaktualizowane zależności: Regularnie aktualizuj pakiety NuGet i monitoruj je pod kątem biuletynów zabezpieczeń.
• Monitorowanie i rejestrowanie aktywności: Włącz rejestrowanie i monitoruj dostęp do wykrywania podejrzanych działań.
• Użyj tożsamości zarządzanych: Podczas wywoływania innych usług platformy Azure użyj tożsamości zarządzanych zamiast zakodowanych na stałe poświadczeń.

Aby uzyskać więcej informacji, zobacz Zabezpieczanie aplikacji usługi App Service i Najlepsze rozwiązania dotyczące zabezpieczeń interfejsu API REST.

Następny krok

Aplikacja App Service została teraz skonfigurowana do użycia jako narzędzie przez Servis Agentów Foundry, umożliwiając interakcję z interfejsami API aplikacji za pomocą języka naturalnego w środowisku testowym agentów. W tym miejscu możesz nadal dodawać funkcje do agenta w portalu Foundry, integrować je z własnymi aplikacjami przy użyciu zestawu Microsoft Foundry SDK lub interfejsu API REST albo wdrażać je w ramach większego rozwiązania. Agentów utworzonych w rozwiązaniu Microsoft Foundry można uruchamiać w chmurze, integrować z czatbotami lub osadzać w aplikacjach internetowych i mobilnych.

Aby wykonać następny krok i dowiedzieć się, jak uruchomić agenta bezpośrednio w usłudze Azure App Service, zobacz następujący samouczek:

Więcej zasobów

• Integrowanie sztucznej inteligencji z aplikacjami usługi Azure App Service
• Co to jest usługa agenta programu Foundry?