雲端環境設定

環境（environment）定義了您的代理程式執行所在的沙箱（sandbox）設定。您只需建立一次環境，之後每次啟動工作階段（session）時參照其 ID 即可。多個工作階段可以共用同一個環境，但每個工作階段都會取得各自獨立的沙箱（一個全新的 Linux 容器）。

本頁涵蓋 type: cloud 環境。若要在您自己的基礎設施上執行沙箱，請參閱自行託管的沙箱。

建立環境

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: python-dev
config:
  type: cloud
  networking:
    type: limited
    allow_package_managers: true

請使用獨特且具描述性的 name，以便您區分不同的環境。

在工作階段中使用環境

在建立工作階段時，以字串形式傳入環境 ID。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

設定選項

套件

packages 欄位會在代理程式啟動前，將套件預先安裝到沙箱中。套件由各自對應的套件管理工具安裝，並在共用同一環境的工作階段之間快取。當指定多個套件管理工具時，它們會依字母順序執行（apt、cargo、gem、go、npm、pip）。您可以選擇性地鎖定特定版本。未鎖定版本的套件會安裝最新版本。如果環境使用 limited 網路，請同時將 networking.allow_package_managers 設為 true；否則請求會被拒絕並回傳 400 錯誤。

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: unrestricted

支援的套件管理工具：

網路

networking 欄位控制沙箱的對外網路存取。它不會影響 web_search 或 web_fetch 工具，這些工具在 Anthropic 的伺服器上執行；若要限制這些工具可連線的網站，請在代理程式工具集中該工具的項目上設定 allowed_domains 或 blocked_domains。請參閱限制網頁搜尋與網頁擷取的網域。

以下範例建立一個使用 limited 網路的環境：

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: api-access
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - api.example.com
    allow_mcp_servers: true
    allow_package_managers: true

使用 limited 網路時：

• allowed_hosts 指定沙箱可以存取的網域。請指定純主機名稱或萬用字元模式（例如 *.example.com）。請勿包含 URL 協定、連接埠或路徑。
• allow_mcp_servers 允許對代理程式上所設定的 MCP 伺服器端點進行對外存取，範圍超出 allowed_hosts 陣列中所列的主機。預設為 false。
• allow_package_managers 允許對一組公開套件登錄庫和程式碼託管主機進行對外存取，範圍超出 allowed_hosts 陣列中所列的主機。清單請參閱套件管理器主機。預設為 false。只要環境指定了 packages，就請將其設為 true；否則即使登錄庫主機已列在 allowed_hosts 中，請求仍會被拒絕並回傳 400 錯誤。

套件管理器主機

當 allow_package_managers 為 true 時，除了 allowed_hosts 中的主機之外，沙箱還可以存取下列主機。此清單由 Anthropic 維護，並可能隨時變更。

環境生命週期

• 環境會持續存在，直到被明確封存或刪除為止。
• 每個工作階段都會取得各自的沙箱實例，即使多個工作階段參照同一個環境亦然。工作階段之間不共用檔案系統狀態。
• 環境沒有版本控管。如果您經常更新環境，請自行記錄變更，以便辨別每個工作階段使用的是哪一個設定。

管理環境

# List environments
environments = client.beta.environments.list()

# Retrieve a specific environment
env = client.beta.environments.retrieve(environment.id)

# Archive an environment (read-only, existing sessions continue)
client.beta.environments.archive(environment.id)

# Delete an environment (only if no sessions reference it)
client.beta.environments.delete(environment.id)

預先安裝的執行環境

雲端沙箱內建常見的程式語言執行環境、資料庫與命令列工具。完整清單請參閱雲端沙箱參考。

後續步驟