# 🚀 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)
- 使用以下指令更新至最新版：

  winget upgrade Microsoft.Azd

---

## 🔐 Step 0：登入 azd

azd auth login

---

## 📁 Step 1：建立空資料夾並初始化專案

azd init -t https://github.com/Azure-Samples/azd-ai-starter-basic

### 操作說明
- 輸入 **azd environment name**（可任意命名）
- azd 會下載部署所需檔案至目前資料夾

---

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

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

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

**a. 調整 targetScope**

// targetScope = 'subscription'
targetScope = 'resourceGroup'

**b. 移除整段 Resource Group 建立邏輯**

// 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**

// 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`

disableLocalAuth: false

---

## 🧭 Step 2：指定 Microsoft Foundry Project

### 初始化 Agent 專案

# 請自行替換 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 取得

- 若出現以下錯誤，**再次執行一次即可**

  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 連線資訊

---

## 📦 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 開放** --> **環境變數設定** --> **啟動指令**

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顯示的名稱

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

docker build --no-cache -t hostedagent-financial-analyst:1 .

### Docker Run

docker run -p 8088:8088 hostedagent-financial-analyst:1

### curl 測試

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

`request.json` 範例：

{
  "input": "我要建立2404公司的財務數字分析...",
  "stream": true
}

---

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

### 初始化 Agent

azd ai agent init -m <path-to-agent.yaml>

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

---

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

⚠️ 使用其他值會導致部署失敗

---

### 🚀 環境與應用部署

azd up

#### 部署完成

- Foundry Portal 中可看到 Agent 類型為 **hosted**
- Foundry Portal 中進行對話

---

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

| 變更內容 | 需要的指令 |
|----------|-----------|
| 改程式碼 | `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

azd ai agent init -m <path-to-agent.yaml>


### 重新部署

azd deploy


---

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