搭配 Azure Developer CLI 的託管代理程式基礎結構

Azure 開發者 CLI（azd）可從 中azure.yaml宣告的服務產生 Bicep 或 Terraform 基礎架構。 選擇 Terraform 與 azd ai agent init --infra=terraform，或 Bicep 與 --infra=bicep。 執行 azd provision 會套用所選的基礎架構。

基礎設施配置與代理部署是分開的。 Terraform 或 Bicep 會管理支援性 Azure 資源；azd deploy 會建立代管代理程式的資料平面版本。 若想用 Terraform 而非 azd 管理代理程式本身，請參見 「部署託管代理與 Terraform」。

哪些會被佈建

預設情況下， azd ai agent init 不會建立基礎設施即程式碼檔案。 使用 --infra 或 --infra=bicep 新增 Bicep 基礎結構。 使用 --infra=terraform 來新增 Terraform 基礎設施並設定 infra.provider: terraform。

當你新增 Bicep 基礎設施時，範本是基於 azd-ai-starter-basic 儲存庫，並建立以下 Azure 資源：

範本會根據在 azure.yaml 中宣告的服務與相依性，有條件地建立更多的資源：

• 代理能力設定——宣告持有代理狀態、向量資料和檔案的 Azure 資源。 當你需要代理人使用你擁有的儲存空間時，就設定它們。
• Grounding with Bing 或 Grounding with Bing Custom Search——用於網頁搜尋工具。
• Azure AI 搜尋服務 —— 作為搜尋依據。
• Azure 儲存體 -- 用於檔案操作。

專案結構

對於 Bicep，生成的專案結構如下：

infra/
|-- main.bicep                 # Main deployment template (subscription-scoped)
|-- main.parameters.json       # Parameter bindings to azd environment variables
|-- abbreviations.json         # Naming convention abbreviations
\-- core/
    |-- ai/                    # Foundry account, project, and connections
    |-- host/                  # Container registry
    |-- monitor/               # Application Insights and Log Analytics
    |-- search/                # Azure AI Search (conditional)
    \-- storage/               # Azure Storage (conditional)

參數的流動方式

對於 Bicep，該main.parameters.json檔案會將環境變數映射azd到參數：

{
  "environmentName": { "value": "${AZURE_ENV_NAME}" },
  "location": { "value": "${AZURE_LOCATION}" },
  "aiFoundryResourceName": { "value": "${AZURE_AI_ACCOUNT_NAME}" },
  "aiProjectDeploymentsJson": { "value": "${AI_PROJECT_DEPLOYMENTS=[]}" }
}

在 azd provision 期間，azd 會從環境 (${VAR}) 解析這些 .azure/<env>/.env 參考，並將其傳遞給 Bicep 部署。 部署的輸出內容，例如 Foundry 專案端點、模型部署名稱和容器登錄端點，會回寫至環境中，供 azd deploy、azd ai agent run 和 azd ai 資源命令使用。

Terraform 基礎設施

建立新專案時，azd ai agent init --infra=terraform 會產生如下檔案：

infra/
|-- main.tf
|-- provider.tf
|-- variables.tf
|-- outputs.tf
|-- main.tfvars.json
\-- .azd-foundry

基於容器的服務也能產生 container-registry.tf。 現有專案可保留其原有基礎架構，並在 infra/foundry/ 下取得獨立的 Foundry 層。 使用實際產生的版面配置，而不是在圖層間移動檔案。

Terraform 設定提供 Foundry 帳號、專案、模型部署及所選服務所需的相關資源。 容器登錄檔的建立取決於部署模式與映像設定。

main.tfvars.json 將基礎設施輸入綁定於 AZD 環境值。 outputs.tf 在配置後，將像 Foundry 專案端點這類的值暴露給 azd。 這些繫結是 azd 工作流程的一部分；不要假設產生的參數檔可以原封不動地在獨立的 terraform apply 中使用。

要自訂 Terraform 基礎架構，請編輯產生 .tf 的檔案、保留代理服務所需的輸出，並執行 azd provision。 在實施基礎設施變更前，請先檢視 Terraform 計畫。

Terraform 狀態與 CI/CD

產生的檔案不會啟動遠端狀態後端。 對於團隊部署，請先設定以 Azure 儲存體 為後端的狀態、各環境各自的狀態金鑰，以及所需的後端權限，再進行 CI/CD 設定。

請參閱「 使用 Terraform 設定 CI/CD 」來了解部署流程，並 使用 Terraform 搭配 azd 進行後端設定。

Terraform 退出限制

Terraform 退出路徑在目前的 Foundry Agent 擴充功能中，不支援服務network:設定。 在退出已有基礎設施的專案前，請檢視現有資源限制。 退出不是一般 Bicep 到 Terraform 的狀態移轉，且刪除生產資源並不是採用 Terraform 的先決條件。

現有資源

Bicep 範本支援連接現有的 Azure 資源，而非建立新的資源。 這對於團隊已經有共用基礎設施特別有用。

在執行azd env set前，先將這些變數設定為 azd provision 。

客製化基礎設施

目錄 infra/ 是標準 azd 的基礎設施。 新增或更改 Bicep 資源：

1. 編輯infra/main.bicep或在infra/core/下方新增模組。
2. 將新參數加入main.parameters.json，並使用${VAR}綁定。
3. 將對應 azd 的環境變數設為 azd env set。
4. 執行 azd provision 以套用變更。

Bicep 檔案的變更會保存在各個部署。

區域限制

該 main.bicep 範本限制 location 於支援託管代理的區域。 如果你需要部署到不在允許清單中的區域，請在 @allowed 中更新 main.bicep 裝飾器。

相關內容

• azure.yaml 的託管代理程式參考
• 為託管代理設定 CI/CD
• azd-ai-starter-basic repository