雲端環境設定

環境定義了您的代理程式執行所在的容器配置。您建立一次環境，然後在每次啟動工作階段時參考其 ID。多個工作階段可以共享同一個環境，但每個工作階段都會獲得自己隔離的容器實例。

所有 Managed Agents API 請求都需要 managed-agents-2026-04-01 beta 標頭。SDK 會自動設定 beta 標頭。

建立環境

ant beta:environments create \
  --name "python-dev" \
  --config '{type: cloud, networking: {type: unrestricted}}'

name 必須在您的組織和工作區內是唯一的。

在工作階段中使用環境

建立工作階段時，將環境 ID 作為字串傳遞。

配置選項

套件

packages 欄位在代理程式啟動前將套件預先安裝到容器中。套件由各自的套件管理器安裝，並在共享同一環境的工作階段中快取。當指定多個套件管理器時，它們按字母順序執行（apt、cargo、gem、go、npm、pip）。您可以選擇性地固定特定版本；預設為最新版本。

支援的套件管理器：

欄位	套件管理器	範例
`apt`	系統套件 (apt-get)	`"ffmpeg"`
`cargo`	Rust (cargo)	`"[email protected]"`
`gem`	Ruby (gem)	`"rails:7.1.0"`
`go`	Go 模組	`"golang.org/x/tools/cmd/goimports@latest"`
`npm`	Node.js (npm)	`"[email protected]"`

網路

networking 欄位控制容器的出站網路存取。它不會影響 web_search 或 web_fetch 工具的允許網域。

模式	說明
`unrestricted`	完整的出站網路存取，除了一般安全封鎖清單。這是預設值。
`limited`	將容器網路存取限制為 `allowed_hosts` 清單。進一步的存取可透過 `allow_package_managers` 和 `allow_mcp_servers` 布林值啟用。

對於生產部署，使用 limited 網路搭配明確的 allowed_hosts 清單。遵循最小權限原則，僅授予您的代理程式所需的最小網路存取權限，並定期審計您允許的網域。

使用 limited 網路時：

allowed_hosts 指定容器可以到達的網域。這些必須以 HTTPS 為前綴。
allow_mcp_servers 允許出站存取在代理程式上配置的 MCP 伺服器端點，超出 allowed_hosts 陣列中列出的端點。預設為 false。
allow_package_managers 允許出站存取公開套件登錄（PyPI、npm 等），超出 allowed_hosts 陣列中列出的端點。預設為 false。

環境生命週期

環境會持續存在，直到明確存檔或刪除。
多個工作階段可以參考同一個環境。
每個工作階段都會獲得自己的容器實例。工作階段不共享檔案系統狀態。
環境不進行版本控制。如果您經常更新環境，您可能想在您這一側記錄這些更新，以將環境狀態與工作階段對應。

管理環境

預先安裝的執行時環境

雲端容器開箱即用包含常見的執行時環境。請參閱容器參考以取得預先安裝的語言、資料庫和公用程式的完整清單。

ant beta:environments create <<'YAML'
name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: unrestricted
YAML

config = {
    "type": "cloud",
    "networking": {
        "type": "limited",
        "allowed_hosts": ["api.example.com"],
        "allow_mcp_servers": True,
        "allow_package_managers": True,
    },
}

# List environments
ant beta:environments list

# Retrieve a specific environment
ant beta:environments retrieve --environment-id "$ENVIRONMENT_ID"

# Archive an environment (read-only, existing sessions continue)
ant beta:environments archive --environment-id "$ENVIRONMENT_ID"

# Delete an environment (only if no sessions reference it)
ant beta:environments delete --environment-id "$ENVIRONMENT_ID"