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

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

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

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

SDK также поддерживает программную конфигурацию песочницы для выполнения команд.

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

Каждый экземпляр 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 ЦП (варьируйте в зависимости от вашей задачи по мере необходимости)

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

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

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

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

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

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

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

• Modal Sandbox - демонстрационная реализация
• Cloudflare Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

Для самостоятельно размещаемых вариантов (Docker, gVisor, Firecracker) и подробной конфигурации изоляции см. Технологии изоляции.

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

Шаблон 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 в цикле.

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

• Безопасное развертывание - Сетевые элементы управления, управление учетными данными и усиление изоляции
• TypeScript SDK - Параметры песочницы - Программная конфигурация песочницы
• Руководство по сеансам - Узнайте об управлении сеансами
• Разрешения - Конфигурация разрешений инструментов
• Отслеживание затрат - Мониторинг использования API
• Интеграция MCP - Расширение с помощью пользовательских инструментов