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

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

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

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

先决条件

本教程假设你使用的是在 Azure 中使用 PostgreSQL 部署 Python FastAPI Web 应用中使用的示例。

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

将 OpenAPI 功能添加到 Web 应用

FasAPI 已在默认路径 /openapi.json 中包含 OpenAPI 功能。 只需对现有代码进行一些更改即可使其可由智能体远程调用。

1. 打开 src/fastapi_app/app.py 并找到第 24 行，其中声明了 FastAPI 应用。 将 app = FastAPI() 替换为以下代码：

   if os.getenv("WEBSITE_HOSTNAME"):
       server_url = f"https://{os.getenv('WEBSITE_HOSTNAME')}"
   else:
       server_url = "http://localhost:8000"
   app = FastAPI(
       title="Restaurant Review API",
       version="1.0.0",
       description="Can show restaurant ratings HTML and add new restaurants and reviews.",
       servers=[{"url": server_url}],
   )
   

   此代码将元数据添加到 OpenAPI 架构，例如 title 和 description。 最重要的是，它添加 API 终结点的服务器 URL。

2. 打开 src/fastapi_app/app.py，将 operation_id 添加到 / 和 /details/{id} GET API。 这两个 API 返回 AI 智能体可以分析的 HTML 文档。 对于所有其他 API，请添加 include_in_schema=False 参数。

   @app.get("/", response_class=HTMLResponse, operation_id="getRestaurantsWithRatingsHtml")
       ...    
   
   @app.get("/create", response_class=HTMLResponse, include_in_schema=False)
       ...    
   
   @app.post("/add", response_class=RedirectResponse, include_in_schema=False)
       ...
   
   @app.get("/details/{id}", response_class=HTMLResponse, operation_id="getRestaurantDetails")
       ...    
   
   @app.post("/review/{id}", response_class=RedirectResponse, include_in_schema=False)
       ...
   

   你使用 include_in_schema=False 排除 GET /create、POST /add 和 POST /review/{id}，因为它们是基于表单的功能的一部分，而 AI 智能体需要提交 JSON 数据。

3. 若要添加餐厅并使用 JSON 添加审阅功能，请添加以下代码：

   from typing import Optional
   from fastapi import Body, HTTPException
   
   @app.post("/api/restaurants", response_model=Restaurant, status_code=status.HTTP_201_CREATED, operation_id="createRestaurant")
   async def create_restaurant_json(
       name: str = Body(...),
       street_address: str = Body(...),
       description: str = Body(...),
       session: Session = Depends(get_db_session),
   ):
       restaurant = Restaurant(name=name, street_address=street_address, description=description)
       session.add(restaurant)
       session.commit()
       session.refresh(restaurant)
       return restaurant
   
   
   @app.post("/api/restaurants/{id}/reviews", response_model=Review, status_code=status.HTTP_201_CREATED,operation_id="createReview")
   async def create_review_for_restaurant_json(
       id: int,
       user_name: str = Body(...),
       rating: Optional[int] = Body(None),
       review_text: str = Body(...),
       session: Session = Depends(get_db_session),
   ):
       if not session.get(Restaurant, id):
           raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Restaurant not found")
   
       review = Review(
           restaurant=id, user_name=user_name, rating=rating, review_text=review_text, review_date=datetime.now()
       )
       session.add(review)
       session.commit()
       session.refresh(review)
       return review
   

   此代码仅显示创建 API，以便简洁起见，并与现有示例应用程序奇偶校验。 如果需要，还可以添加其他 API，例如更新和删除。

4. 使用以下命令启动示例应用的开发服务器：

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r src/requirements.txt
   pip install -e src
   python3 src/fastapi_app/seed_data.py
   python3 -m uvicorn fastapi_app:app --reload --port=8000
   

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

6. 通过将 /openapi.json 添加到 URL 来查看 OpenAPI 架构，这是 FastAPI 用于提供架构的默认路径。

7. 返回 codespace 终端，通过提交更改（GitHub Actions 方法）或运行 azd up (Azure Developer CLI 方法)来部署更改。

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

在 Microsoft Foundry 中创建代理

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

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

2. 按照“如何使用 OpenAPI 规范工具”中的步骤，选择新智能体并使用 OpenAPI 3.0 指定的工具添加操作。

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

小窍门

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

测试代理

1. 如果智能体操场尚未在 Foundry 门户中打开，请选择智能体，然后选择“在操场中试用”。

2. 使用以下提示建议与智能体聊天：

   • “展示餐馆评论的列表。”
   • “创建一家餐馆。 将你的想象力用于细节。”
   • “我不喜欢这家餐厅的食物。 请创建 2 星评论。”

   

安全最佳做法

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

• 身份验证和授权：使用 Microsoft Entra 身份验证保护 OpenAPI 终结点。 有关分步说明，请参阅 Foundry 代理服务的安全 OpenAPI 端点。 还可以 使用 Microsoft Entra ID 保护 Azure API 管理 背后的终结点，并确保只有经过授权的用户或代理才能访问这些工具。
• 验证输入数据：始终验证传入数据，以防止无效或恶意输入。 对于 Python 应用，请使用 Pydantic 等库通过专用请求架构模型（如 RestaurantCreate 和 ReviewCreate）强制实施数据验证规则。 有关最佳做法和实现详细信息，请参阅其文档。
• 使用 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 和移动应用中。

若要执行下一步，了解如何直接在 Azure 应用服务中运行智能体，请参阅以下教程：

教程：使用 LangGraph 或 Foundry 代理服务在 Azure 应用服务中生成代理 Web 应用（Python）

更多资源

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