从 Azure AI Foundry 代理服务调用应用服务 Web 应用

使用 Azure AI Foundry 代理服务 ，可以通过自定义说明创建根据需求定制的 AI 代理，并通过高级工具（如代码解释器和自定义函数）进行扩充。 现在，可以使用 OpenAPI 3.0 指定的工具将 Azure AI 代理连接到外部 API，从而实现与各种应用程序的可缩放互作性。

Azure 应用服务是一个完全托管的平台，用于生成、部署和缩放 Web 应用和 API。 如果 API 托管在 Azure 应用服务上，则可以使用 OpenAPI 规范将 AI 代理连接到 API。 OpenAPI 规范定义 API 以及如何与之交互。 然后，可以使用自然语言通过 AI 代理调用 API。 此工具非常强大，因为它允许你通过最少的代码更改将 AI 代理功能添加到现有应用。 此外，此代理还能够直接与应用交互。 无须进行重大代码更改或实现工作，只需进行一些小的更新即可通过可用的SDK与代理程序交互。

在本教程中，你将使用 Azure AI Foundry 代理调用 Azure 应用服务上托管的现有 API。 本教程结束时，你已使用 Azure AI Foundry 代理服务中的 AI 代理在应用服务中运行时尚助理聊天应用程序。

先决条件

1. GitHub 帐户。 也可以 免费获取一个。
2. 拥有有效订阅的 Azure 帐户。 如果没有 Azure 帐户，可以免费创建一个帐户。

1. 检查 GitHub Codespaces 中的示例

1. 登录到你的 GitHub 帐户并导航到 https://github.com/Azure-Samples/ai-agent-openai-web-app/fork。
2. 选择“创建分支”。
3. 选择“代码”>“在 main 上创建代码空间”。 设置代码空间需要几分钟时间。

示例存储库包含以下内容：

2.部署 Azure 基础结构和应用程序

1. 使用 azd auth login 命令并按照提示登录到 Azure 帐户：

   azd auth login
   

2. 使用 azd up 命令创建应用服务应用并部署代码：

   azd up
   

   azd up 命令可能需要几分钟时间才能完成。 azd up 使用项目中的 Bicep 文件在 P0v3 定价层中创建应用服务应用，并在 src/webapp 中部署 .NET 应用。 该命令还会为代理创建 Azure AI Foundry 和支持资源。

3.创建 AI 代理

1. 在 Azure 门户中，导航到 azd template 创建的 资源组 。 资源组的名称位于运行的 azd 命令的输出中。

2. 选择 Azure AI 项目 资源。 名称的格式应为 ai-aiproject-<identifier>。 确保选择 项目 资源，而不是中心或 AI 服务资源。 代理是从 Azure AI 项目资源创建的。

3. 选择 “启动工作室 ”以打开 Azure AI Foundry 工作室。

4. 在“ 生成”和“自定义”下的左侧菜单中，选择 “代理”。

5. 加载页面时，在下拉列表中，选择为你创建的自动生成的 Azure OpenAI 服务资源，然后选择“ 让我们去”。

6. 选择 “+ 新建代理 ”以创建新代理，或者在已为你创建代理时使用默认代理。

7. 创建代理后，在右侧菜单中添加以下说明。 这些说明可确保代理仅回答问题并完成与时装店应用相关的任务。

    You are an agent for a fashion store that sells clothing. You have the ability to view inventory, update the customer's shopping cart, and answer questions about the clothing items that are in the inventory. You should not answer questions about topics that are unrelated to the fashion store. If a user asks an unrelated question, please respond by telling them that you can only talk about things that are related to the fashion store.
    

4. 将 OpenAPI 指定工具添加到 AI 代理

有关屏幕截图和其他信息的详细指南，请参阅 Azure AI Foundry 门户中的“添加 OpenAPI 规范”工具。 这些步骤在以下说明中进行了汇总。

1. 选择“操作”旁边的“+ 添加”。

2. 选择 OpenAPI 3.0 指定的工具。

3. 为工具提供名称和以下说明。 模型使用说明来确定何时以及如何使用该工具。

    This tool is used to interact with and manage an online fashion store. The tool can add or remove items from a shopping cart as well as view inventory.
    

4. 将身份验证方法保留为匿名方法。 Web 应用上没有身份验证。 如果应用需要 API 密钥或托管标识才能访问它，则此位置将指定此信息。

5. 将 OpenAPI 规范复制并粘贴到文本框中。 OpenAPI 规范在目录中的 Codespace src/webapp 中提供，称为 swagger.json。

6. 在完成创建该工具之前，需要将应用的 URL 复制并粘贴到 OpenAPI 规范中。 将 OpenAPI 规范第 10 行中的占位符 <APP-SERVICE-URL> 替换为应用的 URL。 其格式为：https://<app-name>.azurewebsites.net。

   • 若要查找应用的 URL，请返回到资源组并导航到 应用服务。 该 URL 位于应用服务的 “概述 ”页上。

7. 选择“ 下一步”，查看提供的详细信息，然后选择“ 创建工具”。

5.将应用服务连接到 AI 代理

设置 AI 代理并添加 OpenAPI 指定工具后，需要使用相应的环境变量配置应用服务，以便应用知道要连接到哪个代理。 应用已经分配了一个托管标识，该标识允许它访问 AI 代理服务。 应用需要此托管标识才能访问代理，并使用 azd 模板创建。

1. 在添加 OpenAPI 工具的代理仪表板中，记下“代理 ID”。 其格式为：asst_<unique-identifier>。
2. 在菜单中选择 “概述 ”，记下 项目的连接字符串。 其格式为：<region>.api.azureml.ms;<subscription-id>;<resource-group-name>;<project-name>。
3. 在 Azure 门户中导航到你的应用服务。
4. 在左侧菜单中选择 环境变量 。
5. 在 “应用设置 ”选项卡中，选择“ + 添加 ”并添加以下设置：
   • 名称：AzureAIAgent__ConnectionString
   • 值：从 AI 智能代理服务中记录的连接字符串
6. 添加另一个应用设置：
   • 名称：AzureAIAgent__AgentId
   • 值：创建代理时记录的代理 ID
7. 选择页面底部 的“应用 ”，并在出现提示时确认。 应用会重启并应用新设置。

6.验证正在运行的应用

在 azd 输出中，找到应用的 URL 并在浏览器中导航到该 URL。 URL 在 azd 输出中如下所示：

Deploying services (azd deploy)

    (✓) Done: Deploying service web
    - Endpoint: https://<app-name>.azurewebsites.net/

在聊天窗口中，询问代理问题，例如：

• 我的购物车中有什么？
• 向我的购物车添加一件小牛仔夹克
• 我们有西装外套的库存吗？ 还可以询问有关项的一般问题，代理应能够提供信息。
• 告诉我关于红色修身格纹休闲衬衫的信息
• 外套是否温暖？

清理

完成此应用后，请运行以下命令以删除资源组，其中包含在本教程中创建的所有资源。

azd down

故障排除

常见问题

1. 聊天不起作用
   • 验证在应用服务环境变量中是否正确设置了环境变量（AzureAIAgent__ConnectionString 和 AzureAIAgent__AgentId）。
   • 检查 AI 代理是否已正确创建并配置了正确的 OpenAPI 工具。
   • 确保可从 Azure AI Foundry 代理服务访问 OpenAPI 规范 URL。
   • 确保在提供给 OpenAPI 指定工具的 swagger.json 中更新了应用服务 URL。
2. 权限问题
   • 如果遇到身份验证错误，请确保应用服务的托管标识具有访问 Azure AI Foundry 代理服务的适当权限。 托管标识至少需要 Microsoft.MachineLearningServices/workspaces/agents/action 权限才能与代理交互。 提供的“Azure AI 开发人员角色”具有此权限，并且应该足够。 如果您决定更改此角色，请确保它具备必要的权限。
3. API 问题
   • 如果代理无法对库存或购物车执行操作，请检查OpenAPI规范中的API路由。
   • 通过在 Swagger UI 中 /api/docs直接测试 API 终结点，验证 API 终结点是否正确响应。

查看日志

若要查看应用服务的日志，请执行以下作：

1. 在 Azure 门户中导航到你的应用服务。
2. 在左侧菜单中，选择“ 监视>日志流 ”以查看实时日志。
3. 这些日志显示可能需要解决的任何应用程序问题。

了解 API 功能

OpenAPI 规范为 AI 代理提供了有关可用终结点的信息：

购物车 API 端点

• GET /api/Cart：检索当前的购物车内容和总成本
• DELETE /api/Cart：清除购物车中的所有项目
• POST /api/Cart/add：向购物车添加项目
• PUT /api/Cart/{productId}/size/{size}：更新特定项目的数量
• DELETE /api/Cart/{productId}/size/{size}：从购物车中删除特定项目

清单 API 终结点

• GET /api/Inventory：列出所有可用的清单项
• GET /api/Inventory/{id}：获取有关特定产品的详细信息
• GET /api/Inventory/{id}/size/{size}：检查特定产品大小的库存
• GET /api/Inventory/sizes：获取清单中的所有可用大小

高级代理交互

除了基本交互之外，AI 代理还可以处理更复杂的方案：

• 个性化建议：“我需要商务休闲服装参加会议”
• 尺寸指南：“身高188厘米、体重82公斤的人应该穿多大号的西装外套？”
• 服装搭配：“什么可以与黑色牛仔夹克搭配得很好？”
• 购物车管理：“移除大号衬衫，改为添加中号的”
• 库存检查：“有没有中号的红色衬衫？”
• 价格查询：“外套的价格范围是什么？

安全注意事项

• 应用程序使用 Azure 托管标识在生产环境中对 Azure AI Foundry 代理服务进行安全身份验证。
• 可以使用任何标准做法和 Azure 资源进一步保护应用和代理。 有关安全的 Azure AI 代理基础结构模板，请参阅 azureai 示例存储库。

后续步骤

了解如何将 AI 代理连接到 Azure 应用服务上的 API 后，可以探索应用服务提供的其他 AI 集成：