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

Мониторинг и устранение неполадок самостоятельно размещаемых воркеров

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

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

Чтение глубины очереди

client.beta.environments.work.stats() возвращает состояние очереди для среды:

ПолеЗначениеДля чего использовать
depthЭлементы, ожидающие получения.Масштабирование парка воркеров или оповещение о накоплении задач.
pendingЭлементы, полученные воркером, но ещё не подтверждённые. Вспомогательные средства воркера подтверждают каждый элемент перед его обработкой, поэтому при нормальной работе это значение остаётся близким к нулю.Обнаружение воркера, зависшего между получением и подтверждением: настройте оповещение на устойчивое ненулевое значение.
oldest_queued_atВременная метка самого старого элемента, всё ещё находящегося в очереди: ожидающего получения либо полученного, но ещё не подтверждённого. None, если такого элемента нет.Узнать, как долго ждёт самый старый элемент.
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
}

Корректная остановка сеанса

Используйте client.beta.environments.work.stop(), чтобы попросить воркер, обрабатывающий конкретный сеанс, завершить его.

По умолчанию элемент работы переходит в состояние stopping. Воркер обнаруживает это при следующем «lease heartbeat» (контрольном сигнале аренды), отменяет выполняющийся вызов инструмента сеанса и подтверждает завершение. После этого элемент работы переходит в состояние stopped. Воркер на Python SDK вместо этого сначала позволяет выполняющемуся вызову инструмента завершиться, что может занять до 2,5 минуты.

Передайте force=True, чтобы немедленно пометить элемент работы как stopped, не дожидаясь подтверждения от воркера. Принудительная остановка не завершает выполняющийся вызов инструмента быстрее, поскольку воркер всё равно замечает остановку при следующем heartbeat-сигнале.

Поскольку эти вызовы выполняются из ваших инструментов эксплуатации, а не на хосте воркера, ANTHROPIC_WORK_ID не устанавливается автоматически. Перед запуском следующих примеров задайте в этой переменной ID целевого элемента работы. Чтобы найти ID элемента работы, вызовите конечную точку Список рабочих элементовДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. с ключом среды, переданным как Authorization: Bearer $ANTHROPIC_ENVIRONMENT_KEY. Эта конечная точка отклоняет ключ API вашей организации.

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)

Корректная остановка воркеров

Воркер, отменённый во время выполнения сеанса, завершает этот сеанс перед выходом — так же, как при остановке сеанса. Если к сеансу подключены хранилища памяти, воркер всё равно загружает новые и изменённые файлы и удаляет каталоги хранилищ. Он не отправляет удаления, поэтому запись памяти, удалённая агентом, остаётся в хранилище, если только одна из предыдущих синхронизаций уже не удалила её из хранилища.

Процесс, который завершается принудительно, не выполняет никакой очистки. Чтобы корректно остановить воркер:

  1. Убедитесь, что SIGTERM и SIGINT отменяют воркер. Способ зависит от воркера:

    ВоркерЧто сделать
    CLI antНичего. CLI сам обрабатывает оба сигнала: он отменяет выполняющийся вызов инструмента, отправляет результат с ошибкой и помечает элемент работы как stopped.
    Воркер SDK, работающий как отдельный процессEnvironmentWorker не устанавливает обработчики сигналов. Отменяйте воркер из обработчика сигнала, как это сделано в примерах автономных воркеров.
    Воркер SDK внутри сервера вебхуковОтменяйте воркер из собственного хука завершения сервера, как это сделано в примерах с вебхуками. Воркер не должен перехватывать сигналы сервера.
  2. Останавливайте воркер сигналом SIGTERM и дайте ему время завершить работу до любого принудительного завершения. Воркеру нужно время, чтобы завершить выполняющийся вызов инструмента и выгрузить изменённые файлы в хранилище памяти. По умолчанию Docker отправляет SIGKILL через 10 секунд после сигнала остановки. Увеличьте этот лимит с помощью --stop-timeout 210 в docker run или задайте для периода ожидания завершения (termination grace period) вашего оркестратора такое же количество секунд.

Если воркер принудительно завершается до выполнения очистки, все несинхронизированные изменения памяти теряются. На долгоживущем хосте также удалите оставшийся каталог хранилища в /mnt/memory/ перед следующим сеансом, который подключает это хранилище. Песочница, которая обслуживает один сеанс и затем удаляется, не требует очистки.

Устранение неполадок

Воркер не подключается

Если workers_polling остаётся равным 0, воркер не достигает очереди. Убедитесь, что ANTHROPIC_ENVIRONMENT_KEY и ANTHROPIC_ENVIRONMENT_ID установлены на хосте воркера.

Сеанс остаётся в очереди

Ни один воркер не получает работу. Сеанс в очереди ожидает, а не завершается с ошибкой. Проверьте workers_polling и depth в разделе Чтение глубины очереди.

Хранилища памяти не монтируются или не синхронизируются

То, где проявляется сбой хранилища памяти, зависит от его типа:

  • Сбой монтирования: если воркер не может смонтировать хранилище памяти при получении сеанса, он записывает сбой в журнал и завершает элемент работы с ошибкой. Сеанс не генерирует событие ошибки и остаётся в состоянии простоя.
  • Сбой синхронизации: воркер записывает сбой в журнал и не сообщает о нём сеансу.
  • Отклонённая запись в хранилище только для чтения: агент получает ошибку инструмента. См. Хранилища только для чтения и конфликты.
СимптомПричинаРешение
Журнал воркера содержит the work item carried no sessions token (в Go — ошибка ErrSessionMemoryNoToken), и элемент работы завершается с ошибкой.secret элемента работы для конкретного сеанса не дошёл до воркера. Либо ваш код не передал его, либо хранилища памяти в самостоятельно размещаемых песочницах не включены для вашей организации.Передайте секрет элемента работы. Если воркер опрашивает очередь и выполняет сеансы в одном процессе и всё равно записывает это в журнал, обратитесь в службу поддержки.
Журнал воркера содержит something already exists at the memory store's path.Этот путь используется другим сеансом в той же файловой системе. Либо воркер предыдущего сеанса был принудительно завершён до выполнения очистки, и каталог остался.Проверьте, выполняет ли какой-либо воркер всё ещё сеанс, использующий этот путь. Если да, не удаляйте каталог: воркер удалит его, когда закончит работу с сеансом. Если нет, удалите каталог, указанный в строке журнала. Несинхронизированные изменения в нём теряются. Чтобы запустить два таких сеанса одновременно, см. Изоляция сеансов, использующих общее хранилище.
Журнал воркера содержит cannot create the memory store's folder и the worker host must make this mount path writable.Пользователь, от имени которого работает воркер, не может создавать каталоги в /mnt/memory.Создайте /mnt/memory и выполните для него chown на этого пользователя. См. Подготовка хоста. В macOS вместо этого следуйте инструкциям из раздела Подготовка хоста macOS.
Сеанс находится в состоянии idle с причиной остановки requires_action и без события ошибки вскоре после того, как воркер его получил.Воркер завершил элемент работы с ошибкой, поскольку не смог смонтировать хранилище памяти по одной из указанных выше причин.Устраните причину на хосте, затем отправьте событие user.interrupt. Работа сеанса снова ставится в очередь, и следующий воркер, который её получит, повторит попытку монтирования.

Вызов пользовательского инструмента не возвращает результат

Если сеанс приостановлен с причиной остановки requires_action, ни один воркер или клиент не обслуживает этот инструмент. См. Предоставление пользовательского инструмента.

Вызов обёрнутого инструмента MCP зависает

Без тайм-аута на клиенте MCP зависший вызов к обёрнутому серверу MCP превращается в результат инструмента с ошибкой только при срабатывании страховочного механизма:

SDKСтраховочный механизмСрабатывает через
PythonСобственный лимит воркера на вызов инструментаОколо 2,5 минуты
TypeScriptТайм-аут запроса по умолчанию в MCP SDKОколо минуты
GoВоркер отменяет вызов инструмента, превысивший лимит по умолчанию120 секунд

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