雲端環境設定

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

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



建立環境

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

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



在工作階段中使用環境

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

ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID"



設定選項



套件

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

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

支援的套件管理器：



網路

networking 欄位控制沙箱的對外網路存取。它不會影響 web_search 或 web_fetch 工具所允許的網域。

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

ant beta:environments create <<'YAML'
name: api-access
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - api.example.com
    allow_mcp_servers: true
    allow_package_managers: true
YAML

使用 limited 網路時：

• allowed_hosts 指定沙箱可以連線的網域。請指定純主機名稱或萬用字元模式（例如 *.example.com）。請勿包含 URL 配置（scheme）、連接埠或路徑。
• allow_mcp_servers 允許對代理程式上設定的 MCP 伺服器端點進行對外存取，超出 allowed_hosts 陣列中所列的範圍。預設為 false。
• allow_package_managers 允許對公開套件登錄檔（例如 PyPI 和 npm）進行對外存取，超出 allowed_hosts 陣列中所列的範圍。預設為 false。



環境生命週期

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



管理環境

# 列出環境
ant beta:environments list

# 擷取特定環境
ant beta:environments retrieve --environment-id "$ENVIRONMENT_ID"

# 封存環境（唯讀，現有工作階段仍可繼續）
ant beta:environments archive --environment-id "$ENVIRONMENT_ID"

# 刪除環境（僅限沒有工作階段參照時）
ant beta:environments delete --environment-id "$ENVIRONMENT_ID"



預先安裝的執行環境

雲端沙箱內建常見的執行環境。請參閱雲端沙箱參考以取得預先安裝的程式語言、資料庫和公用程式的完整清單。



後續步驟