Настройка облачной среды

Среды (environments) определяют конфигурацию песочницы (sandbox), в которой работает ваш агент. Вы создаёте среду один раз, а затем ссылаетесь на её идентификатор каждый раз при запуске сессии. Несколько сессий могут использовать одну и ту же среду, но каждая сессия получает собственную изолированную песочницу (новый контейнер Linux).

На этой странице рассматриваются среды type: cloud. Чтобы запускать песочницы на собственной инфраструктуре, см. раздел Самостоятельно размещаемые песочницы.

Создание среды

ant apply 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

Используйте уникальное, описательное значение name, чтобы вы могли различать среды.

Использование среды в сессии

Передайте идентификатор среды в виде строки при создании сессии.

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

# 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

Поддерживаемые менеджеры пакетов:

Сеть

Поле networking управляет исходящим сетевым доступом песочницы. Оно не влияет на инструменты web_search и web_fetch, которые работают на серверах Anthropic; чтобы ограничить сайты, к которым могут обращаться эти инструменты, задайте allowed_domains или blocked_domains в записи инструмента в наборе инструментов агента. См. раздел Ограничение доменов для веб-поиска и веб-загрузки.

В следующем примере создаётся среда с режимом сети limited:

ant apply 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. Устанавливайте для него значение true всякий раз, когда в среде указано поле packages; в противном случае запрос будет отклонён с ошибкой 400, даже если хосты реестров перечислены в allowed_hosts.

Хосты менеджеров пакетов

Когда allow_package_managers имеет значение true, песочница может обращаться к следующим хостам в дополнение к перечисленным в allowed_hosts. Anthropic поддерживает этот список и может его изменять.

Жизненный цикл среды

• Среды сохраняются до тех пор, пока не будут явно архивированы или удалены.
• Каждая сессия получает собственный экземпляр песочницы, даже если несколько сессий ссылаются на одну и ту же среду. Сессии не разделяют состояние файловой системы.
• Среды не версионируются. Если вы часто обновляете среду, ведите собственный учёт изменений, чтобы можно было определить, какую конфигурацию использовала каждая сессия.

Управление средами

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

Предустановленные среды выполнения

Облачные песочницы изначально включают распространённые среды выполнения языков, базы данных и инструменты командной строки. Полный список см. в разделе Справочник по облачным песочницам.

Следующие шаги