在 Foundry Agent Service（Python）中新增一個 App Service 應用程式作為工具

在這個教學中，你將學習如何透過 OpenAPI 暴露 FastAPI 應用程式的功能，將其作為工具加入 Foundry Agent Service，並在代理的遊樂場中用自然語言與你的應用程式互動。

如果您的網頁應用程式已有實用功能，如購物、飯店預訂或資料管理，您可以輕鬆透過 Foundry Agent Service 讓 AI 代理使用這些功能。 只要將 OpenAPI 結構描述新增至您的應用程式，您就可以讓代理程式在回應使用者的提示時了解和使用應用程式的功能。 這意味著您的應用程式可以做的操作，您的 AI 代理程式也可以執行，只需除了為您的應用程式建立 OpenAPI 端點之外最少的努力。 在本教學課程中，您將從一個簡單的餐廳評等應用程式開始。 最後，您將能夠查看餐廳評等，並通過對話式 AI 與代理程式一起創建新餐廳和新評論。

• 將 OpenAPI 功能新增至您的 Web 應用程式。
• 確保 OpenAPI 架構與 Foundry Agent Service 相容。
• 在 Foundry Agent Service 中註冊你的應用程式為 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 開發人員 CLI 方法) 來部署變更。

8. 部署變更後，請瀏覽至 https://<your-app's-url>/openapi.json 並複製結構描述以供稍後使用。

在 Microsoft Foundry 建立代理程式

備註

這些步驟使用了新的 Foundry 入口網站。

1. 在 Foundry 入口網站，右上角選單中選擇 「New Foundry」。

2. 如果你是第一次進入新的 Foundry 入口網站，請選擇專案名稱並選擇 建立新專案。

3. 給你的專案取個名字，然後選擇 「創建」。

4. 選擇 開始建置，然後 建立代理。

5. 給你的經紀人一個名字，然後選擇 「建立」。 當 Agent 準備就緒時，您應該會看到 Agent 遊樂場。

   記下您可以使用的模型和可用區域。

6. 在代理遊玩場中，展開 「工具 」並選擇 「新增>自訂>OpenAPI 工具>」「建立」。

7. 給工具一個名稱和描述。 在 OpenAPI 3.0+ 的架構 框裡，貼上你之前複製的架構。

8. 選擇 建立工具。

9. 選取 [儲存]。

小提示

在本教學課程中，OpenAPI 工具會設定為匿名呼叫您的應用程式，無需驗證。 針對生產案例，您應該使用受控識別驗證來保護工具。 如需逐步操作說明，請參閱 Foundry Agent Service 的安全 OpenAPI 端點。

測試代理程式

1. 在 說明中，給出一些簡單的指示，例如 「請使用 restaurantReview 工具協助管理餐廳評論」。

2. 用以下提示建議與代理程式聊天：

   • 「給我看看餐廳評論清單。」
   • 「創立一家餐廳。 發揮你的想像力來構想細節。」
   • 「我不喜歡這家餐廳的食物。 請建立 2 星評論。」

   

安全性最佳做法

在 Azure App Service 中透過 OpenAPI 公開 API 時，請遵循下列安全性最佳做法：

• 驗證和授權：使用 Microsoft Entra 驗證保護您的 OpenAPI 端點。 如需逐步操作說明，請參閱 Foundry Agent Service 的安全 OpenAPI 端點。 您也可以 使用 Microsoft Entra ID 保護 Azure API 管理 後方的端點，並確保只有授權的使用者或代理程式才能存取工具。
• 驗證輸入資料： 一律驗證傳入資料，以防止無效或惡意輸入。 對於 Python 應用程式，請使用 Pydantic 等程式庫，透過專用請求結構描述模型 (例如 RestaurantCreate 和 ReviewCreate) 強制執行資料驗證規則。 請參閱其文件，以取得最佳做法和實作詳細資料。
• 使用HTTPS：此範例依賴 Azure App Service，預設會強制執行 HTTPS，並提供免費的 TLS/SSL 憑證來加密傳輸中的資料。
• 限制 CORS：將 CORS 限制為僅受信任的網域。 如需詳細資訊，請參閱啟用 CORS。
• 套用速率限制： 使用 APIM 或自訂中介軟體來防止濫用和阻斷服務攻擊。
• 隱藏敏感性端點：避免在 OpenAPI 結構描述中公開內部或系統管理 API。
• 檢閱 OpenAPI 結構描述：確保您的 OpenAPI 結構描述不會洩漏敏感資訊 (例如內部 URL、秘密或實作詳細資料)。
• 保持相依性更新：定期更新 NuGet 套件並監視安全性建議。
• 監控和記錄活動：啟用記錄並監控存取以偵測可疑活動。
• 使用受控識別：呼叫其他 Azure 服務時，請使用受控識別，而不是硬式編碼認證。

如需詳細資訊，請參閱保護您的 App Service 應用程式和 REST API 安全性的最佳做法。

後續步驟

您至此已經啟用 App Service 應用程式，可讓 Foundry Agent Service 當作工具使用，並透過自然語言在代理程式的環境與應用程式的 API 互動。 接著，你可以繼續在 Foundry 入口網站為代理程式新增功能，或使用 Microsoft Foundry SDK 或 REST API 將其整合到自己的應用程式中，或將其部署為更大解決方案的一部分。 在 Microsoft Foundry 中建立的代理可以在雲端執行、整合進聊天機器人，或嵌入網頁和行動應用程式中。

若要採取下一個步驟，並了解如何直接在 Azure App Service 內執行代理程式，請參閱下列教學課程：

教學：在 Azure App Service 中使用 LangGraph 或 Foundry Agent Service（Python）建立代理型網頁應用

更多資源

• 將 AI 整合至 Azure App Service 應用程式
• 什麼是 Foundry Agent Service？ (部分內容可能是機器或 AI 翻譯)