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

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

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



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

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

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



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

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



Воркер среды

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

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

И CLI, и SDK поставляются с готовыми воркерами. CLI ant поддерживает только постоянно работающий вариант; SDK поддерживает как постоянно работающий, так и запускаемый по вебхуку. Оба настраиваемы: см. Самостоятельно размещаемый воркер в справочнике для флагов CLI и Вспомогательные функции SDK на этой странице для параметров SDK. Для большего контроля вызывайте эндпоинты Environments Work напрямую и реализуйте собственный воркер.



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

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



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

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

• Существующий агент. Если у вас его нет, сначала выполните Быстрый старт и запишите его идентификатор агента.
• 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(): опрашивает очередь работ от вашего имени и передаёт вам каждую забранную сессию. Используйте это, когда хотите сами решать, что происходит для каждой сессии, например запускать песочницу вместо выполнения инструментов в процессе.
  • 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 получает сессию (GET /v1/sessions/{session_id}), чтобы прочитать поле metadata, а затем размещает файлы в рабочем каталоге до начала выполнения инструментов.

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

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



Обслуживание пользовательских инструментов из вашей песочницы

Пользовательские инструменты — это инструменты, которые выполняет ваш собственный код: агент генерирует событие agent.custom_tool_use и ожидает соответствующий user.custom_tool_result. Воркер может быть этим кодом, и поскольку он работает внутри вашей песочницы, инструмент получает доступ к внутренним сервисам, учётным данным и исходящему сетевому трафику, которые вы настроили для песочницы, — и ни к чему больше. Ключ среды авторизует отправку результатов пользовательских инструментов, поэтому ваш ключ API Claude не попадает на хост воркера.

Воркер отвечает только на инструменты, зарегистрированные в нём. Пользовательский инструмент, объявленный на агенте, но не зарегистрированный ни в одном воркере или клиенте, оставляет сессию приостановленной с причиной остановки requires_action, пока что-то не отправит его результат; поток событий см. в разделе Обработка вызовов пользовательских инструментов.



Оборачивание MCP-сервера в пользовательские инструменты

MCP-коннектор подключается к MCP-серверам со стороны Anthropic, поэтому сервер должен предоставлять HTTP-эндпоинт, доступный для Anthropic напрямую или через MCP-туннель. Чтобы использовать сервер, доступный только из вашей сети, сделайте воркер MCP-клиентом и объявите инструменты сервера как пользовательские инструменты. MCP-серверу не требуется входящее подключение извне вашей сети; Anthropic получает определения инструментов, которые вы объявляете на агенте, входные данные каждого вызова и результат, который ваш воркер отправляет обратно. Во время выполнения модель вызывает обёрнутый инструмент как любой другой пользовательский инструмент:

1. Агент генерирует событие agent.custom_tool_use.
2. Воркер внутри вашей песочницы перенаправляет вызов через свою открытую MCP-сессию на сервер в вашей сети.
3. Воркер отправляет ответ сервера как user.custom_tool_result.

Клиентские вспомогательные функции MCP в SDK преобразуют инструменты сервера в исполняемые инструменты, которые принимает воркер; установите MCP SDK вместе с Anthropic SDK (pip install "anthropic[mcp]" "mcp>=1.24", npm install @modelcontextprotocol/sdk, go get github.com/modelcontextprotocol/go-sdk). Примеры подключаются без аутентификации; чтобы отправлять учётные данные, настройте HTTP-клиент или параметры запроса, которые вы передаёте MCP-транспорту (http_client в Python, requestInit в TypeScript, HTTPClient в Go).

При оборачивании MCP-сервера учитывайте следующее:

• Инструменты объявляются, а не обнаруживаются во время выполнения. Воркер перечисляет инструменты MCP-сервера один раз при запуске и не может добавлять инструменты в работающую сессию. Когда инструменты сервера меняются, объявите их снова — на агенте или в простаивающей сессии через Обновление конфигурации агента — и перезапустите воркер.
• Имена и описания должны соответствовать API Managed Agents. Имена пользовательских инструментов уникальны в пределах агента и используют буквы, цифры, подчёркивания и дефисы (1–128 символов); требуется непустое описание; массив tools агента принимает не более 128 записей (каждый обёрнутый инструмент — одна запись, а встроенный набор инструментов — ещё одна). API отклоняет объявление, которое повторно использует имя инструмента, называет пользовательский инструмент именем встроенного инструмента агента, такого как bash или read, или использует зарезервированный префикс mcp__. Вспомогательные функции MCP сохраняют имена и описания сервера, поэтому переименовывайте или сокращайте их при необходимости. Когда два сервера предоставляют инструмент с одинаковым именем, определите обёртку самостоятельно под именем с префиксом и заставьте её вызывать оригинальное имя инструмента сервера.
• Большинство схем проходят без изменений. API принимает ключевые слова JSON Schema, которые обычно генерируют MCP-серверы, такие как additionalProperties и title. Он отклоняет ключевые слова ссылок, такие как $ref, в любом месте input_schema пользовательского инструмента, поэтому встраивайте схемы, которые генераторы вроде pydantic выносят в $defs. Он также отклоняет oneOf, anyOf и allOf на верхнем уровне, а также имена свойств, содержащие символы помимо букв, цифр, подчёркиваний, точек и дефисов (1–64 символа).
• Сбои инструментов отображаются как результаты инструментов с ошибкой. Когда MCP-сервер сообщает об ошибке инструмента, воркер отправляет результат инструмента с ошибкой, на который модель может отреагировать. MCP-контент без эквивалента результата инструмента, такой как аудиоблоки и ссылки на ресурсы, также отображается как ошибка. Установите тайм-аут на MCP-клиенте для более быстрого и понятного сбоя, как это делает пример воркера на Python с read_timeout_seconds. Без него зависший вызов становится результатом с ошибкой только когда срабатывает тайм-аут запроса по умолчанию в TypeScript MCP SDK (около минуты) или когда срабатывает собственная защита воркера: около двух с половиной минут в Python и две минуты в Go, где воркер отменяет вызов инструмента, превысивший 120-секундное значение по умолчанию, и отправляет результат с ошибкой.
• Оборачивайте серверы, которыми вы управляете или которым доверяете. Имя, описание и результаты обёрнутого инструмента попадают в контекст модели как и у любого другого инструмента: это недоверенный ввод, который может влиять на то, что агент делает с другими своими инструментами, включая bash на хосте воркера. Объявляйте только те инструменты, которые вы намерены предоставить агенту.
• Политики разрешений не применяются к пользовательским инструментам. Политики разрешений управляют встроенными и MCP-наборами инструментов; воркер выполняет каждый вызов обёрнутого инструмента, который делает модель, поэтому размещайте любой шаг одобрения в вашем собственном коде инструмента.



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

Эти вызовы выполняются из вашего инструментария мониторинга или эксплуатации, аутентифицированного вашим ключом 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, чтобы попросить воркер, обрабатывающий конкретную сессию, завершить её. По умолчанию рабочий элемент переходит в состояние stopping: воркер замечает это при следующем heartbeat-сигнале аренды, отменяет выполняющийся вызов инструмента сессии и подтверждает завершение работы, после чего рабочий элемент переходит в состояние stopped. Передайте force: true в теле запроса (при использовании CLI передайте --force), чтобы сразу пометить рабочий элемент как stopped, не дожидаясь подтверждения от воркера.

Поскольку эти вызовы выполняются из ваших операционных инструментов, а не с хоста воркера, переменная 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)



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