為 azd 指令設定 Foundry 專案上下文

Important

本文中標示為預覽的項目目前仍在預覽中。此預覽版未簽訂服務等級協議，Microsoft 不建議用於生產工作負載。某些功能可能不被支援或功能受限。欲了解更多資訊，請參閱 Microsoft Azure 預覽版補充使用條款。

azd ai 指令會在兩種情境下執行：在 azd 專案內（典型的團隊工作流程），以及以獨立模式執行（臨時性工作、單次使用的指令碼，或來自沒有 azure.yaml 可作為依據的自動化作業呼叫）。這兩種模式都針對相同的 Microsoft Foundry 資源。它們唯一的差別是 CLI 如何決定要與哪個 Foundry 專案溝通。在本文中，你將學習解決順序以及如何設定獨立的上下文。

先決條件

安裝了 Azure Developer CLI Foundry 擴充套件。
一個認證過的 Azure session （azd auth login）。
一個現有的 Foundry 專案端點，供獨立使用。

何時使用各語境

背景	外觀	何時使用
在一個 `azd` 專案中	你從一個包含 `azd ai ...` 和啟用中的 `azure.yaml` 環境的目錄執行 `azd`。	你在追蹤專案中建置或操作代理，並希望環境來規範你鎖定的 Foundry 專案。
獨立	你可以從其他目錄執行 `azd ai ...` 。	您可以針對現有的 Foundry 專案執行臨時工作，或由不擁有 `azd` 專案的自動化流程撰寫一次性作業指令碼。

資源指令（azd ai connection， azd ai toolbox， azd ai skill，和 azd ai routine）是針對單一 Foundry 專案運作，因此必須先從這些上下文中解析專案端點，才能執行。

有些 azd ai agent 指令需要專案 azd ，因為它們是依據本地服務定義運作的。其他指令則支援獨立使用。例如， azd ai agent optimize 當你提供已部署代理的名稱，並從全域設定、明確旗標或環境變數解析 Foundry 專案端點時，就可以鎖定它。使用 --agent-endpoint 在 azd ai agent invoke 上呼叫已部署的代理程式，而無需磁碟上的 azd 專案。

端點解析如何運作

對於每個針對 Foundry 專案的指令，CLI 會依此順序解析該端點。第一個回傳該值的來源獲勝，之後的來源則不被參考：

指令上的 -p 或 --project-endpoint 旗標。無論情境如何，它總是贏。
如果您位於 azd 專案目錄中，則為作用中的 azd 環境。
extensions.ai-agents.context.endpoint 中 ~/.azd/config.json 下的全域設定。這就是 azd ai project set 所寫的內容。
目前 shell 的 FOUNDRY_PROJECT_ENDPOINT 環境變數。
Error。 CLI 會帶著結構化的建議退出，要求執行 azd ai project set 或傳遞 --project-endpoint。

終端是 CLI 唯一需要的東西。它會在呼叫時解析 Azure Resource Manager 的資源 ID（訂閱、資源群組、帳號和專案），所以無論是從你的環境還是全域設定取得端點，指令的運作方式都一樣。

設定獨立的上下文

這個 azd ai project set 指令會將活躍的 Foundry 專案端點寫入你的全域 azd 設定，因此後續從任何地方執行的指令可以省略 --project-endpoint。指令以端點為位置參數：

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project

當你通過端點時，這個指令是完全非互動的。在腳本和 CI 中加入 --no-prompt，讓缺少或未解析的值立即失敗，而不是卡住：

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt

Note

只有端點才是標準。資源指令會在呼叫時從端點重新衍生出訂閱、資源群組、帳號和專案。

清除獨立上下文

azd ai project unset

此命令會從 context 中移除整個 ~/.azd/config.json 區塊。它不涉及任何 azd 環境價值。

檢視主動情境

azd ai project show 指令會逐一檢查完整的解析鏈，並回報是哪個來源提供了目前使用中的端點。在執行前，先用它確認下一個指令的目標：

azd ai project show

當端點來自全域設定時的範例輸出：

Project endpoint:  https://my-project.services.ai.azure.com/api/projects/my-project
Source:            global config (~/.azd/config.json)
Tenant:            contoso.onmicrosoft.com
Subscription:      Contoso Dev (00000000-0000-0000-0000-000000000000)
Foundry project:   my-project

在 azd 專案中，Source 這一行會改為顯示 azd env <env-name>，而顯示的值來自該環境的 .env 檔案，而不是來自全域設定。

儲存位置

在 extensions.ai-agents 中，獨立內容位於 ~/.azd/config.json 命名空間下：

{
  "extensions": {
    "ai-agents": {
      "context": {
        "endpoint": "https://my-project.services.ai.azure.com/api/projects/my-project",
        "subscription": "00000000-0000-0000-0000-000000000000",
        "tenant": "contoso.onmicrosoft.com",
        "foundryProject": "my-project",
        "setAt": "2026-01-15T10:23:00Z"
      }
    }
  }
}

只有 endpoint 才是正式版本。其他欄位是為了讓 azd ai project show 更容易閱讀。 CLI 在解析目標時從不讀取這些訊息。你可以手動編輯檔案，但 azd ai project set 和 azd ai project unset 是管理它所支援的方式。

azd 專案中的優先順序

在 azd 專案中，作用中環境的專案端點一律優先於全域內容。在專案內部執行 azd ai project set 仍會更新全域設定，但 CLI 會印出一行警告，表示該環境仍優先處理該目錄執行的指令。

這是刻意的行為。專案層級的環境變數值是團隊工作流程的一部分，而全域內容則是每台機器各自的偏好設定。若要在專案內針對單一指令覆寫環境，請傳入 --project-endpoint，或在 shell 中設定 FOUNDRY_PROJECT_ENDPOINT，而不要依賴全域設定。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-09-30