保護您的 Managed Agents 部署

本指南列出限制 Claude Managed Agents 上的代理可以存取和執行哪些內容的設定，依重要性由高至低排列。每個章節都會連結到完整說明該設定的頁面。

安全風險與沙箱邊界說明了這些設定為何重要，以及它們無法防範哪些情況。若要審查和監控工作階段，請參閱審查與監控代理工作階段。

選擇代理的執行位置

代理的工具在何處執行，決定了由誰負責保護沙箱：使用雲端環境時由 Anthropic 負責，使用自行託管的沙箱時則由您負責。若要在兩者之間做選擇，並了解每種方式會有哪些內容傳送到 Anthropic，請參閱選擇代理環境。

如果您使用自行託管的沙箱，請記住以下四點：

• 網路： 限制網路適用於雲端環境。對於自行託管的沙箱，請在您自己的防火牆中對其流量設定同等的限制。您的防火牆不會限制代理所宣告的 MCP 伺服器，因此請審查這些伺服器，以及您的應用程式為工作階段設定的任何伺服器。
• 網頁工具： 網頁工具在 Anthropic 的伺服器上執行，因此您的防火牆不會限制它們。請使用它們的網域清單來加以限制。請參閱限制網頁搜尋和網頁擷取。
• 憑證： 自行託管的沙箱尚不支援環境變數憑證。
• 隔離與強化： 兩者皆由您負責。請參閱安全模型。

兩種選項都不會改變 Managed Agents 的合規涵蓋範圍，也不會改變其保留工作階段歷史記錄的時間長度。請參閱監控工作階段並檢視保留政策。

限制網路

將 networking.type 設為 limited，並在 allowed_hosts 中僅列出代理需要的主機。省略 networking 的環境建立請求可能會得到 unrestricted，因此請在每個建立請求中都設定 networking。請參閱不受限網路的風險。

無論 allowed_hosts 如何設定，您附加的檔案、記憶體儲存區和 GitHub 儲存庫都會持續提供給代理使用。

本頁的範例使用一個客服代理。它會讀取客戶的工單、查詢訂單、閱讀您的說明中心，並草擬回覆。訂單查詢由您的應用程式執行，不需要任何主機，因此此環境只允許一個主機，也就是供 web_fetch 使用的說明中心：

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: support-agent
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - help.example.com

limited 環境有三項網路設定：

allow_package_managers 和 allow_mcp_servers 設定不會為網頁搜尋和網頁擷取新增任何主機。

請將 allow_mcp_servers 保持關閉（這是預設值），並在 allowed_hosts 中列出您營運或信任的每個 MCP 伺服器的主機。您列出的每個主機也會對沙箱中的程式碼開放。在 allow_mcp_servers 關閉的情況下，如果 MCP 伺服器的主機未被列出，工作階段建立時的檢查會拒絕該請求。請參閱在建立工作階段時提供驗證。當工作階段更新變更 mcp_servers 時，也會執行相同的檢查。

為 allowed_hosts 選擇主機時，請遵循以下兩條規則：

• 僅列出您營運或信任的主機。
• 避免使用 *. 萬用字元，以及任何人都可以發布內容的共用託管網域。

如果代理保留 bash，請依照核准有風險的動作的說明設定 bash 工具的權限政策。

如需所有網路設定，請參閱雲端環境設定。

將憑證保存在保管庫中

將每個機密儲存在保管庫中。對於每個環境變數憑證，請將注入位置設為僅限請求標頭，並僅列出該機密所對應的主機。沙箱中的程式碼看到的是佔位符，而非機密本身。Managed Agents 只會在傳送至憑證所允許主機的對外 HTTPS 請求中將佔位符替換為真正的機密。因此，除非某個服務將機密傳回（例如會回顯請求標頭的端點），否則模型無法直接接觸到該機密。如果憑證的 networking 為 unrestricted，Managed Agents 會在傳送至環境允許沙箱存取的任何主機的請求中將佔位符替換為真正的機密。若要使用保管庫，請在建立工作階段或部署時，於 vault_ids 中傳入其 ID。

客服代理不需要保管庫憑證，因為您的應用程式持有您訂單 API 的 API 金鑰。如果您的代理確實持有保管庫憑證，請參閱新增憑證以取得各種語言的請求範例。

請勿將金鑰放在系統提示、代理定義和訊息中。不要給代理 Claude API 金鑰。即使 Claude API 金鑰存放在保管庫中，沙箱中的程式碼仍可使用它直接呼叫 Claude API。它可以執行該金鑰允許的任何操作，例如啟動或刪除工作階段，或使用網頁搜尋和網頁擷取。代理的工具設定、核准和預算都不適用於這些呼叫。在 limited 環境中，只有當 allowed_hosts 允許沙箱存取 api.anthropic.com 時，程式碼才能進行這些呼叫。

請自行擷取權杖並將其儲存在保管庫中，因為沙箱中的程式碼使用已儲存機密所擷取的權杖會以未遮蔽的形式傳回。

請將不同信任等級工作負載的保管庫放在不同的工作區中，因為任何可存取某個工作區的 API 金鑰都可以參照該工作區的保管庫。請使用範圍限定於單一工作區的 API 金鑰。

如需 MCP 憑證和輪替的相關資訊，請參閱使用 vault 進行驗證。

限制網頁搜尋和網頁擷取

將 web_fetch 上的 allowed_domains 設為代理需要的網站。代理擷取的任何 URL 都可能將資料帶到其所指向的網站，因此這份清單是一項安全控制措施。在 web_search 上，將 allowed_domains 設為您希望取得結果的網站，讓結果只來自您信任其準確性的網站。這份清單無法阻止搜尋查詢傳送到搜尋服務提供者。搜尋結果包含網頁中的文字，因此這份清單也會限制哪些網站的文字能傳到代理。請在每種類型的環境中，為兩個工具都設定 allowed_domains。

blocked_domains 清單會封鎖您列出的主機及其子網域，但不會封鎖其他任何主機。相同的內容仍可能透過網頁封存、快取、鏡像或您未列出的相關網域傳到代理。請勿依賴 blocked_domains 來確保安全。請使用 allowed_domains 並指定您信任的主機。

在 limited 環境中，限制網路中的 allowed_hosts 清單也會限制網頁工具。unrestricted 環境或自行託管的沙箱不會限制網頁工具。

兩份清單比對主機的方式不同：

如果代理需要某個網站及其所有子網域，請在 allowed_hosts 中同時列出 example.com 和 *.example.com，否則請列出確切的主機。如果某個工具列出 example.com，而 allowed_hosts 只列出 *.example.com，工作階段仍會被建立。工作階段建立時的檢查會將 example.com 視為在 *.example.com 範圍內，但該工具不會從 example.com 本身傳回任何內容。如需兩份清單的比對方式，請參閱在代理上設定網域清單。

web_fetch 工具也只會開啟已在工作階段中出現過的 URL：

在多代理工作階段中，只有當來自另一個代理的 URL 是透過標記為「是」的來源傳到該代理時，web_fetch 才會開啟它。直接呼叫所得的自訂工具結果算作標記為「是」的來源。即使其文字是由 Claude 撰寫的也是如此，例如當工具重複其輸入時。即使 URL 在撰寫時沒有 https://（例如 example.com/docs），也可能被計入。web_fetch 工具不一定能開啟以文字而非 URL 顯示的連結，例如「Contact support」。如果代理必須擷取尚未在工作階段中出現過的 URL，請在使用者訊息中傳送該 URL。

此規則可降低注入的文字建構出夾帶私人資料之 URL 的機會。終端使用者文字、搜尋結果、擷取的網頁和自訂工具結果仍可能新增 URL，因此請保持設定 allowed_domains。Messages API 套用類似的規則，但來源清單不同。請參閱 URL 驗證。

web_fetch 上的網域清單不會限制 bash 工具。請同時限制網路。請參閱網域清單規則。

核准有風險的動作

在 bash、write、edit 和 web_fetch，以及僅讀取資料的 MCP 工具上設定 auto。如果您無法在沙箱外復原某個工具所做的變更，請改為在該工具上使用 always_ask。對於不應僅因您轉送的終端使用者文字要求就執行的工具，也請使用它。權限政策決定工具呼叫是直接執行、等待您的核准，還是由伺服器評估。

為代理提供最小的工具集中的工具集套用了這些政策。

auto 政策讓伺服器執行呼叫、拒絕呼叫或暫停以等待核准。在長時間的執行中，人員無法核准每個呼叫，因此改由伺服器檢查每個呼叫。請將 auto 與受限網路、權限範圍狹窄的金鑰、預算以及閒置工作階段警示搭配使用。auto 並非人工檢查點，因此如果必須由人員在工具呼叫執行前進行審查，請在該工具上設定 always_ask。

auto 會將 user.message 事件中的文字以及 user.define_outcome 事件中的描述視為您的指示，包括您轉送的終端使用者文字。

暫停的工作階段會無限期等待，因此無人看管的工作階段需要一個能回應暫停呼叫或中斷工作階段的用戶端。

在允許每個暫停的呼叫之前，請先審查它。一個未向人員顯示就允許每個呼叫的用戶端，等同於 always_allow。請參閱回應確認請求和查看每次呼叫的評估方式。

為代理提供最小的工具集

將 default_config.enabled 設為 false，並僅啟用代理需要的工具。代理工具集預設會啟用全部八個內建工具。

客服代理需要三個內建工具：用於草稿的 read 和 write，以及用於說明中心的 web_fetch。它透過由您的應用程式執行的自訂工具 lookup_order 查詢訂單。您的應用程式持有您訂單 API 的 API 金鑰，因此代理既不需要 bash，也不需要憑證。

以下範例使用 allowed_domains 將 web_fetch 限制為 help.example.com。它依照核准有風險的動作的建議，在 write 和 web_fetch 上設定 auto。如果客戶的工單導致代理使用這些工具，代理只能變更沙箱中的檔案或開啟說明中心的網頁。這就是兩個工具都不需要 always_ask 的原因。此範例也在 default_config 中設定了 always_ask，因此您之後啟用但未設定自身政策的工具會使用 always_ask：

ant apply agent.md

---
name: Support Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      enabled: false
      permission_policy:
        type: always_ask
    configs:
      - name: read
        enabled: true
        permission_policy:
          type: always_allow
      - name: write
        enabled: true
        permission_policy:
          type: auto
      - name: web_fetch
        enabled: true
        allowed_domains: [help.example.com]
        permission_policy:
          type: auto
  - type: custom
    name: lookup_order
    description: Look up one order by its ID. Returns the status, the items, and the delivery date.
    input_schema:
      type: object
      properties:
        order_id:
          type: string
          description: The order ID from the ticket
      required:
        - order_id
---

代理更新會取代整個 tools 陣列，因此請傳送您想保留的每個項目。

代理更新只會套用到新的工作階段，因此也請檢查部署、列出此代理的代理，以及現有的工作階段：

• 部署會固定一個代理版本，因此請將每個部署指向新版本。
• 在 subagents.predefined_agents 或 workflows.predefined_agents 中列出此代理的代理，會保留其固定的版本，因此也請更新該代理。
• 若要收緊已存在的工作階段，請更新該工作階段的工具。工作階段必須處於 idle 狀態，且更新會取代整個 tools 陣列。在多代理工作階段中，工作階段所執行代理的網頁工具上新的 allowed_domains 和 blocked_domains 清單也會套用到其他每個代理。它們會從每個代理的下一個回合開始套用。這些代理已啟用的工具和權限政策不會改變。若要變更這些設定，請更新每個代理，然後啟動新的工作階段。

也請將 MCP 伺服器和自訂工具限制在代理需要的範圍內：

• MCP 伺服器： MCP 工具集預設會啟用伺服器公開的每個工具。將 default_config.enabled 設為 false 並啟用指定的工具，讓伺服器之後新增的工具保持關閉。移除代理未使用的伺服器。請參閱 MCP 連接器。
• 自訂工具： 由您的應用程式執行，權限政策不適用。請在您的應用程式中驗證每個呼叫的輸入，並限制該工具可以接觸的範圍。

讓不受信任的輸入遠離強大的工具

每當代理讀取不受信任的輸入（也就是您團隊以外的人可以撰寫的文字）時，請檢查它持有哪些工具和憑證。本節使用兩個術語：

• 不受信任的輸入： 網頁、搜尋結果、客服工單、電子郵件、儲存庫檔案、上傳內容、MCP 伺服器結果，以及您轉送的終端使用者訊息。
• 強大的工具： bash、write、edit、web_fetch、web_search、會寫入或傳送資料的 MCP 工具和自訂工具，以及任何使用憑證的工具。

不受信任輸入中的文字可能會指示代理使用它所持有的強大工具。客服代理會讀取工單，因此它只能透過自訂工具 lookup_order 存取您的訂單 API。您的應用程式會檢查該訂單是否屬於工單的寄件者。

在雲端環境中，使用 read 讀取檔案也可能將 CLAUDE.md 和 AGENTS.md 檔案載入為指示。它們會從該檔案所在的目錄及其上層目錄載入，直到沙箱的工作目錄為止。它們以 @ 加上路徑所參照的檔案（例如 @docs/setup.md）也會被載入，最多可達五層參照。參照可以指向沙箱中的任何位置，例如 @/etc/hosts。除了停用 read 之外，沒有任何設定可以關閉此行為，因此請將您團隊以外的人可以撰寫的儲存庫、套件或封存檔視為不受信任的輸入。

當代理必須讀取不受信任的輸入並同時採取行動時，本指南建議以下三種設計之一：

• 將讀取與行動分開。 在一個多代理工作階段中，由主導代理將任務分派給負責讀取網路的擷取者，以及負責變更檔案或記錄的撰寫者。
• 為代理提供一個範圍狹窄的自訂工具。 由您的應用程式執行該工具、檢查其輸入並持有憑證。客服代理使用的是這種設計，而非分離設計。請參閱回應使工作階段暫停的工具呼叫。
• 讓人員參與流程。 在強大的工具上使用 always_ask，讓人員核准每個呼叫。

分離設計使用三個代理：

擷取者的結果是由不受信任的網頁建構而成，而主導者可能會將其文字傳遞給撰寫者。請在撰寫者的工具上保持 auto 或 always_ask。擷取者仍可能將其讀取的部分內容傳送到其 web_fetch 清單上的網站，並透過查詢傳送給搜尋服務提供者。

同一個多代理工作階段中的代理會共用沙箱、其檔案以及保管庫憑證，因此這種分離只會區隔它們的工具和對話。若要更強的分離，請使用兩個具有各自環境和保管庫的工作階段。讓您的應用程式在兩個工作階段之間只傳遞固定欄位，例如訂單 ID。

設定限制和停止方式

在建立每個工作階段時設定預算，並事先決定如何停止代理。

若要停止執行中的代理，請依照以下步驟操作：

1. 單獨傳送 user.interrupt。
2. 對於排程代理，也請暫停部署，以免啟動新的排程執行。若要永久結束排程，請封存部署。
3. 如果金鑰可能已外洩，請在核發該金鑰的服務端輪替它。
4. 如果代理有開啟中的工作流程執行，也請傳送一則 user.message 要求它停止這些執行，因為中斷不會結束任何執行。如需應先取消的工具呼叫，請參閱在有開啟的執行時中斷工作階段。
5. 等待工作階段進入 idle。執行中的工作階段無法被封存或刪除。
6. 封存工作階段以保留其歷史記錄。當您不再需要歷史記錄時，請將其刪除。

中斷不會復原代理已經執行或傳送的內容。封存代理不會停止其執行中的工作階段。

預算的 max_list_cost.amount 是以字串表示的美分整數，因此 "125" 代表 $1.25。請參閱在建立工作階段時設定預算。

您無法為建立時未設定預算的工作階段新增預算。若要變更或移除上限，請參閱恢復達到預算的工作階段。移除工作階段的上限後，您就無法再設定新的上限。

預算會限制支出，但不會限制代理在達到上限之前所做的事。若要區隔不同信任等級的工作負載，請使用不同的工作區。為每個工作負載提供範圍限定於單一工作區的 API 金鑰，因為可存取多個工作區的金鑰可以在其中任何一個工作區中執行操作。

請參閱工作階段預算、工作階段操作和排程部署。

後續步驟