Claude Platform Docs
Управляемые агентыСамостоятельно размещаемые песочницы

Развёртывание самостоятельно размещаемых воркеров

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

Быстрый старт по самостоятельно размещаемым песочницам запускает один воркер ant CLI, который непрерывно опрашивает очередь и выполняет каждую сессию в одном процессе. Эта страница поможет вам выбрать шаблон развёртывания, а затем описывает постоянно работающие воркеры и воркеры, запускаемые по вебхукам.

Выбор шаблона развёртывания

При развёртывании воркеров необходимо сделать два выбора: как воркер получает работу и где выполняется каждый сеанс.

Как воркер получает работу:

  • Постоянная работа («always-on»): долго работающий процесс непрерывно опрашивает очередь. Процесс выполняет только исходящие HTTPS-запросы, поэтому вам не нужно открывать конечную точку для Anthropic.
  • Запуск по вебхуку («webhook-triggered»): обработчик активируется по событию session.status_run_started и начинает опрос. Это позволяет избежать простаивающего опрашивающего процесса, но требует конечной точки вебхука, доступной для Anthropic.

Где выполняется каждый сеанс:

  • В процессе: воркер, получивший сеанс, сам выполняет его вызовы инструментов в одном общем рабочем каталоге.
  • Песочница на сеанс: опрашивающий процесс запускает новую песочницу для каждого полученного сеанса. Выбирайте этот вариант для более сильной изоляции: новая файловая система, ограничения ресурсов или сетевые ограничения для каждого сеанса. См. раздел Запуск отдельной песочницы для каждого сеанса, где также описан Helm-чарт для Kubernetes.

Воркеры CLI и SDK поддерживают разные комбинации:

ВозможностьCLI antSDK (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())

Запуск воркеров по вебхукам

  1. Подпишитесь на вебхуки сеансов

    В Claude Console определите конечную точку вебхука, которая прослушивает события session.status_run_started. Подробности см. в разделе Подписка на вебхуки.

  2. Экспортируйте ключ подписи вебхука

    Вместе с ID среды и ключом из раздела Запуск первого сеанса экспортируйте ключ подписи вебхука на хосте обработчика. Обработчик использует его для проверки входящих полезных данных.

    export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..."
  3. Реализуйте обработчик вебхука

    Запускайте воркер при срабатывании session.status_run_started. Обработчик опустошает очередь и передаёт каждый забранный элемент работы в handle_item() (в SDK для Python, TypeScript и Go). Этот метод загружает навыки, выполняет вызовы инструментов, отправляет результаты обратно и завершается.

    В примерах в качестве рабочего каталога используется /workspace. Перед запуском обработчика создайте этот каталог на хосте обработчика. Убедитесь, что пользователь обработчика может записывать в него, как в шаге «Запустите воркер» раздела Запуск первого сеанса.

    Чтобы проверять подписи вебхуков, установите дополнительный пакет 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.

Отслеживайте глубину очереди, корректно останавливайте сеансы и воркеры и устраняйте распространённые сбои.

Модель разделённой ответственности для самостоятельно размещаемых сред песочниц.

Доступность

Готовые самостоятельно размещаемые воркеры
Требования к доступности Готовые самостоятельно размещаемые воркеры одинаковы на всех поддерживаемых платформах.
Статус
Бета
API
  • Managed Agents
Бета-заголовок
Требуется
Модели
  • Все модели

Обработка данных

Обзор обработки данных

Применимые конечные точки

  • /v1/agents
  • /v1/sessions
  • /v1/environments
Нулевое хранение данныхНе допускается

Не подпадает под ZDR, за исключением самостоятельно размещаемых Managed Agents. Сессии — это ресурсы с состоянием; их расшифровки хранятся, пока вы их не удалите. Подробнее

HIPAAНе допускается

Не подпадает под HIPAA. Относится ко всем подфункциям Managed Agents.

Эта страница была полезной?