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

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



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

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



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

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

• Существующий агент. Если у вас его нет, сначала пройдите Быстрый старт и запишите его ID агента.
• Хост 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(): выполняет вызовы инструментов для одной сессии по заданному 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:
    # навыки загружены в /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 в ID агента, который вы записали в разделе Перед началом работы. Сессия попадает в очередь работ окружения и ждёт там, пока воркер её не заберёт; если ни один воркер не подключён, сессия остаётся в очереди, а не завершается с ошибкой.

Anthropic не монтирует файлы или репозитории GitHub в самостоятельно размещаемые песочницы. Чтобы сделать доступными файлы, специфичные для сессии, передайте ссылки на файлы (например, путь S3 или SHA коммита) в поле metadata сессии. Забранный рабочий элемент не содержит метаданные сессии, но содержит ID сессии: ваш скрипт запуска или обработчик --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"},
)

См. Self-hosted worker в справочнике для полного списка флагов 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 один раз при запуске и не может добавлять инструменты в работающую сессию. Когда инструменты сервера меняются, объявите их снова, на агенте или на простаивающей сессии через Обновление конфигурации агента, и перезапустите воркер.
• Имена и описания должны соответствовать Managed Agents API. Имена пользовательских инструментов уникальны в рамках агента и используют буквы, цифры, подчёркивания и дефисы (1–128 символов); описание обязательно (1–4 096 символов); а массив 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, чтобы попросить worker, обрабатывающий конкретную сессию, завершить её. По умолчанию рабочий элемент переходит в состояние stopping: worker замечает это при следующем heartbeat аренды, отменяет выполняемый вызов инструмента сессии и подтверждает завершение, после чего рабочий элемент становится stopped. Передайте force: true в теле запроса (в CLI передайте --force), чтобы немедленно пометить рабочий элемент как stopped, не дожидаясь подтверждения от worker.

Поскольку эти вызовы выполняются из ваших инструментов эксплуатации, а не с хоста worker, переменная ANTHROPIC_WORK_ID не устанавливается автоматически. Установите её в ID целевого рабочего элемента перед запуском следующих примеров. Чтобы найти 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)



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