使用 Azure Developer CLI 進行代理程式開發

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 執行代理程式評估

代理人類型

The azd ai agent擴充功能支援託管、提示及語音 Agent。

類型 Description 何時使用
託管代理 一個你部署為原始碼或容器映像的應用程式。 你需要自訂邏輯、框架整合,或是完全控制行為。
提示 Agent 代理完全透過指令和工具配置定義,沒有自訂程式碼。 你需要一個快速、設定驅動的代理程式,且不需要寫應用程式程式碼。
語音 Agent 宣告式提示語音 Agent,或連接至託管 Agent 的語音包裝函式。 你需要透過 Voice Live 客戶端獲得即時語音體驗。

託管代理讓您完全掌控執行時、框架與工具整合,而 Foundry 則負責基礎架構、擴展與會話管理。

基於提示的語音代理不需要自訂容器。 如果你需要在自己的容器中執行自訂的語音轉語音或級聯音訊管線,請建立 搭配託管代理程式的語音代理,並使用 invocations_ws 協定。

若要在託管文字代理中保留對話邏輯,而 Voice Live 處理音訊,請使用 託管語音包裝器工作流程。 包裝器和目標是同一 azure.yaml 專案中不同的服務。 這個流程並不會取代現有的自訂 invocations_ws 音訊管線流程。

在使用語音 CLI 選項之前,請先依照 voice agent 快速入門必要條件中的說明,確認您已安裝所需的擴充功能。

組態檔

託管代理專案會在專案根節點使用一個 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服務會以內嵌方式,或透過明確的根$ref指向直接的 YAML 或 JSON 定義,來定義您的 Agent。 若為以檔案為後端的服務,請使用azd ai agent add <service> --file <path> 。 目前初始化不支援參數化 AgentManifest 包裝器。 服務的 uses: 清單列出專案、連線和工具箱等相依項目。

對於基於提示的語音代理,儲存 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 環境變數。
  • 從主動環境解析的非空端點優先於全域上下文。 關於 shell 的備援與指令特定行為,請參見 設定專案上下文。

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 一個針對單一代理互動的隔離執行環境。 每個工作階段都在各自的沙盒中執行,並配有專屬資源。
談話 Responses 通訊協定的訊息歷程記錄。 Invocations 不會自動保存對話歷程記錄。

工作階段會以 session_id 識別。 CLI 會將每個代理的會話選擇儲存下來,並預設沿用該選擇。 使用 --new-session 重新開始,或使用 --session-id <id> 指定特定工作階段。 快取不是以委派使用者為鍵;使用 --user-identity 時請保留明確的使用者至工作階段對應。

鑄造廠專案資源

Foundry 專案包含的不只是代理程式。 它同時儲存在執行時代理者參考的共享資源。 CLI 透過專用指令群組管理每一個。

Resource 內容 受控方式
Connection 將 Foundry 專案連結至外部資源,例如 MCP 伺服器、Foundry IQ(Azure AI 搜尋服務)或 Grounding with Bing。 azd ai connection 指令
工具箱 一組有名稱的工具集合,供代理在執行時使用。 azd ai toolbox 指令
技能 專案中各代理共享的可重複使用行為指引。 azd ai skill 指令
例行程式 一個觸發點加上一個會召喚代理人的動作。 azd ai routine 指令

這些資源會在同一專案中由開發者和代理人共享。 它們的命令各不相同:連線與常式使用update、技能透過update發佈新版本,而工具箱則使用會產生版本的連線與技能變更,之後再執行publish。

評估並改進代理人

在代理程式執行完畢後,兩個相關的工作流程可協助你衡量並改善其品質:

  • 快速 Agent 評估會使用azd ai agent eval與本機的eval.yaml,包括最佳化工具工作流程。 專案評估會使用另行安裝的azd ai eval擴充功能與evals/azure.eval.yaml,並搭配追蹤或資料集來源及明確的 CI 品質閘門。 這兩種配置格式不能互換。
  • 最佳化會反覆重新寫入您的代理程式提示,以提升評估訊號。 它以評估為目標,並產生一個候選提示,你必須審閱並接受。 你可以用 azd ai agent optimize來管理。

詳情請參見 「用azd CLI執行代理評估 」和 「優化代理提示」。

依開發者職務將指令分組

選擇可達成你所需結果的命令。 附加--help,以檢查其旗標與支援的輸出格式。

Job Commands 指引
設定專案與受控模型 azd ai project add,azd ai project deployment add Project 設定與情境
選擇或檢查端點上下文 azd ai project set、azd ai project show、azd ai project unset、azd ai project context 全域端點選擇與基礎設施宣告是分開的。 上下文輸出可以包含機密。
瀏覽範例或初始化 Agent azd ai agent sample list、azd ai agent init、azd ai agent add 初始化託管代理、提示代理及語音代理
為代理程式解析、擷取及分類文件與內容 azd ai cu analyze,azd ai cu analyzer Azure Content Understanding CLI 快速入門(預覽)
在本機執行並檢查 azd ai agent run,azd ai inspector launch 本機開發
呼叫、委派使用者身份,或傳送自訂標頭 azd ai agent invoke 呼叫選項
檢查、追蹤或取消工作 azd ai agent invocations show、azd ai agent invocations follow、azd ai agent invocations cancel 長時間執行的叫用
檢查或更新端點 azd ai agent endpoint show,azd ai agent endpoint update 端點與卡片更新
檢查狀態、診斷問題或查看記錄 azd ai agent show、azd ai agent doctor、azd ai agent monitor 診斷 和 日誌
建立、列出、檢查、停止或刪除沙盒 azd ai agent sessions create、、 azd ai agent sessions list、 azd ai agent sessions show、 azd ai agent sessions stop、 azd ai agent sessions delete 工作階段管理
植入、擷取或維護沙箱檔案 azd ai agent files upload、azd ai agent files download、azd ai agent files list、azd ai agent files mkdir、azd ai agent files stat、azd ai agent files delete 會話檔案操作
復原已部署的原始碼 azd ai agent code download 下載代碼或壓縮檔
檢查耐久存放區並維護共用項目 azd ai agent state-stores list、azd ai agent state-stores select、azd ai agent state-stores show、azd ai agent state-stores items 狀態儲存操作與限制
在部署設定中新增代理程式相依性 azd ai agent connection add,azd ai agent toolbox add 這兩個服務必須已經存在於 azure.yaml;這些指令是新增 uses 條目,而非遠端資源。
管理連線憑證與元資料 azd ai connection create、、 azd ai connection list、 azd ai connection show、 azd ai connection update、 azd ai connection delete 連線驗證與維護
撰寫、設定版本或下載可重複使用的技能 azd ai skill add、azd ai skill create、azd ai skill update、azd ai skill list、azd ai skill show、azd ai skill download、azd ai skill delete 技能工作流程
撰寫及管理工具箱 azd ai toolbox add、、 azd ai toolbox create、 azd ai toolbox list、 azd ai toolbox show、 azd ai toolbox delete 工具箱配置
演進並提升工具集合 azd ai toolbox connection、azd ai toolbox skill、azd ai toolbox versions list、azd ai toolbox publish 變更會從最新版本分支;提升則須明確執行。
排程、分派或檢查常式 azd ai routine add、azd ai routine create、azd ai routine list、azd ai routine show、azd ai routine update、azd ai routine enable、azd ai routine disable、azd ai routine dispatch、azd ai routine run list、azd ai routine delete 例行工作流程
快速生成並執行評估 azd ai agent eval generate、、 azd ai agent eval update、 azd ai agent eval run、 azd ai agent eval list、 azd ai agent eval show 快速評估與優化資產
改進並部署最佳化候選項目 azd ai agent optimize、azd ai agent optimize status、azd ai agent optimize list、azd ai agent optimize cancel、azd ai agent optimize apply、azd ai agent optimize deploy 最佳化工作流程
封裝或發佈供 Teams 使用的 Activity Agent azd ai agent pack,azd ai agent publish Teams 發佈
刪除託管版本或 Agent azd ai agent delete 代理程式刪除
評估專案並強制品質閘門 azd ai eval init、azd ai eval generate、azd ai eval create、azd ai eval run、azd ai eval dataset、azd ai eval evaluator、azd ai eval job Project 評估; 需另行安裝azure.ai.evaluations。
註冊並設定可重複使用資料集的版本 azd ai dataset 資料集生命週期;另外安裝 azure.ai.dataset。
提交、暫停、繼續、取消或部署微調工作 azd ai finetuning init,azd ai finetuning jobs 微調;請另外安裝 azure.ai.finetune。
上傳並管理自訂模型權重 azd ai models 客製化模型匯入與維護;另外安裝 azure.ai.models 。

每個新增指令的擴充功能都會公開 version;改用 azd ext list 檢查 microsoft.foundry 組合包。 連線、常式及技能群組也會公開context,供本機專案與環境檢查使用;請將輸出視為可能含敏感資訊。

Activity Agent 發佈

部署 Activity-protocol 代理後,azd ai agent pack 會建立 appPackage.zip 供側載使用。 使用 --output-dir、 --display-name、 --app-version 來自訂套件。 封裝並不等同於發行。

azd ai agent publish透過 Microsoft 365 發佈。 Simple Activity 代理程式預設為 shared 分發,除非另有設定;--scope tenant 需經管理員批准。 數位工作者需要租用戶範圍。 使用可 --access-boundary 重複的值來 --clear-access-boundaries 移除現有邊界,並使用可 --optional-permission-scope <resource-app-id>=<scope> 重複的值用於可選權限。 personal 不是發佈範圍;使用 pack --scope personal 並側載該套件以進行逐用戶測試。

部署生命週期

完整的開發迴圈會濃縮成一連串簡短的指令。 先搭建一次支架,然後隨著專案成長使用直接指令。

關於受管理的語音代理路徑,請參見 快速入門:建立提示語音代理。

# 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