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

По умолчанию Managed Agents выполняет инструменты и код внутри облачных песочниц, управляемых Anthropic. Самостоятельно размещаемые песочницы (self-hosted sandboxes) оставляют оркестрацию на стороне 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 поддерживает как постоянно работающий, так и запускаемый вебхуком. Оба настраиваемы: см. Self-hosted worker в справочнике для флагов CLI и Вспомогательные средства SDK на этой странице для опций SDK. Для большего контроля вызывайте конечные точки Environments Work напрямую и реализуйте собственный воркер.



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

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



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

Вам понадобится:

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



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

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



Вспомогательные средства SDK

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

• EnvironmentWorker: готовый воркер. Обрабатывает опрос, настройку и выполнение от начала до конца.
  • .run(): работает бесконечно, подхватывая сессии по мере их поступления.
  • .handle_item(): обрабатывает один забранный рабочий элемент и завершается. Передайте идентификаторы работы, сессии и среды явно или позвольте ему прочитать переменные ANTHROPIC_*, которые ant beta:worker poll --on-work устанавливает для порождаемого процесса.
• work.poller(): опрашивает очередь работ от вашего имени и передаёт вам каждую забранную сессию. Используйте это, когда хотите решать, что происходит с каждой сессией, например запускать песочницу вместо выполнения инструментов in-process.
  • 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(): выполняет вызовы инструментов для одной сессии по идентификатору сессии и списку инструментов. Используйте, когда вы уже забрали работу и вам нужен только слой выполнения.

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

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:
    # навыки загружены в /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)



Проверьте, что воркер подключён

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

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

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



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

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

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

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

См. Self-hosted worker в справочнике для полного списка флагов 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 в теле запроса (в CLI передайте --force), чтобы прервать немедленно, не дожидаясь завершения текущего вызова инструмента.

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

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)



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