Agent SDK のホスティング

​

サブプロセスモデル

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

​

ローカルディスク上に存在する状態

​

セッションパターンを選択する

​

エフェメラルセッション

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 { 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 },
})) {
  // ...
}

​

マルチエージェントコンテナ

​

コンテナのプロビジョニング

​

コンテナベースのサンドボックス

• サンドボックスを実行するのは誰か：sandbox-as-a-service プロバイダーはインフラストラクチャを運用しますが、自己ホスト型オプションは自分のシステムで実行するソフトウェアを提供します。
• コールドスタートレイテンシ：「サンドボックスを作成」から「最初のリクエストを受け入れる準備ができた」までの時間。一時的なパターンは 1 秒未満の起動が必要です。長時間実行パターンはより長い時間を許容します。
• 永続的なストレージ：プロバイダーが耐久性のあるボリュームを提供するか、一時的なディスクのみを提供するか。ハイブリッドパターンは、サンドボックス内またはその横のいずれかで、どこかに耐久性のあるストレージが必要です。
• 価格モデル：秒単位、リクエスト単位、または時間単位の定額請求。秒単位の価格設定は、バースト的な一時的なワークロードに適しています。時間単位は長時間実行セッションに適しています。
• ネットワーク：カスタム出力ルール、アウトバウンドプロキシ、および規制環境向けのプライベート VPC ピアリングのサポート。

• Modal Sandbox（デモ実装付き）
• Cloudflare Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

​

ランタイム依存関係

• Python SDK の場合は Python 3.10 以上、または TypeScript SDK の場合は Node.js 18 以上
• 両方の SDK パッケージはホストプラットフォーム用のネイティブ Claude Code バイナリをバンドルしているため、生成された CLI に対して個別の Claude Code または Node.js インストールは不要です

​

リソース

​

ネットワーク

​

本番環境の懸念事項に対応する

​

セッションと状態の永続性

• トランスクリプトのみ：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)

​

コスト

​

マルチテナント分離

• TypeScript で settingSources: [] を渡すか、Python で setting_sources=[] を渡して、ファイルシステム設定が読み込まれないようにしてください。
• env で CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 を設定してください。自動メモリ は ~/.claude/projects/<project>/memory/ で settingSources に関係なくシステムプロンプトに読み込まれます。settingSources が制御しないもの を参照して、無条件に読み込まれる他の入力を確認してください。
• CLAUDE_CONFIG_DIR をテナントごとのディレクトリにポイントして、テナントが ~/.claude.json グローバル設定を共有しないようにしてください。
• テナントごとの作業ディレクトリを使用してください。すべての query() 呼び出しで cwd を明示的に渡してください。
• プロキシで異なるアウトバウンド 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",
    },
  },
})) {
  // ...
}

​

既知の制限事項

​

次のステップ

• ホスティングクックブック：Docker、Modal、および Kubernetes 用のデプロイ可能なコードを含むノートブックのウォークスルー。
• セッションストレージ：SessionStore アダプターを使用してホスト間でトランスクリプトを永続化します。
• 可観測性：OTEL トレース、メトリクス、およびログをコレクターにエクスポートします。
• セキュアデプロイメント：ネットワーク制御、認証情報管理、および分離強化。
• コスト追跡：セッションごとのトークンおよびコスト会計。