Начало работы с самостоятельно размещаемым Claude Managed Agents

В этом кратком руководстве вы запускаете самостоятельно размещаемый Claude Managed Agents на одной машине с помощью Docker Compose. Стек Compose состоит из сервера, его базы данных PostgreSQL и набора «workers» (воркеров), которые запускают каждый сеанс в отдельном «sandbox container» (контейнере песочницы), принадлежащем только этому сеансу. Затем вы общаетесь с агентом из терминала и убеждаетесь, что его вызовы инструментов выполнялись в контейнере песочницы. После этого вы можете открыть сеанс в консоли на вашем сервере.

Для промышленной эксплуатации Anthropic рекомендует два Helm-чарта из выпуска. См. Развёртывание в Kubernetes.

Предварительные требования

• Архив выпуска: Чтобы запросить доступ к загрузке, обратитесь к команде по работе с вашим аккаунтом в Anthropic.
• Ключ Claude API: сервер использует его для вызовов модели. Создайте его в Claude Console.
• Docker: последняя версия Docker Engine с плагином Compose (docker compose, а не старый docker-compose).
• Хост как минимум с двумя CPU: x86-64 или Arm. На хосте меньшего размера при создании .env задайте для CMA_SANDBOX_CPUS число его CPU.
• Сетевой доступ при первом запуске: первая сборка загружает данные из Docker Hub, репозиториев пакетов Alpine и релизов GitHub.
• Инструменты: на машине, где вы запускаете Docker, нужны openssl и CLI ant.

Запуск стека

1. 1

   Распакуйте архив

   Распакуйте архив и работайте из его каталога compose. В команде замените <archive> именем вашего архива без .tar.gz.

   tar -xzf <archive>.tar.gz && cd <archive>/compose

   

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

2. 2

   Создайте файл .env

   Compose считывает секреты стека из файла .env, расположенного рядом с docker-compose.yml. Создайте файл:

   cat > .env <<EOF
   CMA_PG_PASSWORD=$(openssl rand -hex 32)
   ANTHROPIC_API_KEY=sk-ant-...
   CMA_SERVER__API_KEY=$(openssl rand -hex 32)
   CMA_STORE__CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
   EOF
   chmod 600 .env

   

   Откройте .env в редакторе и замените sk-ant-... своим ключом Claude API. Остальное генерирует этот блок: пароль базы данных, ключ API сервера, который отправляют ваши приложения, и ключ, которым шифруются секреты, хранящиеся на сервере.

3. 3

   Запустите контейнеры

   Соберите и запустите стек, а затем следите за журналом сервера:

   docker compose up --build -d
   docker compose logs -f cma-server

   

   Когда в журнале появится строка с msg="cma-server listening", нажмите Ctrl+C, чтобы прекратить его просмотр.

4. 4

   Убедитесь, что сервер готов

   curl -s http://127.0.0.1:8400/cma-server/readyz

   

   Готовый сервер отвечает "status":"ready". Сразу после запуска он может в течение нескольких секунд отвечать "status":"degraded", пока выполняются его первые проверки. Если статус остаётся degraded или сервер отвечает "status":"not_ready", см. Устранение неполадок.

Запуск первого сеанса

Создайте агента и общайтесь с ним из терминала с помощью CLI ant.

1. 1

   Направьте CLI на ваш сервер

   Откройте второй терминал в том же каталоге и используйте его для ant. Следующие команды задают для ANTHROPIC_API_KEY ключ API вашего сервера, а не ваш ключ Claude API, как описано в разделе Вызов API на самостоятельно размещаемом сервере:

   export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
   export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)

   

   Выполняйте команды docker compose в первом терминале. Если вы выполните docker compose up в этом терминале, Compose передаст эти переменные серверу, и сервер будет вызывать сам себя вместо Claude API.

2. 2

   Создайте агента

   Сохраните файл, приведённый после команды, как quickstart-agent.md, а затем выполните команду. Этот файл даёт агенту встроенные инструменты и позволяет ему запускать их, не спрашивая вас заранее.

   CLI

   

   ant apply --yes quickstart-agent.md

   quickstart-agent.md

   

   ---
   name: Quickstart agent
   model: claude-opus-5-5
   tools:
     - type: agent_toolset_20260401
   ---
   
   You are a helpful assistant.

   Сначала команда выводит предупреждение о том, что ей could not determine the organization and workspace, с ошибкой 404, а затем создаёт агента. На вашем собственном сервере это ожидаемо.

3. 3

   Запустите сеанс

   Эти команды находят агента и окружение стека, запускают сеанс и сохраняют идентификатор сеанса в SESSION_ID. Стек присваивает своему окружению имя compose-sandbox.

   AGENT_ID=$(ant beta:agents list --format raw \
     --transform 'data.#(name=="Quickstart agent").id' --raw-output)
   ENVIRONMENT_ID=$(ant beta:environments list --format raw \
     --transform 'data.#(name=="compose-sandbox").id' --raw-output)
   SESSION_ID=$(ant beta:sessions create --agent "$AGENT_ID" \
     --environment-id "$ENVIRONMENT_ID" --transform id --raw-output)

   
4. 4

   Попросите агента выполнить команду

   Подключите терминал к сеансу:

   ant beta:sessions connect "$SESSION_ID"

   

   Команда открывает представление чата для сеанса. Отправьте это сообщение:

   Run `hostname` with the bash tool and tell me the output.

   

   Агент отвечает именем хоста, начинающимся с cma-sandbox-. Это имя контейнера песочницы, в котором была выполнена команда, что подтверждает: инструмент работал в песочнице, а не на вашей машине.

5. 5

   Найдите контейнер песочницы

   Не закрывайте чат. В первом терминале выведите список контейнеров песочницы:

   docker ps --filter label=cma-server.sandbox

   

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

   Чтобы выйти из чата, нажмите Ctrl+C в его терминале. Сеанс продолжит работать.

Опробуйте консоль на вашем сервере

Этот раздел необязателен. Для консоли требуется единый вход. Чтобы опробовать её, перезапустите стек с фиктивным поставщиком входа из выпуска. Порт 8080 на вашей машине должен быть свободен.

1. 1

   Перезапустите стек с фиктивным поставщиком входа

   Выполните эти команды в первом терминале:

   export COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml
   docker compose up --build -d

   

   Строка export действует только в первом терминале, поэтому выполняйте её заново в любом новом терминале, который вы открываете для docker compose. Чтобы изменить настройки сервера в этом стеке, отредактируйте compose.config.oidc.yaml, а не compose.config.yaml, а затем выполните docker compose restart cma-server.

2. 2

   Откройте сеанс

   В браузере на той же машине откройте http://127.0.0.1:8400/, нажмите Continue with SSO и выберите alice — демонстрационного администратора. На боковой панели выберите Sessions, а затем выберите сеанс.

   Страница обновляется по мере работы агента, и с неё можно отправить агенту сообщение.

Чтобы также создавать агентов и запускать сеансы в консоли, см. Запуск агента из консоли.

Остановка стека

В первом терминале выполните эту команду:

docker compose down --remove-orphans

Команда удаляет контейнеры и сохраняет базу данных. Чтобы удалить также базу данных со всеми агентами, сеансами и историей сеансов в ней, выполните docker compose down --remove-orphans -v.

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

• В вашем архиве нет каталога compose: архив содержит более ранний выпуск, и команды на этой странице ему не соответствуют. Чтобы получить текущий выпуск, обратитесь к команде по работе с вашим аккаунтом в Anthropic. Чтобы перевести работающее развёртывание на текущий выпуск, см. Обновление самостоятельно размещаемого Claude Managed Agents.
• Сервер так и не запускается: выполните docker compose logs migrate. Одноразовый контейнер migrate создаёт таблицы базы данных. Он должен завершиться со статусом 0 до запуска сервера.
• Проверка готовности остаётся в статусе degraded или каждый ход завершается ошибкой: если вы выполнили docker compose up в терминале, где ANTHROPIC_BASE_URL имеет значение http://127.0.0.1:8400, сервер вызывает сам себя вместо Claude API. Снова выполните docker compose up -d в первом терминале, где эта переменная не задана. В противном случае причина сбоя указана в журнале сервера. Чтобы прочитать его, снова выполните docker compose logs -f cma-server.
• Проверка готовности отвечает not_ready: найдите в ответе проверку с состоянием failed:
  • upstream: Claude API отклонил ваш ключ Claude API. Исправьте ANTHROPIC_API_KEY в .env, а затем в первом терминале снова выполните docker compose up -d. Если ваша оболочка тоже задаёт ANTHROPIC_API_KEY, Compose использует значение из оболочки, поэтому сначала выполните unset ANTHROPIC_API_KEY.
  • database: либо база данных отклонила вход сервера, например из-за неверного пароля, либо оборвалось открытое соединение с базой данных. Чтобы выяснить, что именно произошло, снова выполните docker compose logs -f cma-server.
• Агент отвечает, но его вызов инструмента так и не завершается: ни один воркер не опрашивает окружение. Проверьте журнал воркеров с помощью docker compose logs sandbox. Воркер, который не может подключиться к сокету демона Docker, завершает работу с сообщением, в котором упоминается CMA_DOCKER_SOCKET. Задайте в .env для этой переменной путь к сокету вашего демона, а затем в первом терминале снова выполните docker compose up -d.
• Воркеры работают, но вызов инструмента всё равно так и не завершается: стек запускает 10 воркеров, и каждый из них одновременно выполняет контейнер только одного сеанса. Сеанс занимает свободный воркер при создании, а сеанс, который так и не получает сообщения, удерживает свой воркер до часа. Когда заняты все 10, вызовы инструментов любого другого сеанса ждут воркера. Если команда docker ps на шаге «Найдите контейнер песочницы» выводит 10 контейнеров, архивируйте сеансы, которые вы не используете:
  1. В первом терминале выполните docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}'. Она выводит идентификатор сеанса, которому принадлежит каждый контейнер. У ожидающего сеанса ещё нет контейнера, поэтому его нет в списке.
  2. Во втором терминале нажмите Ctrl+C, чтобы выйти из чата, и выполните ant beta:sessions archive --session-id <session-id> для каждого сеанса из списка, который вы не используете.
  3. Снова выполните ant beta:sessions connect "$SESSION_ID". Вызов инструмента завершится, когда воркер возьмёт его сеанс.

Следующие шаги