Een App Service-app toevoegen als een hulpprogramma in Foundry Agent Service (Spring Boot)

In deze zelfstudie leert u hoe u de functionaliteit van een Spring Boot-web-app beschikbaar maakt via OpenAPI, deze toevoegt als een hulpprogramma aan Foundry Agent Service en hoe u met uw app kunt werken met behulp van natuurlijke taal in de agents-speeltuin.

Als uw webtoepassing al nuttige functies heeft, zoals winkelen, hotelreservering of gegevensbeheer, kunt u deze mogelijkheden eenvoudig beschikbaar maken voor een AI-agent in Foundry Agent Service. Door simpelweg een OpenAPI-schema aan uw app toe te voegen, stelt u de agent in staat om de mogelijkheden van uw app te begrijpen en te gebruiken wanneer deze reageert op de prompts van gebruikers. Dit betekent dat alles wat uw app kan doen, uw AI-agent ook kan doen, met minimale inspanning dan het maken van een OpenAPI-eindpunt voor uw app. In deze handleiding begint u met een eenvoudige to-do lijstapp. Aan het einde kunt u taken maken, bijwerken en beheren met een agent via conversationele AI.

Schermopname van de agentenspeelruimte in het verloop van een gesprek dat acties onderneemt met behulp van de OpenAPI-tool.

OpenAPI-functionaliteit toevoegen aan uw web-app.
Zorg ervoor dat het OpenAPI-schema compatibel is met Foundry Agent Service.
Registreer uw app als een OpenAPI-hulpprogramma in Foundry Agent Service.
Test uw agent in de agentspeelplaats.

Vereiste voorwaarden

In deze zelfstudie wordt ervan uitgegaan dat u met het voorbeeld werkt dat in zelfstudie wordt gebruikt : Een Java Spring Boot-web-app bouwen met Azure App Service op Linux en Azure Cosmos DB.

Open minimaal de voorbeeldtoepassing in GitHub Codespaces en implementeer de app door deze uit te voeren azd up.

OpenAPI-functionaliteit toevoegen aan uw web-app

Aanbeveling

U kunt alle volgende wijzigingen aanbrengen door GitHub Copilot in de Agent-modus opdracht te geven:

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

In de coderuimte, open pom.xml en voeg de volgende afhankelijkheid toe:

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

Open src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/controller/TodoListController.java en voeg de volgende importbewerkingen toe.
```
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
```
De TodoListController klasse implementeert @RestController, dus u hoeft slechts enkele aantekeningen toe te voegen om deze compatibel te maken met OpenAPI. Als u de API's compatibel wilt maken met de Foundry Agent-service, moet u bovendien de operationId eigenschap opgeven in de @Operation aantekening (zie Foundry Agent Service gebruiken met OpenAPI Specified Tools: Prerequisites).

Zoek de klassedeclaratie en voeg de @Tag aantekening toe, zoals wordt weergegeven in het volgende fragment:

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

Zoek de getTodoItem methodedeclaratie en voeg de @Operation aantekening toe met description en operationId, zoals wordt weergegeven in het volgende fragment:

@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) {

Zoek de getAllTodoItems methodedeclaratie en voeg de @Operation aantekening toe met description en operationId, zoals wordt weergegeven in het volgende fragment:

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

Zoek de addNewTodoItem methodedeclaratie en voeg de @Operation aantekening toe met description en operationId, zoals wordt weergegeven in het volgende fragment:

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

Zoek de updateTodoItem methodedeclaratie en voeg de @Operation aantekening toe met description en operationId, zoals wordt weergegeven in het volgende fragment:

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

Zoek de deleteTodoItem methodedeclaratie en voeg de @Operation aantekening toe met description en operationId, zoals wordt weergegeven in het volgende fragment:
```
@Operation(description = "Deletes a todo item by ID", operationId = "deleteTodoItem")
@DeleteMapping("/api/todolist/{id}")
public String deleteTodoItem(@PathVariable("id") String id) {
```
Deze minimale configuratie biedt u de volgende instellingen, zoals beschreven in springdoc-openapi:
- Swagger UI op /swagger-ui.html.
- OpenAPI-specificatie op /v3/api-docs.
Voer in de codespace-terminal de toepassing uit met mvn spring-boot:run.
Klik op In browser openen.
Navigeer naar de Swagger UI door /swagger-ui.html toe te voegen aan de URL.
Controleer of de API-bewerkingen werken door ze uit te proberen in de Swagger-gebruikersinterface.
Implementeer uw wijzigingen in de codespace-terminal door uw wijzigingen door te voeren (GitHub Actions-methode) of door deze uit te voeren azd up (Azure Developer CLI-methode).
Zodra uw wijzigingen zijn geïmplementeerd, gaat u naar https://<your-app's-url>/v3/api-docs en kopieert u het schema voor later.

Een agent maken in Microsoft Foundry

Opmerking

In deze stappen wordt de nieuwe Foundry-portal gebruikt.

Selecteer New Foundry in het menu rechtsboven in de Foundry-portal.
Als dit uw eerste keer is in de nieuwe Foundry-portal, selecteert u de projectnaam en selecteert u Nieuw project maken.
Geef uw project een naam en selecteer Maken.
Selecteer Bouwen starten en vervolgens Agent maken.
Geef uw agent een naam en selecteer Maken. Wanneer de agent klaar is, ziet u de agentspeelplaats.

Let op de modellen die u kunt gebruiken en de beschikbare regio's.
In de agentspeelplaats, vouw Hulpmiddelen uit en selecteer Toevoegen>Aangepast>OpenAPI-hulpprogramma>Maken.
Geef het hulpprogramma een naam en een beschrijving. Plak in het vak OpenAPI 3.0+ het schema dat u eerder hebt gekopieerd.
Selecteer Hulpprogramma maken.
Selecteer Opslaan.

Aanbeveling

In deze zelfstudie is het OpenAPI-hulpprogramma geconfigureerd om uw app anoniem aan te roepen zonder verificatie. Voor productiescenario's moet u het hulpprogramma beveiligen met verificatie van beheerde identiteiten. Zie voor stapsgewijze instructies Secure OpenAPI-eindpunten voor Foundry Agent Service.

De agent testen

Geef in Instructies enkele eenvoudige instructies, zoals 'Gebruik het hulpprogramma todosApp om taken te beheren'.
Chat met de agent met de volgende promptsuggesties:
- Toon alle taken.
- Maak een taak genaamd 'Bedenk drie sla-grappen'.
- Wijzig dit in 'Kom met drie knock-knock-grappen'.

Aanbevolen procedures voor beveiliging

Wanneer u API's beschikbaar maakt via OpenAPI in Azure App Service, volgt u deze aanbevolen beveiligingsprocedures:

Verificatie en autorisatie: Bescherm uw OpenAPI-eindpunten met Microsoft Entra-verificatie. Zie voor stapsgewijze instructies Secure OpenAPI-eindpunten voor Foundry Agent Service. U kunt uw eindpunten ook beveiligen achter Azure API Management met Microsoft Entra ID en ervoor zorgen dat alleen geautoriseerde gebruikers of agents toegang hebben tot de hulpprogramma's.
Invoergegevens valideren en opschonen: De voorbeeldcode in deze zelfstudie laat invoervalidatie en opschoning weg voor eenvoud en duidelijkheid. Implementeer in productiescenario's altijd de juiste validatie en opschoning om uw toepassing te beveiligen. Zie Spring: Validatie van formulierinvoer.
HTTPS gebruiken: Het voorbeeld is afhankelijk van Azure App Service, dat HTTPS standaard afdwingt en gratis TLS/SSL-certificaten biedt om gegevens tijdens overdracht te versleutelen.
CORS beperken: Beperk Cross-Origin Resource Sharing (CORS) alleen tot vertrouwde domeinen. Zie CORS inschakelen voor meer informatie.
Frequentiebeperking toepassen: Gebruik API Management of aangepaste middleware om misbruik en denial-of-service-aanvallen te voorkomen.
Gevoelige eindpunten verbergen: Vermijd het beschikbaar maken van interne API's of beheerders-API's in uw OpenAPI-schema.
OpenAPI-schema controleren: Zorg ervoor dat uw OpenAPI-schema geen gevoelige informatie lekt (zoals interne URL's, geheimen of implementatiedetails).
Afhankelijkheden bijgewerkt houden: Werk NuGet-pakketten regelmatig bij en bewaak regelmatig op beveiligingsadviezen.
Activiteiten bewaken en registreren: Schakel logboekregistratie in en bewaak de toegang om verdachte activiteiten te detecteren.
Beheerde identiteiten gebruiken: Wanneer u andere Azure-services aanroept, gebruikt u beheerde identiteiten in plaats van vastgelegde referenties.

Zie Uw App Service-app beveiligen en aanbevolen procedures voor REST API-beveiliging voor meer informatie.

Volgende stap

U hebt nu ingeschakeld dat uw App Service-app wordt gebruikt als een hulpprogramma van Foundry Agent Service en interactie hebt met de API's van uw app via natuurlijke taal in de agents-speeltuin. Vanaf hier kunt u functies toevoegen aan uw agent in de Foundry-portal, deze integreren in uw eigen toepassingen met behulp van de Microsoft Foundry SDK of REST API, of deze implementeren als onderdeel van een grotere oplossing. Agents die zijn gemaakt in Microsoft Foundry kunnen worden uitgevoerd in de cloud, geïntegreerd in chatbots of ingesloten in web- en mobiele apps.

Opmerking

Foundry Agent Service heeft momenteel geen Java SDK. Zie zelfstudie: Een agent-web-app bouwen in Azure App Service met Microsoft Semantic Kernel of Foundry Agent Service (.NET) om te zien hoe u de agent kunt gebruiken die u hebt gemaakt.

Meer middelen

Feedback

Is deze pagina nuttig?

Last updated on 2025-12-16