使用 azd AI 搭配編碼代理和腳本

從程式碼撰寫代理程式和指令碼中使用 azd ai，其行為方式與人類在終端機中操作時相同。 你可以設定獨立上下文、停用提示、解析 JSON 輸出，並呼叫直接代理端點，以確保自動化可靠。

先決條件

• azd Foundry 的擴充功能已安裝。
• 一個經過 azd 認證的會話。
• 一個 Microsoft Foundry 專案端點，用於執行你想執行的指令。 欲了解更多資訊，請參閱 設定 azd 專案上下文。
• 可選：當你需要呼叫代理端點時，使用已部署的託管代理。 關於設定，請參見 部署託管代理。

從 Microsoft Foundry 技能開始

程式設計代理在已經了解 azd ai 慣例時表現最佳。 Microsoft Foundry 技能賦予程式代理該知識：它能產生正確的azd ai指令與 Foundry 接線，並應用本文的做法——設定專案上下文、傳遞 --no-prompt，以及請求--output json結構化結果。 先讓您的程式碼撰寫代理程式使用該技能，然後運用本文其餘部分的模式來檢閱並強化它產生的內容。

設定專案上下文一次

每個資源指令，如 connection、 toolbox、 skill或 routine，都需要一個 Foundry 專案端點作為目標。 在自動化中，每個會話、CI 工作或編碼代理呼叫時，先設定該端點一次，然後在整個執行過程中使用它。

有兩種模式。

使用 azd ai project set 釘選一次

當你希望上下文能在不同 shell 之間持續存在而不匯出環境變數時，請在全域設定中設定：

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

azd ai project set <endpoint> 當你已經知道網址時，是完全非互動的。 azd ai project show 確認是哪個來源解析了活躍端點。 如果你不確定主機處於哪個狀態，可以在會話開頭使用。

設定環境變數

設定 FOUNDRY_PROJECT_ENDPOINT 在你的腳本或程式代理執行的環境中。 每個 azd ai 指令都會在專案內的 azd 環境和全域設定之後自動採用該設定。

export FOUNDRY_PROJECT_ENDPOINT="https://my-project.services.ai.azure.com/api/projects/my-project"
azd ai connection list --output json

這種模式很適合 CI，因為秘密和設定通常已經以環境變數的形式出現，且沒有全域狀態需要在工作間清理。

關於 CLI 如何解析端點的完整說明，包括優先順序，請參見 「設定 azd 專案上下文」。

停用提示訊息

每個 azd ai 指令都接受 --no-prompt。 設定時，指令會很快失敗，而不是阻擋互動輸入。 缺少必要引數，或原本會等待按鍵的 delete 確認，在結構化輸出下都會立即報錯。

總是設定 --no-prompt 在 CI 和 coding-agent invocations 裡。

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --no-prompt

取得 JSON 輸出

大多數azd ai指令支援 --output json，包括 connection、 toolbox、 skillroutine、 以及 資源指令 azd ai agent show和 。 使用它搭配 jq、ConvertFrom-Json，或你的程式語言的 JSON 解析器來可靠地解析結果，而非擷取供人類閱讀的文字輸出。 azd ai agent invoke 指令使用 --output raw 表示未經修改的伺服器回應。

# List connections, extract names with jq
azd ai connection list --output json | jq -r '.[].name'

# Show a single resource as JSON
azd ai routine show daily-digest --output json | jq '.trigger'

# PowerShell example
$conn = azd ai connection show my-search --output json | ConvertFrom-Json
Write-Host $conn.target

文字輸出內容供人類閱讀，且在不同版本之間可能會有所變動。 JSON 結構是穩定的契約。

以冪等方式建立資源

create 不是 upsert。 如果該指定資源已經存在，重跑會失敗。 此預設在共享且專案範圍的資源中效果良好，因為它防止一個呼叫者無聲覆寫另一個呼叫者的狀態。

對於必須成功的自動化，無論先前狀態如何，指令 connection 會接受 --force 以替換現有資源。

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --force --no-prompt

如果你只需要改幾個欄位，且想保留其他部分，請使用 update。 或者，使用專用的集合子指令如 tool、 tag、 metadatakey、 。

從檔案建立工具箱

對於一個包含內建工具、連結和技能的多項目工具箱，請將完整定義放入 YAML 檔案並傳遞 --from-file 給 azd ai toolbox create。 檔案使用對應的 AgentSchema 形狀。

azd ai toolbox create research --from-file ./resources/research-toolbox.yaml --no-prompt

--from-file 是一次性輸入，會在叫用時讀取。 CLI 不會追蹤或重新讀取檔案，因此未來對 YAML 的編輯不會生效，除非你重執行該指令。 建立帶有明確標誌（、--kind、 --target--auth-type、 及匹配憑證標誌）的連線，然後從工具箱檔案中以名稱引用它們。

在沒有 azd 專案的情況下叫用已部署的代理程式

當程式代理程式或腳本需要呼叫位於其工作目錄外的已部署代理程式時，請直接 --agent-endpoint 鎖定該代理程式。 這種方法會略過 azure.yaml 和目前作用中的 azd env。 光是網址就足夠了。

azd ai agent invoke \
  --agent-endpoint https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/versions/3 \
  "Summarize today's release notes." \
  --no-prompt

當某個儲存庫的 CI 需要呼叫另一個儲存庫所擁有的代理程式時，或當 MCP 伺服器做為多個代理程式的前端且只知道這些代理程式的端點 URL 時，請使用這種形式。 完整 invoke 選項請參見 「呼叫託管代理人」。

將密鑰傳遞至本機執行

若要在本機以密鑰啟動代理程式，請將密鑰設為 azd 環境變數，並在 env 中你的 azure.ai.agent 服務的 azure.yaml map 內參照這些變數。 這些值位於 .azure/<env>/.env 中，且預設會被 Git 忽略。

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

# azure.yaml
services:
  my-agent:
    host: azure.ai.agent
    env:
      OPENAI_KEY: ${OPENAI_KEY}

對於不該存在本地 .env 檔案的秘密，將它們儲存在 Foundry 專案連線中，並用 ${{connections.<name>.credentials.<field>}} 佔位符來參考。 請參閱「 本地運行託管代理」 以了解完整的本地運行表面。

寫個簡短的設定

這個 bash 字體結合了上述的圖案。 它會釘選專案上下文，以冪等方式建立連線和工具箱，將工具接線到工具箱，並透過剖析 JSON 確認結果。

#!/usr/bin/env bash
set -euo pipefail

azd ai project set "$FOUNDRY_PROJECT_ENDPOINT" --no-prompt

# A 'remote-tool' connection holds the URL and credentials for the MCP server.
azd ai connection create tavily \
  --kind remote-tool \
  --target https://mcp.tavily.com/mcp \
  --auth-type custom-keys \
  --custom-key "x-api-key=$TAVILY_KEY" \
  --force --no-prompt

# Create the toolbox with the connection wired in, in a single shot
cat > research-toolbox.yaml <<'EOF'
description: Research tools
connections:
  - name: tavily
EOF

azd ai toolbox create research --from-file ./research-toolbox.yaml --no-prompt

echo "Toolbox state:"
azd ai toolbox connection list research --output json | jq .

set -euo pipefail 確保若有任何步驟錯誤，腳本會迅速失敗。結合 --no-prompt，這會給你一個適合 CI 閘的確定性退出碼。

檢閱端點解析

編碼代理可以透過走動此優先順序來預測指令將鎖定哪個 Foundry 專案。 第一個給出數值的來源獲勝;後期的資料來源則不被參考。

1. --project-endpoint（或 -p）旗標（一律優先）。
2. 在 azd 專案中：目前作用中的 azd env 值。
3. 全域設定 (由 azd ai project set 設定)。
4. FOUNDRY_PROJECT_ENDPOINT 環境變數。
5. 含有結構化建議的錯誤，建議執行 azd ai project set 或傳遞 --project-endpoint。

完整說明，包括獨立上下文如何與專案內工作互動，請參見 「設定 azd 專案上下文」。

運用程式碼編寫代理程式技巧

• 一律傳遞 --no-prompt，並在支援該選項的指令上加上 --output json。 兩者合起來會給你一個可預測的退出代碼和一個可解析的結果。
• 如果你不確定主機處於什麼狀態，可以在會話開始時用 azd ai project show 已解決的上下文來驗證。 這是一個便宜且唯讀的呼叫。
• 失敗時，寧願解析錯誤輸出中的結構化建議，而非決定下一步。 例如，若出現「No Foundry project endpoint resolved」錯誤，表示你應該先執行 azd ai project set 或設定 FOUNDRY_PROJECT_ENDPOINT，然後再重試。
• 只在診斷問題時使用 --debug 。 它產生冗長、多行的輸出，難以解析，從來不是設計成程式介面。
• 將帶有「already exists」訊息的 create 失敗視為可復原。 如果該資源應由你替換，請重新執行 --force；如果你只需要變更其中一部分，請改用 update 和 collection 子命令。

相關內容

• 設定 azd 專案上下文 ，以了解 CLI 如何解析 Foundry 專案端點。
• 用 Azure Developer CLI 為託管代理程式設定 CI/CD，針對在管線中執行 azd ai 的模式。
• 呼叫託管代理 以獲取完整 azd ai agent invoke 選項，包括 --agent-endpoint。