Important
本文中標示為 (預覽) 的項目目前處於公開預覽狀態。 此預覽版本沒有服務等級協定，不建議將其用於生產工作負載。 某些功能可能不被支援或功能受限。 欲了解更多資訊，請參閱 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 | 代理完全透過指令和工具配置定義，沒有自訂程式碼。 | 你需要一個快速、設定驅動的代理程式，且不需要寫應用程式程式碼。 |
託管代理讓您完全掌控執行時、框架與工具整合，而 Foundry 則負責基礎架構、擴展與會話管理。
組態檔
託管代理專案會在專案根節點使用一個 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檔案。
變數替換
對於依 azd 環境而異的值，請在 azure.yaml 中使用 ${VAR_NAME}。 預留位置會在部署或執行階段從 .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 執行時合約。
會議與對話
| 概念 | 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