Песочница Claude Agent SDK: каждой задаче — свое рабочее пространство

Песочница Claude Agent SDK — это среда, в которой работают процесс агента SDK и его инструменты и находятся рабочие файлы. SDK запускает дочерний процесс Claude CLI. Отдельная ВМ или контейнер для этого процесса позволяет определить, к каким файлам и учетным данным он получит доступ и что произойдет после завершения задачи. Сам по себе выбор рабочего каталога не создает такой границы. Руководство Anthropic по хостингу

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

Мы разрабатываем Lizard. В этом руководстве мы используем Lizard Sandboxes для небольшого примера настройки и сравниваем варианты хостинга. Мы проверили API и команды 4 ноября 2026 года. Новый пример с SDK мы сверили с документацией; мы не запускали его с обращением к Anthropic в облачной песочнице.

Что должен предоставлять хост?

Agent SDK нужны среда выполнения, дочерний процесс CLI, рабочий каталог и доступ к сервису модели. Дочерний процесс также может запускать инструменты, которым нужно больше памяти, процессорных ресурсов и места на диске, чем самому SDK. Выбирайте размер рабочего пространства под задачу: чтение нескольких файлов отличается от сборки репозитория или управления браузером.

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

Выберите среду для хостинга

Lizard Sandboxes предоставляет микро-ВМ Firecracker с собственными ядрами, готовые шаблоны, выполнение команд и передачу файлов. Они подходят для задач на CPU, которым хватает ресурсов машин фиксированного размера. Lizard не предлагает песочницы с GPU или шаблоны песочниц на основе произвольных Dockerfile. Lizard Sandboxes

E2B предоставляет песочницы Linux, шаблоны и API для выполнения кода. Daytona предлагает инструменты для рабочих пространств и несколько классов сред выполнения. Modal поддерживает гибкое выделение ресурсов CPU и рабочие процессы с GPU с ограничениями, которые зависят от среды выполнения. Развертывание в Docker или Kubernetes дает контроль над собственной инфраструктурой, при этом вы отвечаете за ресурсы, изоляцию и очистку. E2B, Daytona, Modal

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

Начните с небольшой задачи SDK только для чтения

Этот пример читает локальный файл проекта и просит Claude кратко описать его. Агенту доступны только инструменты Read, Glob и Grep. Пример не требует неограниченного выполнения команд Bash или обхода разрешений.

Вам нужны проект Lizard и Lizard CLI, в котором вы вошли в систему, а также ключ API Anthropic для вызовов модели. Вычислительные ресурсы Lizard и использование Anthropic оплачиваются отдельно. Установите CLI по актуальной инструкции.

1. Создайте рабочее пространство Small

Подставьте идентификатор проекта, затем скопируйте полученный идентификатор песочницы в SB:

lizard sandbox create --project YOUR_PROJECT_ID \
  --template claude --size small --timeout 3600000 --json
SB=YOUR_SANDBOX_ID
lizard sandbox exec "$SB" -- mkdir -p /workspace/agent

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

2. Сохраните скрипт запуска SDK локально

Создайте summarize.mjs с таким кодом:

import { query } from '@anthropic-ai/claude-agent-sdk';

if (!process.env.ANTHROPIC_API_KEY) {
  throw new Error('Set ANTHROPIC_API_KEY inside the task environment');
}

let completed = false;
for await (const message of query({
  prompt: 'Read README.md and summarize the project in two sentences.',
  options: {
    cwd: '/workspace/agent',
    settingSources: [],
    tools: ['Read', 'Glob', 'Grep'],
    allowedTools: ['Read', 'Glob', 'Grep'],
    permissionMode: 'dontAsk',
    maxTurns: 6,
  },
})) {
  if (message.type !== 'result') continue;
  if (message.subtype !== 'success' || message.is_error) {
    throw new Error(`Agent failed: ${message.subtype}`);
  }
  completed = true;
  console.log(message.result);
}
if (!completed) throw new Error('Agent ended without a successful result');

tools задает доступные встроенные инструменты. allowedTools заранее разрешает вызовы; сам по себе этот параметр не задает полный список разрешенных инструментов. dontAsk отклоняет запросы без разрешения. Небольшой лимит ходов ограничивает цикл работы агента в этом примере; он не ограничивает общие расходы на облако. Справочник Agent SDK

Создайте небольшой README.md рядом со скриптом, затем загрузите оба файла:

lizard sandbox files put "$SB" ./summarize.mjs /workspace/agent/summarize.mjs
lizard sandbox files put "$SB" ./README.md /workspace/agent/README.md
lizard sandbox shell "$SB"

3. Установите зависимости и запустите скрипт в рабочем пространстве

В оболочке Bash песочницы:

cd /workspace/agent
npm init -y
npm install --save-exact @anthropic-ai/claude-agent-sdk
read -rsp 'Anthropic API key: ' ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY
node summarize.mjs
unset ANTHROPIC_API_KEY

Ожидаемый результат — краткое описание в stdout и нулевой код завершения. Отсутствие учетных данных, запрет операции или исчерпание лимита ходов должны привести к сбою запуска. Сохраните созданный lockfile и используйте npm ci, когда будете превращать пример в воспроизводимую среду.

Ввод ключа по запросу не сохраняет его в истории оболочки. При этом ключ остается в окружении агента, пока выполняется задача. Для сервиса, который выполняет недоверенные задачи, рассмотрите прокси-сервер исходящих запросов, который добавляет учетные данные за пределами песочницы. Аутентификация SDK и хостинг

4. Экспортируйте нужные данные, затем приостановите работу

Выйдите из оболочки песочницы и скачайте нужные файлы результатов через lizard sandbox files get. После сохранения результата:

lizard sandbox pause "$SB"

Убедитесь, что итоговый статус — paused. Успешная приостановка прекращает начисление платы за вычисления и сохраняет состояние рабочего пространства; хранилище Persistent Volumes оплачивается отдельно. Локальный диск в этом примере не становится долговечным хранилищем лишь потому, что его путь начинается с /workspace. Сохранение данных, Persistent Volumes

Подготовьте окружение скрипта к работе в продакшене

Создавайте запись задачи для каждого запроса до запуска агента. Храните владельца, идентификатор песочницы, статус, срок завершения и расположение результатов. Передавайте ход выполнения через координатор и сохраняйте итоговый результат независимо от соединения с клиентом.

Обрабатывайте отмену и очистку отдельно. Разрыв соединения с клиентом не обязательно должен отменять полезную работу; отмененная задача не должна оставлять незаметно работающую машину. Повторяйте очистку после временных сбоев и сверяйте записи задач с фактическим состоянием песочниц.

Для сеансов сохраняйте идентификатор сеанса, нужную запись диалога и состояние файлов. Строка в базе данных с одним лишь идентификатором не может восстановить отсутствующие файлы рабочего пространства. Anthropic описывает хранение сеансов отдельно от файлов рабочего каталога. Сеансы, состояние при хостинге

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

Сколько стоит рабочее пространство?

Lizard Small стоит $0.0162 за час работы. Сто часов работы в сумме стоят $1.62 за вычислительные ресурсы; для нового аккаунта Pro по-прежнему действует минимальная плата $19 в месяц, которая включает использование ресурсов на $19. Вызовам модели, Persistent Volumes и другим ресурсам нужен отдельный бюджет. Цены Lizard

Pro поддерживает 20 песочниц Small одновременно и 400 новых запусков в день; также действуют поминутные и почасовые лимиты запусков. Pro 5x стоит $99, включает использование ресурсов на $99 и поддерживает до 110 песочниц Small; Pro 20x стоит $499, включает использование ресурсов на $499 и поддерживает до 600. Большее число одновременных задач не означает, что каждая завершится с той же скоростью. Текущие лимиты

Измеряйте полное время работы, включая установку пакетов, ожидание модели и передачу результатов. Если вы приостанавливаете рабочее пространство между запросами, координатор должен оставаться вне него: приостановленный процесс не может получить запрос, который возобновит его работу.

Является ли рабочий каталог Claude Agent SDK песочницей? Нет. cwd выбирает каталог, в котором работает процесс. Используйте средства операционной системы, отдельный контейнер или ВМ, чтобы задать права доступа за пределами этого каталога.

Можно ли начать с Claude Code вместо разработки сервиса на SDK? Да. Для одной задачи по работе с кодом руководство по песочнице Claude Code показывает более короткий путь через CLI. Используйте SDK, когда вашему приложению нужно управлять сообщениями агента, правилами использования инструментов и поведением сеансов в коде.