Claude Agent SDKは従来のステートレスなLLM APIとは異なり、会話状態を維持し、永続的な環境でコマンドを実行します。このガイドでは、本番環境で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

• リソース割り当て

  • 推奨：1GiB RAM、5GiBのディスク、および1 CPU（必要に応じてタスクに基づいて変更してください）

• ネットワークアクセス

  • api.anthropic.comへの送信HTTPS
  • オプション：MCPサーバーまたは外部ツールへのアクセス

SDKアーキテクチャの理解

ステートレスなAPI呼び出しとは異なり、Claude Agent SDKは以下を行う長時間実行プロセスとして動作します：

• コマンドを実行する永続的なシェル環境内で
• ファイル操作を管理する作業ディレクトリ内で
• ツール実行を処理する以前のインタラクションからのコンテキストで

サンドボックスプロバイダーオプション

AIコード実行用のセキュアなコンテナ環境を専門とするいくつかのプロバイダーがあります：

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

自己ホスト型オプション（Docker、gVisor、Firecracker）および詳細な分離設定については、分離テクノロジーを参照してください。

本番環境デプロイメントパターン

パターン1：エフェメラルセッション

各ユーザータスク用に新しいコンテナを作成し、完了時に破棄します。

ワンオフタスクに最適です。ユーザーはタスク完了中もAIと対話できますが、完了後はコンテナが破棄されます。

例：

• バグ調査と修正：関連するコンテキストを使用して特定の問題をデバッグして解決する
• 請求書処理：領収書/請求書からデータを抽出して会計システム用に構造化する
• 翻訳タスク：言語間でドキュメントまたはコンテンツバッチを翻訳する
• 画像/ビデオ処理：メディアファイルに変換、最適化を適用するか、メタデータを抽出する

パターン2：長時間実行セッション

長時間実行タスク用に永続的なコンテナインスタンスを維持します。多くの場合、需要に基づいてコンテナ内で複数のClaude Agentプロセスを実行します。

ユーザーの入力なしにアクションを取るプロアクティブなエージェント、コンテンツを提供するエージェント、または大量のメッセージを処理するエージェントに最適です。

例：

• メールエージェント：受信メールを監視し、コンテンツに基づいて自律的にトリアージ、応答、またはアクションを実行する
• サイトビルダー：ユーザーごとのカスタムウェブサイトをホストし、コンテナポート経由で提供されるライブ編集機能を備えている
• 高頻度チャットボット：Slackなどのプラットフォームからの継続的なメッセージストリームを処理し、迅速な応答時間が重要である

パターン3：ハイブリッドセッション

履歴と状態で水和されたエフェメラルコンテナ。データベースまたはSDKのセッション再開機能から取得される可能性があります。

ユーザーからの断続的なインタラクションがあり、作業をキックオフして作業完了時にスピンダウンするが、継続できるコンテナに最適です。

例：

• 個人プロジェクトマネージャー：断続的なチェックインで進行中のプロジェクトを管理するのに役立ち、タスク、決定、進捗のコンテキストを維持する
• 深い調査：数時間の調査タスクを実施し、調査結果を保存し、ユーザーが戻ったときに調査を再開する
• カスタマーサポートエージェント：複数のインタラクションにまたがるサポートチケットを処理し、チケット履歴と顧客コンテキストをロードする

パターン4：単一コンテナ

1つのグローバルコンテナで複数のClaude Agent SDKプロセスを実行します。

密接に協力する必要があるエージェントに最適です。これはおそらく最も人気の低いパターンです。エージェントが互いに上書きするのを防ぐ必要があるためです。

例：

• シミュレーション：ビデオゲームなどのシミュレーション内で互いに相互作用するエージェント。

FAQ

サンドボックスとどのように通信しますか？

コンテナでホストする場合、SDKインスタンスと通信するためにポートを公開します。アプリケーションは外部クライアント用のHTTP/WebSocketエンドポイントを公開できますが、SDKはコンテナ内で内部的に実行されます。

コンテナをホストするコストはいくらですか？

エージェントを提供する支配的なコストはトークンであることがわかっています。コンテナはプロビジョニング内容に基づいて異なりますが、最小コストは実行時間あたり約5セントです。

アイドルコンテナをシャットダウンするべきか、それとも温かく保つべきか？

これはおそらくプロバイダーに依存します。異なるサンドボックスプロバイダーは、アイドルタイムアウト後にサンドボックスがスピンダウンする可能性がある異なる基準を設定できます。 ユーザーの応答がどのくらい頻繁に発生する可能性があるかに基づいて、このタイムアウトを調整する必要があります。

Claude Code CLIはどのくらいの頻度で更新する必要がありますか？

Claude Code CLIはsemverでバージョン管理されているため、破壊的な変更はバージョン管理されます。

コンテナの健全性とエージェントのパフォーマンスをどのように監視しますか？

コンテナはサーバーであるため、バックエンド用に使用するのと同じログインフラストラクチャがコンテナで機能します。

エージェントセッションはタイムアウト前にどのくらいの期間実行できますか？

エージェントセッションはタイムアウトしませんが、Claudeがループに引っかかるのを防ぐために「maxTurns」プロパティを設定することをお勧めします。

次のステップ

• セキュアデプロイメント - ネットワーク制御、認証情報管理、および分離強化
• TypeScript SDK - サンドボックス設定 - プログラマティックにサンドボックスを設定する
• セッションガイド - セッション管理について学ぶ
• 権限 - ツール権限を設定する
• コスト追跡 - API使用状況を監視する
• MCP統合 - カスタムツールで拡張する