Размещение Agent SDK

​

Модель подпроцесса

query({ prompt, options: { cwd: "/work/session-a" } })

​

Состояние, которое находится на локальном диске

​

Выберите паттерн сессии

​

Ephemeral sessions

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

const prompt = process.env.TASK_PROMPT!;
for await (const message of query({ prompt, options: { maxTurns: 20 } })) {
  console.log(message);
}

​

Long-running sessions

​

Hybrid sessions

import { query, type SessionStore } from "@anthropic-ai/claude-agent-sdk";

declare const userInput: string;
declare const sessionId: string;          // looked up from your database by user
declare const sessionStore: SessionStore; // S3, Redis, Postgres, or your own adapter

for await (const message of query({
  prompt: userInput,
  options: { resume: sessionId, sessionStore },
})) {
  // ...
}

​

Multi-agent container

​

Подготовка контейнера

​

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

• Кто управляет sandbox: поставщик sandbox-as-a-service управляет инфраструктурой для вас, в то время как самостоятельно размещаемые варианты предоставляют вам программное обеспечение для запуска на собственной инфраструктуре.
• Задержка холодного старта: время от “создания sandbox” до “готовности принять первый запрос”. Эфемерные паттерны требуют запусков менее чем за секунду. Долгоживущие паттерны допускают большую задержку.
• Постоянное хранилище: предоставляет ли поставщик долговечные тома или только эфемерный диск. Гибридный паттерн требует долговечного хранилища где-то, будь то в sandbox или рядом с ним.
• Модель ценообразования: оплата за секунду, за запрос или фиксированная почасовая оплата. Ценообразование за секунду подходит для нестабильных эфемерных рабочих нагрузок. Почасовая оплата подходит для долгоживущих сеансов.
• Сетевые возможности: поддержка пользовательских правил исходящего трафика, исходящих прокси и приватного VPC peering для регулируемых сред.

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

​

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

• Python 3.10+ для Python SDK или Node.js 18+ для TypeScript SDK
• Оба пакета SDK включают встроенный бинарный файл Claude Code для платформы хоста, поэтому отдельная установка Claude Code или Node.js не требуется для порожденного CLI

​

Ресурсы

​

Сеть

​

Решение производственных проблем

​

Сохранение сеанса и состояния

• Только стенограммы: SessionStore зеркалирует стенограммы, а не файлы памяти CLAUDE.md или другие артефакты рабочего каталога. Смонтируйте общий том или синхронизируйте их отдельно.
• Зеркалирование, а не замена: подпроцесс сначала записывает на локальный диск, а хранилище получает копию каждого пакета. Локальные записи остаются авторитетными.
• Сообщения mirror_error: если хранилище отклоняет или истекает время ожидания, SDK выдает сообщение { type: "system", subtype: "mirror_error" } и продолжает запрос без повтора. Оповещайте об этих сообщениях, если долговечность хранилища имеет значение.

​

Наблюдаемость

CLAUDE_CODE_ENABLE_TELEMETRY=1
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318

​

Аутентификация и секреты

• Anthropic API: подпроцесс читает ANTHROPIC_API_KEY из своего окружения. Предоставьте его из вашего менеджера секретов или установите ANTHROPIC_BASE_URL для маршрутизации вызовов модели через прокси, который внедряет ключ вне контейнера. См. Управление учетными данными для шаблона прокси и Обзор SDK для поддерживаемых методов аутентификации.
• Входящие: поместите аутентификацию на шлюз перед контейнером агента. Агент должен получать предварительно аутентифицированные запросы и не должен быть компонентом, который проверяет токены пользователя.
• Исходящие инструменты: держите учетные данные инструмента вне окружения агента. Маршрутизируйте исходящие вызовы через прокси, который внедряет ключи API после того, как запрос покидает контейнер. Агент делает вызов; прокси добавляет учетные данные.

​

Масштабирование и параллелизм

agents per host = (host RAM - overhead) / (per-session RAM ceiling)

​

Стоимость

​

Изоляция мультитенантности

• Передайте settingSources: [] в TypeScript или setting_sources=[] в Python, чтобы не загружались параметры файловой системы.
• Установите CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 в env. Автоматическая память в ~/.claude/projects/<project>/memory/ загружается в системную подсказку независимо от settingSources. См. Что settingSources не контролирует для других входных данных, которые загружаются безусловно.
• Укажите CLAUDE_CONFIG_DIR на каталог для каждого арендатора, чтобы арендаторы не делили глобальный конфиг ~/.claude.json.
• Используйте рабочий каталог для каждого арендатора. Передайте cwd явно при каждом вызове query().
• Применяйте правила исходящего трафика для каждого арендатора на вашем прокси, такие как различные исходящие IP-адреса, учетные данные или списки разрешенных доменов, чтобы скомпрометированный арендатор не мог экспортировать данные через политику исходящего трафика другого арендатора.

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

declare const prompt: string;
declare const tenantDir: string;
declare const configDir: string;

for await (const message of query({
  prompt,
  options: {
    cwd: tenantDir,
    settingSources: [],
    env: {
      ...process.env,
      CLAUDE_CONFIG_DIR: configDir,
      CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
    },
  },
})) {
  // ...
}

​

Известные ограничения

​

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

• Hosting cookbook: пошаговое руководство в виде notebook с развертываемым кодом для Docker, Modal и Kubernetes.
• Session storage: сохранение транскриптов между хостами с помощью адаптера SessionStore.
• Observability: экспорт OTEL трассировок, метрик и логов в ваш сборщик.
• Secure deployment: сетевые элементы управления, управление учетными данными и усиление изоляции.
• Cost tracking: учет токенов и затрат для каждого сеанса.