Freigeben über

Hinzufügen einer App Service-App als Tool im Foundry Agent Service (Spring Boot)

In diesem Lernprogramm erfahren Sie, wie Sie die Funktionen einer Spring Boot Web 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 Funktionen Ihrer App zu verstehen und zu verwenden, 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 eine KI-gestützte Konversationsschnittstelle erstellen, aktualisieren und verwalten.

Screenshot des Agents-Playgrounds in der Mitte einer Unterhaltung, die Aktionen mithilfe des OpenAPI-Tools ausführt.

  • Fügen Sie Ihrer Web-App OpenAPI-Funktionen hinzu.
  • Stellen Sie sicher, dass das OpenAPI-Schema mit dem Foundry Agent Service kompatibel ist.
  • Registrieren Sie Ihre App als OpenAPI-Tool im Foundry Agent Service.
  • Testen Sie Ihren Agent im Agent-Playground.

Voraussetzungen

In diesem Lernprogramm wird davon ausgegangen, dass Sie mit dem Beispiel arbeiten, das im Lernprogramm verwendet wird: Erstellen einer Java Spring Boot Web App-App mit Azure App Service unter Linux und Azure Cosmos DB.

Ö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

Tipp

Sie können alle folgenden Änderungen vornehmen, indem Sie im Agent-Modus zu GitHub Copilot sagen:

I'd like to generate OpenAPI functionality using Spring Boot OpenAPI. Please also generate the server URL and operation ID in the schema.

  1. Öffnen Sie im Codespace pom.xml , und fügen Sie die folgende Abhängigkeit hinzu:

    <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

  2. Öffnen Sie src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/controller/TodoListController.java , und fügen Sie die folgenden Importe hinzu.

    import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;

    Die TodoListController Klasse implementiert @RestController, sodass Sie nur einige Anmerkungen hinzufügen müssen, um sie mit OpenAPI kompatibel zu machen. Um die APIs mit dem Foundry Agent Service kompatibel zu machen, müssen Sie außerdem die operationId Eigenschaft in der @Operation Anmerkung angeben (siehe Verwenden des Foundry-Agent-Diensts mit den angegebenen OpenAPI-Tools: Voraussetzungen).

  3. Suchen Sie die Klassendeklaration, und fügen Sie die @Tag Anmerkung hinzu, wie im folgenden Codeausschnitt gezeigt:

    @RestController
@Tag(name = "Todo List", description = "Todo List management APIs")
public class TodoListController {

  4. Suchen Sie die getTodoItem-Methodendeklaration, und fügen Sie die @Operation-Annotation mit description und operationId hinzu, wie im folgenden Codeausschnitt gezeigt:

    @Operation(description = "Returns a single todo item", operationId = "getTodoItem")
@GetMapping(path = "/api/todolist/{index}", produces = {MediaType.APPLICATION_JSON_VALUE})
public TodoItem getTodoItem(@PathVariable("index") String index) {

  5. Suchen Sie die getAllTodoItems-Methodendeklaration, und fügen Sie die @Operation-Annotation mit description und operationId hinzu, wie im folgenden Codeausschnitt gezeigt:

    @Operation(description = "Returns a list of all todo items", operationId = "getAllTodoItems")
@GetMapping(path = "/api/todolist", produces = {MediaType.APPLICATION_JSON_VALUE})
public List<TodoItem> getAllTodoItems() {

  6. Suchen Sie die addNewTodoItem-Methodendeklaration, und fügen Sie die @Operation-Annotation mit description und operationId hinzu, wie im folgenden Codeausschnitt gezeigt:

    @Operation(description = "Creates a new todo item", operationId = "addNewTodoItem")
@PostMapping(path = "/api/todolist", consumes = MediaType.APPLICATION_JSON_VALUE)
public String addNewTodoItem(@RequestBody TodoItem item) {

  7. Suchen Sie die updateTodoItem-Methodendeklaration, und fügen Sie die @Operation-Annotation mit description und operationId hinzu, wie im folgenden Codeausschnitt gezeigt:

    @Operation(description = "Updates an existing todo item", operationId = "updateTodoItem")
@PutMapping(path = "/api/todolist", consumes = MediaType.APPLICATION_JSON_VALUE)
public String updateTodoItem(@RequestBody TodoItem item) {

  8. Suchen Sie die deleteTodoItem-Methodendeklaration, und fügen Sie die @Operation-Annotation mit description und operationId hinzu, wie im folgenden Codeausschnitt gezeigt:

    @Operation(description = "Deletes a todo item by ID", operationId = "deleteTodoItem")
@DeleteMapping("/api/todolist/{id}")
public String deleteTodoItem(@PathVariable("id") String id) {

    Diese minimale Konfiguration bietet Ihnen die folgenden Einstellungen, wie in springdoc-openapi dokumentiert:

    • Swagger-Benutzeroberfläche bei /swagger-ui.html.
    • OpenAPI-Spezifikation bei /v3/api-docs.

  9. Führen Sie die Anwendung im Codespace-Terminal mit mvn spring-boot:run aus.

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

  11. Navigieren Sie zur Swagger UI, indem Sie /swagger-ui.html zur URL hinzufügen.

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

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

  14. Nachdem Ihre Änderungen bereitgestellt wurden, navigieren Sie zu https://<your-app's-url>/v3/api-docs, und kopieren Sie das Schema für eine spätere Verwendung.

Erstellen eines Agents in Microsoft Foundry

Hinweis

Diese Schritte verwenden das neue Foundry-Portal.

  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.

Tipp

In diesem Lernprogramm ist das OpenAPI-Tool so konfiguriert, dass Ihre App anonym ohne Authentifizierung aufgerufen wird. Für Produktionsszenarien sollten Sie das Tool mit verwalteter Identitätsauthentifizierung sichern. Schrittweise Anleitungen finden Sie unter Secure OpenAPI-Endpunkte für Foundry Agent Service.

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 Agenten mit den folgenden Promptvorschlägen.

    • Alle Aufgaben anzeigen.
    • Erstellen Sie eine Aufgabe namens "Sich drei Witze über Salat ausdenken".
    • Ändern Sie dies in "Denken Sie sich drei Knock-Knock-Witze aus."

    Screenshot des Agents-Playgrounds in der Mitte einer Unterhaltung, die Aktionen mithilfe des OpenAPI-Tools ausführt.

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.
  • Überprüfen und Berigen von Eingabedaten: Im Beispielcode in diesem Lernprogramm werden die Eingabeüberprüfung und -bereinigung aus Gründen der Einfachheit und Klarheit weggelassen. Implementieren Sie in Produktionsszenarien immer die richtige Validierung und Bereinigung, um Ihre Anwendung zu schützen. Weitere Informationen zu Spring finden Sie unter Spring: Validating Form Input.
  • 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 (Cross-Origin Resource Sharing, 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 aktuell: 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

Dank der Aktivierung Ihrer App Service-App kann letztere künftig vom Foundry Agent Service als Tool verwendet werden und mit den APIs Ihrer App im App-Playground über natürliche Sprache interagieren. 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.

Hinweis

Der Foundry Agent Service verfügt derzeit nicht über ein Java SDK. Informationen dazu, wie Sie den von Ihnen erstellten Agent verwenden können, finden Sie im Lernprogramm: Erstellen einer agentischen Web-App in Azure App Service mit Microsoft Semantic Kernel oder Foundry Agent Service (.NET).

Weitere Ressourcen

  • Last updated on