Important
本文中標示為預覽的項目目前仍在預覽中。 此預覽版未簽訂服務等級協議，Microsoft 不建議用於生產工作負載。 某些功能可能不被支援或功能受限。 欲了解更多資訊，請參閱 Microsoft Azure 預覽版補充使用條款。
Azure Developer CLI（azd）及其 azd ai agent 擴充功能提供單一命令列工作流程，讓你能將想法轉化為可在 Microsoft Foundry 上投入生產環境的代理程式。 你可以開發基於程式碼的託管代理，以及宣告式提示式的語音代理。 本文說明開發者的旅程、定義代理的檔案，以及你在過程中遇到的核心概念。
本文是給偏好終端機優先、可腳本化工作流程而非 Foundry 入口網站或語言 SDK 的開發者。
開發者之路
無論您是建置小型原型還是生產代理程式，azd ai 工作流程的生命週期都相同。 你先搭建一個專案，然後隨著專案成長混合搭配指令。
| Stage | 你該怎麼做 | 在哪裡可以了解更多 |
|---|---|---|
| Install | 安裝 azd 和 Foundry 擴充功能。 |
建立你的開發者環境 |
| 鷹架 | 可以從範本或現有程式碼初始化託管代理，或建立基於提示的語音代理。 | 快速啟動：部署託管代理 或 快速啟動：建立即時語音代理 |
| 定義 | 配置代理程式、建模部署相依關係、協定、工具及環境。azure.yaml |
為託管代理程式撰寫 azure.yaml |
| 開發 | 撰寫代理邏輯，使用工具箱新增工具，並在本地測試。 | 工具箱概述 |
| Deploy | 佈建基礎設施並部署至 Foundry。 | 部署託管代理 |
| 操作 | 監控日誌、管理版本並自動化執行。 | 管理託管代理 |
| Evaluate | 衡量代理人的品質並改進提示。 | 使用 azd CLI 執行代理評估 |
代理人類型
此 azd ai agent 擴充支援基於程式碼的代理類型與宣告式代理類型。
| 類型 | Description | 何時使用 |
|---|---|---|
| 託管代理 | 一個容器化的應用程式，你用程式碼建置，打包成 Docker 映像，然後部署到 Foundry。 | 你需要自訂邏輯、框架整合，或是完全控制行為。 |
| 提示 Agent | 代理完全透過指令和工具配置定義，沒有自訂程式碼。 | 你需要一個快速、設定驅動的代理程式，且不需要寫應用程式程式碼。 |
| 提示式語音代理 | 一種宣告式語音代理程式，使用管理型或自我部署模型，無需自訂執行時程式碼。 | 你想要的是即時對話式語音體驗，但又不想建立和託管音訊管道。 |
| 搭配受控包裝層的託管語音 Agent | 託管目標負責處理對話邏輯，另一個語音服務則透過 conversationEngine 將處理工作委派給該目標。 Voice Live 負責音訊體驗。 |
你需要自訂代理邏輯，卻沒有在託管目標中實作語音辨識和合成。 |
託管代理讓您完全掌控執行時、框架與工具整合，而 Foundry 則負責基礎架構、擴展與會話管理。
基於提示的語音代理不需要自訂容器。 如果你需要在自己的容器中執行自訂的語音轉語音或級聯音訊管線，請建立 搭配託管代理程式的語音代理，並使用 invocations_ws 協定。
若要在託管文字代理中保留對話邏輯，而 Voice Live 處理音訊，請使用 託管語音包裝器工作流程。 包裝器和目標是同一 azure.yaml 專案中不同的服務。 這個流程並不會取代現有的自訂 invocations_ws 音訊管線流程。
在使用公開預覽語音 CLI 選項前，請依照 語音代理快速啟動的前提條件，檢查你已安裝的擴充功能。
組態檔
託管代理專案會在專案根節點使用一個 azure.yaml 檔案來宣告代理及其配置與部署模型。 該檔案採用分割服務模型，每個命名服務的值分別為 host 、 azure.ai.project、 azure.ai.agent、 azure.ai.connectionazure.ai.toolboxazure.ai.skill或 。azure.ai.routine
| File | Purpose | 誰來維護它 |
|---|---|---|
azure.yaml |
宣告 Foundry 專案、模型部署、託管代理服務、相依性、協定、工具、環境變數、容器資源及部署設定。 代理身份、模型、協定、工具與環境價值都存在於服務中 azure.ai.agent 。 |
它是在初始化時產生的。 你可以根據需要自訂它。 |
該 azure.ai.agent 服務會內嵌定義你的託管代理人，並用 uses: 來參考其他服務，例如專案、連結、工具箱、技能和例行程序。 目前託管代理agent.yaml專案模型中沒有獨立agent.manifest.yaml或azd檔案。
對於基於提示的語音代理，儲存 azure.yaml 宣告式代理定義，包括 kind: prompt-voice模型、模型類型及代理名稱。 它不包含託管代理程式的容器執行環境。 若要自訂說明、音訊、轉彎偵測、轉錄、語音輸出、工具及問候語，請參閱 「設定語音代理」。
對於託管語音包裝器，則 conversationEngine.name 參考託管目標的服務名稱。 封裝器的 uses 相依性會決定部署順序，而 conversationEngine.version 預設會使用目前環境所部署的版本。 請參閱 語音服務參考資料 中的設定欄位。
變數替換
對於依 ${VAR_NAME} 環境而異的值，請在 azure.yaml 中使用 azd。 預留位置會在部署或執行階段從 .azure/<env>/.env 解析，因此相同的 azure.yaml 可在開發、預備和生產等不同環境中使用。
CLI 執行地點
這些 azd ai 指令在 azd 專案目錄內外皆可使用：
- 在
azd專案內，指令會從作用中的azd環境解析出 Foundry 專案端點。 - 在
azd專案之外，先使用azd ai project set <endpoint>設定一次作用中的上下文，或在個別資源命令 (--project-endpoint、connection、toolbox或skill) 上傳入routine。 作為備用，azd ai讀取FOUNDRY_PROJECT_ENDPOINT環境變數。 - 專案內環境始終優先於全域上下文，因此將目錄變更為專案會將 CLI 重新定位於該專案的端點。
Protocols
一個協定定義了 Foundry 與你的代理容器之間的 HTTP 合約。 你的代理程式會在 8088 連接埠上接聽，並提供健康狀態探測回應，無論使用何種通訊協定。
| Protocol | API 風格 | 何時使用 |
|---|---|---|
responses |
OpenAI 回應 API（POST /responses） |
標準選擇，與 OpenAI API 生態系統相容。 |
invocations |
自訂 JSON 合約 （POST /invocations） |
當你需要完全控制請求與回應的承載資料時。 |
完整規範請參閱 Hosted Agent 執行時合約。
這些協定設定適用於託管代理容器。 基於提示的語音代理不會設定託管代理協定。
azd ai agent invoke 不為提示式語音代理或託管語音包裝器實作語音對話。 關於 CLI 行為與測試指引，請參閱 語音代理限制。
會議與對話
| 概念 | Description |
|---|---|
| Session | 一個針對單一代理互動的隔離執行環境。 每個工作階段都在各自的沙盒中執行，並配有專屬資源。 |
| 談話 | 工作階段中的一連串訊息。 Foundry 會管理對話歷史記錄，並可在不同請求之間重新載入這些記錄。 |
工作階段會以 session_id 識別。 當你執行 azd ai agent invoke時，Foundry 預設會重用你上次召喚的會話。 使用 --new-session 重新開始，或使用 --session-id <id> 指定特定工作階段。
鑄造廠專案資源
Foundry 專案包含的不只是代理程式。 它同時儲存在執行時代理者參考的共享資源。 CLI 透過專用指令群組管理每一個。
| Resource | 內容 | 受控方式 |
|---|---|---|
| Connection | 將 Foundry 專案連結到外部資源，例如 MCP 伺服器、Azure AI 搜尋服務 或 Grounding with Bing。 |
azd ai connection 命令 |
| 工具箱 | 一組有名稱的工具集合，供代理在執行時使用。 |
azd ai toolbox 命令 |
| 技能 | 專案中各代理共享的可重複使用行為指引。 |
azd ai skill 命令 |
| 例行程式 | 一個觸發點加上一個會召喚代理人的動作。 |
azd ai routine 命令 |
這些資源會在同一專案中由開發者和代理人共享。 每個指令群組都提供標準的 create、update、delete、show 和 list 動詞。
評估並改進代理人
在代理程式執行完畢後，兩個相關的工作流程可協助你衡量並改善其品質：
- 評估會讓你的代理人與資料集比較，對一個或多個評估者的回應進行評分，並報告一個整體品質訊號。 你可以用
azd ai agent eval來管理。 - 最佳化會反覆重新寫入您的代理程式提示，以提升評估訊號。 它以評估為目標，並產生一個候選提示，你必須審閱並接受。 你可以用
azd ai agent optimize來管理。
詳情請參見 「用azd CLI執行代理評估 」和 「優化代理提示」。
部署生命週期
完整的開發迴圈會濃縮成一連串簡短的指令。 先搭建一次支架，然後隨著專案成長使用直接指令。
關於受管理的語音代理路徑，請參見 快速入門：建立提示語音代理。
# Scaffold a project from a template or your existing code
azd ai agent init
# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"
# Provision infrastructure and deploy the agent
azd up
# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent
# Evaluate quality
azd ai agent eval generate
azd ai agent eval run
# Tear down all Azure resources
azd down