托管智能体配置智能体环境

云环境设置

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

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

本页介绍 type: cloud 环境。如需在您自己的基础设施上运行沙盒，请参阅自托管沙盒。

所有 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。

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

支持的包管理器：

字段	包管理器	示例
`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]"`
`pip`	Python（pip）	`"pandas==2.2.0"`

网络

networking 字段控制沙盒的出站网络访问。它不会影响 web_search 或 web_fetch 工具的允许域名。

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

以下示例创建一个使用 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 列表。遵循最小权限原则，仅授予智能体所需的最低网络访问权限，并定期审核您允许的域名。

使用 limited 网络时：

allowed_hosts 指定沙盒可以访问的域名。请指定纯主机名或通配符模式（例如 *.example.com）。不要包含 URL 协议、端口或路径。
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"

预安装的运行时

云沙盒开箱即用地包含常见的运行时。请参阅云沙盒参考，了解预安装的语言、数据库和实用工具的完整列表。

后续步骤

云沙盒参考

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

启动会话

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

Was this page helpful?

托管智能体配置智能体环境

云环境设置

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

本页介绍 type: cloud 环境。如需在您自己的基础设施上运行沙盒，请参阅自托管沙盒。

所有 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。

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

配置选项

软件包

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

支持的包管理器：

字段	包管理器	示例
`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]"`
`pip`	Python（pip）	`"pandas==2.2.0"`

网络

networking 字段控制沙盒的出站网络访问。它不会影响 web_search 或 web_fetch 工具的允许域名。

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

以下示例创建一个使用 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 协议、端口或路径。
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"

预安装的运行时

云沙盒开箱即用地包含常见的运行时。请参阅云沙盒参考，了解预安装的语言、数据库和实用工具的完整列表。

后续步骤

云沙盒参考

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

启动会话

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

Was this page helpful?

创建环境

在会话中使用环境

配置选项

软件包

网络

环境生命周期

管理环境

预安装的运行时

后续步骤

创建环境

在会话中使用环境

配置选项

软件包

网络

环境生命周期

管理环境

预安装的运行时

后续步骤

创建环境

在会话中使用环境

配置选项

软件包

网络

环境生命周期

管理环境

预安装的运行时

后续步骤

创建环境

在会话中使用环境

配置选项

软件包

网络

环境生命周期

管理环境

预安装的运行时

后续步骤