Claude Platform Docs
Managed Agents配置智能体环境

云环境设置

为您的会话自定义云沙箱。

环境（environment）定义了您的智能体运行所在的沙箱配置。您只需创建一次环境，然后在每次启动会话时引用其 ID。多个会话可以共享同一个环境，但每个会话都会获得自己独立隔离的沙箱（一个全新的 Linux 容器）。

本页介绍 type: cloud 类型的环境。若要在您自己的基础设施上运行沙箱，请参阅自托管沙箱。

创建环境

ant apply environment.yaml
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

ant apply 会根据 environment.yaml 创建环境，打印其 ID，并将其记录在 claude-lock.json 中。请提交 claude-lock.json，这样下一次运行 ant apply 时会更新此环境，而不是尝试再次创建它。

请使用唯一且具有描述性的 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
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

支持的包管理器：

字段包管理器示例
apt系统软件包（apt-get）"graphviz"
cargoRust（cargo）"hyperfine@1.18.0"
gemRuby（gem）"rails:7.1.0"
goGo 模块"golang.org/x/tools/cmd/goimports@latest"
npmNode.js（npm）"express@4.18.0"
pipPython（pip）"sqlalchemy==2.0.30"

网络

networking 字段控制沙箱的出站网络访问。它不会影响 web_search 或 web_fetch 工具，这些工具运行在 Anthropic 的服务器上；若要限制这些工具可访问的站点，请在智能体工具集中该工具的条目上设置 allowed_domains 或 blocked_domains。请参阅限制网页搜索和网页抓取的域名。

模式描述
unrestricted完全的出站网络访问，但受通用安全阻止列表限制。这是默认值。
limited将沙箱网络访问限制为 allowed_hosts 中的主机。将 allow_package_managers 和 allow_mcp_servers 设置为 true 可允许额外的访问。

以下示例创建一个使用 limited 网络模式的环境：

ant apply environment.yaml
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；否则请求将被拒绝并返回 400 错误，即使注册表主机已列在 allowed_hosts 中也是如此。

包管理器主机

当 allow_package_managers 为 true 时，除 allowed_hosts 中的主机外，沙箱还可以访问以下主机。此列表由 Anthropic 维护，并可能发生变更。

生态系统主机
代码托管github.com、api.github.com、codeload.github.com、raw.githubusercontent.com、objects.githubusercontent.com、release-assets.githubusercontent.com、gitlab.com、bitbucket.org
Node.jsregistry.npmjs.org、registry.yarnpkg.com、nodejs.org
Pythonpypi.org、files.pythonhosted.org
Rustcrates.io、index.crates.io、static.crates.io、static.rust-lang.org
Goproxy.golang.org、sum.golang.org
Javarepo1.maven.org、repo.maven.apache.org、services.gradle.org、plugins.gradle.org、plugins-artifacts.gradle.org
Rubyrubygems.org、index.rubygems.org
PHPpackagist.org、repo.packagist.org
Ubuntu（apt）archive.ubuntu.com、security.ubuntu.com、ppa.launchpad.net
容器registry-1.docker.io、auth.docker.io、production.cloudflare.docker.com、download.docker.com、ghcr.io

环境生命周期

  • 环境会一直保留，直到被显式归档或删除。
  • 每个会话都会获得自己的沙箱实例，即使多个会话引用同一个环境也是如此。会话之间不共享文件系统状态。
  • 环境不进行版本管理。如果您频繁更新环境，请自行记录变更，以便了解每个会话使用的是哪种配置。

管理环境

# 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)

预安装的运行时

云沙箱开箱即包含常用的语言运行时、数据库和命令行工具。完整列表请参阅云沙箱参考。

后续步骤

云沙箱参考

云沙箱中可用的预安装软件包、数据库和实用工具。

启动会话

创建会话以运行您的智能体并开始执行任务。

Was this page helpful?