Claude Agent SDK отличается от традиционных API без сохранения состояния тем, что он поддерживает состояние беседы и выполняет команды в постоянной среде. Это руководство охватывает архитектуру, соображения по размещению и лучшие практики для развертывания агентов на основе SDK в производстве.

Требования к размещению

Изоляция на основе контейнеров

Для безопасности и изоляции SDK должен работать внутри изолированной среды контейнеров. Это обеспечивает:

• Изоляция процессов - отдельная среда выполнения для каждой сессии
• Ограничения ресурсов - ограничения на CPU, память и хранилище
• Контроль сети - ограничение исходящих соединений
• Эфемерные файловые системы - чистое состояние для каждой сессии

Системные требования

Каждый экземпляр SDK требует:

• Зависимости времени выполнения

  • Python 3.10+ (для Python SDK) или Node.js 18+ (для TypeScript SDK)
  • Node.js (требуется Claude Code CLI)
  • Claude Code CLI: npm install -g @anthropic-ai/claude-code

• Выделение ресурсов

  • Рекомендуется: 1 ГБ ОЗУ, 5 ГБ диска и 1 CPU (варьируйте в зависимости от вашей задачи)

• Сетевой доступ

  • Исходящий HTTPS к api.anthropic.com
  • Опционально: доступ к серверам MCP или внешним инструментам

Понимание архитектуры SDK

В отличие от безгосударственных вызовов API, Claude Agent SDK работает как долгоживущий процесс, который:

• Выполняет команды в постоянной среде оболочки
• Управляет файловыми операциями в рабочем каталоге
• Обрабатывает выполнение инструментов с контекстом из предыдущих взаимодействий

Варианты поставщиков песочниц

Несколько поставщиков специализируются на безопасных средах контейнеров для выполнения кода AI:

• Cloudflare Sandboxes
• Modal Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

Шаблоны развертывания в производстве

Шаблон 1: Эфемерные сессии

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

Лучше всего подходит для одноразовых задач, пользователь может по-прежнему взаимодействовать с AI во время выполнения задачи, но после завершения контейнер удаляется.

Примеры:

• Исследование и исправление ошибок: отладка и разрешение конкретной проблемы с соответствующим контекстом
• Обработка счетов: извлечение и структурирование данных из квитанций/счетов для систем бухгалтерского учета
• Задачи перевода: перевод документов или пакетов контента между языками
• Обработка изображений/видео: применение преобразований, оптимизаций или извлечение метаданных из медиафайлов

Шаблон 2: Долгоживущие сессии

Поддерживайте постоянные экземпляры контейнеров для долгоживущих задач. Часто внутри контейнера работают несколько процессов Claude Agent на основе спроса.

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

Примеры:

• Email Agent: отслеживает входящие письма и автономно сортирует, отвечает или предпринимает действия на основе содержания
• Site Builder: размещает пользовательские веб-сайты для каждого пользователя с возможностью редактирования в реальном времени, предоставляемые через порты контейнера
• Высокочастотные чат-боты: обрабатывают непрерывные потоки сообщений с платформ, таких как Slack, где критичны быстрые времена отклика

Шаблон 3: Гибридные сессии

Эфемерные контейнеры, которые заполняются историей и состоянием, возможно, из базы данных или из функций возобновления сессии SDK.

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

Примеры:

• Personal Project Manager: помогает управлять текущими проектами с периодическими проверками, поддерживает контекст задач, решений и прогресса
• Deep Research: проводит многочасовые исследовательские задачи, сохраняет результаты и возобновляет расследование при возвращении пользователя
• Customer Support Agent: обрабатывает билеты поддержки, охватывающие несколько взаимодействий, загружает историю билетов и контекст клиента

Шаблон 4: Одиночные контейнеры

Запустите несколько процессов Claude Agent SDK в одном глобальном контейнере.

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

Примеры:

• Симуляции: агенты, которые взаимодействуют друг с другом в симуляциях, таких как видеоигры.

Часто задаваемые вопросы

Как мне общаться со своими песочницами?

При размещении в контейнерах откройте порты для связи с экземплярами SDK. Ваше приложение может открывать конечные точки HTTP/WebSocket для внешних клиентов, пока SDK работает внутри контейнера.

Какова стоимость размещения контейнера?

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

Когда мне следует отключать неактивные контейнеры в сравнении с их сохранением в горячем состоянии?

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

Как часто мне следует обновлять Claude Code CLI?

Claude Code CLI версионируется с помощью semver, поэтому любые критические изменения будут версионированы.

Как мне отслеживать здоровье контейнера и производительность агента?

Поскольку контейнеры - это просто серверы, та же инфраструктура логирования, которую вы используете для бэкенда, будет работать для контейнеров.

Как долго может работать сессия агента перед истечением времени ожидания?

Сессия агента не будет истекать, но мы рекомендуем установить свойство 'maxTurns', чтобы предотвратить зацикливание Claude.

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

• Руководство по сессиям - узнайте об управлении сессиями
• Разрешения - настройте разрешения инструментов
• Отслеживание затрат - отслеживайте использование API
• Интеграция MCP - расширьте с помощью пользовательских инструментов