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

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

• 使用環境變數設定 AzureChatOpenAI 用戶端。
• 建立預建的 ReAct 代理程式，並附有記憶體及一組 CRUD 工具用於任務管理（參見 LangGraph 快速入門）。
• 選擇一個伺服器管理的對話線程作為已驗證的樣本。

self.memory = InMemorySaver()
# App Service authentication protects this sample, which intentionally
# keeps one server-managed conversation thread per worker process.
self.thread_id = "authenticated-conversation"

try:
    endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    deployment_name = os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME")
    
    if not endpoint or not deployment_name:
        print("Azure OpenAI configuration missing for LangGraph agent")
        return
    
    # 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)

處理使用者訊息時，代理程式會使用由伺服器管理的執行緒 ID 呼叫 ainvoke()：

config = {"configurable": {"thread_id": self.thread_id}}

# Process the message
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
            
# App Service authentication protects this sample, which intentionally
# keeps one server-managed conversation per worker process.
conversation = self.openai_client.conversations.create()
self.conversation_id = conversation.id

Foundry 的對話 ID 會留在伺服器上，瀏覽器不會回傳或接受。 兩個代理實作都會將對話狀態保留在程序記憶體中，因此部署的學習範例會執行一個 Gunicorn 工作者。 如果您增加背景工作計數或擴增應用程式，請使用外部對話存放區在背景工作與執行個體之間分享狀態。

這個初始化程式碼並沒有為代理定義任何功能，因為通常你會在 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
await asyncio.to_thread(
    self.openai_client.conversations.items.create,
    conversation_id=self.conversation_id,
    items=[{"type": "message", "role": "user", "content": message}],
)

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

1. 在 Foundry 入口網站中，建立一個專案。

2. 部署你選擇的模型（參見 Microsoft Foundry 快速入門：建立資源）。

3. 從模型遊樂場頂端複製模型名稱。

4. 在首頁複製 Azure OpenAI 端點以備後用。

1. 在 Foundry 入口網站中，建立一個專案。

2. 在首頁複製 Project 端點以便日後使用。

3. 選擇 開始建造 並依照提示操作。

4. 選擇 工具>新增>新增工具>自訂>OpenAPI 工具>建立。 在 [設定] 窗格，使用 OpenAPI 規格工具新增動作。

5. 貼上你從已認證的 App Service 應用程式複製的 OpenAPI 架構。

6. 對於 認證方法，請選擇 管理身份。

7. 對於 Audience，將 AZD 輸出中的 Foundry OpenAPI 管理身份受眾 值貼上。 它類似：

   api://<generated-client-id>
   

8. 儲存工具和代理程式。

允許父系 Foundry 資源呼叫工作 API

1. 在 Foundry 入口網站中，請在頂方選單選擇 管理 。

2. 在 專案詳細資料 中，選取您的專案的 父資源，然後選取 在 Azure 入口網站中開啟。

3. 複製系統指派身份的 物件（主體）ID。 在 Microsoft Entra ID 中找到該身份，並複製其應用程式 ID。 詳細步驟請參閱 「尋找父 Foundry 資源識別碼」。

4. 在 Codespace 終端機中，將應用程式 ID 儲存在 AZD 環境中，並更新 App Service 認證設定：

   azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
   azd provision
   

1. 在 Foundry 入口網站中，請在頂方選單選擇 管理 。

2. 在 專案詳細資料 中，選取您的專案的 父資源，然後選取 在 Azure 入口網站中開啟。

   從 Azure 入口網站，你可以為該資源指派基於角色的存取權限。

3. 為 App Service 應用程式的受控識別以及您搭配 az login 使用的使用者新增以下角色：

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

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

1. 在 Foundry 入口網站中，請在頂方選單選擇 管理 。

2. 在 Project 詳細資料中，選擇「在 Azure 門戶開啟」。

   你可以從 Azure 入口網站為專案指派基於角色的存取權限。

3. 為 App Service 應用程式的受控識別以及您搭配 az login 使用的使用者新增以下角色：

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

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