在 Microsoft Foundry 中使用 Azure 原則,在不使用 Microsoft Copilot 框架的情況下,控管已儲存的工具箱組態和提示代理程式。 使用 Project 工具控制項來限制執行時工具的使用。 保持他們的允許清單對齊,並確認是否分別儲存與執行。
本指南涵蓋原生工具治理。 它不需要 AI 閘道。 關於閘道路由、速率限制及 MCP 流量的 IP 限制,請參閱使用 AI 閘道治理 MCP 工具。
Prerequisites
- 一個 Foundry 專案及其 Azure 資源 ID。 在對生產工作負載套用限制之前,先使用測試 Project。
- 您必須在指派 Azure 原則 的範圍內具有 擁有者 或 資源原則參與者 角色。 欲了解更多資訊,請參閱 Azure 原則 與 Azure RBAC。
- 透過 Azure Resource Manager 讀取並更新 Foundry Project 的權限。 政策指派權限與執行時工具權限是分開的。
- 對於 REST API 或 Terraform 程序,請使用 Azure CLI,並在 Bash 中執行
jq,包括 Azure Cloud Shell。 登入包含您 Project 的訂閱。 - 如果你使用 Terraform 選項,則為 Terraform。 此範例使用 AzAPI 提供者來更新現有 Project。
- 一個具備可正常工具存取權限的代理程式或工具箱,用於驗證。 治理允許清單不會授予存取資料、憑證或外部服務的權限。
了解這兩個控制項
Azure 原則 與 Project 工具控制項具有不同的設定與執行點:
-
Azure 原則 會根據您組織核准的工具,評估支援的提示代理程式與工具箱設定。 此
Deny效果會阻擋不合規的建立或更新操作。Audit在不封鎖這些操作的情況下回報不合規。 -
Project 工具的控制項儲存在 Project 的
properties.toolControls屬性中,並限制執行時工具的使用。 將defaultAction設定為Deny,並在allowedTools中列出允許的工具。
這些 Azure 原則 檢查目前適用於使用 Responses API 且未使用 Microsoft Copilot harness 的工具箱與提示代理。
託管代理會執行你的程式碼,而這項原則不會檢查你的程式碼,不論你使用哪種控管架構或框架。 透過他們呼叫的工具箱來管理他們的 Foundry 工具存取。 檢查每個工具箱的合規狀態,並設定 Project toolControls 以限制執行時工具透過工具箱的使用。 不合規的工具箱不會阻止託管代理程式的建立。
專案 toolControls.allowedTools 清單為執行時控制項,而非代理程式或工具箱建立、讀取、更新或刪除(CRUD)操作的驗證規則。 例如,只有defaultAction: Denyfile_search在 allowedTools中,您仍可儲存已設定的web_search代理程式或工具箱,除非適用的 Azure 原則 阻止該儲存。 Project 控制會在設定傳播後封鎖執行階段對 web_search 的使用。 儲存工具設定不會啟動該工具。
指派 Azure 原則 不會自動填充或重寫 toolControls。 更新 toolControls 不會建立或變更政策指派。 Project 屬性並非 Azure 原則 定義。
若 toolControls 不存在,此功能不會限制專案執行時工具的使用。 其他控制措施,包括適用的政策、驗證以及網路限制,仍然適用。
將這些控制項視為對由 Foundry 處理的工具的限制,而非網路防火牆。 不要指望它們來管理來自託管代理程式的任意對外呼叫。 對這些呼叫使用 網路隔離 與服務專屬授權。
為工具指派 Azure 原則
內建政策[預覽版]:Microsoft Foundry 代理程式與工具箱應僅使用核准工具,定義了允許清單。 它支援 Audit、 Deny、 Disabled,且預設為 Audit。
Disabled 跳過該政策指派的評估。 它不會停用 Project 工具的控制項。
先使用 Audit 評估其對受支援代理程式和工具箱組態的影響。 使用 Deny 來封鎖這些資源中不符合規範的建立和更新作業。
盡可能在 Foundry 帳戶範圍內指派政策。 每個指派都有可評估的代理程式和工具箱數量上限。 較廣的範圍可能會達到此限制,導致部分資源無法評估。
請求必須滿足所有適用且已強制執行的 Deny 指派(AND 邏輯)。 如果任何一個指派拒絕建立或更新作業,其他指派無法覆寫該拒絕。 如需例外的資源,請參閱 Azure 原則 豁免。
Azure 原則 變更可能需要最多 30 分鐘才能生效。 合規報告則是分開的:結果可能需要長達 12 小時才能顯示或更新。
- 在 Azure 入口網站中,開啟「原則」,然後選擇「定義」。
- 搜尋 [預覽版]:Microsoft Foundry 代理程式與工具箱應僅使用核准的工具。 確認其定義 ID 以
e7352ad2-6c86-4a07-9573-47f67b557ba8結尾,開啟定義,然後選擇 「指派」。 - 盡可能選擇 Foundry 帳戶作為指派範圍,並設定任何必要的排除項目。
- 在 參數中,設定效果及工具限制:
-
核准工具類型 (
approvedToolTypes):來自 工具類型目錄中的工具類型識別碼。 -
核准的 MCP 端點 (
approvedMcpEndpoints):核准的 MCP 伺服器 URL 或端點模式。 -
核准的 MCP 連接器 (
approvedMcpConnectors):核准的 MCP 連接器識別碼。
-
核准工具類型 (
- 檢視該指派並建立。
- 在原則傳播延遲後確認執行情況。 當作業的合規結果可取得時,請另行檢視作業的合規結果。
完整指派程序請參閱在 Azure 入口網站建立原則指派。
如需查看政策指派步驟,請選取 Azure 入口網站索引標籤。 本文中的 REST API 與 Terraform 程序是更新專案執行時控制項,而非政策指派。
選擇核准的工具類型
請使用下列目錄中的工具類型識別碼用於 approvedToolTypes。 這是參考清單,不是推薦的允許清單。
[
"a2a",
"azure_ai_search",
"azure_function",
"bing_custom_search",
"bing_grounding",
"browser_automation",
"code_interpreter",
"computer_use",
"custom",
"fabric_dataagent",
"fabric_iq",
"file_search",
"function",
"image_generation",
"mcp",
"memory_search",
"openapi",
"reminder",
"sharepoint_grounding",
"shell",
"toolbox_search",
"web_search",
"work_iq"
]
僅選擇您組織核准的類型。 可用性依 API 版本、模型以及代理程式或工具箱整合而異。
本清單描述原則參數值。 這並不表示每個識別碼都受 Project toolControls 支援,或在每條執行路徑中都受支援。 特別是,依類型核准 mcp 的範圍比核准單一 MCP 目標更為廣泛。
限制 MCP 目標
approved-tools 政策會在工具的類型、MCP 端點或 MCP 連接器與核准項目相符時接受該工具。 這些是替代的匹配條件,不是要求全部都必須符合的條件。
若要限制 MCP 對特定伺服器的存取,請將其 URL 新增至 approvedMcpEndpoints,或將其連接器識別碼新增至 approvedMcpConnectors。 不要在 approvedToolTypes 中加入廣義 mcp 類型,因為該動作會依類型核准 MCP 工具,且不需要端點或連接器匹配。
針對端點限制,請在每個適用指派中將工具箱的 MCP 端點新增至 approvedMcpEndpoints。 將工具箱端點與其內部工具分開核准。
Azure 原則 中的 MCP 端點模式不區分大小寫。 每個模式最多支援一個 * 萬用字元;不支援正規表達式及其他模式匹配語法。
例如,https://mcp.contoso.com/* 會比對該主機下的端點。 像 這樣的 https://*.contoso.com/* 模式不被支援,因為它包含兩個萬用字元。 使用最窄且符合你需求的模式。
設定 Project 工具控制項
Project toolControls 沒有稽核模式。 在測試專案中測試完整允許清單,再將其套用到正在執行的工作負載專案中。 變更可能需要數分鐘才能生效。
請將工具所使用的所有 MCP 端點納入 allowedTools 其中,以避免無意間阻擋工具存取。
在變更 Project 設定前,請先閱讀目前的 Project 設定。 REST API 與 Terraform 範例僅允許透過專案的工具控制項使用 file_search。 他們不會在代理程式上設定工具,也不會授權存取向量儲存。
讀取目前的專案設定
設定專案識別碼並讀取專案。 將預留位置替換為您的值,並在同一 Bash 工作階段中執行此程序中的指令。
SUBSCRIPTION_ID="<subscription-id>"
RESOURCE_GROUP="<resource-group-name>"
FOUNDRY_RESOURCE="<foundry-resource-name>"
PROJECT_NAME="<project-name>"
PROJECT_ID="/subscriptions/$SUBSCRIPTION_ID"
PROJECT_ID+="/resourceGroups/$RESOURCE_GROUP"
PROJECT_ID+="/providers/Microsoft.CognitiveServices/accounts"
PROJECT_ID+="/$FOUNDRY_RESOURCE/projects/$PROJECT_NAME"
PROJECT_URL="https://management.azure.com${PROJECT_ID}"
PROJECT_URL+="?api-version=2026-09-15-preview"
az rest --method get --url "$PROJECT_URL" \
--output json > project-before.json
jq '.properties.toolControls' project-before.json
此指令會顯示已儲存的專案控制項,或 null 在缺少該屬性時顯示。 保留 project-before.json 作為先前組態的紀錄。
參考資料: az rest。
使用 REST 設定專案工具控制項
使用下列內容建立名為
tool-controls.json的檔案:{ "properties": { "toolControls": { "defaultAction": "Deny", "allowedTools": [ { "type": "file_search" } ] } } }這是預定的替換允許清單,而非附加單一條目的指示。 在應用之前,先包含專案所需的所有工具。 請保留您請求中其他現有
toolControls的設定。請以
PATCH請求更新專案。 使用專案讀取時的 ETag,以避免覆蓋同時進行的變更。ETAG=$(jq -r '.etag // .eTag // empty' project-before.json) if [ -z "$ETAG" ]; then printf 'No project ETag returned. Stop without updating.\n' >&2 exit 1 fi az rest --method patch --url "$PROJECT_URL" \ --headers "Content-Type=application/json" "If-Match=$ETAG" \ --body @tool-controls.json如果更新失敗,請停止並檢查錯誤。 對於並行修改,請重新讀取專案並核對變更後再提交新請求。
參考資料: az rest。
更新後, 請驗證所儲存的專案控制項。
使用 Terraform 更新專案工具控制項
使用 azapi_update_resource 來管理現有專案上的 toolControls,而不建立或取代該專案。 此選項變更的是專案控制項,而非 Azure 原則 指派。
選擇 REST 或 Terraform 來管理這些設定。 不要透過多個 Terraform 資源管理同一個屬性。
請使用以下內容創作
main.tf:terraform { required_providers { azapi = { source = "Azure/azapi" version = "~> 2.13.0" } } } variable "subscription_id" { type = string } variable "tenant_id" { type = string } variable "project_resource_id" { type = string } provider "azapi" { subscription_id = var.subscription_id tenant_id = var.tenant_id use_cli = true use_msi = false use_oidc = false skip_provider_registration = true } resource "azapi_update_resource" "tool_controls" { type = "Microsoft.CognitiveServices/accounts/projects@2026-09-15-preview" resource_id = var.project_resource_id body = { properties = { toolControls = { defaultAction = "Deny" allowedTools = [ { type = "file_search" } ] } } } ignore_missing_property = false response_export_values = ["properties.toolControls"] } output "tool_controls" { value = azapi_update_resource.tool_controls.output.properties.toolControls }參考資料: azapi_update_resource。
此範例將專案允許清單替換為
file_search。 在套用前,請包含所有必要的工具,並保留其他現有toolControls設定。 對於 MCP 項目,請使用具體的serverUrl或connectorId。使用您的專案細節建立
terraform.tfvars:subscription_id = "<subscription-id>" tenant_id = "<tenant-id>" project_resource_id = "<full-project-resource-id>"參考資料:Terraform 輸入變數。
請使用完整的 Azure 資源 ID,而非專案端點。 確認您的 Azure CLI 登入與所提供的訂閱及租戶是否符合專案。
初始化提供程式並檢視已儲存的計劃:
terraform init terraform fmt -check terraform validate terraform plan -out=tool-controls.tfplan參考資料: terraform plan。
確認 plan 針對預定的既有專案,且僅變更所要求的控制措施。 Terraform 可以將更新資源在其狀態中顯示為新增項目;這並不代表它會建立一個 Azure 專案。
套用已儲存的計畫並檢查產生的控制措施:
terraform apply tool-controls.tfplan terraform output -json tool_controls terraform plan -detailed-exitcode參考資料: terraform apply 與 terraform output。
輸出包含
defaultAction: Deny,且包含僅有file_search的allowedTools陣列。 第二個方案應該會回報沒有變動並返回結束代碼0。 套用計畫後,確認儲存的專案控制項。
銷毀 azapi_update_resource 會將其從 Terraform 狀態中移除。 它不會刪除 Azure 專案、移除控制項,或還原控制項先前的值。 若要變更或還原控制項,請明確套用所需的設定;不要用 terraform destroy 來當回滾。
驗證已儲存的專案控制項
等待專案更新完成,然後讀回儲存的設定:
az rest --method get --url "$PROJECT_URL" --output json \
--query "properties.{state:provisioningState,toolControls:toolControls}"
如果佈建仍在進行中,請重複讀取。 如果配置失敗,請停止並檢查操作錯誤。 確認狀態為 Succeeded,且儲存的允許清單符合您預期的設定。
被接受的更新並不代表執行時強制執行已傳播到執行階段。 請預留數分鐘等待 toolControls 變更生效,然後檢查執行時行為。
參考資料: az rest。
將 MCP 伺服器新增至執行時允許清單
對於 MCP 伺服器,請在 allowedTools 陣列中新增一個具體目標。 使用代理程式或工具箱所使用的伺服器 URL:
{
"type": "mcp",
"serverUrl": "https://mcp.contoso.com/mcp"
}
對於基於連接器的 MCP 工具,請改用其連接器識別碼:
{
"type": "mcp",
"connectorId": "<approved-connector-id>"
}
這些片段是個別 allowedTools 條目,並非完整的 Project 更新請求。 每個 MCP 項目必須精確指定 serverUrl 或 connectorId 其中之一。 僅含 {"type": "mcp"} 的項目無效。
在 Project 設定中使用實際的伺服器 URL 或連接器識別碼。 請將 Azure 原則 端點模式與這些具體 Project 項目分開。
對於透過 MCP 存取的工具箱,請在 allowedTools 中包含其端點、所需工具,以及這些工具所使用的每個 MCP 端點。 允許內部工具並不自動核准外層 MCP 連線。
比較預期政策行為
下表區分了核准工具的政策評估與 Project 執行時控制。 Project 工具控制項不會驗證代理程式或工具箱的 CRUD 操作。
在代理程式/工具箱欄位中,代理指的是使用回應 API 且未使用 Copilot 架構的提示代理。 Copilot 框架提示代理目前尚未進行評估。 對於託管代理程式,政策評估的是它們所使用的工具箱,而非託管代理程式的程式碼或建立。
這些情境假設請求有效、所需權限及已傳播的設定。 對於 Deny,也假設強制執行已啟用。
| Configuration | 現有代理程式或工具箱版本 | 代理程式或工具箱的建立或更新 | Runtime |
|---|---|---|---|
| 僅限 Project 層級控制 | 沒有政策評估。 | 允許;沒有 Project 控制檢查。 | Project 控制項允許或拒絕工具使用。 |
已核准工具的政策 Deny |
定義不符的情況會被回報;版本不會被重寫。 | 不合規的寫入會被拒絕。 | Project 控制項允許或拒絕工具使用。 |
已核准工具的政策 Audit |
定義不符的情況會被回報;版本不會被重寫。 | 允許;政策不符會被稽核,而非拒絕。 | Project 控制項允許或拒絕工具使用。 |
Audit 和 Disabled 不會覆寫 Project 限制。 政策的合規狀態本身不會阻擋執行時工具的呼叫。 執行時使用 Project 中儲存的工具控制項,包括內嵌工具定義及先前儲存的代理程式版本。
現有版本是不可更改的。 若要更改定義,請建立符合標準的版本,而非重寫舊版本。 對於工具箱,您可以將符合標準的版本提升為預設。 更改預設不會改變保留版本或固定在它們上的用戶端。
刪除未使用的版本
在所有代理程式與工具箱的例行維護中刪除未使用的版本,即使專案工具控制項尚未設定。 保留仍在使用中的應用程式或回滾計畫仍需要的版本。
如需指引,請參閱 Agent Service 版本限制及 刪除工具箱版本。
分別確認儲存與執行
使用測試專案和不會對外部系統做出不必要變更的工具。 對於儲存時檢查,請使用工具箱或提示代理程式,但不使用 Copilot harness。 在政策與 Project 變更傳遞後,檢查設定與執行階段的路徑。
- 閱讀 Project 範圍內已核准工具的政策指派,包括繼承的指派。 確認定義 ID、
approvedToolTypes以及 MCP 參數、效果及強制執行設定。 - 閱讀專案的
toolControls並確認列出所需的執行時工具。 - 使用核准工具儲存代理程式或工具箱版本。 確認存檔成功。
- 在已強制執行
Deny原則的情況下,嘗試儲存包含不在該原則核准集合內之工具的版本。 確認存檔已遭阻止。 - 執行使用 Project 設定允許的工具的代理程式。 確認它能使用該工具,並具備正常的驗證與權限。
- 在測試專案中,請使用Azure 原則允許但專案控制項排除的工具。 確認新的代理程式或工具箱儲存成功,但執行時該工具的使用被阻擋。
- 在兩種配置中測試由 Project 控制項排除的工具:無代理程式/工具箱政策,以及
Audit指派。 儲存應該成功;執行時存取應保持封鎖狀態。 - 在 Project 控制項中限制其工具後,測試已儲存的現有版本。 確認在不重寫已儲存版本的情況下,已封鎖執行時存取。
不要把成功儲存、符合規範的政策結果或成功的專案更新視為代理程式能執行的證明。 檢查您的應用程式實際使用的執行時路徑。
政策變更最多可能需要 30 分鐘才會生效。 變更 toolControls 可能需要數分鐘,包括在您還原執行時存取權時也是如此。
排除工具治理問題
在變更任一控制項之前,先確認故障發生在儲存設定或執行代理程式時。 儲存時原則範例適用於未使用 Copilot 架構的工具箱與提示代理程式。
工具會執行,但您無法儲存新的代理程式版本
管理員可以在不更改 Project 控制項的情況下,收緊代理程式/工具箱政策。 若專案控制允許使用超出政策核准集的工具,內嵌執行時請求或現有版本即可使用該工具。 使用該工具儲存新版本會因政策 Deny 生效而遭到阻擋。
檢視儲存錯誤中指定的政策,並將其與 Project 的允許清單進行比較。 與管理員合作,將 Project 設定與代理程式定義與政策對齊。 不要以為指派政策會自動改變現有的執行時控制項。
代理程式版本會儲存,但執行時請求會被封鎖
即使新版本的代理程式或工具箱工具不在 toolControls.allowedTools,仍可通過 Azure 原則 檢查。 例如,政策允許 web_search,但 Project 僅允許 file_search。 存檔成功,但執行時的網路搜尋被封鎖。
在 Project 控制變更後,相同情況也適用於現有版本。 Project 控制項不會拒絕或重寫已儲存的定義。
從代理程式中移除已排除的工具,或要求授權的專案管理員在組織核准的設定中更新執行時允許清單。
即使 MCP 工具的內部工具已被允許,MCP 工具仍遭封鎖
檢查代理程式工具設定中的 MCP 伺服器 URL 或連接器識別碼。 對於透過 MCP 存取的工具箱,請檢查其端點、所需工具,以及這些工具所使用的每個 MCP 端點。 將任何缺少的必要條目加入 toolControls.allowedTools,而非廣泛允許 MCP 存取。
政策會回報不合規,但不會封鎖儲存
請先檢查代理人類型。 這些政策檢查目前並未評估使用 Copilot harness 的提示代理。 對於託管代理程式,請測試工具箱設定,而非建立託管代理程式。
針對支援的類型,請檢查政策的效果與執行模式。
Audit 回報不合規情況;它不會阻礙作業。 確認該指派適用於預定範圍,且政策變更已生效。
特定工具類型或 MCP 端點在您指派拒絕政策後仍會保存
首先,找出你更改的設定是哪一種。 Project toolControls 不會阻擋存檔,即使 defaultAction 是 Deny。 測試執行時工具的使用以驗證該控制項。
對於 Azure 原則 指派,檢查其定義 ID 與參數。 approved-tools 定義使用 approvedToolTypes。 從核准清單中省略 web_search ,以使包含該工具的設定不合規。
五分鐘不足以排除原則傳播的可能性。 最多等待 30 分鐘,確認指派的範圍和強制執行模式,然後使用工具箱或提示代理程式,在不透過 Copilot 包裝層的情況下重試。 合規報告更新可能需要長達 12 小時;這種報告延遲與強制執行是分開的。
如果新web_search工具箱版本包含該功能,即使某個適用且強制Deny的指派已經傳播,仍然可以儲存,這不能用 hosted-agent 或 Copilot-harness 排除條款來解釋。 擷取政策定義與指派 ID、目標資源 ID,以及儲存要求詳細資訊,以供支援調查。
允許的工具仍然失敗
允許清單不會授予權限或設定連線。 檢查工具的連線、認證、資料存取及網路設定。 關於 MCP 驗證,請參閱 設定 MCP 工具的驗證。
相關內容
請使用以下指南設定工具存取及輔助控制項: