設定代理環境

雲端環境設定

為您的工作階段自訂雲端容器。

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

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

建立環境

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "python-dev",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)
environment_id=$(jq -r '.id' <<< "$environment")

echo "Environment ID: $environment_id"

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。

環境生命週期

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

管理環境

預先安裝的執行時環境

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

Was this page helpful?

建立環境

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "python-dev",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)
environment_id=$(jq -r '.id' <<< "$environment")

echo "Environment ID: $environment_id"

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

配置選項

套件

支援的套件管理器：

欄位	套件管理器	範例
`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 指定容器可以到達的網域。這些必須以 HTTPS 為前綴。

allow_mcp_servers 允許出站存取在代理程式上配置的 MCP 伺服器端點，超出 allowed_hosts 陣列中列出的端點。預設為 false。

allow_package_managers 允許出站存取公開套件登錄（PyPI、npm 等），超出 allowed_hosts 陣列中列出的端點。預設為 false。

環境生命週期

環境會持續存在，直到明確存檔或刪除。

多個工作階段可以參考同一個環境。

每個工作階段都會獲得自己的容器實例。工作階段不共享檔案系統狀態。

環境不進行版本控制。如果您經常更新環境，您可能想在您這一側記錄這些更新，以將環境狀態與工作階段對應。