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())

​

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

​

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

​

エフェメラルセッション

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())

​

長時間実行セッション

• TypeScript：streamInput()を使用してアクティブセッションにターンを追加します。受信トラフィック前にサブプロセスをプリウォームするにはstartup()を呼び出します。セッションの作業ディレクトリが最初のリクエストが到着するまで不明な場合は、代わりにprewarm()でプリウォームしてください。
• Python：ClaudeSDKClientを使用してセッションをターン全体で開いたままにします。

​

ハイブリッドセッション

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())

​

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

​

コンテナをプロビジョニングする

​

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

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

​

ランタイム依存関係

• Python SDK の場合は Python 3.10 以上、または TypeScript SDK の場合は Node.js 18 以上
• TypeScript SDK と Python SDK の両方は、ほとんどのインストールに対してネイティブ Claude Code バイナリをバンドルしており、生成された CLI は別の Node.js インストールを必要としません。別のネイティブ Claude Code インストールが必要なインストールについては、クイックスタートのインストール注記を参照してください。

​

リソース

​

ネットワーク

​

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

​

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

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

​

コスト

​

マルチテナント分離

• TypeScript で settingSources: [] を渡すか、Python で setting_sources=[] を渡して、ユーザー、プロジェクト、およびローカル設定をスキップしてください。
• env で CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 を設定してください。自動メモリ は ~/.claude/projects/<project>/memory/ にあり、settingSources に関係なくシステムプロンプトに読み込まれます。settingSources が制御しないその他の入力については、settingSources が制御しないもの を参照してください。
• CLAUDE_CONFIG_DIR をテナントごとのディレクトリにポイントして、テナントが ~/.claude.json グローバル設定を共有しないようにしてください。各設定ディレクトリが 1 つの作業ディレクトリにサービスを提供し、テナント間で SessionStore を共有しない場合、env で CLAUDE_CODE_PROJECT_DIR_NAME を設定して、その下のトランスクリプトパスを短く保つこともできます。TypeScript Agent SDK v0.3.234 以降、または Python Agent SDK v0.2.140 以降が必要です。
• テナントごとの作業ディレクトリを使用してください。すべての 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",
    },
  },
})) {
  // ...
}

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 が見つかりませんを参照してください。
• イメージに CLI が存在するが起動しない: Claude Code は、コンテナのアーキテクチャまたは libc と一致しないバイナリから起動できないか、イメージビルド中に実行権限を失ったファイルから起動できません。Claude Code の起動に失敗を参照してください。
• Claude Code プロセスが実行中に終了する: アプリケーションが受け取るエラーは、SDK 言語と CLI が最初にエラー結果を報告したかどうかによって異なります。CLI プロセス終了の下のエントリは各メッセージをカバーしています。

​

次のステップ

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