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

​

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

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

for await (const message of query({
  prompt: "Summarize the files in this directory",
  options: { cwd: "/work/session-a" },
})) {
  console.log(message);
}

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt="Summarize the files in this directory",
        options=ClaudeAgentOptions(cwd="/work/session-a"),
    ):
        print(message)


asyncio.run(main())

​

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

​

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

​

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);
}

import asyncio
import os

from claude_agent_sdk import ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt=os.environ["TASK_PROMPT"],
        options=ClaudeAgentOptions(max_turns=20),
    ):
        print(message)


asyncio.run(main())

​

Long-running sessions

• TypeScript: используйте streamInput() для добавления ходов к активному сеансу. Вызовите startup() для предварительного прогрева подпроцессов перед входящим трафиком. Если вы не знаете рабочий каталог сеанса до поступления его первого запроса, предварительно прогрейте с помощью prewarm() вместо этого.
• Python: используйте ClaudeSDKClient для сохранения сеанса открытым между ходами.

​

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; // an object store, key-value store, database, or your own adapter

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

from claude_agent_sdk import query, ClaudeAgentOptions, SessionStore
import asyncio

user_input: str = ...
session_id: str = ...              # looked up from your database by user
session_store: SessionStore = ...  # an object store, key-value store, database, or your own adapter


async def main():
    async for message in query(
        prompt=user_input,
        options=ClaudeAgentOptions(
            resume=session_id,
            session_store=session_store,
        ),
    ):
        ...


asyncio.run(main())

​

Multi-agent container

​

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

​

Контейнеризованная изоляция

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

​

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

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

​

Ресурсы

​

Сеть

​

Решение проблем в production

​

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

• Только транскрипты: SessionStore зеркалирует транскрипты, а не файлы памяти CLAUDE.md или другие артефакты рабочего каталога. Подключите общий том или синхронизируйте их отдельно.
• Зеркалирование, а не замена: подпроцесс сначала записывает на локальный диск, а SDK пересылает копию каждого пакета в хранилище. Транскрипт нового сеанса на локальном диске пережидает запуск; сеанс, возобновленный из хранилища, удаляет его локальную копию в конце, поэтому хранилище содержит единственную долговечную копию. См. Архитектура двойной записи.
• Сообщения 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. Когда каждый каталог конфигурации обслуживает один рабочий каталог и вы не передаете SessionStore, вы также можете установить CLAUDE_CODE_PROJECT_DIR_NAME в env, чтобы сохранить пути транскрипта под ним короткими. Требуется TypeScript Agent SDK v0.3.234 или позже, или Python Agent SDK v0.2.140 или позже.
• Используйте рабочий каталог для каждого арендатора. Передайте 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",
    },
  },
})) {
  // ...
}

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio

prompt: str = ...
tenant_dir: str = ...
config_dir: str = ...


async def main():
    async for message in query(
        prompt=prompt,
        options=ClaudeAgentOptions(
            cwd=tenant_dir,
            setting_sources=[],
            env={
                "CLAUDE_CONFIG_DIR": config_dir,
                "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1",
            },
        ),
    ):
        ...


asyncio.run(main())

​

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

​

Устранение неполадок развертывания

• CLI не найден при запуске сервиса: в Python контейнер или менеджер сервисов запускает ваше приложение с другим PATH, чем ваша оболочка, поэтому установка, которая работает локально, не видна процессу. В TypeScript сборка образа пропустила дополнительные зависимости SDK, или pathToClaudeCodeExecutable указывает на файл, который не существует в образе. См. Claude Code not found.
• CLI есть в образе, но не запускается: Claude Code не может запуститься из двоичного файла, который не соответствует архитектуре контейнера или libc, или из файла, который потерял разрешение на выполнение при сборке образа. См. Failed to start Claude Code.
• Процесс Claude Code завершается посреди выполнения: ошибка, которую получает ваше приложение, зависит от языка SDK и от того, сообщил ли CLI перед этим о результате с ошибкой. Записи в разделе Выход процесса CLI охватывают каждое сообщение.

​

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

• Cookbook по хостингу: пошаговое руководство в виде notebook с развертываемым кодом для Docker, Modal и Kubernetes.
• Хранилище сеанса: сохранение транскриптов между хостами с помощью адаптера SessionStore.
• Наблюдаемость: экспорт OTEL трассировок, метрик и логов в ваш сборщик.
• Безопасное развертывание: сетевые элементы управления, управление учетными данными и усиление изоляции.
• Отслеживание затрат: учет токенов и затрат для каждого сеанса.