---
# System prepended metadata

title: "\U0001F680 Hosted Agent 部署完整指南"
tags: [Microsoft Agent Framework]

---

# 🚀 Hosted Agent 部署指南

---

## 📚 參考資料
- [What are hosted agents?](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry&tabs=cli)

---

## 🧩 一、前置需求（Prerequisites）

### 🔐 Azure Subscription 權限
- **Resource Group Owner** 或 **Subscription Contributor**

### 🐳 Docker 環境
- 安裝 Docker Desktop（Windows）  
  👉 [Install Docker Desktop on Windows](https://docs.docker.com/desktop/setup/install/windows-install/)

### 🧠 Microsoft Foundry Project
- ⚠️ 目前僅支援 **North Central US**
- 建議事先部署所需的 **LLM Models**

### 🛠️ Azure Developer CLI（azd）
- 目前實測僅 **Azure Developer CLI（azd）** 可正確完成 Hosted Agent 部署
- 安裝或更新 azd  
  👉 [Install or update the Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd?tabs=winget-windows%2Cbrew-mac%2Cscript-linux&pivots=os-windows)
- 使用以下指令更新至最新版：
  ```powershell
  winget upgrade Microsoft.Azd
  ```

---

## 🔐 Step 0：登入 azd
```powershell
azd auth login
```

---

## 📁 Step 1：建立空資料夾並初始化專案
```powershell
azd init -t https://github.com/Azure-Samples/azd-ai-starter-basic
```

### 操作說明
- 輸入 **azd environment name**（可任意命名）
- azd 會下載部署所需檔案至目前資料夾  
  ![image](https://hackmd.io/_uploads/rJcOUwNr-x.png)

---

### 🧱 調整 Bicep：部署至既有 Foundry Resource Group（重要）

預設 `bicep` 會建立新的 Resource Group，若要部署至 **既有 Foundry Resource Group**，請修改：

#### 1️⃣ `infra/main.bicep`

**a. 調整 targetScope**
```bicep
// targetScope = 'subscription'
targetScope = 'resourceGroup'
```

**b. 移除整段 Resource Group 建立邏輯**
```bicep
// Check if resource group exists and create it if it doesn't
resource rg 'Microsoft.Resources/resourceGroups@2021-04-01' = {
  name: resourceGroupName
  location: location
  tags: tags
}
```

**c. 移除 module 中的 scope: rg**
```bicep
// AI Project module
module aiProject 'core/ai/ai-project.bicep' = {
  // scope: rg   <-- 請移除此行
  name: 'ai-project'
  params: {
    tags: tags
    location: aiDeploymentsLocation
    aiFoundryProjectName: aiFoundryProjectName
    principalId: principalId
    principalType: principalType
    existingAiAccountName: aiFoundryResourceName
    deployments: aiProjectDeployments
    connections: aiProjectConnections
    additionalDependentResources: dependentResources
    enableMonitoring: enableMonitoring
    enableHostedAgents: enableHostedAgents
  }
}
```

---

### 🔑 啟用 API Key
預設會 **disable API Key authentication**，現行架構只可使用 API Key，請修改：

📄 `infra/core/ai/ai-project.bicep`
```bicep
disableLocalAuth: false
```

---

## 🧭 Step 2：指定 Microsoft Foundry Project

### 初始化 Agent 專案
```powershell
# 請自行替換 SUBSCRIPTIONID / RESOURCEGROUPNAME / ACCOUNTNAME / PROJECTNAME
azd ai agent init --project-id [project resource id]

# 範例
azd ai agent init --project-id /subscriptions/d598fcd6-0db7-43df-adb8-7b537c178a92/resourceGroups/hosted-agent/providers/Microsoft.CognitiveServices/accounts/north-central-us-hostedagent/projects/north-central-us-hostedagent
```

### 💡 關鍵提示
- **Project Resource ID** 可由 Classic Portal 取得  
  ![image](https://hackmd.io/_uploads/SJo9JdES-g.png)

- 若出現以下錯誤，**再次執行一次即可**
  ```
  Tenant provided in token does not match resource token
  ```

- 出現 ACR Endpoint 提示時，**請留空**
  ```
  If you plan to provision one through azd provision or azd up, leave blank.
  ```
### `azd ai agent init -m agent.yaml` 的作用
```
┌─────────────────────────────────────────────────────────────────┐
│              azd ai agent init -m agent.yaml 做的事              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. 讀取 agent.yaml 設定                                        │
│                                                                 │
│   2. 複製 source code 到 src/ 目錄（準備部署）                    │
│                                                                 │
│   3. 註冊 agent 到 azure.yaml 的 Services                        │
│                                                                 │
│   4. 準備 Dockerfile 和相關部署檔案                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```
---

### ✅ 初始化完成後
- 專案目錄下會新增 `.azure` 資料夾
- `.azure/.env` 內含 Foundry Project 連線資訊  
  ![image](https://hackmd.io/_uploads/SkP3MdVrbe.png)

---

## 📦 Step 3：準備專案原始碼與設定

### 複製原始碼
- 將您的 Agent 原始碼複製到專案目錄
- 💡 **請移除 `.venv`**，避免複製耗時

---

### 🐳 Dockerfile 與 agent.yaml

📌 參考範例：[foundry sample](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent_framework/agents_in_workflow) 取得範例`dockerfile`與 `agent.yaml`

---

#### Dockerfile（範例）
請修改為您的情境，至少包含
**Python Image 設定** --> **工作目錄設定** --> **安裝 requirements.txt** --> **程式碼複製** --> **Port 開放** --> **環境變數設定** --> **啟動指令**
```dockerfile
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8088
ENV PYTHONUNBUFFERED=1

CMD ["python", "src/main_hosted_agent.py"]
```

---

#### agent.yaml（範例）
+ 主要修改Template區段的name,此名稱為Foundry Portal顯示的名稱
 
```yaml
name: financial-agent
description: >
  A workflow agent that answer financial question

metadata:
  authors:
    - George Liang
  tags:
    - Workflows

template:
  name: financial-analyst-agent
  kind: hosted
  protocols:
    - protocol: responses

resources:
  - kind: model
    id: gpt-5
    name: chat
```

💡 **提示**：  
`environment_variables` 可移除，執行時會自動讀取 `.env`

---

## 🧪 本機測試（Optional）

### Docker Build
```powershell
docker build --no-cache -t hostedagent-financial-analyst:1 .
```

### Docker Run
```powershell
docker run -p 8088:8088 hostedagent-financial-analyst:1
```

### curl 測試
```powershell
curl -N -X POST http://localhost:8088/responses `
  -H "Content-Type: application/json" `
  -d @request.json
```

`request.json` 範例：
```json
{
  "input": "我要建立2404公司的財務數字分析...",
  "stream": true
}
```

---

## ☁️ Step 4：部署 Agent 至 Microsoft Foundry

### 初始化 Agent
```powershell
azd ai agent init -m <path-to-agent.yaml>
```

💡 關鍵提示：
- 請在 `azure.yaml` 所在目錄執行
- 必須使用 **絕對路徑**

---

### azure.yaml 預設設定（目前不可更改）
- Memory：`2Gi`
- CPU：`1`
- Min Replicas：`1`
- Max Replicas：`3`

⚠️ 使用其他值會導致部署失敗  
![image](https://hackmd.io/_uploads/SJ2I6hVSZx.png)

---

### 🚀 環境與應用部署
```powershell
azd up
```

#### 部署完成
![image](https://hackmd.io/_uploads/BkVlg6Nrbl.png)

- Foundry Portal 中可看到 Agent 類型為 **hosted**  
  ![image](https://hackmd.io/_uploads/r1OQWa4Bbe.png)
- Foundry Portal 中進行對話  
![image](https://hackmd.io/_uploads/rkY1a1rSbl.png)

---

## 🔄 程式碼更新後的重新部署

| 變更內容 | 需要的指令 |
|----------|-----------|
| 改程式碼 | `azd ai agent init -m agent.yaml` → `azd deploy` |
| 改 `agent.yaml` 的 `environment_variables` | `azd ai agent init -m agent.yaml` → `azd deploy` |
| 改 `.env` | `azd ai agent init -m agent.yaml` → `azd deploy` |
| **任何變更** | **都要** `azd ai agent init -m agent.yaml` → `azd deploy` |


### 重新初始化 Agent
```powershell
azd ai agent init -m <path-to-agent.yaml>
```
![image](https://hackmd.io/_uploads/HJgzUJrrWe.png)

### 重新部署
```powershell
azd deploy
```


![image](https://hackmd.io/_uploads/Hy715ySrZl.png)

---

🎉 **完成！**  
你已成功將 Hosted Agent 部署至 Microsoft Foundry，並可持續迭代更新 🚀
