在 Foundry 代理服务中将应用服务应用添加为工具（Spring Boot）

本教程介绍如何通过 OpenAPI 公开 Spring Boot Web 应用的功能，将其作为工具添加到 Foundry 代理服务，并在代理场中使用自然语言与应用交互。

如果 Web 应用程序已有有用的功能（如购物、酒店预订或数据管理），则可以轻松地在 Foundry 代理服务中向 AI 代理提供这些功能。 只需将 OpenAPI 架构添加到应用，即可在代理响应用户的提示时了解和使用应用的功能。 这意味着你的应用可以执行的任何作，AI 代理也可以执行，除了为应用创建 OpenAPI 终结点之外，也只需付出最少的努力。 本教程从简单的 to-do 列表应用开始。 最后，你将能够通过对话式 AI 通过代理创建、更新和管理任务。

• 将 OpenAPI 功能添加到 Web 应用。
• 确保 OpenAPI 架构与 Foundry 代理服务兼容。
• 在 Foundry 代理服务中将应用注册为 OpenAPI 工具。
• 在智能体操场中测试智能体。

先决条件

本教程假定你使用的是教程中使用的示例 ：使用 Linux 和 Azure Cosmos DB 上的 Azure 应用服务生成 Java Spring Boot Web 应用。

至少，在 GitHub Codespaces 中打开 示例应用程序 ，并通过运行 azd up来部署应用。

将 OpenAPI 功能添加到 Web 应用

小窍门

可以通过在代理模式下告诉 GitHub Copilot 进行以下所有更改：

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

1. 在 codespace 中，打开 pom.xml 并添加以下依赖项：

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

2. 打开 src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/controller/TodoListController.java 并添加以下导入。

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

   类 TodoListController 实现 @RestController，因此只需添加几个批注即可使其与 OpenAPI 兼容。 此外，若要使 API 与 Foundry 代理服务兼容，必须在批注中operationId指定@Operation属性（请参阅如何将 Foundry 代理服务与 OpenAPI 指定工具配合使用：先决条件）。

3. 找到类声明并添加 @Tag 注释，如以下代码片段所示：

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

4. 找到 getTodoItem 方法声明，并添加带有 @Operation 和 description 的 operationId 批注，如以下代码片段所示：

   @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. 找到 getAllTodoItems 方法声明，并添加带有 @Operation 和 description 的 operationId 批注，如以下代码片段所示：

   @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. 找到 addNewTodoItem 方法声明，并添加带有 @Operation 和 description 的 operationId 批注，如以下代码片段所示：

   @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. 找到 updateTodoItem 方法声明，并添加带有 @Operation 和 description 的 operationId 批注，如以下代码片段所示：

   @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. 找到 deleteTodoItem 方法声明，并添加带有 @Operation 和 description 的 operationId 批注，如以下代码片段所示：

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

   此最小配置提供以下设置，如 springdoc-openapi 中所述：

   • Swagger UI，位于 /swagger-ui.html。
   • OpenAPI 规范，位于 /v3/api-docs。

9. 在 codespace 终端中，使用 mvn spring-boot:run.. 运行应用程序。

10. 选择“在浏览器中打开”。

11. 通过将 /swagger-ui.html 添加到 URL 导航到 Swagger UI。

12. 通过在 Swagger UI 中试用 API 操作，确认 API 操作是否正常工作。

13. 返回 codespace 终端，通过提交更改（GitHub Actions 方法）或运行 azd up （Azure 开发人员 CLI 方法）来部署更改。

14. 部署更改后，导航到 https://<your-app's-url>/v3/api-docs 并复制架构以供以后使用。

在 Microsoft Foundry 中创建代理

1. 按照以下步骤在 Foundry 门户中创建代理 ：快速入门：创建新代理。

   请注意 可以使用的模型和可用的区域。

2. 按照《如何使用 OpenAPI 规范工具》的步骤，选择新代理并使用 OpenAPI 3.0 指定的工具添加一个动作。

3. 在 “定义架构 ”页中，粘贴之前复制的架构。 检查并保存操作。

小窍门

在本教程中，OpenAPI 工具配置为在不进行身份验证的情况下匿名调用应用。 对于生产方案，应使用托管标识身份验证保护该工具。 有关分步说明，请参阅 Foundry 代理服务的安全 OpenAPI 端点。

测试代理

1. 如果代理测试区还没有在 Foundry 门户中打开，请选择代理，然后选择在测试区试用。

2. 在 “说明”中，提供一些简单的说明，例如 “请使用 todosApp 工具来帮助管理任务”。

3. 使用以下提示语与智能助手聊天：

   • 向我显示所有任务。
   • 创建一个名为“拿出三个生菜笑话”的任务。
   • 将其改为“想出三个敲门笑话。”

   

安全最佳做法

在 Azure 应用服务中通过 OpenAPI 公开 API 时，请遵循以下安全最佳做法：

• 身份验证和授权：使用 Microsoft Entra 身份验证保护 OpenAPI 终结点。 有关分步说明，请参阅 Foundry 代理服务的安全 OpenAPI 端点。 还可以 使用 Microsoft Entra ID 保护 Azure API 管理 背后的终结点，并确保只有经过授权的用户或代理才能访问这些工具。
• 验证并清理输入数据： 本教程中的示例代码省略输入验证和清理，以便简单明了。 在生产方案中，始终实现适当的验证和清理来保护应用程序。 对于 Spring，请参阅 Spring：验证表单输入。
• 使用 HTTPS： 此示例依赖于 Azure 应用服务，该服务默认强制实施 HTTPS，并提供免费的 TLS/SSL 证书来加密传输中的数据。
• 限制 CORS： 仅将跨域资源共享（CORS）限制为受信任的域。 有关详细信息，请参阅 “启用 CORS”。
• 应用速率限制： 使用 API 管理 或自定义中间件防止滥用和拒绝服务攻击。
• 隐藏敏感终结点： 避免在 OpenAPI 架构中公开内部或管理员 API。
• 查看 OpenAPI 架构： 确保 OpenAPI 架构不会泄露敏感信息（例如内部 URL、机密或实现详细信息）。
• 保持依赖项更新： 定期更新 NuGet 包并监视安全公告。
• 监视和记录活动： 启用日志记录和监视访问以检测可疑活动。
• 使用托管标识： 调用其他 Azure 服务时，请使用托管标识而不是硬编码凭据。

有关详细信息，请参阅 保护应用服务应用 和 REST API 安全性的最佳做法。

后续步骤

现在，你已启用应用服务应用，使其可以作为 Foundry 代理服务的工具，并在代理沙盒中通过自然语言与应用的 API 进行交互。 在这里，可以在 Foundry 门户中继续将功能添加到代理，使用 Microsoft Foundry SDK 或 REST API 将其集成到自己的应用程序中，或将其部署为更大的解决方案的一部分。 在 Microsoft Foundry 中创建的代理可以在云中运行、集成到聊天机器人中或嵌入在 Web 和移动应用中。

注释

Foundry 代理服务目前没有 Java SDK。 若要了解如何使用创建的代理，请参阅 教程：使用Microsoft语义内核或 Foundry 代理服务（.NET）在 Azure 应用服务中生成代理 Web 应用。

更多资源

• 将 AI 集成到 Azure 应用服务应用程序中
• 什么是 Foundry 智能体服务？