Самостоятельно размещаемые песочницы

По умолчанию Managed Agents выполняет инструменты и код внутри облачных песочниц под управлением Anthropic. Самостоятельно размещаемые песочницы оставляют оркестрацию на стороне Anthropic, но переносят выполнение инструментов в инфраструктуру, которую контролируете вы, так что код агента, файловая система и исходящий сетевой трафик никогда не покидают вашу среду.

Выполнение инструментов остаётся на вашем хосте: файловая система, которую агент читает и записывает, процессы, которые он порождает, и сеть, к которой он может обращаться, — всё это находится под вашим контролем. Входные и выходные данные инструментов по-прежнему передаются в управляющую плоскость Anthropic (где работает Claude), чтобы модель могла видеть результаты и определять дальнейшие действия. Полное описание границ потоков данных см. в разделе Модель безопасности.

Отличия от облачных сред

Самостоятельное размещение хорошо подходит, когда агенту нужно работать с данными, которые не могут покидать границы вашей сети, обращаться к внутренним сервисам, недоступным из публичной сети, или работать под собственными средствами контроля соответствия и аудита вашей организации.

О соответствии требованиям Zero Data Retention и HIPAA BAA см. в разделе API и хранение данных.

Когда сочетать с MCP-туннелями

Самостоятельное размещение определяет, где выполняется код агента. MCP-туннели определяют, как Anthropic достигает MCP-серверов в вашей сети. Эти механизмы независимы: сессия, работающая в облачных песочницах Anthropic, всё равно может обращаться к приватным MCP-серверам через туннель, а самостоятельно размещаемая сессия может использовать как туннелированные, так и публичные MCP-серверы. Используйте оба механизма, если хотите, чтобы и выполнение, и доступ к инструментам оставались внутри вашего периметра.

Воркер среды

«Environment worker» (воркер среды) — это процесс, который вы запускаете в собственной инфраструктуре. Он получает запросы на выполнение инструментов от Anthropic и выполняет их локально. Среда self_hosted действует как очередь работ: когда сессия назначается этой среде, Anthropic помещает сессию в очередь как рабочий элемент. Ваш воркер забирает рабочие элементы из этой очереди, создаёт контекст выполнения для каждого из них, загружает навыки агента (переиспользуемые ресурсы на основе файловой системы, которые дают агенту предметную экспертизу), выполняет вызовы инструментов и отправляет результаты обратно.

Рабочие элементы забираются путём опроса очереди среды: либо постоянно работающим воркером, который опрашивает непрерывно, либо обработчиком, запускаемым по вебхуку, который пробуждается по событию session.status_run_started и начинает опрос.

И CLI, и SDK поставляются с готовыми воркерами. CLI ant поддерживает только постоянно работающий вариант; SDK поддерживает оба — постоянно работающий и запускаемый по вебхуку. Оба варианта настраиваемы: флаги CLI см. в разделе Самостоятельно размещаемый воркер справочника, а параметры SDK — в разделе Вспомогательные функции SDK на этой странице. Для большего контроля вызывайте эндпоинты Environments Work напрямую и реализуйте собственный воркер. В Claude Platform on AWS эндпоинт списка GET /v1/environments/{id}/work и его эквивалент в SDK в настоящее время недоступны; остальные эндпоинты работы (poll, ack, heartbeat, stop, post results, получение отдельного элемента и stats) работают в обычном режиме.

Файловая система песочницы

• /workspace: системный рабочий каталог по умолчанию для выполнения инструментов и загрузки навыков. Флаг CLI --workdir по умолчанию указывает на текущий каталог; передайте --workdir /workspace, чтобы соответствовать системному значению по умолчанию. Навыки загружаются в <workdir>/skills/<name>/. Если вы используете другой рабочий каталог, обновите системную подсказку вашего агента, чтобы Claude мог найти файлы навыков.
• /mnt/session/outputs: оснастка воркера инструктирует Claude записывать итоговые результаты сюда. В режиме песочницы смонтируйте каталог хоста по этому пути, чтобы получить результаты после завершения сессии. В режиме выполнения внутри процесса файловые инструменты воркера пишут в рабочий каталог, поэтому этот путь не применяется.

Перед началом работы

Вам потребуется:

• Существующий агент. Если у вас его нет, сначала выполните Быстрый старт и запишите ID агента.
• Linux-хост с /bin/bash по этому точному пути. Для TypeScript SDK дополнительно требуются unzip, tar и Node.js 22 или новее; Python SDK использует стандартную библиотеку для извлечения архивов и не имеет дополнительных требований к бинарным файлам. Эти зависимости разрешаются по фиксированным путям и не учитывают переопределения PATH.
• CLI ant или SDK Anthropic (Python, TypeScript или Go) на хосте воркера.
• Два набора учётных данных: ключ среды (генерируется на следующих шагах) аутентифицирует воркер в его очереди; ваш ключ API Claude создаёт сессии и читает статистику очереди извне хоста воркера.

Запуск воркера

Выберите постоянно работающий вариант для самой простой настройки: долгоживущий процесс непрерывно опрашивает очередь и требует только исходящего HTTPS. Выберите запускаемый по вебхуку вариант, чтобы не держать простаивающий опросчик; для этого требуется эндпоинт вебхука, доступный для Anthropic (см. Вебхуки для настройки эндпоинта и проверки подписи).

Вспомогательные функции SDK

SDK предоставляет три вспомогательные функции с разным уровнем контроля. EnvironmentWorker покрывает большинство сценариев использования; переходите к более низкоуровневым функциям, когда вам нужно запускать собственный процесс для каждой сессии или выполнять инструменты для уже забранной сессии.

• EnvironmentWorker: готовый воркер. Полностью обрабатывает опрос, настройку и выполнение.
  • .run(): работает бесконечно, подхватывая сессии по мере их поступления. Корректно завершается по SIGTERM.
  • .handle_item(): подхватывает одну ожидающую сессию, обрабатывает её и завершается.
• work.poller(): опрашивает очередь работ от вашего имени и передаёт вам каждую забранную сессию. Используйте это, когда хотите сами решать, что происходит для каждой сессии, например запускать песочницу вместо выполнения инструментов внутри процесса.
  • drain: прекращать ли опрос, как только очередь опустеет, вместо ожидания новой работы.
  • block_ms: сколько ждать поступления работы перед возвратом, в миллисекундах. Должно быть от 1 до 999 (ожидание на один опрос; функция автоматически повторяет опрос). Передайте null (None в Python, param.Null[int64]() в Go) для неблокирующей проверки; если параметр опущен, используется длинный опрос по умолчанию в 999 мс.
  • reclaim_older_than_ms: повторно забирать рабочие элементы, арендованные воркером, который перестал отвечать.
  • auto_stop: отправлять ли сигнал остановки для рабочего элемента после выхода из итератора. Опросчик Go не имеет возможности отключения и всегда отправляет сигнал остановки, поэтому блокируйтесь в теле цикла до завершения сессии, а не отсоединяйтесь.
• client.beta.sessions.events.tool_runner(): выполняет вызовы инструментов для одной сессии, получая ID сессии и список инструментов. Используйте, когда вы уже забрали работу и вам нужен только слой выполнения.

Используйте опросчик работ напрямую, когда хотите запускать собственный процесс для каждой сессии, например поднимать песочницу для каждой забранной сессии:

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork


async def launch_container(work: BetaSelfHostedWork) -> None:
    # Замените на собственный запуск песочницы для каждой сессии. Передавайте
    # ANTHROPIC_ENVIRONMENT_KEY в запускаемую песочницу, но никогда
    # не передавайте свой ключ API.
    print(f"claimed session {work.data.id}")


async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    async with AsyncAnthropic(auth_token=environment_key) as client:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

AgentToolContext — это контекст выполнения для вызовов инструментов. Он определяет рабочий каталог и политику путей, а также опционально загружает навыки сессии при использовании в качестве менеджера контекста. beta_agent_toolset_20260401(env) принимает AgentToolContext и возвращает стандартные реализации инструментов (bash, read, write, edit, glob, grep).

С EnvironmentWorker: оба управляются автоматически. Передайте фабрику tools, чтобы настроить список инструментов:

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

С work.poller() и tool_runner(): передайте список инструментов как tools в client.beta.sessions.events.tool_runner(). Чтобы построить этот список, настройте AgentToolContext самостоятельно и вызовите beta_agent_toolset_20260401(env):

from anthropic.lib.tools.agent_toolset import (
    AgentToolContext,
    beta_agent_toolset_20260401,
)

async with AgentToolContext(
    workdir="/workspace", client=client, session_id=work.data.id
) as env:
    # skills downloaded to /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)

Проверка подключения воркера

Из отдельной оболочки, используя ваш ключ API Claude (не ключ среды), убедитесь, что workers_polling не меньше 1:

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

Если workers_polling остаётся равным 0, воркер не достигает очереди: убедитесь, что ANTHROPIC_ENVIRONMENT_KEY и ANTHROPIC_ENVIRONMENT_ID установлены на хосте воркера. Полный ответ статистики и примеры на других языках см. в разделе Чтение глубины очереди.

Запуск сессии

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

Anthropic не монтирует файлы или репозитории GitHub в самостоятельно размещаемые песочницы. Чтобы сделать доступными файлы, специфичные для сессии, передайте ссылки на файлы (например, путь S3 или SHA коммита) в поле metadata сессии. Ваш скрипт запуска или обработчик --on-work считывает эти метаданные из забранного рабочего элемента (через эндпоинты Environments Work) и размещает файлы в рабочем каталоге до начала выполнения инструментов.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

Полный список флагов CLI см. в разделе Самостоятельно размещаемый воркер справочника, а параметры вспомогательных функций SDK — в разделе Вспомогательные функции SDK.

Мониторинг и эксплуатация

Эти вызовы выполняются из ваших инструментов мониторинга или эксплуатации, аутентифицированных вашим ключом API Claude, для наблюдения за парком воркеров и управления им. Цикл забора и поддержания активности обрабатывается внутри вспомогательных функций воркера, поэтому вы не вызываете эти эндпоинты напрямую.

Чтение глубины очереди

work.stats возвращает состояние очереди для среды:

• depth — количество элементов, ожидающих забора. Масштабируйте парк воркеров или настраивайте оповещения о накоплении на основе этого значения.
• pending — количество элементов, которые воркер забрал и в данный момент обрабатывает.
• oldest_queued_at — временная метка самого старого элемента в очереди или null, если очередь пуста.
• workers_polling — количество воркеров, которые опрашивали очередь за последние 30 секунд. Используйте это для оповещений о работоспособности.

import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}

Корректная остановка сессии

Используйте work.stop, чтобы попросить воркер, обрабатывающий конкретную сессию, корректно её завершить. Воркер завершает текущий вызов инструмента, отправляет финальный статус и освобождает сессию. Передайте force: true в теле запроса, чтобы прервать немедленно, не дожидаясь завершения текущего вызова инструмента.

Поскольку эти вызовы выполняются из ваших инструментов эксплуатации, а не с хоста воркера, ANTHROPIC_WORK_ID не устанавливается автоматически. Установите его равным ID целевого рабочего элемента перед запуском следующих примеров.

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)

Дальнейшие шаги