Запуск отдельной песочницы для каждого сеанса
Предоставьте каждому сеансу собственную самостоятельно размещаемую песочницу с помощью Helm-чарта в Kubernetes, скрипта запуска или опрашивающего процесса SDK.
В шаблоне «sandbox-per-session» (песочница на каждый сеанс) каждый сеанс выполняется в новой песочнице, у которой могут быть собственная файловая система, ограничения ресурсов и сетевые ограничения. Чтобы сравнить его с другими шаблонами, см. Выбор шаблона развёртывания.
Настроить его можно тремя способами:
- Helm-чарт в Kubernetes: диспетчер Anthropic забирает работу и запускает под для каждого сеанса в вашем кластере.
- Скрипт запуска: CLI
antзабирает работу и вызывает ваш скрипт, который запускает песочницу на любой платформе. - Опрашивающий процесс SDK: ваш собственный код забирает работу и запускает песочницу.
Разделы после Запуск песочниц в Kubernetes относятся к скрипту запуска и опрашивающему процессу SDK.
Запуск песочниц в Kubernetes
Anthropic публикует Helm-чарт cma-sandboxes и его образы. Чарт запускает отдельную песочницу для каждого сеанса в вашем собственном кластере Kubernetes. Его диспетчер опрашивает очередь работы среды и выделяет каждому сеансу собственный под:
- Изоляция: каждый под работает под управлением gVisor за сетевыми политиками чарта. У него собственная файловая система и ограничения ресурсов. Ключ среды есть только у диспетчера.
- Привязка к сеансу («session affinity»): каждое сообщение в сеансе направляется в песочницу этого сеанса. Когда сеанс находится в состоянии простоя 30 минут (значение по умолчанию параметра чарта
sandbox.idleTimeout), его под останавливается. Его том/workspaceсохраняется до завершения сеанса. Следующее сообщение запускает под на том же томе. - Тёплый пул («warm pool»): везде, кроме Google Kubernetes Engine (GKE), чарт держит наготове два пода для новых сеансов (значение по умолчанию параметра чарта
sandbox.warmPoolSize).
Поды песочниц запускают «worker» (воркер) CLI ant. Они поддерживают хранилища памяти с настройками синхронизации по умолчанию и не поддерживают пользовательские инструменты.
Установка чарта
Чарт работает в GKE, Amazon EKS и других кластерах. Перед установкой настройте следующее:
- В кластере: контроллер Agent Sandbox (в GKE — дополнение Agent Sandbox), узлы с gVisor и сетевой плагин, применяющий NetworkPolicy.
- В вашем собственном пространстве имён: метки Restricted Pod Security Standard, Secret с идентификатором среды и ключом среды, а также TLS-сертификат диспетчера.
В руководстве по установке на GitHub приведены шаги настройки для каждого типа кластера. В нём также описаны обновления и ротация ключей.
Сохраните свои настройки в файле cma-values.yaml. Без трёх параметров из этого файла установка завершится ошибкой:
platform: gke # or eks, or generic for any other cluster
egress:
# The chart already blocks the private ranges. List your other addresses
# that sandboxes must not reach.
clusterCIDRs:
- 203.0.113.10/32 # your cluster's Kubernetes API endpoint
cmaServer:
public: true # the Claude API has a public addressВ руководстве по установке перечислены параметры, зависящие от вашего кластера, например gke.dns в GKE Autopilot. В нём также указано, когда egress.clusterIsPrivate: true заменяет egress.clusterCIDRs.
Затем установите чарт:
helm install cma \
oci://us-docker.pkg.dev/anthropic-public-registry/sandboxes/charts/cma-sandboxes \
--version 0.1.0 \
--namespace cma \
-f cma-values.yaml \
--waitПосле установки выполните предварительную проверку, описанную в руководстве по установке.
Добавление инструментов в образ песочницы
Опубликованный образ песочницы основан на Alpine Linux и содержит bash, curl, jq и CLI ant. Чарт запускает его с корневой файловой системой только для чтения и от имени пользователя без прав root, поэтому агент не может устанавливать пакеты во время сеанса.
Чтобы предоставить агентам больше инструментов, например Python или Git, соберите оба образа из репозитория по тегу релиза. Команды приведены в разделе Install руководства по установке. Отправьте образы в свой реестр как cma-dispatcher и cma-sandbox, указав в качестве тега версию чарта. Затем задайте для image.registry этот реестр. Если вы закрепляете дайджесты образов, используйте дайджесты собственных образов.
Ограничение исходящего сетевого трафика
По умолчанию сетевые политики чарта позволяют песочнице обращаться к публичному интернету IPv4. Они блокируют частные диапазоны адресов, сервер метаданных облака и адреса из egress.clusterCIDRs. Агент, подвергшийся «prompt injection» (внедрению подсказок), может отправить прочитанное на любой адрес, доступный его песочнице. Подробности см. в разделе Network egress руководства по установке.
- GKE с Dataplane V2: задайте
egress.mode: fqdnGke, чтобы ограничить подключения портом 443 на хостах изegress.fqdnGke.hosts. Оставьте в этом спискеapi.anthropic.comи добавьте каждый хост, необходимый командам ваших агентов. В отличие от режима по умолчанию, в этом режиме нет списка заблокированных диапазонов. Он разрешает любой адрес, в который разрешается имя указанного хоста, поэтому указывайте только хосты, DNS которых вы доверяете. Песочница всё равно может передавать данные наружу внутри DNS-запросов. - Другие кластеры и GKE без Dataplane V2: доступен только режим по умолчанию.
- Любой кластер: сетевые политики не распространяются на порты, прослушиваемые собственными узлами кластера. См. Node isolation you own в руководстве по установке.
Запуск песочниц с помощью скрипта запуска
Опрашивающий процесс на хосте забирает работу и вызывает ваш «spawn script» (скрипт запуска) один раз для каждого «work item» (элемента работы). Скрипт запускает песочницу для этого одного сеанса.
Соберите образ песочницы
Установите
antи укажитеant beta:worker runв качестве точки входа. При запуске песочница считывает сведения о сеансе из переменных окружения, обрабатывает этот сеанс и завершает работу. Базовый образ должен предоставлять/bin/bash; при сборкеcurlиспользуется только для загрузкиant.DockerfileFROM your-base-image ARG ANT_VERSION=2.11.0 ARG TARGETARCH RUN ARCH=$([ "$TARGETARCH" = "arm64" ] && echo arm64 || echo amd64) && \ curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${ANT_VERSION}/ant_${ANT_VERSION}_linux_${ARCH}.tar.gz" \ | tar -xz -C /usr/local/bin ant WORKDIR /workspace VOLUME /workspace ENTRYPOINT ["ant", "beta:worker", "run"]Напишите скрипт запуска
Скрипт передаёт сведения о сеансе в новую песочницу. Для него на хосте опрашивающего процесса требуется
jq.spawn.sh#!/bin/bash # spawn.sh: вызывается один раз для каждого забранного элемента работы # Забранный элемент работы поступает в формате JSON через stdin. ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')" export ANTHROPIC_WORK_SECRET mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID" exec docker run --rm \ -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \ -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \ -e ANTHROPIC_WORK_SECRET \ -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \ your-imageОпрашивающий процесс задаёт
ANTHROPIC_WORK_ID,ANTHROPIC_ENVIRONMENT_ID,ANTHROPIC_SESSION_IDиANTHROPIC_ENVIRONMENT_KEY.ANTHROPIC_BASE_URLпопадает в скрипт, только если вы задали её на хосте опрашивающего процесса. Скрипт считываетANTHROPIC_WORK_SECRETиз JSON элемента работы со стандартного ввода. См. Переменные окружения./host/outputs— это выбранный вами каталог хоста. Монтирование его в/workspaceпозволяет получить результаты сеанса после завершения работы песочницы. При монтировании туда также попадают загруженное деревоskills/и любые промежуточные файлы.Запустите опрашивающий процесс
ant beta:worker poll --on-work ./spawn.sh
Передача секрета элемента работы
Каждый забранный элемент работы может содержать secret, выдаваемый Anthropic для этого сеанса. Он нужен воркеру, выполняющему сеанс, чтобы монтировать хранилища памяти.
Воркер, который забирает и выполняет сеансы в одном процессе, сам передаёт секрет дальше. Одним из таких воркеров является EnvironmentWorker с run(), другим — ant beta:worker poll без --on-work. Если между получением работы и воркером находится ваш собственный код, секрет передаёте вы:
| Способ получения работы | В каком виде поступает секрет | Как передать его воркеру |
|---|---|---|
ant beta:worker poll --on-work | Поле secret в JSON элемента работы на стандартном вводе вашего скрипта | ANTHROPIC_WORK_SECRET в окружении песочницы |
work.poller() в SDK для Python, TypeScript или Go | Поле secret каждого забранного элемента работы | ANTHROPIC_WORK_SECRET в окружении песочницы или аргумент work_secret для handle_item() |
Передавайте секрет только в песочницу, обслуживающую этот сеанс, и никогда не записывайте его в журналы. О том, как он связан с ключом среды, см. Модель безопасности.
Запуск песочниц из опрашивающего процесса SDK
Чтобы забирать работу из собственного кода вместо ant beta:worker poll --on-work, используйте опрашивающий процесс в SDK для Python, TypeScript или Go: work.poller(). Он опрашивает очередь и передаёт вам каждый забранный сеанс, а песочницу запускаете вы:
import asyncio
import os
from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork
SANDBOX_ENV = (
"ANTHROPIC_ENVIRONMENT_ID",
"ANTHROPIC_ENVIRONMENT_KEY",
"ANTHROPIC_WORK_ID",
"ANTHROPIC_SESSION_ID",
"ANTHROPIC_WORK_SECRET",
"ANTHROPIC_BASE_URL", # forwarded only when set on this host
)
async def launch_container(work: BetaSelfHostedWork) -> None:
print(f"claimed session {work.data.id}")
# Замените `docker run` собственным средством запуска песочниц. Передайте ключ
# среды (но никогда не ключ API) и секрет сеанса из элемента работы: воркеру
# внутри секрет нужен, чтобы монтировать хранилища памяти сеанса.
env = os.environ | {
"ANTHROPIC_WORK_ID": work.id,
"ANTHROPIC_SESSION_ID": work.data.id,
"ANTHROPIC_WORK_SECRET": work.secret or "",
}
forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
launcher = await asyncio.create_subprocess_exec(
"docker", "run", "--rm", "--detach", *forward, "your-image", env=env
)
await launcher.wait()
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())Запуск воркера SDK внутри песочницы
Замените точку входа ant beta:worker run точкой входа SDK, если песочница должна обслуживать пользовательские инструменты или использовать нестандартные настройки синхронизации памяти. Точка входа создаёт EnvironmentWorker и вызывает handle_item(), который считывает те же переменные ANTHROPIC_*, передаваемые скриптом запуска.
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker
async def main() -> None:
async with AsyncAnthropic(
auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
) as client:
worker = EnvironmentWorker(client, workdir="/workspace")
# Без аргументов handle_item() читает переменные ANTHROPIC_*, переданные скриптом
# запуска, включая ANTHROPIC_WORK_SECRET.
task = asyncio.create_task(worker.handle_item())
# Отмена задачи при остановке контейнера позволяет воркеру загрузить
# изменённые файлы памяти и удалить каталоги хранилища перед завершением.
loop = asyncio.get_running_loop()
for signum in (signal.SIGINT, signal.SIGTERM):
loop.add_signal_handler(signum, task.cancel)
with contextlib.suppress(asyncio.CancelledError):
await task
asyncio.run(main())Подготовка файлов для сеанса
Anthropic не монтирует файлы или репозитории GitHub в самостоятельно размещаемые песочницы. Чтобы сделать файлы, относящиеся к сеансу, доступными:
- Передайте ссылки на файлы, например путь S3 или SHA коммита, в поле
metadataсеанса. - В скрипте запуска или обработчике
--on-workполучите сеанс (GET /v1/sessions/{session_id}) и прочитайтеmetadata. Забранный элемент работы содержит идентификатор сеанса, но не метаданные. - Поместите файлы в рабочий каталог до запуска любого инструмента.
Пример cURL считывает токен доступа (access token) из ANTHROPIC_AUTH_TOKEN. Чтобы получить его, настройте Workload Identity Federation с областью действия (scope) по умолчанию workspace:developer, как описано в разделе Настройка федерации. Затем обменяйте токен идентификации (identity token) вашей рабочей нагрузки на токен доступа, как показано в разделе Аутентификация из вашей рабочей нагрузки. Задавайте ANTHROPIC_AUTH_TOKEN только в той оболочке, где запускаете пример cURL, поскольку эта переменная имеет приоритет над вашими настройками федерации. В разделе Аутентификация перечислены другие учётные данные, принимаемые API, например ключ API из краткого руководства.
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
metadata={"input_file": "s3://my-bucket/data.csv"},
)Дальнейшие шаги
Отслеживайте глубину очереди, корректно останавливайте сеансы и воркеры и устраняйте распространённые сбои.
Эта страница была полезной?