ガイド

Agent SDKのホスティング

本番環境にClaude Agent SDKをデプロイしてホストする

Claude Agent SDKは、従来のステートレスなLLM APIとは異なり、会話状態を維持し、永続的な環境でコマンドを実行します。このガイドでは、本番環境でSDKベースのエージェントをデプロイするためのアーキテクチャ、ホスティングに関する考慮事項、およびベストプラクティスについて説明します。

ホスティング要件

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

セキュリティと分離のため、SDKはサンドボックス化されたコンテナ環境内で実行する必要があります。これにより以下が提供されます：

プロセス分離 - セッションごとの独立した実行環境
リソース制限 - CPU、メモリ、ストレージの制約
ネットワーク制御 - アウトバウンド接続の制限
一時的なファイルシステム - 各セッションのクリーンな状態

システム要件

各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コード実行用のセキュアなコンテナ環境を専門としています：

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

パターン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」プロパティを設定することをお勧めします。

次のステップ

セッションガイド - セッション管理について学ぶ
パーミッション - ツールパーミッションを設定
コスト追跡 - API使用状況を監視
MCP統合 - カスタムツールで拡張

ガイド