Hinzufügen einer App Service-App als Tool im Foundry Agent Service (.NET)

In diesem Lernprogramm erfahren Sie, wie Sie die Funktionalität einer ASP.NET Core-App über OpenAPI verfügbar machen, sie als Tool zum Foundry Agent Service hinzufügen und mit Ihrer App mit natürlicher Sprache im Agents-Playground interagieren.

Wenn Ihre Webanwendung bereits nützliche Funktionen wie Shopping, Hotelbuchung oder Datenverwaltung aufweist, ist es einfach, diese Funktionen einem KI-Agenten im Foundry Agent Service zur Verfügung zu stellen. Indem Sie Ihrer App einfach ein OpenAPI-Schema hinzufügen, ermöglichen Sie es dem Agenten, die Fähigkeiten Ihrer App zu verstehen und zu nutzen, wenn er auf die Eingabeaufforderungen der Benutzer reagiert. Dies bedeutet, dass ihre App alles tun kann, was Ihr KI-Agent auch tun kann, mit minimalem Aufwand, der über das Erstellen eines OpenAPI-Endpunkts für Ihre App hinausgeht. In diesem Tutorial beginnen Sie mit einer einfachen Aufgabenlisten-App. Am Ende können Sie Aufgaben mit einem Agenten über konversationsfähige KI erstellen, aktualisieren und verwalten.

Voraussetzungen

In diesem Lernprogramm wird davon ausgegangen, dass Sie mit dem Beispiel arbeiten, das im Lernprogramm verwendet wird: Bereitstellen einer ASP.NET Core- und Azure SQL-Datenbank-App für Azure App Service.

Öffnen Sie mindestens die Beispielanwendung in GitHub Codespaces, und stellen Sie die App durch Ausführen azd upbereit.

Hinzufügen von OpenAPI-Funktionen zu Ihrer Web-App

1. Fügen Sie im Codespace-Terminal die NuGet-Swashbuckle-Pakete zu Ihrem Projekt hinzu:

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

2. Fügen Sie in Controller/TodosController.cs die folgenden API-Methoden hinzu. Damit sie mit dem Foundry Agent Service kompatibel sind, müssen Sie die OperationId Eigenschaft im SwaggerOperation Attribut angeben (siehe Verwendung des Foundry Agent Service mit OpenAPI Specified Tools: Prerequisites).

       // 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. Fügen Sie oben auf controller/TodosController.cs Folgendes hinzu:

   using Swashbuckle.AspNetCore.Annotations;
   

   Dieser Code dupliziert die Funktionalität des vorhandenen Controllers, was unnötig ist, sie wird jedoch zur Vereinfachung beibehalten. Es empfiehlt sich, die App-Logik in eine Dienstklasse zu verschieben und dann die Dienstmethoden sowohl aus den MVC-Aktionen als auch aus den API-Methoden aufzurufen.

4. Registrieren Sie in Program.cs den Swagger Generator-Dienst. Dadurch wird die OpenAPI-Dokumentation für Ihre API aktiviert, mit der der Foundry Agent Service Ihre APIs verstehen kann. Achten Sie darauf, die Server-URL anzugeben. Der Foundry Agent Service benötigt ein Schema, das die Server-URL enthält.

   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. Aktivieren Sie in Program.cs die Swagger-Middleware. Diese Middleware stellt die generierte OpenAPI-Dokumentation zur Laufzeit bereit, sodass sie über einen Browser zugänglich ist.

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

6. Führen Sie die Anwendung im Codespace-Terminal mit dotnet run aus.

7. Wählen Sie "Im Browser öffnen" aus.

8. Navigieren Sie zur Benutzeroberfläche von Swagger, indem Sie der URL /swagger/index.html hinzufügen.

9. Vergewissern Sie sich, dass die API-Vorgänge funktionieren, indem Sie sie in der Benutzeroberfläche von Swagger ausprobieren.

10. Stellen Sie Ihre Änderungen im Codespace-Terminal bereit, indem Sie die Änderungen übernehmen (GitHub Actions-Methode) oder azd up ausführen (Azure Developer CLI-Methode).

11. Nachdem Ihre Änderungen bereitgestellt wurden, navigieren Sie zu https://<your-app's-url>/swagger/v1/swagger.json, und kopieren Sie das Schema für die spätere Verwendung.

Erstellen eines Agents in Microsoft Foundry

1. Wählen Sie im Findry-Portal im oberen rechten Menü die Option "Neue Gießerei" aus.

2. Wenn Dies Ihr erstes Mal im neuen Foundry-Portal ist, wählen Sie den Projektnamen und dann "Neues Projekt erstellen" aus.

3. Geben Sie Ihrem Projekt einen Namen, und wählen Sie "Erstellen" aus.

4. Wählen Sie "Erstellen beginnen" und dann "Agent erstellen" aus.

5. Geben Sie Ihrem Agent einen Namen, und wählen Sie "Erstellen" aus. Wenn der Agent bereit ist, sollten Sie den Agent-Playground sehen.

   Beachten Sie die Modelle, die Sie verwenden können, und die verfügbaren Regionen.

6. Erweitern Sie im Agent-Playground Tools und wählen Sie Hinzufügen>Benutzerdefiniertes>OpenAPI-Tool>Erstellen aus.

7. Geben Sie dem Tool einen Namen und eine Beschreibung. Fügen Sie im Feld "OpenAPI 3.0+" das Zuvor kopierte Schema ein.

8. Wählen Sie "Tool erstellen" aus.

9. Wählen Sie Speichern aus.

Testen des Agents

1. Geben Sie in Den Anweisungen einige einfache Anweisungen an, z. B. "Verwenden Sie das TodosApp-Tool, um Aufgaben zu verwalten."

2. Chatten Sie mit dem Agent mit den folgenden Prompt-Empfehlungen:

   • Alle Aufgaben anzeigen.
   • Erstellen Sie eine Aufgabe mit dem Namen "Denken Sie sich drei Salatwitze aus".
   • Ändern Sie dies in „Denke dir drei Knock-Knock-Witze aus“.

   

Bewährte Sicherheitsmethoden

Befolgen Sie beim Verfügbarmachen von APIs über OpenAPI in Azure App Service die folgenden bewährten Sicherheitsmethoden:

• Authentifizierung und Autorisierung: Schützen Sie Ihre OpenAPI-Endpunkte mit der Microsoft Entra-Authentifizierung. Schrittweise Anleitungen finden Sie unter Secure OpenAPI-Endpunkte für Foundry Agent Service. Sie können Ihre Endpunkte auch hinter Azure API Management mit Microsoft Entra ID schützen und sicherstellen, dass nur autorisierte Benutzer oder Agents auf die Tools zugreifen können.
• Eingabedaten validieren: Der Beispielcode überprüft ModelState.IsValid in der CreateTodo Methode, wodurch sichergestellt wird, dass die eingehenden Daten den Überprüfungsattributen des Modells entsprechen. Weitere Informationen finden Sie unter Modellüberprüfung in ASP.NET Core.
• Https verwenden: Das Beispiel basiert auf Azure App Service, der STANDARDMÄßIG HTTPS erzwingt und kostenlose TLS/SSL-Zertifikate zum Verschlüsseln von Daten während der Übertragung bereitstellt.
• CORS begrenzen: Beschränken Sie die ursprungsübergreifende Ressourcenfreigabe (CORS) nur auf vertrauenswürdige Domänen. Weitere Informationen finden Sie unter Aktivieren von CORS.
• Anwenden von Ratenbeschränkungen: Verwenden Sie API-Verwaltung oder benutzerdefinierte Middleware, um Missbrauch und Denial-of-Service-Angriffe zu verhindern.
• Vertrauliche Endpunkte ausblenden: Vermeiden Sie die Bereitstellung interner oder Administrator-APIs in Ihrem OpenAPI-Schema.
• OpenAPI-Schema überprüfen: Stellen Sie sicher, dass Ihr OpenAPI-Schema keine vertraulichen Informationen (z. B. interne URLs, geheime Schlüssel oder Implementierungsdetails) verloren geht.
• Halten Sie Abhängigkeiten auf dem neuesten Stand: Aktualisieren Sie NuGet-Pakete regelmäßig und überwachen Sie Sicherheitshinweise.
• Überwachen und Protokollieren von Aktivitäten: Aktivieren Sie die Protokollierung und überwachen Sie den Zugriff, um verdächtige Aktivitäten zu erkennen.
• Verwaltete Identitäten verwenden: Verwenden Sie beim Aufrufen anderer Azure-Dienste verwaltete Identitäten anstelle von hartcodierten Anmeldeinformationen.

Weitere Informationen finden Sie unter Secure your App Service app and Best Practices for REST API security.

Nächster Schritt

Sie haben Ihre App Service-App jetzt so aktiviert, dass sie als Tool vom Foundry Agent Service genutzt werden kann und über natürliche Sprache mit den APIs Ihrer App im Agents-Playground interagiert. Von hier aus können Sie Ihrem Agent weiterhin Features im Foundry-Portal hinzufügen, sie mithilfe des Microsoft Foundry SDK oder der REST-API in Ihre eigenen Anwendungen integrieren oder als Teil einer größeren Lösung bereitstellen. In Microsoft Foundry erstellte Agents können in der Cloud ausgeführt, in Chatbots integriert oder in Web- und mobile Apps eingebettet werden.

Wenn Sie den nächsten Schritt ausführen und erfahren möchten, wie Sie Ihren Agent direkt in Azure App Service ausführen, lesen Sie das folgende Lernprogramm:

Weitere Ressourcen

• Integrieren von KI in Ihre Azure App Service-Anwendungen
• Was ist Foundry Agent Service?