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コード実行のためのセキュアなコンテナ環境を専門とするプロバイダーがいくつかあります：

• Modal Sandbox - デモ実装
• Cloudflare 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統合 - カスタムツールで拡張する