云环境设置

环境定义了代理运行的容器配置。您创建一次环境，然后每次启动会话时引用其 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。

环境生命周期

环境持续存在，直到明确存档或删除。
多个会话可以引用同一环境。
每个会话都获得自己的容器实例。会话不共享文件系统状态。
环境不进行版本控制。如果您经常更新环境，您可能希望在您这一侧记录这些更新，以将环境状态与会话进行映射。

管理环境

预安装的运行时

云容器开箱即用地包含常见运行时。有关预安装语言、数据库和实用程序的完整列表，请参阅容器参考。

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -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
{
  "agent": "$agent_id",
  "environment_id": "$environment_id"
}
EOF
)

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": "data-analysis",
  "config": {
    "type": "cloud",
    "packages": {
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["express"]
    },
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

config=$(cat <<'EOF'
{
  "type": "cloud",
  "networking": {
    "type": "limited",
    "allowed_hosts": ["api.example.com"],
    "allow_mcp_servers": true,
    "allow_package_managers": true
  }
}
EOF
)

# List environments
environments=$(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")

# Retrieve a specific environment
env=$(curl -fsS "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

# Archive an environment (read-only, existing sessions continue)
curl -fsS -X POST "https://api.anthropic.com/v1/environments/$environment_id/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

# Delete an environment (only if no sessions reference it)
curl -fsS -X DELETE "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"