Развёртывание самостоятельно размещаемых воркеров
Выберите, как самостоятельно размещаемые воркеры песочниц получают работу и где выполняются сеансы, а затем запустите постоянно работающий воркер или запускайте воркеры по вебхукам.
Быстрый старт по самостоятельно размещаемым песочницам запускает один воркер ant CLI, который непрерывно опрашивает очередь и выполняет каждую сессию в одном процессе. Эта страница поможет вам выбрать шаблон развёртывания, а затем описывает постоянно работающие воркеры и воркеры, запускаемые по вебхукам.
Выбор шаблона развёртывания
При развёртывании воркеров необходимо сделать два выбора: как воркер получает работу и где выполняется каждый сеанс.
Как воркер получает работу:
- Постоянная работа («always-on»): долго работающий процесс непрерывно опрашивает очередь. Процесс выполняет только исходящие HTTPS-запросы, поэтому вам не нужно открывать конечную точку для Anthropic.
- Запуск по вебхуку («webhook-triggered»): обработчик активируется по событию
session.status_run_startedи начинает опрос. Это позволяет избежать простаивающего опрашивающего процесса, но требует конечной точки вебхука, доступной для Anthropic.
Где выполняется каждый сеанс:
- В процессе: воркер, получивший сеанс, сам выполняет его вызовы инструментов в одном общем рабочем каталоге.
- Песочница на сеанс: опрашивающий процесс запускает новую песочницу для каждого полученного сеанса. Выбирайте этот вариант для более сильной изоляции: новая файловая система, ограничения ресурсов или сетевые ограничения для каждого сеанса. См. раздел Запуск отдельной песочницы для каждого сеанса, где также описан Helm-чарт для Kubernetes.
Воркеры CLI и SDK поддерживают разные комбинации:
| Возможность | CLI ant | SDK (Python, TypeScript, Go) |
|---|---|---|
| Постоянный опрос | Да | Да |
| Запуск по вебхуку | Нет | Да |
| Песочница на сеанс | Да | Да |
| Хранилища памяти | Да, с настройками синхронизации по умолчанию | Да, с настраиваемой синхронизацией |
| Пользовательские инструменты | Нет | Да |
Все флаги CLI и параметры SDK описаны в справочнике по самостоятельно размещаемым воркерам.
Для большего контроля вызывайте конечные точки Environments Work напрямую и реализуйте собственный воркер. Тогда ваш воркер делает то же, что и воркеры SDK. Помимо прочего, он подтверждает каждый элемент работы, отправляет контрольные сигналы (heartbeat) и загружает навыки агента. Он выполняет только те вызовы инструментов, которые разрешает политика разрешений сеанса. Каждый результат он возвращает в виде события user.tool_result или user.custom_tool_result. В конце он останавливает элемент. В качестве образца используйте исходный код воркера в Python SDK, TypeScript SDK или Go SDK.
Запуск постоянно работающего воркера
В этих примерах в качестве рабочего каталога воркера используется /workspace. Каталог должен существовать до запуска воркера. На новом хосте создайте его и предоставьте пользователю воркера права на запись, как в шаге «Запустите воркер» раздела Запуск первого сеанса.
В macOS mkdir не может создать /workspace, поскольку корневой том доступен только для чтения. Вместо этого создайте ~/workspace, как показано в этом шаге. Вместо /workspace используйте полный путь, который выводит echo ~/workspace, поскольку SDK не раскрывает ~.
Запустите воркер, который непрерывно опрашивает очередь. Он проходит аутентификацию с помощью ключа среды из краткого руководства:
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker
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:
worker = EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
workdir="/workspace",
)
task = asyncio.create_task(worker.run())
# Отмена задачи вместо завершения процесса позволяет воркеру остановить
# текущий элемент работы и загрузить изменённые файлы памяти перед выходом.
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())Запуск воркеров по вебхукам
Подпишитесь на вебхуки сеансов
В Claude Console определите конечную точку вебхука, которая прослушивает события
session.status_run_started. Подробности см. в разделе Подписка на вебхуки.Экспортируйте ключ подписи вебхука
Вместе с ID среды и ключом из раздела Запуск первого сеанса экспортируйте ключ подписи вебхука на хосте обработчика. Обработчик использует его для проверки входящих полезных данных.
export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..."Реализуйте обработчик вебхука
Запускайте воркер при срабатывании
session.status_run_started. Обработчик опустошает очередь и передаёт каждый забранный элемент работы вhandle_item()(в SDK для Python, TypeScript и Go). Этот метод загружает навыки, выполняет вызовы инструментов, отправляет результаты обратно и завершается.В примерах в качестве рабочего каталога используется
/workspace. Перед запуском обработчика создайте этот каталог на хосте обработчика. Убедитесь, что пользователь обработчика может записывать в него, как в шаге «Запустите воркер» раздела Запуск первого сеанса.PythonЧтобы проверять подписи вебхуков, установите дополнительный пакет webhooks:
pip install "anthropic[webhooks]".import asyncio import os import anthropic import standardwebhooks # installed by the anthropic[webhooks] extra environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"] environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"] client = anthropic.AsyncAnthropic( auth_token=environment_key, ) # Отменяется через shutdown(), чтобы выполняемый элемент работы мог выгрузить изменённые файлы памяти и # удалить свои каталоги хранилища до завершения процесса. inflight: set[asyncio.Task[None]] = set() # Ожидайте это в хуке завершения работы хоста, например в завершении lifespan ASGI (код после # `yield` в lifespan FastAPI), который uvicorn запускает по SIGTERM. uvicorn даёт открытым запросам # завершиться до запуска этого хука, поэтому задайте --timeout-graceful-shutdown, чтобы ограничить ожидание. async def shutdown() -> None: for task in inflight: task.cancel() await asyncio.gather(*inflight, return_exceptions=True) async def handle(raw: bytes, headers: dict[str, str]) -> tuple[dict[str, str], int]: try: event = client.beta.webhooks.unwrap(raw.decode(), headers=headers) except standardwebhooks.WebhookVerificationError: return {"error": "signature verification failed"}, 401 if event.data.type != "session.status_run_started": return {"status": "ignored"}, 200 task = asyncio.create_task(run_queued_work()) inflight.add(task) task.add_done_callback(inflight.discard) try: # Защищено: разорванная или просроченная доставка не должна отменять элемент; это делает shutdown(). await asyncio.shield(task) except asyncio.CancelledError: return {"status": "shutting down"}, 503 return {"status": "ok"}, 200 async def run_queued_work() -> None: async for work in client.beta.environments.work.poller( environment_id=environment_id, environment_key=environment_key, block_ms=None, reclaim_older_than_ms=2000, drain=True, auto_stop=False, ): await client.beta.environments.work.worker(workdir="/workspace").handle_item( work_id=work.id, environment_id=environment_id, session_id=work.data.id, environment_key=environment_key, # Секрет сеанса позволяет воркеру монтировать хранилища памяти сеанса. work_secret=work.secret, )В SDK для Python, TypeScript и Go методу
handle_item()нужен секрет элемента работы для монтирования хранилищ памяти. У воркера, который опрашивает очередь с помощьюrun(), секрет уже есть. Этот обработчик сам забирает каждый элемент, поэтому передаёт секрет в аргументеwork_secret. См. раздел Передача секрета элемента работы.
Этот обработчик выполняет каждый полученный элемент в одном процессе и одновременно выполняет элементы из разных доставок вебхуков. Эти сеансы используют одну общую файловую систему, включая /workspace и /mnt/memory. Если ваши сеансы подключают одно и то же хранилище памяти, см. раздел Изоляция сеансов, использующих общее хранилище.
Следующие шаги
Запускайте песочницы с помощью Helm-чарта в Kubernetes, скрипта запуска или опрашивающего процесса SDK.
Отслеживайте глубину очереди, корректно останавливайте сеансы и воркеры и устраняйте распространённые сбои.
Модель разделённой ответственности для самостоятельно размещаемых сред песочниц.
Доступность
Claude API
- Статус
- Бета
- API
- Managed Agents
- Бета-заголовок
- Требуется
- Модели
- Все модели
Claude Platform on AWS
- Статус
- Бета
- API
- Managed Agents
- Бета-заголовок
- Требуется
- Модели
- Все модели
Обработка данных
Обзор обработки данныхПрименимые конечные точки
/v1/agents/v1/sessions/v1/environments
Не подпадает под ZDR, за исключением самостоятельно размещаемых Managed Agents. Сессии — это ресурсы с состоянием; их расшифровки хранятся, пока вы их не удалите. Подробнее
Не подпадает под HIPAA. Относится ко всем подфункциям Managed Agents.
Эта страница была полезной?