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

本教學課程示範如何將代理程式功能新增到現有的資料驅動型 FastAPI CRUD 應用程式。它採用兩種不同的方法：LangGraph 與 Foundry Agent Service。

如果你的網頁應用程式已有實用功能，例如購物、飯店預訂或資料管理，透過外掛（LangGraph）或 OpenAPI 端點（Foundry Agent Service）來加入代理功能相對簡單。本教學課程會從簡單的待辦事項清單應用程式開始。最後，您將能夠在 App Service 應用程式使用代理程式建立、更新和管理工作。

LangGraph
Foundry Agent Service

螢幕擷取畫面為 LangGraph 代理程式的聊天完成工作階段。

LangGraph 與 Foundry Agent Service 皆能讓你打造具備 AI 驅動功能的代理型網頁應用程式。 LangGraph 類似於 Microsoft Agent Framework，是一個 SDK。下表列出幾種考量和取捨方向：

考量事項	LangGraph 或 Microsoft 代理框架	鑄造代理服務
Performance	快速 (在本機執行)	較慢 (受控的遠端服務)
發展	完整程式碼，最大控制權	低度程式碼，快速整合
Testing	在程式碼進行手動/單元測試	內建環境，可快速測試
Scalability	應用程式受控	Azure 受控、自動調整
安全護欄	需要自訂實作	內建內容安全與管理
身份	需要自訂實作	內建代理識別碼與認證
Enterprise	自訂整合需求	內建 Microsoft 365/Teams 部署及 Microsoft 365 整合工具的呼叫功能。

在本教學課程中，您將瞭解如何：

將現有應用程式功能轉換為 LangGraph 的外掛程式。
將外掛程式新增至 LangGraph 代理程式，並在 Web 應用程式使用。
將現有應用程式功能轉換為 Foundry Agent Service 的 OpenAPI 端點。
在網頁應用程式中打電話給 Foundry 的代理人。
指派受控身分識別連線所需的權限。

先決條件

包含作用中訂用帳戶的 Azure 帳戶 - 建立免費帳戶。
以 GitHub 帳戶使用 GitHub Codespaces - 深入瞭解 GitHub Codespaces。

以 Codespaces 開啟範例

最簡單的開始方式是使用 GitHub Codespaces，它提供完整的開發環境，並預先安裝所有必要工具。

前往 GitHub 存放庫，網址為 https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-python。
選取 [程式碼] 按鈕，選取 [Codespaces] 索引標籤，然後選取 [在主頁建立 codespace]。
稍候片刻，讓 Codespace 初始化。準備就緒後，您會在瀏覽器看到已完整設定的開發環境。

在本機執行應用程式：

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn src.app:app --host 0.0.0.0 --port 3000

看到 [您在連接埠 3000 執行的應用程式已可用] 時，請選取 [在瀏覽器中開啟] 並新增幾項工作。

代理程式尚未完全設定，因此還無法運作。您稍後會設定它們。

檢視代理程式的程式碼

這兩種方法都使用相同的實作模式，不過代理程式是在應用程式啟動時初始化，並透過 POST 請求回應使用者訊息。

LangGraph
Foundry Agent Service

LangGraphTaskAgent 是在 src/agents/langgraph_task_agent.py 的建構函式初始化。初始化程式碼會執行下列動作：

使用環境變數設定 AzureChatOpenAI 用戶端。
建立預建的 ReAct 代理程式，並附有記憶體及一組 CRUD 工具用於任務管理（參見 LangGraph 快速入門）。

# Initialize Azure OpenAI client
credential = DefaultAzureCredential()
azure_ad_token_provider = get_bearer_token_provider(
    credential, "https://cognitiveservices.azure.com/.default"
)

self.llm = AzureChatOpenAI(
    azure_endpoint=endpoint,
    azure_deployment=deployment_name,
    azure_ad_token_provider=azure_ad_token_provider,
    api_version="2024-10-21"
)

# Define tools
tools = [
    self._create_task_tool(),
    self._get_tasks_tool(),
    self._get_task_tool(),
    self._update_task_tool(),
    self._delete_task_tool()
]

# Create the agent
self.agent = create_react_agent(self.llm, tools, checkpointer=self.memory)
print("LangGraph Task Agent initialized successfully")

處理使用者訊息時，代理會以 ainvoke() 使用者訊息及執行緒 ID 來呼叫，以保持對話連續性：

result = await self.agent.ainvoke(
    {"messages": [("user", message)]},
    config=config
)

FoundryTaskAgent 是在 src/agents/foundry_task_agent.py 的建構函式初始化。初始化程式碼會執行下列動作：

使用 Azure 憑證建立 AIProjectClient。
從專案客戶端取得 OpenAI 客戶端。
依名稱從 Foundry 擷取代理程式。
為這次會話創造新的對話。

# Create the project client using Azure credentials
self.project_client = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential()
)

# Get the OpenAI client for conversation operations
self.openai_client = self.project_client.get_openai_client()

# Find the existing agent by name
self.agent = self.project_client.agents.get(agent_name)

if not self.agent:
    print(f"Agent with name '{agent_name}' not found in project.")
    return
            
# Create a conversation for this session
conversation = self.openai_client.conversations.create()
self.conversation_id = conversation.id
print("Foundry agent initialized successfully")

這個初始化程式碼並沒有為代理定義任何功能，因為通常你會在 Foundry 入口網站中建置代理。作為範例情境的一部分，它也遵循 Foundry Agent Service（Python）中「新增 App Service 應用程式作為工具」中所示的 OpenAPI 模式，並將 CRUD 功能作為 OpenAPI 端點提供。您稍後可將此執行緒當作可呼叫的工具新增至代理程式。

OpenAPI 程式碼是定義在 src/routes/api.py 中。例如，「GET /tasks」路徑定義了一個自訂 operation_id 參數，這是 Microsoft Foundry 中 OpenAPI 規格工具所要求的，並 description 幫助代理程式決定如何呼叫該 API：

@router.get(
    "/tasks",
    response_model=List[TaskItem],
    operation_id="getAllTasks",
    description="Retrieve all tasks in the task list."
)
async def get_all_tasks():
    """Get all tasks"""
    try:
        tasks = await task_service.get_all_tasks()
        return tasks
    except Exception as e:
        print(f"Error getting tasks: {e}")
        import traceback
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=f"Failed to get tasks: {str(e)}")

在處理使用者訊息時，透過將使用者訊息新增至對話並以代理程式參考呼叫 responses.create() 來觸發代理程式：

# Add user message to the conversation
self.openai_client.conversations.items.create(
    conversation_id=self.conversation_id,
    items=[{"type": "message", "role": "user", "content": message}],
)

# Create response using the agent
response = self.openai_client.responses.create(
    conversation=self.conversation_id,
    extra_body={"agent": {"name": self.agent.name, "type": "agent_reference"}},
    input="",
)

部署範例應用程式

範例存放庫包含 Azure 開發人員 CLI (AZD) 範本，可建立具有受控身分識別的 App Service 應用程式，並部署您的範例應用程式。

在終端機，使用 Azure 開發人員 CLI 登入 Azure：
```
azd auth login
```
請遵循指示來完成驗證程式。
使用 AZD 範本部署 Azure App Service 應用程式：
```
azd up
```

出現提示時，請提供下列答案：

Question	回答
輸入新的環境名稱：	輸入唯一名稱。
選取要使用的 Azure 訂用帳戶：	選取訂用帳戶。
挑選要使用的資源群組：	選取 [建立新的資源群組]。
選取要建立資源群組的位置：	選取 [瑞典中部]。
輸入新資源群組的名稱：	輸入 Enter。

在 AZD 輸出中，找到您應用程式的 URL，然後在瀏覽器中打開該 URL。 AZD 輸出中 URL 看起來像這樣：
```
 Deploying services (azd deploy)

   (✓) Done: Deploying service web
   - Endpoint: <URL>
 
```
在https://....azurewebsites.net/openapi.json 路徑上開啟自動生成的 OpenAPI 模式。您稍後會用到此結構描述。

您現在已擁有具備系統指派受控身分識別的 App Service 應用程式。

在 Foundry 入口網站中，確保頂部的 New Foundry 單選按鈕設為啟用，並建立專案。
部署你選擇的模型（參見 Microsoft Foundry 快速入門：建立資源）。
從模型遊樂場頂端複製模型名稱。
取得 Azure OpenAI 端點最簡單的方式仍是從經典入口網站。選擇 New Foundry 單選單選按鈕，然後選擇 Azure OpenAI，然後將 URL 複製到 Azure OpenAI 端點 以備後用。

在 Foundry 入口網站中，確保頂部的 New Foundry 單選按鈕設為啟用，並建立專案。
在首頁複製專案端點以供後用。
選擇開始建置>「建立代理」並依照提示操作。
在新代理程式遊樂場中，透過選擇 [工具]> [新增] > [自訂] > [OpenAPI 工具] > [建立] OpenAPI 工具來呼叫 Web 應用程式。在 [設定] 窗格，使用 OpenAPI 規格工具新增動作。使用您從已部署的 Web 應用程式取得的 OpenAPI 結構描述和匿名驗證。如需詳細步驟，請參閱如何使用 OpenAPI 規格工具。

您的應用程式程式碼已設為包含伺服器的 url 和 operationId，兩者都是代理程式的必要條件。欲了解更多資訊，請參閱連接 OpenAPI 規範。
務必選擇儲存。
選擇 在 Playground 嘗試 ，並用「顯示所有任務」和「請新增任務」等提示來測試你的 Foundry 代理。

如果收到有效回應，代表代理程式已在已部署的 Web 應用程式對 OpenAPI 端點進行工具呼叫。

指派所需的權限

LangGraph
Foundry Agent Service

在新 Foundry 入口網站的頂端選單中，選擇操作，然後選擇 管理員。在你的 Foundry 專案那一列，你應該會看到兩個連結。 Name 欄位中的資源是 Foundry 專案資源，Parent 資源 欄位中的資源是 Foundry 資源。
在 父資源 中選擇 Foundry 資源，然後 在 Azure 入口網站選擇管理此資源。從 Azure 入口網站，你可以將該資源的角色存取權分配給已部署的網頁應用程式。
為 App Service 應用程式的管理身份新增以下角色：

目標資源必要角色所需

鑄造廠認知服務 OpenAI 使用者 Microsoft Agent Framework 中的聊天完成服務。

如需操作指示，請參閱使用 Azure 入口網站指派 Azure 角色。

目標資源	必要角色	所需
鑄造廠	認知服務 OpenAI 使用者	Microsoft Agent Framework 中的聊天完成服務。

在新 Foundry 入口網站的頂端選單中，選擇操作，然後選擇 管理員。在你的 Foundry 專案那一列，你應該會看到兩個連結。 Name 欄位中的資源是 Foundry 專案資源，Parent 資源 欄位中的資源是 Foundry 資源。
在名稱欄中選擇 Foundry 專案資源，然後 在 Azure 入口網站選擇管理此資源。從 Azure 入口網站，你可以將該資源的角色存取權分配給已部署的網頁應用程式。
為 App Service 應用程式的管理身份新增以下角色：

目標資源必要角色所需

鑄造廠計畫 Azure AI 使用者正在讀取與呼叫 Foundry 代理程式。

如需操作指示，請參閱使用 Azure 入口網站指派 Azure 角色。

目標資源	必要角色	所需
鑄造廠計畫	Azure AI 使用者	正在讀取與呼叫 Foundry 代理程式。

在範例應用程式設定連線變數

開啟 .env。利用你之前從 Foundry 入口複製的數值，設定以下變數：

LangGraph
Foundry Agent Service

Variable	Description
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI 端點（從經典 Foundry 入口複製）。
`AZURE_OPENAI_DEPLOYMENT_NAME`	部署中的模型名稱 (從新 Foundry 入口網站的模型遊樂場複製)。

備註

為簡化教學課程，您會在 .env 使用這些變數，而不是在 App Service 使用應用程式設定覆寫變數。

Variable	Description
`AZURE_AI_FOUNDRY_PROJECT_ENDPOINT`	來自新 Foundry 入口網站的 Microsoft Foundry 專案端點。
`AZURE_AI_FOUNDRY_AGENT_NAME`	代理程式名稱 (來自 Foundry 入口的代理程式遊樂場)。

備註

為簡化教學課程，您會在 .env 使用這些變數，而不是在 App Service 使用應用程式設定覆寫變數。

使用 Azure CLI 登入 Azure：
```
az login
```
這可讓範例程式碼的 Azure 身分識別用戶端程式庫接收登入使用者的驗證權杖。別忘了您之前已為此使用者新增了必要角色。
在本機執行應用程式：
```
npm run build
npm start
```
看到 [您在連接埠 3000 執行的應用程式已可用] 時，請選取 [在瀏覽器中開啟]。
選取 [LangGraph 代理程式] 連結和 [Foundry 代理程式] 連結以試用聊天介面。如果你收到回應，代表你的應用程式正在成功連接到 Microsoft Foundry 資源。
返回 GitHub codespace 部署應用程式變更。
```
azd up
```
再次前往已部署的應用程式，並測試聊天代理程式。

LangGraph
Foundry Agent Service

螢幕擷取畫面為 LangGraph 代理程式的聊天完成工作階段。

清理資源

操作完應用程式後，您就可以刪除 App Service 資源，以免產生後續成本：

azd down --purge

由於 AZD 範本沒有包含 Microsoft Foundry 資源，如果你想刪除它們，就必須手動刪除。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-19