Справочник по самостоятельно размещаемым воркерам
Справочник по самостоятельно размещаемым воркерам песочниц: флаги ant CLI, переменные окружения, требования к хосту, пути файловой системы и параметры вспомогательных функций SDK.
На этой странице описаны готовые воркеры, обслуживающие среду self_hosted. Для руководств, ориентированных на задачи, начните с разделов Самостоятельно размещаемые песочницы и Развёртывание самостоятельно размещаемых воркеров.
Команды и флаги CLI
| Команда | Описание |
|---|---|
ant beta:worker poll | Забирает элементы работы из очереди среды и выполняет каждый сеанс внутри процесса. С флагом --on-work вместо этого вызывает ваш скрипт для каждого элемента работы. |
ant beta:worker run | Обрабатывает один забранный сеанс и завершает работу. Используйте эту команду как точку входа песочницы, создаваемой для каждого сеанса. |
| Флаг | Описание |
|---|---|
--environment-id | Среда, из которой опрашивается работа. Также считывается из ANTHROPIC_ENVIRONMENT_ID. |
--environment-key | Аутентифицирует воркер в этой среде. Также считывается из ANTHROPIC_ENVIRONMENT_KEY. |
--workdir | Каталог, в который загружаются навыки и в котором инструменты читают и записывают файлы. По умолчанию . (текущий каталог). |
--on-work | Скрипт, вызываемый для каждого забранного элемента работы вместо выполнения инструментов внутри процесса. Получает сведения о сеансе в виде переменных окружения, а элемент работы — в формате JSON через стандартный ввод. |
--max-idle | Сколько ждать после перехода сеанса в состояние простоя с причиной остановки end_turn перед завершением работы. По умолчанию 60s. |
--log-format | Формат вывода журналов. Используйте json для приёма структурированных журналов. По умолчанию text. |
Переменные окружения
| Переменная | Описание | Кем задаётся |
|---|---|---|
ANTHROPIC_ENVIRONMENT_ID | Среда, очередь которой обслуживает воркер. | Вами, на хосте воркера. Опрашивающий процесс передаёт её скрипту --on-work. |
ANTHROPIC_ENVIRONMENT_KEY | Аутентифицирует воркер в его очереди. | Вами, на хосте воркера. Опрашивающий процесс передаёт её скрипту --on-work. |
ANTHROPIC_SESSION_ID | Сеанс, который представляет забранный элемент работы. | Опрашивающим процессом, для скрипта --on-work. |
ANTHROPIC_WORK_ID | Забранный элемент работы. | Опрашивающим процессом, для скрипта --on-work. |
ANTHROPIC_WORK_SECRET | Секрет элемента работы для конкретного сеанса. | Вами. Опрашивающий процесс её не задаёт. См. Передача секрета элемента работы. |
ANTHROPIC_BASE_URL | Переопределяет конечную точку API по умолчанию. Необязательна. | Вами, на хосте воркера. |
ANTHROPIC_WEBHOOK_SIGNING_KEY | Проверяет входящие полезные нагрузки вебхуков. | Вами, на хосте обработчика вебхуков. |
Требования к хосту
| Воркер | Требование |
|---|---|
| Все воркеры | Хост Linux с /bin/bash именно по этому пути. Инструмент bash воркера вызывает его напрямую, не обращаясь к PATH. |
| TypeScript SDK | unzip и tar в PATH, а также Node.js 22 или новее. |
| Python и Go SDK | Дополнительные исполняемые файлы не требуются. Эти SDK используют свои стандартные библиотеки для распаковки архивов. |
Хранилища памяти добавляют собственные требования.
Файловая система песочницы
| Путь | Содержимое |
|---|---|
/workspace | Системный рабочий каталог по умолчанию для выполнения инструментов и загрузки навыков. Если вы используете другой рабочий каталог, обновите системную подсказку вашего агента, чтобы Claude мог найти файлы навыков. |
<workdir>/skills/<name>/ | Загруженные навыки агента. |
/mnt/memory/<store>/ | По одному каталогу на каждое подключённое хранилище памяти, по пути mount_path хранилища (например, /mnt/memory/user-preferences/). Воркер создаёт эти каталоги, когда забирает сеанс, и удаляет их по завершении сеанса. |
В самостоятельно размещаемых средах системная подсказка сеанса не содержит инструкции /mnt/session/outputs, используемой в песочницах, управляемых Anthropic. Итоговые результаты оказываются там, куда агент записывает их в файловой системе вашей песочницы, обычно в рабочем каталоге.
Навыки могут включать исполняемые файлы, которые агент может запускать напрямую. Воркеры CLI и SDK сохраняют права на выполнение, записанные в пакете навыка, при его распаковке. Если вы реализуете загрузку навыков вручную, вы отвечаете за установку прав на выполнение.
Вспомогательные функции SDK
SDK для Python, TypeScript и Go предоставляют три вспомогательные функции с разным уровнем контроля:
| Вспомогательная функция | Что делает | Когда использовать |
|---|---|---|
EnvironmentWorker | Полностью обрабатывает опрос, настройку и выполнение. | В большинстве случаев. |
work.poller() | Опрашивает очередь работ и передаёт вам каждый забранный сеанс. | Вы сами определяете, что происходит для каждого сеанса, например запускаете песочницу вместо выполнения инструментов внутри процесса. |
client.beta.sessions.events.tool_runner() | Выполняет вызовы инструментов для одного сеанса по заданному ID сеанса и списку инструментов. | Вы уже забрали работу, и вам нужен только уровень выполнения. |
EnvironmentWorker
| Метод | Описание |
|---|---|
run() | Работает бесконечно, подхватывая сеансы по мере их поступления. |
handle_item() | Обрабатывает один забранный элемент работы и возвращает управление. Передайте идентификаторы работы, сеанса и среды, а также work_secret явно или позвольте методу считать переменные ANTHROPIC_*. |
| Параметр | Описание |
|---|---|
tools | Фабрика, которая получает AgentToolContext сеанса и возвращает список инструментов. По умолчанию используется стандартный набор инструментов агента. |
memory_sync_interval | Как часто подключённые хранилища памяти синхронизируются с сервером во время работы сеанса. См. Интервал синхронизации. |
memory_sync_deletions | Удаляются ли из хранилища файлы, которые агент удаляет локально. См. Удаления. |
EnvironmentWorker автоматически управляет AgentToolContext и набором инструментов. Передайте фабрику tools, чтобы настроить список инструментов:
EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])Опрашивающий процесс очереди работ
| Параметр | Описание |
|---|---|
drain | Прекращать ли опрос, когда очередь опустеет, вместо ожидания новой работы. |
block_ms | Сколько каждый опрос ждёт поступления работы перед возвратом, в миллисекундах. Значение должно быть от 1 до 999; вспомогательная функция автоматически повторяет опрос. Передайте None для неблокирующей проверки. По умолчанию используется длинный опрос длительностью 999 мс. |
reclaim_older_than_ms | Повторно забирает элементы работы, которые были забраны, но не подтверждены в течение указанного числа миллисекунд. |
auto_stop | Отправлять ли сигнал остановки для каждого элемента работы после того, как тело вашего цикла завершит его обработку. Установите значение False, если то, что выполняет элемент работы, само отправляет сигнал остановки. Так делает handle_item(), а также запускаемая вами песочница, которая сама отвечает за вызов остановки. |
Полный пример см. в разделе Запуск песочниц из опрашивающего процесса SDK.
Исполнитель инструментов сеанса
client.beta.sessions.events.tool_runner() принимает список инструментов в параметре tools. Чтобы построить этот список, самостоятельно настройте 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)AgentToolContext и набор инструментов агента
AgentToolContext — это контекст выполнения для вызовов инструментов. Он определяет рабочий каталог и политику путей, а также может загружать навыки сеанса.
| Параметр | Описание |
|---|---|
allowed_roots | Каталоги, помимо рабочего каталога, к которым могут обращаться файловые инструменты (read, write, edit, glob, grep). |
read_only_roots | Каталоги, пути внутри которых write и edit отклоняют. |
EnvironmentWorker сам добавляет каталоги хранилищ памяти сеанса в allowed_roots, а каталоги хранилищ, подключённых с access: "read_only", — в read_only_roots.
Это ограничение является защитной мерой только для файловых инструментов, а не песочницей. Оно не ограничивает bash.
beta_agent_toolset_20260401(env) принимает AgentToolContext и возвращает стандартные реализации инструментов (bash, read, write, edit, glob, grep).
Was this page helpful?